Erlang networking kernel.
The net kernel is a system process, registered as
net_kernel
, which must be operational for distributed Erlang
to work. The purpose of this process is to implement parts of
the BIFs spawn/4
and spawn_link/4
, and to provide
monitoring of the network.
An Erlang node is started using command-line flag
-name
or -sname
:
$ erl -sname foobar
It is also possible to call net_kernel:start([foobar])
directly from the normal Erlang shell prompt:
1> net_kernel:start([foobar, shortnames]).
{ok,<0.64.0>}
(foobar@gringotts)2>
If the node is started with command-line flag -sname
,
the node name is foobar@Host
, where Host
is
the short name of the host (not the fully qualified domain name).
If started with flag -name
, the node name is foobar@Host
,
where Host
is the fully qualified domain name.
For more information, see
erl
.
Normally, connections are established automatically when
another node is referenced. This functionality can be disabled
by setting Kernel configuration parameter
dist_auto_connect
to never
, see
kernel(6)
. In this case,
connections must be established explicitly by calling
connect_node/1
.
Which nodes that are allowed to communicate with each other is handled by the magic cookie system, see section Distributed Erlang in the Erlang Reference Manual.
Warning!
Starting a distributed node without also specifying
-proto_dist inet_tls
will expose the node to attacks that may give the attacker
complete access to the node and in extension the cluster.
When using un-secure distributed nodes, make sure that the
network is configured to keep potential attackers out.
See the
Using SSL for Erlang Distribution User's Guide
for details on how to setup a secure distributed node.
Functions
allow(Nodes) -> ok | error
Nodes = [node()]
Permits access to the specified set of nodes.
Before the first call to allow/1
, any node with the correct
cookie can be connected. When allow/1
is called, a list
of allowed nodes is established. Any access attempts made from (or to)
nodes not in that list will be rejected.
Subsequent calls to allow/1
will add the specified nodes
to the list of allowed nodes. It is not possible to remove nodes
from the list.
Returns error
if any element in
is not
an atom.
connect_node(Node) -> boolean() | ignored
Node = node()
Establishes a connection to
. Returns
true
if a connection was established or was already
established or if
is the local node
itself. Returns false
if the connection attempt failed, and
ignored
if the local node is not alive.
get_net_ticktime() -> Res
Res = NetTicktime | {ongoing_change_to, NetTicktime} | ignored
NetTicktime = integer() >= 1
Gets net_ticktime
(see
kernel(6)
).
Defined return values (
):
NetTicktime
net_ticktime
is
seconds.
{ongoing_change_to, NetTicktime }
net_kernel
is currently changing
net_ticktime
to
seconds.
ignored
The local node is not alive.
getopts(Node, Options) ->
{ok, OptionValues} | {error, Reason} | ignored
Node = node()
Options = [inet:socket_getopt()]
OptionValues = [inet:socket_setopt()]
Reason = inet:posix() | noconnection
Get one or more options for the distribution socket
connected to
.
If
is a connected node
the return value is the same as from
inet:getopts(Sock, Options)
where Sock
is the distribution socket for
.
Returns ignored
if the local node is not alive or
{error, noconnection}
if
is not connected.
monitor_nodes(Flag) -> ok | Error
Flag = boolean()
Error = error | {error, term()}
monitor_nodes(Flag, Options) -> ok | Error
Flag = boolean()
Options = [Option]
Option = {node_type, NodeType} | nodedown_reason
NodeType = visible | hidden | all
Error = error | {error, term()}
The calling process subscribes or unsubscribes to node
status change messages. A nodeup
message is delivered
to all subscribing processes when a new node is connected, and
a nodedown
message is delivered when a node is
disconnected.
If
is true
, a new subscription is
started. If
is false
, all previous
subscriptions started with the same
are stopped. Two
option lists are considered the same if they contain the same
set of options.
As from Kernel version 2.11.4, and ERTS version 5.5.4, the following is guaranteed:
nodeup
messages are delivered before delivery of any message from the remote node passed through the newly established connection.nodedown
messages are not delivered until all messages from the remote node that have been passed through the connection have been delivered.
Notice that this is not guaranteed for Kernel versions before 2.11.4.
As from Kernel version 2.11.4, subscriptions can also be
made before the net_kernel
server is started, that is,
net_kernel:monitor_nodes/[1,2]
does not return
ignored
.
As from Kernel version 2.13, and ERTS version 5.7, the following is guaranteed:
nodeup
messages are delivered after the corresponding node appears in results fromerlang:nodes/X
.nodedown
messages are delivered after the corresponding node has disappeared in results fromerlang:nodes/X
.
Notice that this is not guaranteed for Kernel versions before 2.13.
The format of the node status change messages depends on
. If
is
[]
, which is the default, the format is as follows:
{nodeup, Node} | {nodedown, Node} Node = node()
If
is not []
, the format is
as follows:
{nodeup, Node, InfoList} | {nodedown, Node, InfoList} Node = node() InfoList = [{Tag, Val}]
InfoList
is a list of tuples. Its contents depends on
, see below.
Also, when OptionList == []
, only visible nodes, that
is, nodes that appear in the result of
erlang:nodes/0
,
are monitored.
can be any of the following:
{node_type, NodeType}
Valid values for NodeType
:
visible
Subscribe to node status change messages for visible
nodes only. The tuple {node_type, visible}
is
included in InfoList
.
hidden
Subscribe to node status change messages for hidden
nodes only. The tuple {node_type, hidden}
is
included in InfoList
.
all
Subscribe to node status change messages for both
visible and hidden nodes. The tuple
{node_type, visible | hidden}
is included in
InfoList
.
nodedown_reason
The tuple {nodedown_reason, Reason}
is included in
InfoList
in nodedown
messages.
Reason
can, depending on which
distribution module or process that is used be any term,
but for the standard TCP distribution module it is
any of the following:
connection_setup_failed
The connection setup failed (after nodeup
messages were sent).
no_network
No network is available.
net_kernel_terminated
The net_kernel
process terminated.
shutdown
Unspecified connection shutdown.
connection_closed
The connection was closed.
disconnect
The connection was disconnected (forced from the current node).
net_tick_timeout
Net tick time-out.
send_net_tick_failed
Failed to send net tick over the connection.
get_status_failed
Status information retrieval from the Port
holding the connection failed.
set_net_ticktime(NetTicktime) -> Res
NetTicktime = integer() >= 1
Res =
unchanged | change_initiated |
{ongoing_change_to, NewNetTicktime}NewNetTicktime = integer() >= 1
set_net_ticktime(NetTicktime, TransitionPeriod) -> Res
NetTicktime = integer() >= 1
TransitionPeriod = integer() >= 0
Res =
unchanged | change_initiated |
{ongoing_change_to, NewNetTicktime}NewNetTicktime = integer() >= 1
Sets net_ticktime
(see
kernel(6)
) to
seconds.
defaults to 60
.
Some definitions:
MTTI
)minimum(
milliseconds.
The time of the least number of consecutive MTTI
s
to cover
seconds following
the call to set_net_ticktime/2
(that is,
((
milliseconds).
If
NetTicktime < PreviousNetTicktime
,
the net_ticktime
change is done at the end of
the transition period; otherwise at the beginning. During
the transition period, net_kernel
ensures that
there is outgoing traffic on all connections at least
every MTTI
millisecond.
Note!
The net_ticktime
changes must be initiated on all
nodes in the network (with the same
)
before the end of any transition period on any node;
otherwise connections can erroneously be disconnected.
Returns one of the following:
unchanged
net_ticktime
already has the value of
and is left unchanged.
change_initiated
net_kernel
initiated the change of
net_ticktime
to
seconds.
{ongoing_change_to, NewNetTicktime }
The request is ignored because
net_kernel
is busy changing net_ticktime
to
seconds.
setopts(Node, Options) -> ok | {error, Reason} | ignored
Node = node() | new
Options = [inet:socket_setopt()]
Reason = inet:posix() | noconnection
Set one or more options for distribution sockets.
Argument
can be either one node name
or the atom new
to affect the distribution sockets of all
future connected nodes.
The return value is the same as from
inet:setopts/2
or {error, noconnection}
if
is not
a connected node or new
.
If
is new
the
will then also be added to kernel configration parameters
inet_dist_listen_options
and
inet_dist_connect_options.
Returns ignored
if the local node is not alive.
Name = atom()
NameType = shortnames | longnames
Reason = {already_started, pid()} | term()
Turns a non-distributed node into a distributed node by
starting net_kernel
and other necessary processes.
Notice that the argument is a list with exactly one, two, or
three arguments. NameType
defaults to longnames
and Ticktime
to 15000
.
stop() -> ok | {error, Reason}
Reason = not_allowed | not_found
Turns a distributed node into a non-distributed node. For
other nodes in the network, this is the same as the node
going down. Only possible when the net kernel was started using
start/1
,
otherwise {error, not_allowed}
is returned. Returns
{error, not_found}
if the local node is not alive.