epmd(1) User Commands epmd(1)NAMEepmd - 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
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 sec‐
tion 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 sec‐
tion 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 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.
-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 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
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 con‐
nection 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. sig‐
nals or some other OS specific method if it has active clients reg‐
istered.
-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 implic‐
itly 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, 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.
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 com‐
mands 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 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
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.
Ericsson AB erts 6.3 epmd(1)
