path: root/lib/kernel/doc/src/net_kernel.xml

<?xml version="1.0" encoding="utf-8" ?>
<!DOCTYPE erlref SYSTEM "erlref.dtd">

<erlref>
  <header>
    <copyright>
      <year>1996</year><year>2022</year>
      <holder>Ericsson AB. All Rights Reserved.</holder>
    </copyright>
    <legalnotice>
      Licensed under the Apache License, Version 2.0 (the "License");
      you may not use this file except in compliance with the License.
      You may obtain a copy of the License at
 
          http://www.apache.org/licenses/LICENSE-2.0

      Unless required by applicable law or agreed to in writing, software
      distributed under the License is distributed on an "AS IS" BASIS,
      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
      See the License for the specific language governing permissions and
      limitations under the License.
    
    </legalnotice>

    <title>net_kernel</title>
    <prepared>Claes Wikstrom</prepared>
    <docno>1</docno>
    <date>1996-09-10</date>
    <rev>A</rev>
  </header>
  <module since="">net_kernel</module>
  <modulesummary>Erlang networking kernel.</modulesummary>
  <description>
    <p>The net kernel is a system process, registered as
      <c>net_kernel</c>, which must be operational for distributed Erlang
      to work. The purpose of this process is to implement parts of
      the BIFs <c>spawn/4</c> and <c>spawn_link/4</c>, and to provide 
      monitoring of the network.</p>
    <p>An Erlang node is started using command-line flag
      <c>-name</c> or <c>-sname</c>:</p>
     <pre>
