aboutsummaryrefslogtreecommitdiffstats
path: root/system/doc/reference_manual/distributed.xml
diff options
context:
space:
mode:
Diffstat (limited to 'system/doc/reference_manual/distributed.xml')
-rw-r--r--system/doc/reference_manual/distributed.xml279
1 files changed, 279 insertions, 0 deletions
diff --git a/system/doc/reference_manual/distributed.xml b/system/doc/reference_manual/distributed.xml
new file mode 100644
index 0000000000..52222c6d9d
--- /dev/null
+++ b/system/doc/reference_manual/distributed.xml
@@ -0,0 +1,279 @@
+<?xml version="1.0" encoding="latin1" ?>
+<!DOCTYPE chapter SYSTEM "chapter.dtd">
+
+<chapter>
+ <header>
+ <copyright>
+ <year>2003</year><year>2009</year>
+ <holder>Ericsson AB. All Rights Reserved.</holder>
+ </copyright>
+ <legalnotice>
+ The contents of this file are subject to the Erlang Public License,
+ Version 1.1, (the "License"); you may not use this file except in
+ compliance with the License. You should have received a copy of the
+ Erlang Public License along with this software. If not, it can be
+ retrieved online at http://www.erlang.org/.
+
+ Software distributed under the License is distributed on an "AS IS"
+ basis, WITHOUT WARRANTY OF ANY KIND, either express or implied. See
+ the License for the specific language governing rights and limitations
+ under the License.
+
+ </legalnotice>
+
+ <title>Distributed Erlang</title>
+ <prepared></prepared>
+ <docno></docno>
+ <date></date>
+ <rev></rev>
+ <file>distributed.xml</file>
+ </header>
+
+ <section>
+ <title>Distributed Erlang System</title>
+ <p>A <em>distributed Erlang system</em> consists of a number of
+ Erlang runtime systems communicating with each other. Each such
+ runtime system is called a <em>node</em>. Message passing between
+ processes at different nodes, as well as links and monitors, are
+ transparent when pids are used. Registered names, however, are
+ local to each node. This means the node must be specified as well
+ when sending messages etc. using registered names.</p>
+ <p>The distribution mechanism is implemented using TCP/IP sockets.
+ How to implement an alternative carrier is described in <em>ERTS User's Guide</em>.</p>
+ </section>
+
+ <section>
+ <title>Nodes</title>
+ <p>A <em>node</em> is an executing Erlang runtime system which has
+ been given a name, using the command line flag <c>-name</c>
+ (long names) or <c>-sname</c> (short names).</p>
+ <p>The format of the node name is an atom <c>name@host</c> where
+ <c>name</c> is the name given by the user and <c>host</c> is
+ the full host name if long names are used, or the first part of
+ the host name if short names are used. <c>node()</c> returns
+ the name of the node. Example:</p>
+ <pre>
+% <input>erl -name dilbert</input>
+([email protected])1> <input>node().</input>
+
+% <input>erl -sname dilbert</input>
+(dilbert@uab)1> <input>node().</input>
+dilbert@uab</pre>
+ <note>
+ <p>A node with a long node name cannot communicate with a node
+ with a short node name.</p>
+ </note>
+ </section>
+
+ <section>
+ <title>Node Connections</title>
+ <p>The nodes in a distributed Erlang system are loosely connected.
+ The first time the name of another node is used, for example if
+ <c>spawn(Node,M,F,A)</c> or <c>net_adm:ping(Node)</c> is called,
+ a connection attempt to that node will be made.</p>
+ <p>Connections are by default transitive. If a node A connects to
+ node B, and node B has a connection to node C, then node A will
+ also try to connect to node C. This feature can be turned off by
+ using the command line flag <c>-connect_all false</c>, see
+ <c>erl(1)</c>.</p>
+ <p>If a node goes down, all connections to that node are removed.
+ Calling <c>erlang:disconnect(Node)</c> will force disconnection
+ of a node.</p>
+ <p>The list of (visible) nodes currently connected to is returned by
+ <c>nodes()</c>.</p>
+ </section>
+
+ <section>
+ <title>epmd</title>
+ <p>The Erlang Port Mapper Daemon <em>epmd</em> is automatically
+ started at every host where an Erlang node is started. It is
+ responsible for mapping the symbolic node names to machine
+ addresses. See <c>epmd(1)</c>.</p>
+ </section>
+
+ <section>
+ <title>Hidden Nodes</title>
+ <p>In a distributed Erlang system, it is sometimes useful to
+ connect to a node without also connecting to all other nodes.
+ An example could be some kind of O&amp;M functionality used to
+ inspect the status of a system without disturbing it. For this
+ purpose, a <em>hidden node</em> may be used.</p>
+ <p>A hidden node is a node started with the command line flag
+ <c>-hidden</c>. Connections between hidden nodes and other nodes
+ are not transitive, they must be set up explicitly. Also, hidden
+ nodes does not show up in the list of nodes returned by
+ <c>nodes()</c>. Instead, <c>nodes(hidden)</c> or
+ <c>nodes(connected)</c> must be used. This means, for example,
+ that the hidden node will not be added to the set of nodes that
+ <c>global</c> is keeping track of.</p>
+ <p>This feature was added in Erlang 5.0/OTP R7.</p>
+ </section>
+
+ <section>
+ <title>C Nodes</title>
+ <p>A <em>C node</em> is a C program written to act as a hidden node
+ in a distributed Erlang system. The library <em>Erl_Interface</em>
+ contains functions for this purpose. Refer to the documentation
+ for Erl_Interface and <em>Interoperability Tutorial</em> for more
+ information about C nodes.</p>
+ </section>
+
+ <section>
+ <title>Security</title>
+ <p>Authentication determines which nodes are allowed to communicate
+ with each other. In a network of different Erlang nodes, it is
+ built into the system at the lowest possible level. Each node has
+ its own <em>magic cookie</em>, which is an Erlang atom.</p>
+ <p>When a nodes tries to connect to another node, the magic cookies
+ are compared. If they do not match, the connected node rejects
+ the connection.</p>
+ <p>At start-up, a node has a random atom assigned as its magic
+ cookie and the cookie of other nodes is assumed to be
+ <c>nocookie</c>. The first action of the Erlang network
+ authentication server (<c>auth</c>) is then to read a file named
+ <c>$HOME/.erlang.cookie</c>. If the file does not exist, it is
+ created. The UNIX permissions mode of the file is set to octal
+ 400 (read-only by user) and its contents are a random string. An
+ atom <c>Cookie</c> is created from the contents of the file and
+ the cookie of the local node is set to this using
+ <c>erlang:set_cookie(node(), Cookie)</c>. This also makes
+ the local node assume that all other nodes have the same cookie
+ <c>Cookie</c>.</p>
+ <p>Thus, groups of users with identical cookie files get Erlang
+ nodes which can communicate freely and without interference from
+ the magic cookie system. Users who want run nodes on separate
+ file systems must make certain that their cookie files are
+ identical on the different file systems.</p>
+ <p>For a node <c>Node1</c> with magic cookie <c>Cookie</c> to be
+ able to connect to, or accept a connection from, another node
+ <c>Node2</c> with a different cookie <c>DiffCookie</c>,
+ the function <c>erlang:set_cookie(Node2, DiffCookie)</c> must
+ first be called at <c>Node1</c>. Distributed systems with
+ multiple user IDs can be handled in this way.</p>
+ <p>The default when a connection is established between two nodes,
+ is to immediately connect all other visible nodes as well. This
+ way, there is always a fully connected network. If there are
+ nodes with different cookies, this method might be inappropriate
+ and the command line flag <c>-connect_all false</c> must be set,
+ see <seealso marker="erts:erl">erl(1)</seealso>.</p>
+ <p>The magic cookie of the local node is retrieved by calling
+ <c>erlang:get_cookie()</c>.</p>
+ </section>
+
+ <section>
+ <title>Distribution BIFs</title>
+ <p>Some useful BIFs for distributed programming, see
+ <c>erlang(3)</c> for more information:</p>
+ <table>
+ <row>
+ <cell align="left" valign="middle"><c>erlang:disconnect_node(Node)</c></cell>
+ <cell align="left" valign="middle">Forces the disconnection of a node.</cell>
+ </row>
+ <row>
+ <cell align="left" valign="middle"><c>erlang:get_cookie()</c></cell>
+ <cell align="left" valign="middle">Returns the magic cookie of the current node.</cell>
+ </row>
+ <row>
+ <cell align="left" valign="middle"><c>is_alive()</c></cell>
+ <cell align="left" valign="middle">Returns <c>true</c>if the runtime system is a node and can connect to other nodes, <c>false</c>otherwise.</cell>
+ </row>
+ <row>
+ <cell align="left" valign="middle"><c>monitor_node(Node, true|false)</c></cell>
+ <cell align="left" valign="middle">Monitor the status of <c>Node</c>. A message<c>{nodedown, Node}</c>is received if the connection to it is lost.</cell>
+ </row>
+ <row>
+ <cell align="left" valign="middle"><c>node()</c></cell>
+ <cell align="left" valign="middle">Returns the name of the current node. Allowed in guards.</cell>
+ </row>
+ <row>
+ <cell align="left" valign="middle"><c>node(Arg)</c></cell>
+ <cell align="left" valign="middle">Returns the node where <c>Arg</c>, a pid, reference, or port, is located.</cell>
+ </row>
+ <row>
+ <cell align="left" valign="middle"><c>nodes()</c></cell>
+ <cell align="left" valign="middle">Returns a list of all visible nodes this node is connected to.</cell>
+ </row>
+ <row>
+ <cell align="left" valign="middle"><c>nodes(Arg)</c></cell>
+ <cell align="left" valign="middle">Depending on <c>Arg</c>, this function can return a list not only of visible nodes, but also hidden nodes and previously known nodes, etc.</cell>
+ </row>
+ <row>
+ <cell align="left" valign="middle"><c>set_cookie(Node, Cookie)</c></cell>
+ <cell align="left" valign="middle">Sets the magic cookie used when connecting to <c>Node</c>. If <c>Node</c>is the current node, <c>Cookie</c>will be used when connecting to all new nodes.</cell>
+ </row>
+ <row>
+ <cell align="left" valign="middle"><c>spawn[_link|_opt](Node, Fun)</c></cell>
+ <cell align="left" valign="middle">Creates a process at a remote node.</cell>
+ </row>
+ <row>
+ <cell align="left" valign="middle"><c>spawn[_link|opt](Node, Module, FunctionName, Args)</c></cell>
+ <cell align="left" valign="middle">Creates a process at a remote node.</cell>
+ </row>
+ <tcaption>Distribution BIFs.</tcaption>
+ </table>
+ </section>
+
+ <section>
+ <title>Distribution Command Line Flags</title>
+ <p>Examples of command line flags used for distributed programming,
+ see <c>erl(1)</c> for more information:</p>
+ <table>
+ <row>
+ <cell align="left" valign="middle"><c>-connect_all false</c></cell>
+ <cell align="left" valign="middle">Only explicit connection set-ups will be used.</cell>
+ </row>
+ <row>
+ <cell align="left" valign="middle"><c>-hidden</c></cell>
+ <cell align="left" valign="middle">Makes a node into a hidden node.</cell>
+ </row>
+ <row>
+ <cell align="left" valign="middle"><c>-name Name</c></cell>
+ <cell align="left" valign="middle">Makes a runtime system into a node, using long node names.</cell>
+ </row>
+ <row>
+ <cell align="left" valign="middle"><c>-setcookie Cookie</c></cell>
+ <cell align="left" valign="middle">Same as calling <c>erlang:set_cookie(node(), Cookie)</c>.</cell>
+ </row>
+ <row>
+ <cell align="left" valign="middle"><c>-sname Name</c></cell>
+ <cell align="left" valign="middle">Makes a runtime system into a node, using short node names.</cell>
+ </row>
+ <tcaption>Distribution Command Line Flags.</tcaption>
+ </table>
+ </section>
+
+ <section>
+ <title>Distribution Modules</title>
+ <p>Examples of modules useful for distributed programming:</p>
+ <p>In Kernel:</p>
+ <table>
+ <row>
+ <cell align="left" valign="middle"><c>global</c></cell>
+ <cell align="left" valign="middle">A global name registration facility.</cell>
+ </row>
+ <row>
+ <cell align="left" valign="middle"><c>global_group</c></cell>
+ <cell align="left" valign="middle">Grouping nodes to global name registration groups.</cell>
+ </row>
+ <row>
+ <cell align="left" valign="middle"><c>net_adm</c></cell>
+ <cell align="left" valign="middle">Various Erlang net administration routines.</cell>
+ </row>
+ <row>
+ <cell align="left" valign="middle"><c>net_kernel</c></cell>
+ <cell align="left" valign="middle">Erlang networking kernel.</cell>
+ </row>
+ <tcaption>Kernel Modules Useful For Distribution.</tcaption>
+ </table>
+ <p>In STDLIB:</p>
+ <table>
+ <row>
+ <cell align="left" valign="middle"><c>slave</c></cell>
+ <cell align="left" valign="middle">Start and control of slave nodes.</cell>
+ </row>
+ <tcaption>STDLIB Modules Useful For Distribution.</tcaption>
+ </table>
+ </section>
+</chapter>
+