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.