NAME

       epmd - Erlang Port Mapper Daemon

DESCRIPTION

         epmd [-d|-debug] [DbgExtra...] [-address Addresses] [-port No] [-daemon] [-relaxed_command_check]:
           Starts the port mapper daemon.

         epmd [-d|-debug] [-port No] [-names|-kill|-stop Name]:
           Communicates with a running port mapper daemon.

       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
       address  are  sent  to  the  epmd  daemon running on the local host. In a TCP/IP environment, the address
       consists of the IP address and a port number. The node name is an atom on the form of Name@Node. The  job
       of  the  epmd  daemon  is  to  keep  track  of which node name listens on which address. Hence, epmd maps
       symbolic node names to machine addresses.

       The TCP/IP epmd daemon only keeps track of the Name (first) part of an Erlang node name.  The  Host  part
       (whatever  is after the @) is implicit in the node name where the epmd daemon was 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.

         Starting the port mapper daemon:
           The daemon is started automatically by command erl(1) if the node is to be distributed and no running
           instance  is  present.  If  automatically  launched  environment variables must be used to change the
           behavior of the daemon; see section Environment Variables.

           If argument -daemon is not specified, epmd runs as a normal program with the controlling terminal  of
           the shell in which it is started. Normally, it is to be run as a daemon.

           Regular startup options are described in section Regular Options.

           The DbgExtra options are described in section DbgExtra Options.

         Communicating with a running port mapper daemon:
           Communicating  with  the  running  epmd  daemon  by  the epmd program is done primarily for debugging
           purposes.

           The different queries are described in section Interactive options.

REGULAR OPTIONS

       These options are available  when  starting  the  name  server.  The  name  server  is  normally  started
       automatically by command erl(1) (if not already available), but it can also be started at system startup.

         -address List:
           Lets  this  instance  of  epmd  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 environment variable ERL_EPMD_ADDRESS; see section Environment Variables.

         -port No:
           Lets  this  instance of epmd listen to another TCP port than default 4369. This can also be set using
           environment variable ERL_EPMD_PORT; see section Environment Variables.

         -d | -debug:
           Enables debug output. The more -d flags specified, 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.

         -daemon:
           Starts  epmd  detached  from  the  controlling terminal. Logging ends up in syslog when available and
           correctly configured. If the epmd daemon is started at boot, this option is definitely to be used. It
           is also used when command erl automatically starts epmd.

         -relaxed_command_check:
           Starts the epmd program with relaxed command  checking  (mostly  for  backward  compatibility).  This
           affects the following:

           * With relaxed command checking, the epmd daemon can be killed from the local host with, for example,
             command  epmd  -kill  even if active nodes are registered. Normally only daemons with an empty node
             database can be killed with epmd -kill.

           * Command  epmd  -stop  (and  the  corresponding  messages  to  epmd,  as  can  be  specified   using
             erl_interface:ei(3erl))  is  normally always ignored. This because it can cause a strange situation
             where two nodes of the same name can be alive at the same time. A node unregisters itself  by  only
             closing  the  connection  to epmd, which is why command stop was only intended for use in debugging
             situations.

             With relaxed command checking enabled, you can forcibly unregister live nodes.

           Relaxed   command   checking   can   also   be    enabled    by    setting    environment    variable
           ERL_EPMD_RELAXED_COMMAND_CHECK before starting epmd.

           Use relaxed command checking only on systems with very limited interactive usage.

DBGEXTRA OPTIONS

   Note:
       These  options  are  only  for  debugging  and  testing  epmd  clients. They are not to be used in normal
       operation.

         -packet_timeout Seconds:
           Sets the number of seconds a connection can  be  inactive  before  epmd  times  out  and  closes  the
           connection. Defaults to 60.

         -delay_accept Seconds:
           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.

         -delay_write Seconds:
           Also a simulation of a busy server. Inserts a delay before a reply is sent.

INTERACTIVE OPTIONS

       These options make epmd run as an interactive command, displaying the results of sending  queries  to  an
       already running instance of epmd. The epmd contacted is always on the local node, but option -port can be
       used to select between instances if several are running using different ports on the host.

         -port No:
           Contacts  the  epmd  listening  on the specified TCP port number (default 4369). This can also be set
           using environment variable ERL_EPMD_PORT; see section Environment Variables.

         -names:
           Lists names registered with the currently running epmd.

         -kill:
           Kills the currently running epmd.

           Killing  the  running  epmd  is  only  allowed  if  epmd  -names  shows  an  empty  database  or   if
           -relaxed_command_check was specified when the running instance of epmd was started.

           Notice  that  -relaxed_command_check  is specified when starting the daemon that is to accept killing
           when it has live nodes registered. When running epmd  interactively,  -relaxed_command_check  has  no
           effect.  A daemon that is started without relaxed command checking must be killed using, for example,
           signals or some other OS-specific method if it has active clients registered.

         -stop Name:
           Forcibly unregisters a live node from the epmd database.

           This  command   can   only   be   used   when   contacting   epmd   instances   started   with   flag
           -relaxed_command_check.

           Notice  that  relaxed  command checking must enabled for the epmd daemon contacted. When running epmd
           interactively, -relaxed_command_check has no effect.

ENVIRONMENT VARIABLES

         ERL_EPMD_ADDRESS:
           Can be set to a comma-separated list of IP addresses, in which case the epmd 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 behavior is to listen on all available IP addresses.

         ERL_EPMD_PORT:
           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.

         ERL_EPMD_RELAXED_COMMAND_CHECK:
           If  set  before  start,  the epmd daemon behaves as if option -relaxed_command_check was specified at
           startup. Consequently, if this option  is  set  before  starting  the  Erlang  virtual  machine,  the
           automatically started epmd accepts the -kill and -stop commands without restrictions.

LOGGING

       On  some  operating systems syslog will be used for error reporting when epmd runs as a daemon. To enable
       the error logging, you must edit the /etc/syslog.conf file and add an entry:

         !epmd
         *.*<TABs>/var/log/epmd.log

       where <TABs> are at least one real tab character. Spaces are silently ignored.

ACCESS RESTRICTIONS

       The epmd daemon accepts messages from both the local host 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 node name if the client is not a process on the same  host  as  the  epmd  instance  is
       running on. Such requests are considered hostile and the connection is closed immediately.

       The following queries are accepted from remote nodes:

         * Port queries, that is, on which port the node with a specified name listens

         * Name listing, that is, gives a list of all names registered on the host

       To restrict access further, firewall software must be used.

Ericsson AB                                        erts 10.6.4                                           epmd(1)