.TH net_kernel 3erl "kernel 3.0.3" "Ericsson AB" "Erlang Module Definition"
.SH NAME
net_kernel \- Erlang Networking Kernel
.SH DESCRIPTION
.LP
The net kernel is a system process, registered as \fInet_kernel\fR\&, which must be running for distributed Erlang to work\&. The purpose of this process is to implement parts of the BIFs \fIspawn/4\fR\& and \fIspawn_link/4\fR\&, and to provide monitoring of the network\&.
.LP
An Erlang node is started using the command line flag \fI-name\fR\& or \fI-sname\fR\&:
.LP
.nf
$ erl -sname foobar
.fi
.LP
It is also possible to call \fInet_kernel:start([foobar])\fR\& directly from the normal Erlang shell prompt:
.LP
.nf
1> net_kernel:start([foobar, shortnames])\&.
{ok,<0.64.0>}
(foobar@gringotts)2>
.fi
.LP
If the node is started with the command line flag \fI-sname\fR\&, the node name will be \fIfoobar@Host\fR\&, where \fIHost\fR\& is the short name of the host (not the fully qualified domain name)\&. If started with the \fI-name\fR\& flag, \fIHost\fR\& is the fully qualified domain name\&. See \fIerl(1)\fR\&\&.
.LP
Normally, connections are established automatically when another node is referenced\&. This functionality can be disabled by setting the Kernel configuration parameter \fIdist_auto_connect\fR\& to \fIfalse\fR\&, see \fBkernel(7)\fR\&\&. In this case, connections must be established explicitly by calling \fInet_kernel:connect_node/1\fR\&\&.
.LP
Which nodes are allowed to communicate with each other is handled by the magic cookie system, see \fBDistributed Erlang\fR\& in the Erlang Reference Manual\&.
.SH EXPORTS
.LP
.nf

.B
allow(Nodes) -> ok | error
.br
.fi
.br
.RS
.LP
Types:

.RS 3
Nodes = [node()]
.br
.RE
.RE
.RS
.LP
Limits access to the specified set of nodes\&. Any access attempts made from (or to) nodes not in \fINodes\fR\& will be rejected\&.
.LP
Returns \fIerror\fR\& if any element in \fINodes\fR\& is not an atom\&.
.RE

.LP
.nf

.B
connect_node(Node) -> boolean() | ignored
.br
.fi
.br
.RS
.LP
Types:

.RS 3
Node = node()
.br
.RE
.RE
.RS
.LP
Establishes a connection to \fINode\fR\&\&. Returns \fItrue\fR\& if successful, \fIfalse\fR\& if not, and \fIignored\fR\& if the local node is not alive\&.
.RE

.LP
.nf

.B
monitor_nodes(Flag) -> ok | Error
.br
.fi
.br
.nf

.B
monitor_nodes(Flag, Options) -> ok | Error
.br
.fi
.br
.RS
.LP
Types:

.RS 3
Flag = boolean()
.br
Options = [Option]
.br
Option = {node_type, NodeType} | nodedown_reason
.br
NodeType = visible | hidden | all
.br
Error = error | {error, term()}
.br
.RE
.RE
.RS
.LP
The calling process subscribes or unsubscribes to node status change messages\&. A \fInodeup\fR\& message is delivered to all subscribing process when a new node is connected, and a \fInodedown\fR\& message is delivered when a node is disconnected\&.
.LP
If \fIFlag\fR\& is \fItrue\fR\&, a new subscription is started\&. If \fIFlag\fR\& is \fIfalse\fR\&, all previous subscriptions -- started with the same \fIOptions\fR\& -- are stopped\&. Two option lists are considered the same if they contain the same set of options\&.
.LP
As of \fIkernel\fR\& version 2\&.11\&.4, and \fIerts\fR\& version 5\&.5\&.4, the following is guaranteed:
.RS 2
.TP 2
*
\fInodeup\fR\& messages will be delivered before delivery of any message from the remote node passed through the newly established connection\&.
.LP
.TP 2
*
\fInodedown\fR\& messages will not be delivered until all messages from the remote node that have been passed through the connection have been delivered\&.
.LP
.RE

