From b35b4eeb6f0cb25c3c5b5e785939fb829f77ef6a Mon Sep 17 00:00:00 2001 From: Patrik Nyblom Date: Fri, 27 Aug 2010 11:08:32 +0200 Subject: Document epmd and it's options properly and fixup help text --- erts/doc/src/epmd.xml | 252 ++++++++++++++++++++++++++++++++++++++++++-------- 1 file changed, 211 insertions(+), 41 deletions(-) (limited to 'erts/doc/src') diff --git a/erts/doc/src/epmd.xml b/erts/doc/src/epmd.xml index 796ab3820b..f01cf90a36 100644 --- a/erts/doc/src/epmd.xml +++ b/erts/doc/src/epmd.xml @@ -4,7 +4,7 @@
- 19962009 + 19962010 Ericsson AB. All Rights Reserved. @@ -31,9 +31,23 @@ A epmd.xml
+ epmd - Erlang Port Mapper Daemon + +

Erlang Port Mapper Daemon

+ + + +

Starts the port mapper daemon

+ + + +

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 @@ -46,47 +60,170 @@ The job of the daemon is to keep track of which node name listens on which address. Hence, map symbolic node names to machine addresses.

-

The daemon is started automatically by the Erlang start-up script.

-

The program can also be used for a variety of other - purposes, for example checking the DNS (Domain Name System) - configuration of a host.

+ +

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 has to be used to alter the behavior of + the daemon. See the Environment + variables section below.

+ +

If the -daemon argument is not given, the + 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.

+ + + - - - epmd [-daemon] - Start a name server as a daemon - -

Starts a name server as a daemon. If it has no argument, the - runs as a normal program with the controlling terminal - of the shell in which it is started. Normally, it should run as a - daemon.

- - - - epmd -names - Request the names of the registered Erlang nodes on this host - -

Requests the names of the local Erlang nodes has - registered.

- - - - epmd -kill - Kill the process - -

Kills the process.

- - - - epmd -help - List options - -

Write short info about the usage including some debugging - options not listed here.

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

+ + + +

Let this instance of epmd listen to another TCP port than + default 4369. This can be also be set using the + environment variable, see the + section Environment + variables below

+ + + + +

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.

+ + + +

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.

+ + + +

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 for strange situation when two nodes of the same name can be alive at the same time. A node unregisters itself by just closing the connection to epmd, 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.

+ + + + +

Set the number of seconds a connection can be + inactive before epmd times out and closes the + connection (default 60).

+ + + +

To simulate a busy server you can insert a delay between epmd + gets notified about that a new connection is requested and + when the connections gets accepted.

+ + + +

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 ta 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 port on the host.

+ + + +

Contacts the epmd listening on the given TCP port number + (default 4369). This can be also be set using the + environment variable, see the + section Environment + variables below

+ + + +

List names registered with the currently running epmd

+ + + +

Kill the currently running epmd.

+ +

Killing the running epmd is only allowed if epmd + -names show 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.

+ + + +

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 @@ -99,6 +236,15 @@ 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 prior to start, the epmd daemon will behave + as if the -relaxed_command_check option was given at + start-up. If consequently setting this option before starting + the Erlang virtual machine, the automatically started + epmd will accept the -kill and -stop + commands without restrictions.

+
@@ -116,5 +262,29 @@ 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, + why 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.

+
+ -- cgit v1.2.3