$ <input>erl -sname foobar</input></pre>
    <p>It is also possible to call
      <seemfa marker="#start/2"><c>net_kernel:start(foobar, #{})</c></seemfa>
      directly from the normal Erlang shell prompt:</p>
    <pre>
1> <input>net_kernel:start(foobar, #{name_domain => shortnames}).</input>
{ok,&lt;0.64.0>}
(foobar@gringotts)2></pre>
    <p>If the node is started with command-line flag <c>-sname</c>,
      the node name is <c>foobar@Host</c>, where <c>Host</c> is
      the short name of the host (not the fully qualified domain name).
      If started with flag <c>-name</c>, the node name is <c>foobar@Host</c>,
      where <c>Host</c> is the fully qualified domain name.
      For more information, see
      <seecom marker="erts:erl"><c>erl</c></seecom>.</p>
    <p>Normally, connections are established automatically when
      another node is referenced. This functionality can be disabled
      by setting Kernel configuration parameter
      <c>dist_auto_connect</c> to <c>never</c>, see
      <seeapp marker="kernel_app"><c>kernel(6)</c></seeapp>. In this case,
      connections must be established explicitly by calling
      <seemfa marker="#connect_node/1"><c>connect_node/1</c></seemfa>.</p>
    <p>Which nodes that are allowed to communicate with each other is handled
      by the magic cookie system, see section
      <seeguide marker="system/reference_manual:distributed">Distributed Erlang</seeguide>
      in the Erlang Reference Manual.</p>
    <warning>
      <p>
        Starting a distributed node without also specifying
        <seecom marker="erts:erl#proto_dist"><c>-proto_dist inet_tls</c></seecom>
        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 <seeguide marker="ssl:ssl_distribution">
        Using SSL for Erlang Distribution</seeguide> User's Guide
        for details on how to setup a secure distributed node.
      </p>
    </warning>
  </description>

  <funcs>
    <func>
      <name name="allow" arity="1" since=""/>
      <fsummary>Permit access to a specified set of nodes</fsummary>
      <desc>
        <p>Permits access to the specified set of nodes.</p>
        <p>Before the first call to <c>allow/1</c>, any node with the correct
          cookie can be connected. When <c>allow/1</c> is called, a list
          of allowed nodes is established. Any access attempts made from (or to)
          nodes not in that list will be rejected.</p>
        <p>Subsequent calls to <c>allow/1</c> will add the specified nodes
          to the list of allowed nodes. It is not possible to remove nodes
          from the list.</p>
        <p>Returns <c>error</c> if any element in <c><anno>Nodes</anno></c> is not
          an atom.</p>
      </desc>
    </func>

    <func>
      <name name="connect_node" arity="1" since=""/>
      <fsummary>Establish a connection to a node.</fsummary>
      <desc>
        <p>Establishes a connection to <c><anno>Node</anno></c>. Returns
          <c>true</c> if a connection was established or was already
	  established or if <c><anno>Node</anno></c> is the local node
	  itself. Returns <c>false</c> if the connection attempt failed, and
	  <c>ignored</c> if the local node is not alive.</p>
      </desc>
    </func>

    <func>
      <name name="get_net_ticktime" arity="0" since=""/>
      <fsummary>Get <c>net_ticktime</c>.</fsummary>
      <desc>
        <p>Returns currently used net tick time in seconds. For more information
        see the
        <seeapp marker="kernel_app#net_ticktime"><c>net_ticktime</c></seeapp>
        <c>kernel(6)</c> parameter.</p>

        <p>Defined return values (<c><anno>Res</anno></c>):</p>
        <taglist>
          <tag><c><anno>NetTicktime</anno></c></tag>
          <item><p><c>net_ticktime</c> is <c><anno>NetTicktime</anno></c>
            seconds.</p></item>
          <tag><c>{ongoing_change_to, <anno>NetTicktime</anno>}</c></tag>
          <item><p><c>net_kernel</c> is currently changing
            <c>net_ticktime</c> to <c><anno>NetTicktime</anno></c>
            seconds.</p></item>
          <tag><c>ignored</c></tag>
          <item><p>The local node is not alive.</p></item>
        </taglist>
      </desc>
    </func>

    <func>
      <name name="getopts" arity="2" since="OTP 19.1"/>
      <fsummary>Get distribution socket options.</fsummary>
      <desc>
        <p>Get one or more options for the distribution socket
	connected to <c><anno>Node</anno></c>.</p>
        <p>If <c><anno>Node</anno></c> is a connected node
	the return value is the same as from
	<seemfa marker="inet#getopts/2"><c>inet:getopts(Sock, Options)</c></seemfa>
	where <c>Sock</c> is the distribution socket for <c><anno>Node</anno></c>.</p>
	<p>Returns <c>ignored</c> if the local node is not alive or
	<c>{error, noconnection}</c> if <c><anno>Node</anno></c> is not connected.</p>
      </desc>
    </func>

    <func>
      <name name="get_state" arity="0" since="OTP 25.0"/>
      <fsummary>Get various distribution state.</fsummary>
      <desc>
        <p>Get the current state of the distribution for the local node.</p>
        <p>Returns a map with (at least) the following key-value pairs:</p>
        <taglist>
          <tag><c>started => Started</c></tag>
          <item>
            <p>Valid values for <c>Started</c>:</p>
            <taglist>
              <tag><c>no</c></tag>
              <item>
                <p>The distribution is not started. In this state none of
                the other keys below are present in the map.</p>
              </item>
              <tag><c>static</c></tag>
              <item>
                <p>The distribution was started with command line arguments
                <seecom marker="erts:erl#name"><c>-name</c></seecom> or
                <seecom marker="erts:erl#sname"><c>-sname</c></seecom>.</p>
              </item>
              <tag><c>dynamic</c></tag>
              <item>
                <p>The distribution was started with
                <seemfa marker="#start/1"><c>net_kernel:start/1</c></seemfa>
                and can be stopped with
                <seemfa marker="#start/1"><c>net_kernel:stop/0</c></seemfa>.</p>
              </item>
            </taglist>
          </item>
          <tag><c>name => Name</c></tag>
          <item>
            <p>The name of the node. Same as returned by
            <seemfa marker="erts:erlang#node/0"><c>erlang:node/0</c></seemfa>
            except when <c>name_type</c> is <c>dynamic</c> in which case
            <c>Name</c> may be <c>undefined</c> (instead of <c>nonode@nohost</c>).
            </p>
          </item>
          <tag><c>name_type => NameType</c></tag>
          <item>
            <p>Valid values for <c>NameType</c>:</p>
            <taglist>
              <tag><c>static</c></tag>
              <item>
                <p>The node has a static node name set by the node itself.</p>
              </item>
              <tag><c>dynamic</c></tag>
              <item>
                <p>The distribution was started in
                <seeguide marker="system/reference_manual:distributed#dyn_node_name">
                dynamic node name</seeguide> mode, and will get its node name assigned
                from the first node it connects to. If key <c>name</c> has value
                <c>undefined</c> that has not happened yet.</p>
              </item>
            </taglist>
          </item>
          <tag><c>name_domain => NameDomain</c></tag>
          <item>
            <p>Valid values for <c>NameDomain</c>:</p>
            <taglist>
              <tag><c>shortnames</c></tag>
              <item>
                <p>The distribution was started to use node names with a short
                host portion (not fully qualified).</p>
              </item>
              <tag><c>longnames</c></tag>
              <item>
                <p>The distribution was started to use node names with a long
                fully qualified host portion.</p>
              </item>
            </taglist>
          </item>
        </taglist>
      </desc>
    </func>

    <func>
      <name name="monitor_nodes" arity="1" since=""/>
      <name name="monitor_nodes" arity="2" since=""/>
      <fsummary>Subscribe to node status change messages.</fsummary>
      <desc>
        <p>The calling process subscribes or unsubscribes to node
          status change messages. A <c>nodeup</c> message is delivered
          to all subscribing processes when a new node is connected, and
          a <c>nodedown</c> message is delivered when a node is
          disconnected.</p>
        <p>If <c><anno>Flag</anno></c> is <c>true</c>, a new subscription is
          started. If <c><anno>Flag</anno></c> is <c>false</c>, all previous
          subscriptions started with the same <c><anno>Options</anno></c>
          are stopped. Two
          option lists are considered the same if they contain the same
          set of options.</p>
        <p>Delivery guarantees of <c>nodeup</c>/<c>nodedown</c> messages:</p>
        <list>
          <item><p>
            <c>nodeup</c> messages are delivered before delivery
            of any signals from the remote node through the newly
            established connection.
          </p></item>
          <item>
            <p><c>nodedown</c> messages are delivered after all
            the signals from the remote node over the connection
            have been delivered.
          </p></item>
          <item><p>
            <c>nodeup</c> messages are delivered after the
	    corresponding node appears in results from
	    <c>erlang:nodes()</c>.
          </p></item>
          <item>
            <p><c>nodedown</c> messages are delivered after the
	    corresponding node has disappeared in results from
	    <c>erlang:nodes()</c>.
          </p></item>
          <item><p>
            As of OTP 23.0, a <c>nodedown</c> message for a
            connection being taken down will be delivered before a
            <c>nodeup</c> message due to a new connection to the
            same node. Prior to OTP 23.0, this was not
            guaranteed to be the case.
          </p></item>
        </list>
        <p>The format of the node status change messages depends on
          <c><anno>Options</anno></c>. If <c><anno>Options</anno></c> is
          the empty list or if <c>net_kernel:monitor_nodes/1</c> is called,
          the format is as follows:</p>
        <code type="erl">
{nodeup, Node} | {nodedown, Node}
  Node = node()</code>
        <p>
          When <c><anno>Options</anno></c> 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
          <seemfa marker="erts:erlang#nodes/0"><c>erlang:nodes/0</c></seemfa>.
        </p>
        <p>
          If <c><anno>Options</anno></c> equals anything other than the
          empty list, the format of the status change messages is as follows:
        </p>
        <code type="erl">
{nodeup, Node, Info} | {nodedown, Node, Info}
  Node = node()
  Info = #{Tag => Val} | [{Tag, Val}]</code>
        <p>
          <c>Info</c> is either a map or a list of 2-tuples. Its content
          depends on <c><anno>Options</anno></c>. If <c><anno>Options</anno></c>
          is a map, <c>Info</c> will also be a map. If <c><anno>Options</anno></c>
          is a list, <c>Info</c> will also be a list.
        </p>
        <p>
          When <c><anno>Options</anno></c> is a map, currently
          the following associations are allowed:
        </p>
        <taglist>
          <tag><c>connection_id => boolean()</c></tag>
          <item>
            <p>
              If the value of the association equals <c>true</c>, a
              <c>connection_id => ConnectionId</c> association will be
              included in the <c>Info</c> map where <c>ConnectionId</c>
              is the connection identifier of the connection coming up
              or going down. For more info about this connection
              identifier see the documentation of
              <seeerl marker="erts:erlang#connection_id">erlang:nodes/2</seeerl>.
            </p>
          </item>
          <tag><c>node_type => <anno>NodeType</anno></c></tag>
          <item>
            <p>Valid values for <c>NodeType</c>:</p>
            <taglist>
              <tag><c>visible</c></tag>
              <item><p>Subscribe to node status change messages for visible
               nodes only. The association <c>node_type => visible</c> will
               be included in the <c>Info</c> map.</p></item>
              <tag><c>hidden</c></tag>
              <item><p>Subscribe to node status change messages for hidden
               nodes only. The association <c>node_type => hidden</c> will
               be included in the <c>Info</c> map.</p></item>
              <tag><c>all</c></tag>
              <item><p>Subscribe to node status change messages for both
               visible and hidden nodes. The association
               <c>node_type => visible | hidden</c> will be included in
               the <c>Info</c> map.</p></item>
            </taglist>
            <p>
              If no <c>node_type => <anno>NodeType</anno></c> association
              is included in the <c><anno>Options</anno></c> map, the
              caller will subscribe for status change messages for visible
              nodes only, but <i>no</i> <c>node_type => visible</c>
              association will be included in the <c>Info</c> map.
            </p>
          </item>
          <tag><c>nodedown_reason => boolean()</c></tag>
          <item>
            <p>
              If the value of the association equals <c>true</c>, a
              <c>nodedown_reason => Reason</c> association will be
              included in the <c>Info</c> map for <c>nodedown</c>
              messages.
            </p>
            <marker id="nodedown_reasons"/>
            <p>
	      <c>Reason</c> 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:
	    </p>
            <taglist>
              <tag><c>connection_setup_failed</c></tag>
              <item><p>The connection setup failed (after <c>nodeup</c>
                messages were sent).</p></item>
              <tag><c>no_network</c></tag>
              <item><p>No network is available.</p></item>
              <tag><c>net_kernel_terminated</c></tag>
              <item><p>The <c>net_kernel</c> process terminated.</p></item>
              <tag><c>shutdown</c></tag>
              <item><p>Unspecified connection shutdown.</p></item>
              <tag><c>connection_closed</c></tag>
              <item><p>The connection was closed.</p></item>
              <tag><c>disconnect</c></tag>
              <item><p>The connection was disconnected (forced from the
                current node).</p></item>
              <tag><c>net_tick_timeout</c></tag>
              <item><p>Net tick time-out.</p></item>
              <tag><c>send_net_tick_failed</c></tag>
              <item><p>Failed to send net tick over the connection.</p></item>
              <tag><c>get_status_failed</c></tag>
              <item><p>Status information retrieval from the <c>Port</c>
                holding the connection failed.</p></item>
            </taglist>
          </item>
        </taglist>
        <p>
          When <c><anno>Options</anno></c> is a list, currently
          <c><anno>ListOption</anno></c> can be one of the following:
        </p>
        <taglist>
          <tag><c>connection_id</c></tag>
          <item>
            <p>
              A <c>{connection_id, ConnectionId}</c> tuple will be
              included in <c>Info</c> where <c>ConnectionId</c> is the
              connection identifier of the connection coming up or
              going down. For more info about this connection identifier
              see the documentation of
              <seeerl marker="erts:erlang#connection_id">erlang:nodes/2</seeerl>.
            </p>
          </item>
          <tag><c>{node_type, <anno>NodeType</anno>}</c></tag>
          <item>
            <p>Valid values for <c><anno>NodeType</anno></c>:</p>
            <taglist>
              <tag><c>visible</c></tag>
              <item><p>Subscribe to node status change messages for visible
               nodes only. The tuple <c>{node_type, visible}</c> will be
               included in the <c>Info</c> list.</p></item>
              <tag><c>hidden</c></tag>
              <item><p>Subscribe to node status change messages for hidden
               nodes only. The tuple <c>{node_type, hidden}</c> will be
               included in the <c>Info</c> list.</p></item>
              <tag><c>all</c></tag>
              <item><p>Subscribe to node status change messages for both
               visible and hidden nodes. The tuple
               <c>{node_type, visible | hidden}</c> will be included in
               the <c>Info</c> list.</p></item>
            </taglist>
            <p>
              If no <c>{node_type, <anno>NodeType</anno>}</c> option
              has been given. The caller will subscribe for status
              change messages for visible nodes only, but <i>no</i>
              <c>{node_type, visible}</c> tuple will be included in the
              <c>Info</c> list.
            </p>
          </item>
          <tag><c>nodedown_reason</c></tag>
          <item>
            <p>
              The tuple <c>{nodedown_reason, Reason}</c> will be included
              in the <c>Info</c> list for <c>nodedown</c> messages.
            </p>
            <p>
              See the documentation of the
              <seeerl marker="#nodedown_reasons"><c>nodedown_reason
              => boolean()</c></seeerl> association above for information
              about possible <c>Reason</c> values.
	    </p>
          </item>
        </taglist>
        <p>Example:</p>
        <code type="erl">
(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> 
        </code>
      </desc>
    </func>

    <func>
      <name name="set_net_ticktime" arity="1" since=""/>
      <name name="set_net_ticktime" arity="2" since=""/>
      <fsummary>Set <c>net_ticktime</c>.</fsummary>
      <desc>
        <p>Sets <c>net_ticktime</c> (see
          <seeapp marker="kernel_app"><c>kernel(6)</c></seeapp>) to
          <c><anno>NetTicktime</anno></c> seconds.
          <c><anno>TransitionPeriod</anno></c> defaults to <c>60</c>.</p>
        <p>Some definitions:</p>
        <taglist>
          <tag>Minimum transition traffic interval (<c>MTTI</c>)</tag>
          <item><p><c>minimum(<anno>NetTicktime</anno>,
            PreviousNetTicktime)*1000 div 4</c> milliseconds.</p></item>
          <tag>Transition period</tag>
          <item><p>The time of the least number of consecutive <c>MTTI</c>s
            to cover <c><anno>TransitionPeriod</anno></c> seconds following
            the call to <c>set_net_ticktime/2</c> (that is,
            ((<c><anno>TransitionPeriod</anno>*1000 - 1) div MTTI + 1)*MTTI</c>
            milliseconds).</p></item>
        </taglist>
        <p>If
          <c><![CDATA[NetTicktime < PreviousNetTicktime]]></c>,
          the <c>net_ticktime</c> change is done at the end of
          the transition period; otherwise at the beginning. During
          the transition period, <c>net_kernel</c> ensures that
          there is outgoing traffic on all connections at least
          every <c>MTTI</c> millisecond.</p>
        <note>
          <p>The <c>net_ticktime</c> changes must be initiated on all
            nodes in the network (with the same <c><anno>NetTicktime</anno></c>)
            before the end of any transition period on any node;
            otherwise connections can erroneously be disconnected.</p>
        </note>
        <p>Returns one of the following:</p>
        <taglist>
          <tag><c>unchanged</c></tag>
          <item>
            <p><c>net_ticktime</c> already has the value of
              <c><anno>NetTicktime</anno></c> and is left unchanged.</p>
          </item>
          <tag><c>change_initiated</c></tag>
          <item>
            <p><c>net_kernel</c> initiated the change of
              <c>net_ticktime</c> to <c><anno>NetTicktime</anno></c>
              seconds.</p>
          </item>
          <tag><c>{ongoing_change_to, <anno>NewNetTicktime</anno>}</c></tag>
          <item>
            <p>The request is <em>ignored</em> because
              <c>net_kernel</c> is busy changing <c>net_ticktime</c> to
              <c><anno>NewNetTicktime</anno></c> seconds.</p>
          </item>
        </taglist>
      </desc>
    </func>

    <func>
      <name name="setopts" arity="2" since="OTP 19.1"/>
      <fsummary>Set distribution socket options.</fsummary>
      <desc>
        <p>Set one or more options for distribution sockets.
	Argument <c><anno>Node</anno></c> can be either one node name
	or the atom <c>new</c> to affect the distribution sockets of all
	future connected nodes.</p>
        <p>The return value is the same as from
	<seemfa marker="inet#setopts/2"><c>inet:setopts/2</c></seemfa>
	or <c>{error, noconnection}</c> if <c><anno>Node</anno></c> is not
	a connected node or <c>new</c>.</p>
	<p>If <c><anno>Node</anno></c> is <c>new</c> the <c><anno>Options</anno></c>
	will then also be added to kernel configuration parameters
	<seeapp marker="kernel:kernel_app#inet_dist_listen_options">inet_dist_listen_options</seeapp>
	and
	<seeapp marker="kernel:kernel_app#inet_dist_connect_options">inet_dist_connect_options</seeapp>.</p>
	<p>Returns <c>ignored</c> if the local node is not alive.</p>
      </desc>
    </func>

    <func>
      <name name="start" arity="2" since="OTP 24.3"/>
      <fsummary>Turn an Erlang runtime system into a distributed node.</fsummary>
      <desc>
        <p>
          Turns a non-distributed node into a distributed node by
          starting <c>net_kernel</c> and other necessary processes.
        </p>

        <p>
          If <c><anno>Name</anno></c> is set to <em><c>undefined</c></em> the
          distribution will be started to request a dynamic node name from the
          first node it connects to. See
          <seeguide marker="system/reference_manual:distributed#dyn_node_name">
            Dynamic Node Name</seeguide>. Setting <c><anno>Name</anno></c> to
            <c>undefined</c> implies options <c>dist_listen => false</c> and
            <c>hidden => true</c>.
        </p>

        <p>Currently supported options:</p>
        <taglist>
          <tag><c>name_domain => <anno>NameDomain</anno></c></tag>
          <item><p>
            Determines the host name part of the node name. If
            <c><anno>NameDomain</anno></c> equals <c>longnames</c>, fully
            qualified domain names will be used which also is the default.
            If <c><anno>NameDomain</anno></c> equals <c>shortnames</c>, only the
            short name of the host will be used.
          </p></item>
          <tag><c>net_ticktime => <anno>NetTickTime</anno></c></tag>
          <item><p>
            <i>Net tick time</i> to use in seconds. Defaults to the value of the
            <seeapp marker="kernel_app#net_ticktime"><c>net_ticktime</c></seeapp>
            <c>kernel(6)</c> parameter. For more information about <i>net tick
            time</i>, see the <c>kernel</c> parameter. However, note that if the
            value of the <c>kernel</c> parameter is invalid, it will silently be
            replaced by a valid value, but if an invalid
            <c><anno>NetTickTime</anno></c> value is passed as option value to
            this function, the call will fail.
          </p></item>
          <tag><c>net_tickintensity => <anno>NetTickIntensity</anno></c></tag>
          <item><p>
            <i>Net tick intensity</i> to use. Defaults to the value of the
            <seeapp marker="kernel_app#net_tickintensity"><c>net_tickintensity</c></seeapp>
            <c>kernel(6)</c> parameter. For more information about <i>net tick
            intensity</i>, see the <c>kernel</c> parameter. However, note that if
            the value of the <c>kernel</c> parameter is invalid, it will silently
            be replaced by a valid value, but if an invalid
            <c><anno>NetTickIntensity</anno></c> value is passed as option value
            to this function, the call will fail.
          </p></item>
          <tag><c>dist_listen => boolean()</c></tag>
          <item><p>
            Enable or disable listening for incoming connections. Defaults to
            the value of the
            <seecom marker="erts:erl#dist_listen"><c>-dist_listen</c></seecom>
            <c>erl</c> command line argument. Note that
            <c>dist_listen => false</c> implies <c>hidden => true</c>.
          </p>
          <p>
            If <c>undefined</c> has been passed as <c><anno>Name</anno></c>,
            the <c>dist_listen</c> option will be overridden with
            <c>dist_listen => false</c>.
          </p></item>
          <tag><c>hidden => boolean()</c></tag>
          <item><p>
            Enable or disable hidden node. Defaults to <c>true</c> if the
            <seecom marker="erts:erl#hidden"><c>-hidden</c></seecom> <c>erl</c>
            command line argument has been passed; otherwise <c>false</c>.
          </p>
          <p>
            If <c>undefined</c> has been passed as <c><anno>Name</anno></c>,
            or the option <c>dist_listen</c> equals <c>false</c>, the
            <c>hidden</c> option will be overridden with <c>hidden => true</c>.
          </p></item>
        </taglist>
      </desc>
    </func>
    <func>
      <name name="start" arity="1" since=""/>
      <fsummary>Turn an Erlang runtime system into a distributed node.</fsummary>
      <desc>
        <warning><p>
          <c>start/1</c> is deprecated. Use
          <seemfa marker="#start/2"><c>start/2</c></seemfa> instead.
        </p></warning>
        <p>
          Turns a non-distributed node into a distributed node by
          starting <c>net_kernel</c> and other necessary processes.
        </p>
        <p>
          <c><anno>Options</anno></c> list can only be exactly one of
          the following lists (order is imporant):
        </p>
        <taglist>
          <tag><c>[<anno>Name</anno>]</c></tag>
          <item>
            <p>
              The same as <c>net_kernel:start([<anno>Name</anno>,
              longnames, 15000])</c>.
            </p>
          </item>
          <tag><c>[<anno>Name</anno>, <anno>NameDomain</anno>]</c></tag>
          <item>
            <p>
              The same as <c>net_kernel:start([<anno>Name</anno>,
              <anno>NameDomain</anno>, 15000])</c>.
            </p>
          </item>
          <tag><c>[<anno>Name</anno>, <anno>NameDomain</anno>,
                   <anno>TickTime</anno>]</c></tag>
          <item>
            <p>
              The same as <seemfa marker="#start/2">
              <c>net_kernel:start(<anno>Name</anno>, #{name_domain =>
              <anno>NameDomain</anno>, net_ticktime =>
              ((<anno>TickTime</anno>*4-1) div 1000) + 1,
              net_tickintensity => 4})</c></seemfa>.
              Note that <c><anno>TickTime</anno></c> is <i>not</i> the same
              as net tick time expressed in milliseconds.
              <c><anno>TickTime</anno></c> is the time between ticks when
              net tick intensity equals <c>4</c>.
            </p>
          </item>
        </taglist>
      </desc>
    </func>

    <func>
      <name name="stop" arity="0" since=""/>
      <fsummary>Turn a node into a non-distributed Erlang runtime system.</fsummary>
      <desc>
        <p>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
          <seemfa marker="#start/2"><c>start/2</c></seemfa>,
          otherwise <c>{error, not_allowed}</c> is returned. Returns
          <c>{error, not_found}</c> if the local node is not alive.</p>
      </desc>
    </func>
  </funcs>
</erlref>