.LP
Note, that this is \fInot\fR\& guaranteed for \fIkernel\fR\& versions before 2\&.11\&.4\&.
.LP
As of \fIkernel\fR\& version 2\&.11\&.4 subscriptions can also be made before the \fInet_kernel\fR\& server has been started, i\&.e\&., \fInet_kernel:monitor_nodes/[1,2]\fR\& does not return \fIignored\fR\&\&.
.LP
As of \fIkernel\fR\& version 2\&.13, and \fIerts\fR\& version 5\&.7, the following is guaranteed:
.RS 2
.TP 2
*
\fInodeup\fR\& messages will be delivered after the corresponding node appears in results from \fIerlang:nodes/X\fR\&\&.
.LP
.TP 2
*
\fInodedown\fR\& messages will be delivered after the corresponding node has disappeared in results from \fIerlang:nodes/X\fR\&\&.
.LP
.RE

.LP
Note, that this is \fInot\fR\& guaranteed for \fIkernel\fR\& versions before 2\&.13\&.
.LP
The format of the node status change messages depends on \fIOptions\fR\&\&. If \fIOptions\fR\& is [], which is the default, the format is:
.LP
.nf

{nodeup, Node} | {nodedown, Node}
  Node = node()
.fi
.LP
If \fIOptions /= []\fR\&, the format is:
.LP
.nf

{nodeup, Node, InfoList} | {nodedown, Node, InfoList}
  Node = node()
  InfoList = [{Tag, Val}]
.fi
.LP
\fIInfoList\fR\& is a list of tuples\&. Its contents depends on \fIOptions\fR\&, see below\&.
.LP
Also, when \fIOptionList == []\fR\& only visible nodes, that is, nodes that appear in the result of \fBnodes/0\fR\&, are monitored\&.
.LP
\fIOption\fR\& can be any of the following:
.RS 2
.TP 2
.B
\fI{node_type, NodeType}\fR\&:
Currently valid values for \fINodeType\fR\& are:
.RS 2
.TP 2
.B
\fIvisible\fR\&:
Subscribe to node status change messages for visible nodes only\&. The tuple \fI{node_type, visible}\fR\& is included in \fIInfoList\fR\&\&.
.TP 2
.B
\fIhidden\fR\&:
Subscribe to node status change messages for hidden nodes only\&. The tuple \fI{node_type, hidden}\fR\& is included in \fIInfoList\fR\&\&.
.TP 2
.B
\fIall\fR\&:
Subscribe to node status change messages for both visible and hidden nodes\&. The tuple \fI{node_type, visible | hidden}\fR\& is included in \fIInfoList\fR\&\&.
.RE
.TP 2
.B
\fInodedown_reason\fR\&:
The tuple \fI{nodedown_reason, Reason}\fR\& is included in \fIInfoList\fR\& in \fInodedown\fR\& messages\&. \fIReason\fR\& can be:
.RS 2
.TP 2
.B
\fIconnection_setup_failed\fR\&:
The connection setup failed (after \fInodeup\fR\& messages had been sent)\&.
.TP 2
.B
\fIno_network\fR\&:
No network available\&.
.TP 2
.B
\fInet_kernel_terminated\fR\&:
The \fInet_kernel\fR\& process terminated\&.
.TP 2
.B
\fIshutdown\fR\&:
Unspecified connection shutdown\&.
.TP 2
.B
\fIconnection_closed\fR\&:
The connection was closed\&.
.TP 2
.B
\fIdisconnect\fR\&:
The connection was disconnected (forced from the current node)\&.
.TP 2
.B
\fInet_tick_timeout\fR\&:
Net tick timeout\&.
.TP 2
.B
\fIsend_net_tick_failed\fR\&:
Failed to send net tick over the connection\&.
.TP 2
.B
\fIget_status_failed\fR\&:
Status information retrieval from the \fIPort\fR\& holding the connection failed\&.
.RE
.RE
.RE

.LP
.nf

.B
get_net_ticktime() -> Res
.br
.fi
.br
.RS
.LP
Types:

.RS 3
Res = NetTicktime | {ongoing_change_to, NetTicktime} | ignored
.br
NetTicktime = integer() >= 1
.br
.RE
.RE
.RS
.LP
Gets \fInet_ticktime\fR\& (see \fBkernel(7)\fR\&)\&.
.LP
Currently defined return values (\fIRes\fR\&):
.RS 2
.TP 2
.B
\fINetTicktime\fR\&:
\fInet_ticktime\fR\& is \fINetTicktime\fR\& seconds\&.
.TP 2
.B
\fI{ongoing_change_to, NetTicktime}\fR\&:
\fInet_kernel\fR\& is currently changing \fInet_ticktime\fR\& to \fINetTicktime\fR\& seconds\&.
.TP 2
.B
\fIignored\fR\&:
The local node is not alive\&.
.RE
.RE

