| net_kernel(3erl) | Erlang Module Definition | net_kernel(3erl) |
net_kernel - 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, #{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.
allow(Nodes) -> ok | error
Types:
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:
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:
Returns currently used net tick time in seconds. For more information see the net_ticktime kernel(7) parameter.
Defined return values (Res):
getopts(Node, Options) ->
{ok, OptionValues} | {error, Reason} | ignored
Types:
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.
get_state() ->
#{started => no | static | dynamic,
name => atom(),
name_type => static | dynamic,
name_domain => shortnames | longnames}
Get the current state of the distribution for the local node.
Returns a map with (at least) the following key-value pairs:
monitor_nodes(Flag) -> ok | Error
monitor_nodes(Flag, Options) -> ok | Error
Types:
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.
Delivery guarantees of nodeup/nodedown messages:
The format of the node status change messages depends on Options. If Options is the empty list or if net_kernel:monitor_nodes/1 is called, the format is as follows:
{nodeup, Node} | {nodedown, Node}
Node = node()
When Options is the empty map or empty list, the caller will only subscribe for status change messages for visible nodes. That is, only nodes that appear in the result of erlang:nodes/0.
If Options equals anything other than the empty list, the format of the status change messages is as follows:
{nodeup, Node, Info} | {nodedown, Node, Info}
Node = node()
Info = #{Tag => Val} | [{Tag, Val}]
Info is either a map or a list of 2-tuples. Its content depends on Options. If Options is a map, Info will also be a map. If Options is a list, Info will also be a list.
When Options is a map, currently the following associations are allowed:
If no node_type => NodeType association is included in the Options map, the caller will subscribe for status change messages for visible nodes only, but no node_type => visible association will be included in the Info map.
Reason can, depending on which distribution module or process that is used, be any term, but for the standard TCP distribution module it is one of the following:
When Options is a list, currently ListOption can be one of the following:
If no {node_type, NodeType} option has been given. The caller will subscribe for status change messages for visible nodes only, but no {node_type, visible} tuple will be included in the Info list.
See the documentation of the nodedown_reason => boolean() association above for information about possible Reason values.
Example:
(a@localhost)1> net_kernel:monitor_nodes(true, #{connection_id=>true, node_type=>all, nodedown_reason=>true}).
ok
(a@localhost)2> flush().
Shell got {nodeup,b@localhost,
#{connection_id => 3067552,node_type => visible}}
Shell got {nodeup,c@localhost,
#{connection_id => 13892107,node_type => hidden}}
Shell got {nodedown,b@localhost,
#{connection_id => 3067552,node_type => visible,
nodedown_reason => connection_closed}}
Shell got {nodedown,c@localhost,
#{connection_id => 13892107,node_type => hidden,
nodedown_reason => net_tick_timeout}}
Shell got {nodeup,b@localhost,
#{connection_id => 3067553,node_type => visible}}
ok
(a@localhost)3>
set_net_ticktime(NetTicktime) -> Res
set_net_ticktime(NetTicktime, TransitionPeriod) -> Res
Types:
Sets net_ticktime (see kernel(7)) to NetTicktime seconds. TransitionPeriod defaults to 60.
Some definitions:
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.
Returns one of the following:
setopts(Node, Options) -> ok | {error, Reason} | ignored
Types:
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 configuration 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:
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. Setting Name to undefined implies options dist_listen => false and hidden => true.
Currently supported options:
If undefined has been passed as Name, the dist_listen option will be overridden with dist_listen => false.
If undefined has been passed as Name, or the option dist_listen equals false, the hidden option will be overridden with hidden => true.
start(Options) -> {ok, pid()} | {error, Reason}
Types:
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):
stop() -> ok | {error, Reason}
Types:
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.
| kernel 8.5.3 | Ericsson AB |