* doc/guide.tex: Added explanations about epmd, cookie and node

name (EJAB-251)

SVN Revision: 1027

2 files changed, 83 insertions, 6 deletions

diff --git a/ChangeLog b/ChangeLog
index 1ddeaea11..bec6559e5 100644
--- a/ChangeLog
+++ b/ChangeLog
@@ -1,5 +1,8 @@
 2007-12-05  Badlop  <badlop@process-one.net>
 
+	* doc/guide.tex: Added explanations about epmd, cookie and node
+	name (EJAB-251)
+
 	* src/msgs/zh.msg: Updated (thanks to Shelley Shyan)
 
 	* src/mod_muc/mod_muc_room.erl: Rephrase the invitation sentence
diff --git a/doc/guide.tex b/doc/guide.tex
index 76786a2f0..af31f1ebb 100644
--- a/doc/guide.tex
+++ b/doc/guide.tex
@@ -3379,16 +3379,90 @@ You need to take the following TCP ports in mind when configuring your firewall:
   \centering
   \begin{tabular}{|l|l|}
     \hline Port& Description\\
-    \hline \hline 5222& SASL and unencrypted c2s connections.\\
-    \hline 5223& Obsolete SSL c2s connections.\\
-    \hline 5269& s2s connections.\\
-    \hline 4369& Only for clustering (see~\ref{clustering}).\\
-    \hline port range& Only for clustring (see~\ref{clustering}). This range
-    is configurable (see~\ref{start}).\\
+    \hline \hline 5222& Standard port for Jabber/XMPP client connections, plain or STARTTLS.\\
+    \hline 5223& Standard port for Jabber client connections using the old SSL method.\\
+    \hline 5269& Standard port for Jabber/XMPP server connections.\\
+    \hline 4369& Port used by EPMD for communication between Erlang nodes.\\
+    \hline port range& Used for connections between Erlang nodes. This range is configurable.\\
     \hline
   \end{tabular}
 \end{table}
 
+\section{epmd }
+\label{epmd}
+
+\footahref{http://www.erlang.org/doc/man/epmd.html}{epmd (Erlang Port Mapper Daemon)}
+is a small name server included in Erlang/OTP 
+and used by Erlang programs when establishing distributed Erlang communications. 
+ejabberd needs \term{epmd} to use \term{ejabberdctl} and also when clustering ejabberd nodes. 
+This small program is automatically started by Erlang, and is never stopped.
+If ejabberd is stopped, and there aren't any other Erlang programs 
+running in the system, you can safely stop \term{epmd} if you want.
+
+ejabberd runs inside an Erlang node. 
+To communicate with ejabberd, the script \term{ejabberdctl} starts a new Erlang node 
+and connects to the Erlang node that holds ejabberd.
+In order for this communication to work,
+\term{epmd} must be running and listening for name requests in the port 4369.
+You should block the port 4369 in the firewall,
+so only the programs in your machine can access it.
+
+If you build a cluster of several ejabberd instances,
+each ejabberd instance is called an ejabberd node.
+Those ejabberd nodes use a special Erlang communication method to
+build the cluster, and EPMD is again needed listening in the port 4369.
+So, if you plan to build a cluster of ejabberd nodes
+you must open the port 4369 for the machines involved in the cluster.
+Remember to block the port so Internet doesn't have access to it.
+
+Once an Erlang node solved the node name of another Erlang node using EPMD and port 4369,
+the nodes communicate directly.
+The ports used in this case are random. 
+You can limit the range of ports when starting Erlang with a command-line parameter, for example:
+\begin{verbatim}
+erl ... -kernel inet_dist_listen_min 4370 inet_dist_listen_max 4375
+\end{verbatim}
+
+
+\section{Erlang Cookie}
+\label{cookie}
+
+The Erlang cookie is a string with numbers and letters. 
+An Erlang node reads the cookie at startup from the command-line parameter \term{-setcookie}
+or from a cookie file.
+Two Erlang nodes communicate only if they have the same cookie.
+Setting a cookie on the Erlang node allows you to structure your Erlang network 
+and define which nodes are allowed to connect to which.
+
+Thanks to Erlang cookies, you can prevent access to the Erlang node by mistake,
+for example when there are several Erlang nodes running different programs in the same machine.
+
+Setting a secret cookie is a simple method
+to difficult unauthorized access to your Erlang node.
+However, the cookie system is not ultimately effective 
+to prevent unauthorized access or intrusion to an Erlang node.
+The communication between Erlang nodes are not encrypted,
+so the cookie could be read sniffing the traffic on the network.
+The recommended way to secure the Erlang node is to block the port 4369.
+
+
+\section{Erlang node name}
+\label{nodename}
+
+An Erlang node may have a node name.
+The name can be short (if indicated with the command-line parameter \term{-sname}) 
+or long (if indicated with the parameter \term{-name}). 
+Starting an Erlang node with -sname limits the communication between Erlang nodes to the LAN.
+
+Using the option \term{-sname} instead of \term{-name} is a simple method 
+to difficult unauthorized access to your Erlang node.
+However, it is not ultimately effective  to prevent access to the Erlang node,
+because it may be possible to fake the fact that you are on another network 
+using a modified version of Erlang \term{epmd}.
+The recommended way to secure the Erlang node is to block the port 4369.
+
+
+
 \chapter{Integrating ejabberd with other Instant Messaging servers}
 \section{SRV Records}
 \label{srv}