Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages


home | help
epmd(1)				 User Commands			       epmd(1)

       epmd - Erlang Port Mapper Daemon

	 epmd [-d|-debug] [DbgExtra...]	[-address Addresses] [-port No]	[-dae-
	 mon] [-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 en-
       vironment, 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 ad-
       dress where the Erlang node can be reached. Consistent and correct  TCP
       naming  services	 are therefore required	for an Erlang network to func-
       tion 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 auto-
	   matically 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.

       These options are available when	starting the  name  server.  The  name
       server  is normally started automatically by command erl(1) (if not al-
       ready 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 Envi-
	   ronment 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 use-
	   ful when the	epmd daemon is not started as a	daemon.

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

	   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 ac-
	     tive 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(3))  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  un-
	     registers itself by only closing the connection to	epmd, which is
	     why command stop was only intended	for use	 in  debugging	situa-

	     With  relaxed command checking enabled, you can forcibly unregis-
	     ter 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 in-
	   teractive usage.

       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 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 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 (de-
	   fault 4369).	This  can  also	 be  set  using	 environment  variable
	   ERL_EPMD_PORT; see section Environment Variables.

	   Lists names registered with the currently running epmd.

	   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 ef-
	   fect. A daemon that is started  without  relaxed  command  checking
	   must	 be  killed  using, for	example, signals or some other OS-spe-
	   cific 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 dae-
	   mon	contacted.  When  running  epmd	 interactively,	 -relaxed_com-
	   mand_check has no effect.

	   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.

	   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.

	   If  set  before  start,  the	 epmd daemon behaves as	if option -re-
	   laxed_command_check was specified at	startup. Consequently, if this
	   option is set before	starting the Erlang virtual machine, the auto-
	   matically started epmd accepts the -kill and	-stop commands without

       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:


       where  _TABs_  are at least one real tab	character. Spaces are silently

       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

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

       To restrict access further, firewall software must be used.

Ericsson AB			   erts	10.3			       epmd(1)


Want to link to this manual page? Use this URL:

home | help