.LP
.nf

.B
set_net_ticktime(NetTicktime) -> Res
.br
.fi
.br
.nf

.B
set_net_ticktime(NetTicktime, TransitionPeriod) -> Res
.br
.fi
.br
.RS
.LP
Types:

.RS 3
NetTicktime = integer() >= 1
.br
TransitionPeriod = integer() >= 0
.br
Res = unchanged
.br
    | change_initiated
.br
    | {ongoing_change_to, NewNetTicktime}
.br
NewNetTicktime = integer() >= 1
.br
.RE
.RE
.RS
.LP
Sets \fInet_ticktime\fR\& (see \fBkernel(7)\fR\&) to \fINetTicktime\fR\& seconds\&. \fITransitionPeriod\fR\& defaults to 60\&.
.LP
Some definitions:
.RS 2
.TP 2
.B
The minimum transition traffic interval (\fIMTTI\fR\&):
\fIminimum(NetTicktime, PreviousNetTicktime)*1000 div 4\fR\& milliseconds\&.
.TP 2
.B
The transition period:
The time of the least number of consecutive \fIMTTI\fR\&s to cover \fITransitionPeriod\fR\& seconds following the call to \fIset_net_ticktime/2\fR\& (i\&.e\&. ((\fITransitionPeriod*1000 - 1) div MTTI + 1)*MTTI\fR\& milliseconds)\&.
.RE
.LP
If \fI<anno>NetTicktime</anno> < PreviousNetTicktime\fR\&, the actual \fInet_ticktime\fR\& change will be done at the end of the transition period; otherwise, at the beginning\&. During the transition period, \fInet_kernel\fR\& will ensure that there will be outgoing traffic on all connections at least every \fIMTTI\fR\& millisecond\&.
.LP

.RS -4
.B
Note:
.RE
The \fInet_ticktime\fR\& changes have to be initiated on all nodes in the network (with the same \fINetTicktime\fR\&) before the end of any transition period on any node; otherwise, connections may erroneously be disconnected\&.

.LP
Returns one of the following:
.RS 2
.TP 2
.B
\fIunchanged\fR\&:
\fInet_ticktime\fR\& already had the value of \fINetTicktime\fR\& and was left unchanged\&.
.TP 2
.B
\fIchange_initiated\fR\&:
\fInet_kernel\fR\& has initiated the change of \fInet_ticktime\fR\& to \fINetTicktime\fR\& seconds\&.
.TP 2
.B
\fI{ongoing_change_to, NewNetTicktime}\fR\&:
The request was \fIignored\fR\&; because, \fInet_kernel\fR\& was busy changing \fInet_ticktime\fR\& to \fINewNetTicktime\fR\& seconds\&.
.RE
.RE

.LP
.B
start([Name]) -> {ok, pid()} | {error, Reason}
.br
.B
start([Name, NameType]) -> {ok, pid()} | {error, Reason}
.br
.B
start([Name, NameType, Ticktime]) -> {ok, pid()} | {error, Reason}
.br
.RS
.LP
Types:

.RS 3
Name = atom()
.br
NameType = shortnames | longnames
.br
Reason = {already_started, pid()} | term()
.br
.RE
.RE
.RS
.LP
Note that the argument is a list with exactly one, two or three arguments\&. \fINameType\fR\& defaults to \fIlongnames\fR\& and \fITicktime\fR\& to 15000\&.
.LP
Turns a non-distributed node into a distributed node by starting \fInet_kernel\fR\& and other necessary processes\&.
.RE

.LP
.nf

.B
stop() -> ok | {error, Reason}
.br
.fi
.br
.RS
.LP
Types:

.RS 3
Reason = not_allowed | not_found
.br
.RE
.RE
.RS
.LP
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 \fIstart/1\fR\&, otherwise returns \fI{error, not_allowed}\fR\&\&. Returns \fI{error, not_found}\fR\& if the local node is not alive\&.
.RE