path: root/erts/doc/src/epmd.xml

<?xml version="1.0" encoding="utf-8" ?>
<!DOCTYPE comref SYSTEM "comref.dtd">

<comref>
  <header>
    <copyright>
      <year>1996</year><year>2013</year>
      <holder>Ericsson AB. All Rights Reserved.</holder>
    </copyright>
    <legalnotice>
      Licensed under the Apache License, Version 2.0 (the "License");
      you may not use this file except in compliance with the License.
      You may obtain a copy of the License at
 
          http://www.apache.org/licenses/LICENSE-2.0

      Unless required by applicable law or agreed to in writing, software
      distributed under the License is distributed on an "AS IS" BASIS,
      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
      See the License for the specific language governing permissions and
      limitations under the License.
    
    </legalnotice>

    <title>epmd</title>
    <prepared>Claes Wikstr&ouml;m</prepared>    
    <responsible></responsible>
    <docno>1</docno>
    <approved></approved>
    <checked></checked>
    <date>98-01-05</date>
    <rev>A</rev>
    <file>epmd.xml</file>
  </header>

  <com>epmd</com>
  <comsummary>
  <p>Erlang Port Mapper Daemon</p>
  <taglist>
  <tag><c><![CDATA[epmd [-d|-debug] [DbgExtra...] [-address Addresses] [-port No] [-daemon] [-relaxed_command_check]]]></c></tag>
  <item>
  <p>Starts the port mapper daemon</p>
  </item>
  <tag><c><![CDATA[epmd [-d|-debug] [-port No] [-names|-kill|-stop Name]]]></c></tag>
  <item>
  <p>Communicates with a running port mapper daemon</p>
  </item>
  </taglist>
  </comsummary>
  <description>

    <p>This daemon acts as a name server on all hosts  involved  in
      distributed  Erlang computations. When an Erlang node 
      starts, the node has a name and it obtains an address from the host 
      OS kernel.
      The name and the address are sent to the
      <c><![CDATA[epmd]]></c> daemon running on the local host.
      In a TCP/IP environment, the address consists
      of the IP address and a port number. The name of the node is
      an atom on the form of <c><![CDATA[Name@Node]]></c>.
      The job of the <c><![CDATA[epmd]]></c> daemon is to keep track of which
      node name listens on which address. Hence, <c><![CDATA[epmd]]></c> maps
      symbolic node names to machine addresses.</p>

      <p>The TCP/IP <c>epmd</c> daemon actually only keeps track of
      the <c>Name</c> (first) part of an Erlang node name. The <c>Host</c>
      part (whatever is after the <c><![CDATA[@]]></c>) is implicit in the
      node name where the <c>epmd</c> daemon was actually contacted,
      as is the IP address where the Erlang node can be
      reached. Consistent and correct TCP naming services are
      therefore required for an Erlang network to function
      correctly.</p>

    <taglist>
    <tag>Starting the port mapper daemon</tag>
    <item>

        <p>The daemon is started automatically by the <c>erl</c>
        command if the node is to be distributed and there is no
        running instance present. If automatically launched,
        environment variables have to be used to alter the behavior of
        the daemon. See the <seealso
        marker="#environment_variables">Environment
        variables</seealso> section below.</p>

        <p>If the -daemon argument is not given, 
        <c><![CDATA[epmd]]></c> runs as a normal program with the
	controlling terminal of the shell in which it is
	started. Normally, it should run as a daemon.</p>

	<p>Regular start-up options are described in the
	<seealso marker="#daemon_flags">Regular options</seealso>
	section below.</p>

	<p>The <c>DbgExtra</c> options are described in the
	<seealso marker="#debug_flags">DbgExtra options</seealso>
        section below.</p>

     </item>
     <tag>Communicating with a running port mapper daemon</tag>
     <item>

	<p>Communicating with the running epmd daemon by means of the
	<c>epmd</c> program is done primarily for debugging
	purposes.</p>

	<p>The different queries are described in the <seealso
        marker="#interactive_flags">Interactive options</seealso>
        section below.</p>

     </item>
     </taglist>
  </description>
  <section>
    <marker id="daemon_flags"></marker>
    <title>Regular options</title>

    <p>These options are available when starting the actual name server. The name server is normally started automatically by the <c>erl</c> command (if not already available), but it can also be started at i.e. system start-up.</p>
    <taglist>
    <tag><c><![CDATA[-address List]]></c></tag>
    <item>
    <p>Let this instance of <c>epmd</c> listen only on the
      comma-separated list of IP addresses and on the loopback address
      (which is implicitly added to the list if it has not been
      specified). This can also be set using the
      <c><![CDATA[ERL_EPMD_ADDRESS]]></c> environment variable. See the
      section <seealso marker="#environment_variables">Environment
      variables</seealso> below.</p>
    </item>
    <tag><c><![CDATA[-port No]]></c></tag>
    <item>
      <p>Let this instance of epmd listen to another TCP port than
      default 4369. This can also be set using the
      <c><![CDATA[ERL_EPMD_PORT]]></c> environment variable. See the
      section <seealso marker="#environment_variables">Environment
      variables</seealso> below</p>
    </item>
    <tag><c><![CDATA[-d | -debug]]></c></tag>
    <item>

      <p>Enable debug output. The more <c>-d</c> flags given, the more
      debug output you will get (to a certain limit). This option is
      most useful when the epmd daemon is not started as a daemon.</p>
    </item>
    <tag><c><![CDATA[-daemon]]></c></tag>
    <item>
      <p>Start epmd detached from the controlling terminal. Logging will end up in syslog when available and correctly configured. If the epmd daemon is started at boot, this option should definitely be used. It is also used when the <c>erl</c> command automatically starts <c>epmd</c>.</p>
    </item>
    <tag><c><![CDATA[-relaxed_command_check]]></c></tag>
    <item>
      <p>Start the epmd program with relaxed command checking (mostly for backward compatibility). This affects the following:</p>
      <list type="bulleted">
          <item>
            <p>With relaxed command checking, the <c>epmd</c> daemon can be killed from the localhost with i.e. <c>epmd -kill</c> even if there are active nodes registered. Normally only daemons with an empty node database can be killed with the <c>epmd -kill</c> command.</p>
	  </item>
	  <item>
	    <p>The <c>epmd -stop</c> command (and the corresponding messages to epmd, as can be given using <c>erl_interface/ei</c>) is normally always ignored, as it opens up the possibility of a strange situation where two nodes of the same name can be alive at the same time. A node unregisters itself by just closing the connection to epmd, which is why the <c>stop</c> command was only intended for use in debugging situations.</p>
	    <p>With relaxed command checking enabled, you can forcibly unregister live nodes.</p>
	  </item>
        </list>
	<p>Relaxed command checking can also be enabled by setting the environment variable <c>ERL_EPMD_RELAXED_COMMAND_CHECK</c> prior to starting <c>epmd</c>.</p>
	<p>Only use relaxed command checking on systems with very limited interactive usage.</p>
    </item>
  </taglist>
  </section>

  <section>
    <marker id="debug_flags"></marker>
    <title>DbgExtra options</title>
    <p>These options are purely for debugging and testing epmd clients. They should not be used in normal operation.</p>

    <taglist>
    <tag><c><![CDATA[-packet_timeout Seconds]]></c></tag>
    <item>
    <p>Set the number of seconds a connection can be
    inactive before epmd times out and closes the
    connection (default 60).</p>
    </item>
    <tag><c><![CDATA[-delay_accept Seconds]]></c></tag>
    <item>
    <p>To simulate a busy server you can insert a delay between when epmd
    gets notified that a new connection is requested and
    when the connection gets accepted.</p>
    </item>
    <tag><c><![CDATA[-delay_write Seconds]]></c></tag>
    <item>
    <p>Also a simulation of a busy server. Inserts
    a delay before a reply is sent.</p>
    </item>
    </taglist>
  </section>
  <section>
    <marker id="interactive_flags"></marker>
    <title>Interactive options</title>
    <p>These options make <c>epmd</c> run as an interactive command, displaying the results of sending queries to an already running instance of <c>epmd</c>. The epmd contacted is always on the local node, but the <c>-port</c> option can be used to select between instances if several are running using different ports on the host.</p>
    <taglist>
    <tag><c><![CDATA[-port No]]></c></tag>
    <item>
      <p>Contacts the <c>epmd</c> listening on the given TCP port number
      (default 4369). This can also be set using the
      <c><![CDATA[ERL_EPMD_PORT]]></c> environment variable. See the
      section <seealso marker="#environment_variables">Environment
      variables</seealso> below.</p>
    </item>
    <tag><c><![CDATA[-names]]></c></tag>
    <item>
      <p>List names registered with the currently running epmd</p>
    </item>
    <tag><c><![CDATA[-kill]]></c></tag>
    <item>
      <p>Kill the currently running <c>epmd</c>.</p>

      <p>Killing the running <c>epmd</c> is only allowed if <c>epmd
        -names</c> shows an empty database or
        <c>-relaxed_command_check</c> was given when the running
        instance of <c>epmd</c> was started. Note that
        <c>-relaxed_command_check</c> is given when starting the
        daemon that is to accept killing when it has live nodes
        registered. When running epmd interactively,
        <c>-relaxed_command_check</c> has no effect. A daemon that is
        started without relaxed command checking has to be killed
        using i.e. signals or some other OS specific method if it has
        active clients registered.</p>
    </item>
    <tag><c><![CDATA[-stop Name]]></c></tag>
    <item>
       <p>Forcibly unregister a live node from <c>epmd</c>'s database</p>

       <p>This command can only be used when contacting <c>epmd</c>
       instances started with the <c>-relaxed_command_check</c>
       flag. Note that relaxed command checking has to be enabled for
       the <c>epmd</c> daemon contacted. When running epmd
       interactively,
        <c>-relaxed_command_check</c> has no effect.</p>
    </item>
  </taglist>
  </section>
  <section>
    <marker id="environment_variables"></marker>
    <title>Environment variables</title>
    <taglist>
      <tag><c><![CDATA[ERL_EPMD_ADDRESS]]></c></tag>
      <item>
        <p>This environment variable may be set to a comma-separated
          list of IP addresses, in which case the <c>epmd</c> daemon
          will listen only on the specified address(es) and on the
          loopback address (which is implicitly added to the list if it
          has not been specified). The default behaviour is to listen on
          all available IP addresses.</p>
      </item>
      <tag><c><![CDATA[ERL_EPMD_PORT]]></c></tag>
      <item>
        <p>This environment variable can contain the port number epmd will use.
          The default port will work fine in most cases. A different port can
          be specified to allow several instances of epmd, representing
          independent clusters of nodes, to co-exist on the same host.
          All nodes in a cluster must use the same epmd port number.</p>
      </item>
      <tag><c><![CDATA[ERL_EPMD_RELAXED_COMMAND_CHECK]]></c></tag>
      <item>
        <p>If set prior to start, the <c>epmd</c> daemon will behave
        as if the <c>-relaxed_command_check</c> option was given at
        start-up. Consequently, if this option is set before starting
        the Erlang virtual machine, the automatically started
        <c>epmd</c> will accept the <c>-kill</c> and <c>-stop</c>
        commands without restrictions.</p>
      </item>
    </taglist>
  </section>

  <section>
    <title>Logging</title>
    <p>On some operating systems <em>syslog</em> will be used for
      error reporting when epmd runs as an daemon. To enable
      the error logging you have to edit <path unix="" windows="">/etc/syslog.conf</path>
      file and add an entry</p>
    <code type="none"><![CDATA[
      !epmd
      *.*<TABs>/var/log/epmd.log
    ]]></code>
    <p>where &lt;TABs&gt; are at least one real tab character. Spaces will
      silently be ignored.
      </p>
  </section>
  <section>
  <title>Access restrictions</title>
  <p>The <c>epmd</c> daemon accepts messages from both localhost and
  remote hosts. However, only the query commands are answered (and
  acted upon) if the query comes from a remote host. It is always an
  error to try to register a nodename if the client is not a process
  located on the same host as the <c>epmd</c> instance is running on-
  such requests are considered hostile and the connection is
  immediately closed.</p>

  <p>The queries accepted from remote nodes are:</p>
      <list type="bulleted">
          <item>
	  <p>Port queries - i.e. on which port does the node with a given
	  name listen</p>
	  </item>
	  <item>
	  <p>Name listing - i.e. give a list of all names registered on
	  the host</p>
	  </item>
     </list>
  <p>To restrict access further, firewall software has to be used.</p>
  </section>

</comref>