epmd - Erlang Port Mapper Daemon
- epmd [-d|-debug] [DbgExtra...] [-address Addresses] [-port No]
- 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
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
symbolic node names to machine addresses.
The TCP/IP epmd
daemon only keeps track of the Name
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
- 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
options are described in section DbgExtra
- 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 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
- -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.
- 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.
- 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(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 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
Relaxed command checking can also be enabled by setting environment variable
before starting epmd
Use relaxed command checking only on systems with very limited interactive
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
- -delay_write Seconds:
- Also a simulation of a busy server. Inserts a delay before a reply is
These options make epmd
run as an interactive command, displaying the
results of sending queries to an already running instance of epmd
contacted is always on the local node, but option -port
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.
- Lists names registered with the currently running epmd.
- Kills the currently running epmd.
Killing the running epmd
is only allowed if epmd -names
empty database or if -relaxed_command_check
was specified when the
running instance of epmd
Notice that -relaxed_command_check
is specified when starting the daemon
that is to accept killing when it has live nodes registered. When running
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
- -stop Name:
- Forcibly unregisters a live node from the epmd database.
This command can only be used when contacting epmd
instances started with
Notice that relaxed command checking must enabled for the epmd
contacted. When running epmd
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
- 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
-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.
On some operating systems syslog
will be used for error reporting when
runs as a daemon. To enable the error logging, you must edit the
/etc/syslog.conf file and add an entry:
are at least one real tab character. Spaces are
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.