1epmd(1)                          User Commands                         epmd(1)
2
3
4

NAME

6       epmd - Erlang Port Mapper Daemon
7

DESCRIPTION

9         epmd [-d|-debug] [DbgExtra...] [-address Addresses] [-port No] [-dae‐
10         mon] [-relaxed_command_check]:
11           Starts the port mapper daemon.
12
13         epmd [-d|-debug] [-port No] [-names|-kill|-stop Name]:
14           Communicates with a running port mapper daemon.
15
16       This daemon acts as a name server on all hosts involved in  distributed
17       Erlang  computations.  When  an Erlang node starts, the node has a name
18       and it obtains an address from the host OS kernel. The name and address
19       are  sent  to  the  epmd  daemon running on the local host. In a TCP/IP
20       environment, the address consists of the IP address and a port  number.
21       The  node name is an atom on the form of Name@Node. The job of the epmd
22       daemon is to keep track of which node name listens  on  which  address.
23       Hence, epmd maps symbolic node names to machine addresses.
24
25       The  TCP/IP epmd daemon only keeps track of the Name (first) part of an
26       Erlang node name. The Host part (whatever is after the @)  is  implicit
27       in  the  node  name  where  the epmd daemon was contacted, as is the IP
28       address where the Erlang node can be reached.  Consistent  and  correct
29       TCP  naming  services  are  therefore required for an Erlang network to
30       function correctly.
31
32         Starting the port mapper daemon:
33           The daemon is started automatically by command erl(1) if  the  node
34           is  to  be distributed and no running instance is present. If auto‐
35           matically launched environment variables must be used to change the
36           behavior of the daemon; see section Environment Variables.
37
38           If argument -daemon is not specified, epmd runs as a normal program
39           with the controlling terminal of the shell in which it is  started.
40           Normally, it is to be run as a daemon.
41
42           Regular startup options are described in section Regular Options.
43
44           The DbgExtra options are described in section DbgExtra Options.
45
46         Communicating with a running port mapper daemon:
47           Communicating  with  the running epmd daemon by the epmd program is
48           done primarily for debugging purposes.
49
50           The different queries are described in section Interactive options.
51

REGULAR OPTIONS

53       These options are available when starting the  name  server.  The  name
54       server  is  normally  started  automatically  by command erl(1) (if not
55       already available), but it can also be started at system startup.
56
57         -address List:
58           Lets this instance of epmd listen only on the comma-separated  list
59           of  IP  addresses  and on the loopback address (which is implicitly
60           added to the list if it has not been specified). This can  also  be
61           set  using environment variable ERL_EPMD_ADDRESS; see section Envi‐
62           ronment Variables.
63
64         -port No:
65           Lets this instance of epmd listen to another TCP port than  default
66           4369.   This   can   also   be   set   using  environment  variable
67           ERL_EPMD_PORT; see section Environment Variables.
68
69         -d | -debug:
70           Enables debug output. The more -d flags specified, the  more  debug
71           output  you will get (to a certain limit). This option is most use‐
72           ful when the epmd daemon is not started as a daemon.
73
74         -daemon:
75           Starts epmd detached from the controlling terminal. Logging ends up
76           in syslog when available and correctly configured. If the epmd dae‐
77           mon is started at boot, this option is definitely to be used. It is
78           also used when command erl automatically starts epmd.
79
80         -relaxed_command_check:
81           Starts  the  epmd program with relaxed command checking (mostly for
82           backward compatibility). This affects the following:
83
84           * With relaxed command checking, the epmd daemon can be killed from
85             the  local  host  with,  for  example, command epmd -kill even if
86             active nodes are registered. Normally only daemons with an  empty
87             node database can be killed with epmd -kill.
88
89           * Command  epmd  -stop  (and the corresponding messages to epmd, as
90             can be specified using erl_interface:ei(3))  is  normally  always
91             ignored.  This because it can cause a strange situation where two
92             nodes of the same name can be alive at  the  same  time.  A  node
93             unregisters  itself by only closing the connection to epmd, which
94             is why command stop was only intended for use in debugging situa‐
95             tions.
96
97             With  relaxed command checking enabled, you can forcibly unregis‐
98             ter live nodes.
99
100           Relaxed command checking can also be enabled by setting environment
101           variable ERL_EPMD_RELAXED_COMMAND_CHECK before starting epmd.
102
103           Use  relaxed  command  checking  only  on systems with very limited
104           interactive usage.
105

