.TH net_kernel 3 "kernel  2.12.3" "Ericsson AB" "ERLANG MODULE DEFINITION"
.SH MODULE
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:

.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 kernel(6)\&. 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 Distributed Erlang in the Erlang Reference Manual\&.

.SH EXPORTS
.LP
.B
allow(Nodes) -> ok | error
.br
.RS
.TP
Types
Nodes = [node()]
.br
.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
.B
connect_node(Node) -> true | false | ignored
.br
.RS
.TP
Types
Node = node()
.br
.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
.B
monitor_nodes(Flag) -> ok | Error
.br
.B
monitor_nodes(Flag, Options) -> ok | Error
.br
.RS
.TP
Types
Flag = true | false
.br
Options = [Option]
.br
Option -- see below
.br
Error = error | {error, term()}
.br
.RE
.RS
.LP
The calling process subscribes or unsubcscribes 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\&.
.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\&.
.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 subscribtions 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
The format of the node status change messages depends on \fIOptions\fR\&. If \fIOptions\fR is [], which is the default, the format is:

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

.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 nodes/0, are monitored\&.
.LP
\fIOption\fR can be any of the following:
.RS 2
.TP 4
.B
\fI{node_type, NodeType}\fR:
Currently valid values for \fINodeType\fR are:
.RS 4
.LP

.RS 2
.TP 4
.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 4
.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 4
.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
.RE
.TP 4
.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 4
.LP

.RS 2
.TP 4
.B
\fIconnection_setup_failed\fR:
The connection setup failed (after \fInodeup\fR messages had been sent)\&.
.TP 4
.B
\fIno_network\fR:
No network available\&.
.TP 4
.B
\fInet_kernel_terminated\fR:
The \fInet_kernel\fR process terminated\&.
.TP 4
.B
\fIshutdown\fR:
Unspecified connection shutdown\&.
.TP 4
.B
\fIconnection_closed\fR:
The connection was closed\&.
.TP 4
.B
\fIdisconnect\fR:
The connection was disconnected (forced from the current node)\&.
.TP 4
.B
\fInet_tick_timeout\fR:
Net tick timeout\&.
.TP 4
.B
\fIsend_net_tick_failed\fR:
Failed to send net tick over the connection\&.
.TP 4
.B
\fIget_status_failed\fR:
Status information retrieval from the \fIPort\fR holding the connection failed\&.
.RE
.RE
.RE
.RE
.LP
.B
get_net_ticktime() -> Res
.br
.RS
.TP
Types
Res = NetTicktime | {ongoing_change_to, NetTicktime}
.br
NetTicktime = int()
.br
.RE
.RS
.LP
Gets \fInet_ticktime\fR (see kernel(6))\&.
.LP
Currently defined return values (\fIRes\fR):
.RS 2
.TP 4
.B
\fINetTicktime\fR:
\fInet_ticktime\fR is \fINetTicktime\fR seconds\&.
.TP 4
.B
\fI{ongoing_change_to, NetTicktime}\fR:
\fInet_kernel\fR is currently changing \fInet_ticktime\fR to \fINetTicktime\fR seconds\&.
.RE
.RE
.LP
.B
set_net_ticktime(NetTicktime) -> Res
.br
.B
set_net_ticktime(NetTicktime, TransitionPeriod) -> Res
.br
.RS
.TP
Types
NetTicktime = int() > 0
.br
TransitionPeriod = int() >= 0
.br
Res = unchanged | change_initiated | {ongoing_change_to, NewNetTicktime}
.br
NewNetTicktime = int() > 0
.br
.RE
.RS
.LP
Sets \fInet_ticktime\fR (see kernel(6)) to \fINetTicktime\fR seconds\&. \fITransitionPeriod\fR defaults to 60\&.
.LP
Some definitions:
.LP

.RS 2
.TP 4
.B
The minimum transition traffic interval (\fIMTTI\fR):
\fIminimum(NetTicktime, PreviousNetTicktime)*1000 div 4\fR milliseconds\&.
.TP 4
.B
The transition period:
The time of the least number of consecutive \fIMTTI\fRs 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 \fINetTicktime < 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\&.
.SS Note:
.LP
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 4
.B
\fIunchanged\fR:
\fInet_ticktime\fR already had the value of \fINetTicktime\fR and was left unchanged\&.
.TP 4
.B
\fIchange_initiated\fR:
\fInet_kernel\fR has initiated the change of \fInet_ticktime\fR to \fINetTicktime\fR seconds\&.
.TP 4
.B
\fI{ongoing_change_to, NewNetTicktime}\fR:
The request was \fIignored\fR; because, \fInet_kernel\fR was busy changing \fInet_ticktime\fR to \fINewTicktime\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
.TP
Types
Name = atom()
.br
NameType = shortnames | longnames
.br
Reason = {already_started, pid()} | term()
.br
.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
.B
stop() -> ok | {error, not_allowed | not_found}
.br
.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