xenial (1) epmd.1.gz

Provided by: erlang-base-hipe_18.3-dfsg-1ubuntu3.1_amd64 bug

NAME

       epmd  - Erlang Port Mapper Daemonepmd [-d|-debug] [DbgExtra...] [-address Addresses] [-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

DESCRIPTION

       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 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  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 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 purposes.

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

REGULAR OPTIONS

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

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

         -relaxed_command_check:
           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
             debugging situations.

             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.

DBGEXTRA OPTIONS

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

         -names:
           List names registered with the currently running epmd

         -kill:
           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. 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 interactively, -relaxed_command_check has no effect.

ENVIRONMENT VARIABLES

         ERL_EPMD_ADDRESS:
           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
           implicitly added to the list if it has not been specified). The default behaviour is to listen on all
           available IP addresses.

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

         ERL_EPMD_RELAXED_COMMAND_CHECK:
           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 commands without restrictions.

LOGGING

       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

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

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

ACCESS RESTRICTIONS

       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- 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 used.