Provided by: erlang-manpages_24.3.4.1+dfsg-1_all 
NAME
net_kernel - Erlang networking kernel.
DESCRIPTION
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, #{name_domain => 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(7). 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.
EXPORTS
allow(Nodes) -> ok | error
Types:
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 Nodes is not an atom.
connect_node(Node) -> boolean() | ignored
Types:
Node = node()
Establishes a connection to Node. Returns true if a connection was established or
was already established or if Node 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
Types:
Res = NetTicktime | {ongoing_change_to, NetTicktime} | ignored
NetTicktime = integer() >= 1
Returns currently used net tick time in seconds. For more information see the
net_ticktime kernel(7) parameter.
Defined return values (Res):
NetTicktime:
net_ticktime is NetTicktime seconds.
{ongoing_change_to, NetTicktime}:
net_kernel is currently changing net_ticktime to NetTicktime seconds.
ignored:
The local node is not alive.
getopts(Node, Options) ->
{ok, OptionValues} | {error, Reason} | ignored
Types:
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 Node.
If Node is a connected node the return value is the same as from inet:getopts(Sock,
Options) where Sock is the distribution socket for Node.
Returns ignored if the local node is not alive or {error, noconnection} if Node is
not connected.
monitor_nodes(Flag) -> ok | Error
monitor_nodes(Flag, Options) -> ok | Error
Types:
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 Flag is true, a new subscription is started. If Flag is false, all previous
subscriptions started with the same Options 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
from erlang:nodes/X.
* nodedown messages are delivered after the corresponding node has disappeared in
results from erlang:nodes/X.
Notice that this is not guaranteed for Kernel versions before 2.13.
The format of the node status change messages depends on Options. If Options is [],
which is the default, the format is as follows:
{nodeup, Node} | {nodedown, Node}
Node = node()
If Options 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 Options, see below.
Also, when OptionList == [], only visible nodes, that is, nodes that appear in the
result of erlang:nodes/0, are monitored.
Option 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
set_net_ticktime(NetTicktime, TransitionPeriod) -> Res
Types:
NetTicktime = integer() >= 1
TransitionPeriod = integer() >= 0
Res =
unchanged | change_initiated |
{ongoing_change_to, NewNetTicktime}
NewNetTicktime = integer() >= 1
Sets net_ticktime (see kernel(7)) to NetTicktime seconds. TransitionPeriod defaults
to 60.
Some definitions:
Minimum transition traffic interval (MTTI):
minimum(NetTicktime, PreviousNetTicktime)*1000 div 4 milliseconds.
Transition period:
The time of the least number of consecutive MTTIs to cover TransitionPeriod
seconds following the call to set_net_ticktime/2 (that is,
((TransitionPeriod*1000 - 1) div MTTI + 1)*MTTI 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 NetTicktime) 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 NetTicktime and is left unchanged.
change_initiated:
net_kernel initiated the change of net_ticktime to NetTicktime seconds.
{ongoing_change_to, NewNetTicktime}:
The request is ignored because net_kernel is busy changing net_ticktime to
NewNetTicktime seconds.
setopts(Node, Options) -> ok | {error, Reason} | ignored
Types:
Node = node() | new
Options = [inet:socket_setopt()]
Reason = inet:posix() | noconnection
Set one or more options for distribution sockets. Argument Node 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
Node is not a connected node or new.
If Node is new the Options 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.
start(Name, Options) -> {ok, pid()} | {error, Reason}
Types:
Options =
#{name_domain => NameDomain,
net_ticktime => NetTickTime,
net_tickintensity => NetTickIntensity}
Name = atom()
NameDomain = shortnames | longnames
NetTickTime = integer() >= 1
NetTickIntensity = 4..1000
Reason = {already_started, pid()} | term()
Turns a non-distributed node into a distributed node by starting net_kernel and
other necessary processes.
If Name is set to undefined the distribution will be started to request a dynamic
node name from the first node it connects to. See Dynamic Node Name.
Currently supported options:
name_domain => NameDomain:
Determines the host name part of the node name. If NameDomain equals longnames,
fully qualified domain names will be used which also is the default. If
NameDomain equals shortnames, only the short name of the host will be used.
net_ticktime => NetTickTime:
Net tick time to use in seconds. Defaults to the value of the net_ticktime
kernel(7) parameter. For more information about net tick time , see the kernel
parameter. However, note that if the value of the kernel parameter is invalid,
it will silently be replaced by a valid value, but if an invalid NetTickTime
value is passed as option value to this function, the call will fail.
net_tickintensity => NetTickIntensity:
Net tick intensity to use. Defaults to the value of the net_tickintensity
kernel(7) parameter. For more information about net tick intensity , see the
kernel parameter. However, note that if the value of the kernel parameter is
invalid, it will silently be replaced by a valid value, but if an invalid
NetTickIntensity value is passed as option value to this function, the call
will fail.
start(Options) -> {ok, pid()} | {error, Reason}
Types:
Options = [Name | NameDomain | TickTime, ...]
Name = atom()
NameDomain = shortnames | longnames
TickTime = integer() >= 1
Reason = {already_started, pid()} | term()
Warning:
start/1 is deprecated. Use start/2 instead.
Turns a non-distributed node into a distributed node by starting net_kernel and
other necessary processes.
Options list can only be exactly one of the following lists (order is imporant):
[Name]:
The same as net_kernel:start([Name, longnames, 15000]).
[Name, NameDomain]:
The same as net_kernel:start([Name, NameDomain, 15000]).
[Name, NameDomain, TickTime]:
The same as net_kernel:start(Name, #{name_domain => NameDomain, net_ticktime =>
((TickTime*4-1) div 1000) + 1, net_tickintensity => 4}). Note that TickTime is
not the same as net tick time expressed in milliseconds. TickTime is the time
between ticks when net tick intensity equals 4.
stop() -> ok | {error, Reason}
Types:
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/2, otherwise {error, not_allowed} is returned. Returns
{error, not_found} if the local node is not alive.