Go to main content

man pages section 1: User Commands

Exit Print View

Updated: July 2017

epmd (1)


epmd - 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


epmd(1)                          User Commands                         epmd(1)

       epmd  -  Erlang Port Mapper Daemonepmd [-d|-debug] [DbgExtra...] [-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  maps  symbolic  node  names  to  machine

       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 have to be used to
           alter the behavior of the daemon.  See  the  Environment  variables
           section below.

           If the -daemon argument is not given, 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 sec-
           tion below.

           The DbgExtra options are described in the DbgExtra options  section

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

           The different queries are described in the Interactive options sec-
           tion below.

       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

         -address List:
           Let 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  the ERL_EPMD_ADDRESS environment variable. See the sec-
           tion 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. 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 erl command automatically starts epmd.

           Start  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 localhost with i.e. epmd -kill even if there are active nodes
             registered. Normally only daemons 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 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 stop command was only intended for use in debug-
             ging situations.

             With  relaxed command checking enabled, you can forcibly unregis-
             ter live nodes.

           Relaxed command checking can also be enabled by setting  the  envi-
           ronment  variable  ERL_EPMD_RELAXED_COMMAND_CHECK prior to starting

           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 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  con-
           nection 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,  displaying  the
       results  of sending queries to 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
       ports on the host.

         -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  shows  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  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.  sig-
           nals or some other OS specific method if it has active clients reg-

         -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  interactively,  -relaxed_command_check  has no

           This environment variable may 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 implic-
           itly  added  to the list if it has not been specified). The default
           behaviour 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 several instances  of  epmd,  repre-
           senting  independent  clusters  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. Consequently,
           if this option is set before starting the Erlang  virtual  machine,
           the automatically started epmd will accept the -kill and -stop com-
           mands without restrictions.

       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 entry


       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 regis-
       ter a nodename if the client is not a process located on the same  host
       as  the  epmd instance is running on- such requests are considered hos-
       tile 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

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

       To restrict access further, firewall software has to be used.

       See attributes(5) for descriptions of the following attributes:

       |Availability   | runtime/erlang   |
       |Stability      | Uncommitted      |
       This     software     was    built    from    source    available    at
       https://java.net/projects/solaris-userland.   The  original   community
       source     was     downloaded     from      http://www.erlang.org/down-

       Further information about this software can be found on the open source
       community website at http://www.erlang.org/.

Ericsson AB                        erts 6.4                            epmd(1)