man pages section 1: User Commands

Exit Print View

Updated: July 2014

epmd (1)


epmd - tra...] [-port No] [-daemon] [-relaxed_command_check]Starts the port mapper daemonepmd [-d|-debug] [-port No] [-names|-kill|-stop Name]Communicates with a running port mapper daemon


Please see following description for synopsis


User Commands                                             epmd(1)

     epmd  -  Erlang  Port  Mapper Daemonepmd [-d|-debug] [DbgEx-
     tra...] [-port No] [-daemon]  [-relaxed_command_check]Starts
     the   port   mapper   daemonepmd   [-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 the 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  name  of  the node 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 map symbolic node
     names to machine addresses.

     The TCP/IP epmd daemon actually 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  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.

       Starting the port mapper daemon:
         The daemon is started automatically by the  erl  command
         if the node is to be distributed and there is no running
         instance present. If automatically launched, environment
         variables  has  to  be used to alter the behavior of the
         daemon. See the Environment variables section below.

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

         Regular  start-up  options  are described in the Regular
         options section below.

         The DbgExtra  options  are  described  in  the  DbgExtra
         options section below.

       Communicating with a running port mapper daemon:
         Communicating  with  the running epmd daemon by means of
         the epmd program is done primarily  for  debugging  pur-

         The  different  queries are described in the Interactive
         options section below.

Ericsson AB         Last change: erts                   1

User Commands                                             epmd(1)

     These options are available when starting  the  actual  name
     server. The name server is normally started automatically by
     the erl command (if not already available), but it can  also
     be started at i.e. system start-up.

       -address List:
         Let this instance of epmd listen only on the comma-sepa-
         rated 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
         ERL_EPMD_ADDRESS  environment  variable, see the section
         Environment variables below.

       -port No:
         Let this instance of epmd listen  to  another  TCP  port
         than  default  4369.  This  can  also  be  set using the
         ERL_EPMD_PORT  environment  variable,  see  the  section
         Environment variables below

       -d | -debug:
         Enable  debug  output. The more -d 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.

         Start epmd detached from the controlling terminal.  Log-
         ging  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 erl command automatically starts epmd.

         Start the epmd program  with  relaxed  command  checking
         (mostly  for  backward  compatibility). This affects the

         * With relaxed command checking, the epmd daemon can  be
           killed from the localhost with i.e. epmd -kill even if
           there are active nodes registered. Normally only  dae-
           mons  with  an  empty node database can be killed with
           the epmd -kill command.

         * The epmd -stop command (and the corresponding messages
           to  epmd,  as  can be given using erl_interface/ei) is
           normally always ignored, as it opens  up  for  strange
           situation when two nodes of the same name can be alive
           at the same time. A node unregisters  itself  by  just
           closing  the  connection to epmd, why the stop command
           was only intended for use in debugging situations.

Ericsson AB         Last change: erts                   2

User Commands                                             epmd(1)

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

         Relaxed  command checking can also be enabled by setting
         the environment variable  ERL_EPMD_RELAXED_COMMAND_CHECK
         prior to starting epmd.

         Only  use  relaxed command checking on systems with very
         limited interactive usage.

     These options are purely  for  debugging  and  testing  epmd
     clients, they should not be used in normal operation.

       -packet_timeout Seconds:
         Set  the  number of seconds a connection can be inactive
         before epmd times out and closes the connection (default

       -delay_accept Seconds:
         To simulate a busy server you can insert a delay between
         epmd gets  notified  about  that  a  new  connection  is
         requested and when the connections gets accepted.

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

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

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

         List names registered with the currently running epmd

         Kill the currently running epmd.

         Killing the running epmd is only allowed if epmd  -names
         show  an  empty  database  or -relaxed_command_check was
         given when the running instance  of  epmd  was  started.
         Note  that -relaxed_command_check is given when starting

Ericsson AB         Last change: erts                   3

User Commands                                             epmd(1)

         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  has  to be
         killed using i.e. signals  or  some  other  OS  specific
         method if it has active clients registered.

       -stop Name:
         Forcibly unregister a live node from epmd's database

         This  command  can  only  be  used  when contacting epmd
         instances started with the -relaxed_command_check  flag.
         Note that relaxed command checking has to be enabled for
         the epmd daemon contacted, When  running  epmd  interac-
         tively, -relaxed_command_check has no effect.

         This  environment  variable  may be set to a comma-sepa-
         rated list of IP addresses, in which case the epmd  dae-
         mon 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 behav-
         iour is to listen on all available IP addresses.

         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  sev-
         eral  instances  of epmd, representing independent clus-
         ters of nodes, to co-exist on the same host.  All  nodes
         in a cluster must use the same epmd port number.

         If set prior to start, the epmd daemon will behave as if
         the -relaxed_command_check option was given at start-up.
         If  consequently setting this option before starting the
         Erlang virtual machine, the automatically  started  epmd
         will   accept  the  -kill  and  -stop  commands  without

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


Ericsson AB         Last change: erts                   4

User Commands                                             epmd(1)

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

     The epmd 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 epmd
     instance  is  running  on,  why such requests are considered
     hostile and the connection is immediately closed.

     The queries accepted from remote nodes are:

       * Port queries - i.e. on which port does the node  with  a
         given name listen

       * Name  listing - i.e. give a list of all names registered
         on the host

     To restrict access further,  firewall  software  has  to  be

     See   attributes(5)   for   descriptions  of  the  following

     |Availability   | runtime/erlang   |
     |Stability      | Uncommitted      |
     This  software  was   built   from   source   available   at    The  original
     community       source       was       downloaded       from

     Further  information about this software can be found on the
     open source community website at

Ericsson AB         Last change: erts                   5