# net_kernel

### MODULE

net_kernel

### MODULE SUMMARY

Erlang Networking Kernel

### DESCRIPTION

The net kernel is a system process which must be running 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 authentication and monitoring of the network.

An Erlang runtime system can be started from the UNIX command line as follows:

          % erl -name foobar

With this command line, the `net_kernel` is started as `net_kernel:start([foobar])`. See erl(1).

This is done by the system itself, but the `start([Name])` function can also be called directly from the normal Erlang shell prompt, and a normal Erlang runtime system is then converted to a node. The kernel can be shut down with the function `stop()`, but only if the kernel was not started by the system itself. The node is then converted into a normal Erlang runtime system. All other nodes on the network will regard this as a total node crash.

If the system is started as `% erl -sname foobar`, the node name of the node will be `foobar@Host`, where `Host` is the short name of the host (not the fully qualified domain name). The `-name` flag gives a node with the fully qualified domain name. See erl(1).

The system can be started with the flag `-dist_auto_connect` to control automatic connection of remote nodes. See `connect_node/1` below and erl(1).

### EXPORTS

`monitor_nodes(Flag, OptionList) -> ok | ignored | Error`

Types:

`Flag = true | false`
`OptionList = [Option]`
`Option = atom() | {atom(), term()}`
`Error = error | {error, term()}`

The process evaluating `monitor_nodes/2` subscribes or unsubscribes for `nodeup`/`nodedown` messages. `nodeup` messages are delivered to all processes that have subscribed for `nodeup`/`nodedown` messages when a new node is connected, and `nodedown` messages are delivered when a node is disconnected.

If `Flag` is `true`, a new subscription is made. If `Flag` is `false`, all previous subscriptions with the same `OptionList` are unsubscribed. Two option lists are considered the same if lists:usort/1 on the two lists evaluates to terms that are equal.

If `OptionList == []` when subscribing, `{nodeup, Node}`, and `{nodedown, Node}` messages will be delivered; otherwise, `{nodeup, Node, InfoList}`, and `{nodedown, Node, InfoList}` messages will be delivered. Where:

- `Node = atom() (the nodename)`
- `InfoList = [{atom(), term()}]`

Also, when `OptionList == []` only visible nodes, i.e. nodes that appear in the result of nodes/0 and the current node, are monitored.

Currently the following `Option`s are valid:

`{node_type, NodeType}`
  Currently valid `NodeType`s are:
  `visible`
    `nodeup` and `nodedown` messages will be delivered when visible nodes connect/disconnect. A `{node_type, visible}` tuple will be part of the `InfoList` element.
  `hidden`
    `nodeup` and `nodedown` messages will be delivered when hidden nodes connect/disconnect. A `{node_type, hidden}` tuple will be part of the `InfoList` element.
  `all`
    `nodeup` and `nodedown` messages will be delivered when a node connect/disconnect. A `{node_type, visible}` tuple will be part of the `InfoList` element when the node is visible, and a `{node_type, hidden}` tuple will be part of the `InfoList` element when the node is hidden.
`nodedown_reason`
  A `{nodedown_reason, Reason}` tuple will be part of the `InfoList` element in `nodedown` messages. `Reason` can currently be:
  `connection_setup_failed`
    The connection setup failed (after `nodeup` messages had been sent).
  `no_network`
    No network 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`
    No traffic from the connected node during net_ticktime seconds.
  `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.

`monitor_nodes(Flag) -> ok | ignored | Error`

Types:

`Flag = atom()`
`Error = error | {error, term()}`

The same as evaluating `net_kernel:monitor_nodes(Flag, [])`.

`allow(NodeList)`

In a simple way, this function limits access to a node from a specific number of named nodes. A node which evaluates this function can only be accessed from nodes listed in the `NodeList` variable. Any access attempts made from nodes not listed in `NodeList` are rejected.

`connect_node(Node)`

Explicitly establishes a connection to the node specified by the atom `Node`. Returns `true` if successful, `false` if not, and `ignored` if `net_kernel` is not started.

This function is only necessary if the system is started with the flag `-dist_auto_connect`. See erl(1).

`set_net_ticktime(NetTicktime, TransitionPeriod) -> Res`

Types:

`NetTicktime = integer() (> 0)`
`TransitionPeriod = integer() (>= 0)`
`Res = atom() | {atom(), integer()}`

Sets `net_ticktime` (see `kernel(6)`) to `NetTicktime` seconds.

Some definitions:

The minimum transition traffic interval (`MTTI`)
  `minimum(NetTicktime, PreviousNetTicktime)*1000 div 4` milliseconds.
The transition period
  The time of the least number of consecutive `MTTI`s to cover `TransitionPeriod` seconds following the call to `set_net_ticktime()` (i.e. ((`TransitionPeriod*1000 - 1) div MTTI + 1)*MTTI` milliseconds).

If `NetTicktime < PreviousNetTicktime`, the actual `net_ticktime` change will be done at the end of the transition period; otherwise, at the beginning. During the transition period the `net_kernel` will ensure that there will be outgoing traffic on all connections at least every `MTTI` millisecond.

| The `net_ticktime` changes have to be initiated on all nodes in the network (with the same `NetTicktime`) before the end of any transition period on any node; otherwise, connections may erroneously be disconnected.

Currently defined return values (`Res`):

`unchanged`
  The `net_ticktime` already had the value of `NetTicktime` and was left unchanged.
`change_initiated`
  The `net_kernel` has initiated the change of the `net_ticktime` to `NetTicktime` seconds.
`{ongoing_change_to, NewNetTicktime}`
  The request was ignored; because, the `net_kernel` was busy changing the `net_ticktime` to `NewTicktime` seconds.

`set_net_ticktime(NetTicktime) -> Res`

Types:

`NetTicktime = integer()`
`Res = atom() | {atom(), integer()}`

The same as the call `set_net_ticktime(NetTicktime, 60)`.

`get_net_ticktime() -> Res`

Types:

`Res = integer() | {atom(), integer()}`

Gets the `net_ticktime`.

Currently defined return values (`Res`):

`NetTicktime`
  The `net_ticktime` is `NetTicktime` seconds.
`{ongoing_change_to, NetTicktime}`
  The `net_kernel` is currently changing the `net_ticktime` to `NetTicktime` seconds.

### AUTHORS

Claes Wikstrom - support@erlang.ericsson.se
Rickard Green - support@erlang.ericsson.se

kernel 2.10.9
Copyright © 1991-2005 Ericsson AB