DBGEXTRA OPTIONS

107   Note:
108       These options are only for debugging and testing epmd clients. They are
109       not to be used in normal operation.
110
111
112         -packet_timeout Seconds:
113           Sets the number of seconds a connection can be inactive before epmd
114           times out and closes the connection. Defaults to 60.
115
116         -delay_accept Seconds:
117           To simulate a busy server, you can insert a delay between when epmd
118           gets  notified that a new connection is requested and when the con‐
119           nection gets accepted.
120
121         -delay_write Seconds:
122           Also a simulation of a busy server. Inserts a delay before a  reply
123           is sent.
124

INTERACTIVE OPTIONS

126       These  options  make epmd run as an interactive command, displaying the
127       results of sending queries to an already running instance of epmd.  The
128       epmd  contacted  is  always  on the local node, but option -port can be
129       used to select between instances if several are running using different
130       ports on the host.
131
132         -port No:
133           Contacts  the  epmd  listening  on  the  specified  TCP port number
134           (default 4369). This can also be  set  using  environment  variable
135           ERL_EPMD_PORT; see section Environment Variables.
136
137         -names:
138           Lists names registered with the currently running epmd.
139
140         -kill:
141           Kills the currently running epmd.
142
143           Killing  the  running  epmd is only allowed if epmd -names shows an
144           empty database or if -relaxed_command_check was specified when  the
145           running instance of epmd was started.
146
147           Notice  that  -relaxed_command_check is specified when starting the
148           daemon that is to accept killing when it has live nodes registered.
149           When  running  epmd  interactively,  -relaxed_command_check  has no
150           effect. A daemon that is started without relaxed  command  checking
151           must  be  killed  using, for example, signals or some other OS-spe‐
152           cific method if it has active clients registered.
153
154         -stop Name:
155           Forcibly unregisters a live node from the epmd database.
156
157           This command can  only  be  used  when  contacting  epmd  instances
158           started with flag -relaxed_command_check.
159
160           Notice that relaxed command checking must enabled for the epmd dae‐
161           mon  contacted.  When  running  epmd  interactively,  -relaxed_com‐
162           mand_check has no effect.
163

ENVIRONMENT VARIABLES

165         ERL_EPMD_ADDRESS:
166           Can be set to a comma-separated list of IP addresses, in which case
167           the epmd daemon will listen only on the specified  address(es)  and
168           on  the  loopback address (which is implicitly added to the list if
169           it has not been specified). The default behavior is  to  listen  on
170           all available IP addresses.
171
172         ERL_EPMD_PORT:
173           Can  contain  the  port number epmd will use. The default port will
174           work fine in most cases. A different port can be specified to allow
175           several  instances  of  epmd,  representing independent clusters of
176           nodes, to co-exist on the same host. All nodes in  a  cluster  must
177           use the same epmd port number.
178
179         ERL_EPMD_RELAXED_COMMAND_CHECK:
180           If  set  before  start,  the  epmd  daemon  behaves  as  if  option
181           -relaxed_command_check was specified at startup.  Consequently,  if
182           this  option is set before starting the Erlang virtual machine, the
183           automatically started epmd accepts the  -kill  and  -stop  commands
184           without restrictions.
185

LOGGING

187       On  some operating systems syslog will be used for error reporting when
188       epmd runs as a daemon. To enable the error logging, you must  edit  the
189       /etc/syslog.conf file and add an entry:
190
191         !epmd
192         *.*<TABs>/var/log/epmd.log
193
194
195       where  <TABs>  are at least one real tab character. Spaces are silently
196       ignored.
197

ACCESS RESTRICTIONS

199       The epmd daemon accepts messages from both the local  host  and  remote
200       hosts.  However,  only the query commands are answered (and acted upon)
201       if the query comes from a remote host. It is always an error to try  to
202       register a node name if the client is not a process on the same host as
203       the epmd instance is running on. Such requests are  considered  hostile
204       and the connection is closed immediately.
205
206       The following queries are accepted from remote nodes:
207
208         * Port queries, that is, on which port the node with a specified name
209           listens
210
211         * Name listing, that is, gives a list of all names registered on  the
212           host
213
214       To restrict access further, firewall software must be used.
215
216
217
218Ericsson AB                       erts 10.5.6                          epmd(1)
Impressum