1<?xml version="1.0" encoding="utf-8" ?> 2<!DOCTYPE erlref SYSTEM "erlref.dtd"> 3 4<erlref> 5 <header> 6 <copyright> 7 <year>1996</year><year>2018</year> 8 <holder>Ericsson AB. All Rights Reserved.</holder> 9 </copyright> 10 <legalnotice> 11 Licensed under the Apache License, Version 2.0 (the "License"); 12 you may not use this file except in compliance with the License. 13 You may obtain a copy of the License at 14 15 http://www.apache.org/licenses/LICENSE-2.0 16 17 Unless required by applicable law or agreed to in writing, software 18 distributed under the License is distributed on an "AS IS" BASIS, 19 WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 20 See the License for the specific language governing permissions and 21 limitations under the License. 22 23 </legalnotice> 24 25 <title>net_kernel</title> 26 <prepared>Claes Wikstrom</prepared> 27 <docno>1</docno> 28 <date>1996-09-10</date> 29 <rev>A</rev> 30 </header> 31 <module since="">net_kernel</module> 32 <modulesummary>Erlang networking kernel.</modulesummary> 33 <description> 34 <p>The net kernel is a system process, registered as 35 <c>net_kernel</c>, which must be operational for distributed Erlang 36 to work. The purpose of this process is to implement parts of 37 the BIFs <c>spawn/4</c> and <c>spawn_link/4</c>, and to provide 38 monitoring of the network.</p> 39 <p>An Erlang node is started using command-line flag 40 <c>-name</c> or <c>-sname</c>:</p> 41 <pre> 42$ <input>erl -sname foobar</input></pre> 43 <p>It is also possible to call <c>net_kernel:start([foobar])</c> 44 directly from the normal Erlang shell prompt:</p> 45 <pre> 461> <input>net_kernel:start([foobar, shortnames]).</input> 47{ok,<0.64.0>} 48(foobar@gringotts)2></pre> 49 <p>If the node is started with command-line flag <c>-sname</c>, 50 the node name is <c>foobar@Host</c>, where <c>Host</c> is 51 the short name of the host (not the fully qualified domain name). 52 If started with flag <c>-name</c>, the node name is <c>foobar@Host</c>, 53 where <c>Host</c> is the fully qualified domain name. 54 For more information, see 55 <seecom marker="erts:erl"><c>erl</c></seecom>.</p> 56 <p>Normally, connections are established automatically when 57 another node is referenced. This functionality can be disabled 58 by setting Kernel configuration parameter 59 <c>dist_auto_connect</c> to <c>never</c>, see 60 <seeapp marker="kernel_app"><c>kernel(6)</c></seeapp>. In this case, 61 connections must be established explicitly by calling 62 <seemfa marker="#connect_node/1"><c>connect_node/1</c></seemfa>.</p> 63 <p>Which nodes that are allowed to communicate with each other is handled 64 by the magic cookie system, see section 65 <seeguide marker="system/reference_manual:distributed">Distributed Erlang</seeguide> 66 in the Erlang Reference Manual.</p> 67 <warning> 68 <p> 69 Starting a distributed node without also specifying 70 <seecom marker="erts:erl#proto_dist"><c>-proto_dist inet_tls</c></seecom> 71 will expose the node to attacks that may give the attacker 72 complete access to the node and in extension the cluster. 73 When using un-secure distributed nodes, make sure that the 74 network is configured to keep potential attackers out. 75 See the <seeguide marker="ssl:ssl_distribution"> 76 Using SSL for Erlang Distribution</seeguide> User's Guide 77 for details on how to setup a secure distributed node. 78 </p> 79 </warning> 80 </description> 81 82 <funcs> 83 <func> 84 <name name="allow" arity="1" since=""/> 85 <fsummary>Permit access to a specified set of nodes</fsummary> 86 <desc> 87 <p>Permits access to the specified set of nodes.</p> 88 <p>Before the first call to <c>allow/1</c>, any node with the correct 89 cookie can be connected. When <c>allow/1</c> is called, a list 90 of allowed nodes is established. Any access attempts made from (or to) 91 nodes not in that list will be rejected.</p> 92 <p>Subsequent calls to <c>allow/1</c> will add the specified nodes 93 to the list of allowed nodes. It is not possible to remove nodes 94 from the list.</p> 95 <p>Returns <c>error</c> if any element in <c><anno>Nodes</anno></c> is not 96 an atom.</p> 97 </desc> 98 </func> 99 100 <func> 101 <name name="connect_node" arity="1" since=""/> 102 <fsummary>Establish a connection to a node.</fsummary> 103 <desc> 104 <p>Establishes a connection to <c><anno>Node</anno></c>. Returns 105 <c>true</c> if a connection was established or was already 106 established or if <c><anno>Node</anno></c> is the local node 107 itself. Returns <c>false</c> if the connection attempt failed, and 108 <c>ignored</c> if the local node is not alive.</p> 109 </desc> 110 </func> 111 112 <func> 113 <name name="get_net_ticktime" arity="0" since=""/> 114 <fsummary>Get <c>net_ticktime</c>.</fsummary> 115 <desc> 116 <p>Gets <c>net_ticktime</c> (see 117 <seeapp marker="kernel_app"><c>kernel(6)</c></seeapp>).</p> 118 <p>Defined return values (<c><anno>Res</anno></c>):</p> 119 <taglist> 120 <tag><c><anno>NetTicktime</anno></c></tag> 121 <item><p><c>net_ticktime</c> is <c><anno>NetTicktime</anno></c> 122 seconds.</p></item> 123 <tag><c>{ongoing_change_to, <anno>NetTicktime</anno>}</c></tag> 124 <item><p><c>net_kernel</c> is currently changing 125 <c>net_ticktime</c> to <c><anno>NetTicktime</anno></c> 126 seconds.</p></item> 127 <tag><c>ignored</c></tag> 128 <item><p>The local node is not alive.</p></item> 129 </taglist> 130 </desc> 131 </func> 132 133 <func> 134 <name name="getopts" arity="2" since="OTP 19.1"/> 135 <fsummary>Get distribution socket options.</fsummary> 136 <desc> 137 <p>Get one or more options for the distribution socket 138 connected to <c><anno>Node</anno></c>.</p> 139 <p>If <c><anno>Node</anno></c> is a connected node 140 the return value is the same as from 141 <seemfa marker="inet#getopts/2"><c>inet:getopts(Sock, Options)</c></seemfa> 142 where <c>Sock</c> is the distribution socket for <c><anno>Node</anno></c>.</p> 143 <p>Returns <c>ignored</c> if the local node is not alive or 144 <c>{error, noconnection}</c> if <c><anno>Node</anno></c> is not connected.</p> 145 </desc> 146 </func> 147 148 <func> 149 <name name="monitor_nodes" arity="1" since=""/> 150 <name name="monitor_nodes" arity="2" since=""/> 151 <fsummary>Subscribe to node status change messages.</fsummary> 152 <desc> 153 <p>The calling process subscribes or unsubscribes to node 154 status change messages. A <c>nodeup</c> message is delivered 155 to all subscribing processes when a new node is connected, and 156 a <c>nodedown</c> message is delivered when a node is 157 disconnected.</p> 158 <p>If <c><anno>Flag</anno></c> is <c>true</c>, a new subscription is 159 started. If <c><anno>Flag</anno></c> is <c>false</c>, all previous 160 subscriptions started with the same <c><anno>Options</anno></c> 161 are stopped. Two 162 option lists are considered the same if they contain the same 163 set of options.</p> 164 <p>As from Kernel version 2.11.4, and ERTS version 165 5.5.4, the following is guaranteed:</p> 166 <list type="bulleted"> 167 <item><p><c>nodeup</c> messages are delivered before delivery 168 of any message from the remote node passed through the 169 newly established connection.</p></item> 170 <item><p><c>nodedown</c> messages are not delivered until all 171 messages from the remote node that have been passed 172 through the connection have been delivered.</p></item> 173 </list> 174 <p>Notice that this is <em>not</em> guaranteed for Kernel 175 versions before 2.11.4.</p> 176 <p>As from Kernel version 2.11.4, subscriptions can also be 177 made before the <c>net_kernel</c> server is started, that is, 178 <c>net_kernel:monitor_nodes/[1,2]</c> does not return 179 <c>ignored</c>.</p> 180 <p>As from Kernel version 2.13, and ERTS version 181 5.7, the following is guaranteed:</p> 182 <list type="bulleted"> 183 <item><p><c>nodeup</c> messages are delivered after the 184 corresponding node appears in results from 185 <c>erlang:nodes/X</c>.</p></item> 186 <item><p><c>nodedown</c> messages are delivered after the 187 corresponding node has disappeared in results from 188 <c>erlang:nodes/X</c>.</p></item> 189 </list> 190 <p>Notice that this is <em>not</em> guaranteed for Kernel 191 versions before 2.13.</p> 192 <p>The format of the node status change messages depends on 193 <c><anno>Options</anno></c>. If <c><anno>Options</anno></c> is 194 <c>[]</c>, which is the default, the format is as follows:</p> 195 <code type="none"> 196{nodeup, Node} | {nodedown, Node} 197 Node = node()</code> 198 <p>If <c><anno>Options</anno></c> is not <c>[]</c>, the format is 199 as follows:</p> 200 <code type="none"> 201{nodeup, Node, InfoList} | {nodedown, Node, InfoList} 202 Node = node() 203 InfoList = [{Tag, Val}]</code> 204 <p><c>InfoList</c> is a list of tuples. Its contents depends on 205 <c><anno>Options</anno></c>, see below.</p> 206 <p>Also, when <c>OptionList == []</c>, only visible nodes, that 207 is, nodes that appear in the result of 208 <seemfa marker="erts:erlang#nodes/0"><c>erlang:nodes/0</c></seemfa>, 209 are monitored.</p> 210 <p><c><anno>Option</anno></c> can be any of the following:</p> 211 <taglist> 212 <tag><c>{node_type, NodeType}</c></tag> 213 <item> 214 <p>Valid values for <c>NodeType</c>:</p> 215 <taglist> 216 <tag><c>visible</c></tag> 217 <item><p>Subscribe to node status change messages for visible 218 nodes only. The tuple <c>{node_type, visible}</c> is 219 included in <c>InfoList</c>.</p></item> 220 <tag><c>hidden</c></tag> 221 <item><p>Subscribe to node status change messages for hidden 222 nodes only. The tuple <c>{node_type, hidden}</c> is 223 included in <c>InfoList</c>.</p></item> 224 <tag><c>all</c></tag> 225 <item><p>Subscribe to node status change messages for both 226 visible and hidden nodes. The tuple 227 <c>{node_type, visible | hidden}</c> is included in 228 <c>InfoList</c>.</p></item> 229 </taglist> 230 </item> 231 <tag><c>nodedown_reason</c></tag> 232 <item> 233 <p>The tuple <c>{nodedown_reason, Reason}</c> is included in 234 <c>InfoList</c> in <c>nodedown</c> messages.</p> 235 <p> 236 <c>Reason</c> can, depending on which 237 distribution module or process that is used be any term, 238 but for the standard TCP distribution module it is 239 any of the following: 240 </p> 241 <taglist> 242 <tag><c>connection_setup_failed</c></tag> 243 <item><p>The connection setup failed (after <c>nodeup</c> 244 messages were sent).</p></item> 245 <tag><c>no_network</c></tag> 246 <item><p>No network is available.</p></item> 247 <tag><c>net_kernel_terminated</c></tag> 248 <item><p>The <c>net_kernel</c> process terminated.</p></item> 249 <tag><c>shutdown</c></tag> 250 <item><p>Unspecified connection shutdown.</p></item> 251 <tag><c>connection_closed</c></tag> 252 <item><p>The connection was closed.</p></item> 253 <tag><c>disconnect</c></tag> 254 <item><p>The connection was disconnected (forced from the 255 current node).</p></item> 256 <tag><c>net_tick_timeout</c></tag> 257 <item><p>Net tick time-out.</p></item> 258 <tag><c>send_net_tick_failed</c></tag> 259 <item><p>Failed to send net tick over the connection.</p></item> 260 <tag><c>get_status_failed</c></tag> 261 <item><p>Status information retrieval from the <c>Port</c> 262 holding the connection failed.</p></item> 263 </taglist> 264 </item> 265 </taglist> 266 </desc> 267 </func> 268 269 <func> 270 <name name="set_net_ticktime" arity="1" since=""/> 271 <name name="set_net_ticktime" arity="2" since=""/> 272 <fsummary>Set <c>net_ticktime</c>.</fsummary> 273 <desc> 274 <p>Sets <c>net_ticktime</c> (see 275 <seeapp marker="kernel_app"><c>kernel(6)</c></seeapp>) to 276 <c><anno>NetTicktime</anno></c> seconds. 277 <c><anno>TransitionPeriod</anno></c> defaults to <c>60</c>.</p> 278 <p>Some definitions:</p> 279 <taglist> 280 <tag>Minimum transition traffic interval (<c>MTTI</c>)</tag> 281 <item><p><c>minimum(<anno>NetTicktime</anno>, 282 PreviousNetTicktime)*1000 div 4</c> milliseconds.</p></item> 283 <tag>Transition period</tag> 284 <item><p>The time of the least number of consecutive <c>MTTI</c>s 285 to cover <c><anno>TransitionPeriod</anno></c> seconds following 286 the call to <c>set_net_ticktime/2</c> (that is, 287 ((<c><anno>TransitionPeriod</anno>*1000 - 1) div MTTI + 1)*MTTI</c> 288 milliseconds).</p></item> 289 </taglist> 290 <p>If 291 <c><![CDATA[NetTicktime < PreviousNetTicktime]]></c>, 292 the <c>net_ticktime</c> change is done at the end of 293 the transition period; otherwise at the beginning. During 294 the transition period, <c>net_kernel</c> ensures that 295 there is outgoing traffic on all connections at least 296 every <c>MTTI</c> millisecond.</p> 297 <note> 298 <p>The <c>net_ticktime</c> changes must be initiated on all 299 nodes in the network (with the same <c><anno>NetTicktime</anno></c>) 300 before the end of any transition period on any node; 301 otherwise connections can erroneously be disconnected.</p> 302 </note> 303 <p>Returns one of the following:</p> 304 <taglist> 305 <tag><c>unchanged</c></tag> 306 <item> 307 <p><c>net_ticktime</c> already has the value of 308 <c><anno>NetTicktime</anno></c> and is left unchanged.</p> 309 </item> 310 <tag><c>change_initiated</c></tag> 311 <item> 312 <p><c>net_kernel</c> initiated the change of 313 <c>net_ticktime</c> to <c><anno>NetTicktime</anno></c> 314 seconds.</p> 315 </item> 316 <tag><c>{ongoing_change_to, <anno>NewNetTicktime</anno>}</c></tag> 317 <item> 318 <p>The request is <em>ignored</em> because 319 <c>net_kernel</c> is busy changing <c>net_ticktime</c> to 320 <c><anno>NewNetTicktime</anno></c> seconds.</p> 321 </item> 322 </taglist> 323 </desc> 324 </func> 325 326 <func> 327 <name name="setopts" arity="2" since="OTP 19.1"/> 328 <fsummary>Set distribution socket options.</fsummary> 329 <desc> 330 <p>Set one or more options for distribution sockets. 331 Argument <c><anno>Node</anno></c> can be either one node name 332 or the atom <c>new</c> to affect the distribution sockets of all 333 future connected nodes.</p> 334 <p>The return value is the same as from 335 <seemfa marker="inet#setopts/2"><c>inet:setopts/2</c></seemfa> 336 or <c>{error, noconnection}</c> if <c><anno>Node</anno></c> is not 337 a connected node or <c>new</c>.</p> 338 <p>If <c><anno>Node</anno></c> is <c>new</c> the <c><anno>Options</anno></c> 339 will then also be added to kernel configration parameters 340 <seeapp marker="kernel:kernel_app#inet_dist_listen_options">inet_dist_listen_options</seeapp> 341 and 342 <seeapp marker="kernel:kernel_app#inet_dist_connect_options">inet_dist_connect_options</seeapp>.</p> 343 <p>Returns <c>ignored</c> if the local node is not alive.</p> 344 </desc> 345 </func> 346 347 <func> 348 <name since="">start([Name]) -> {ok, pid()} | {error, Reason}</name> 349 <name since="">start([Name, NameType]) -> {ok, pid()} | {error, Reason}</name> 350 <name since="">start([Name, NameType, Ticktime]) -> {ok, pid()} | {error, Reason}</name> 351 <fsummary>Turn an Erlang runtime system into a distributed node.</fsummary> 352 <type> 353 <v>Name = atom()</v> 354 <v>NameType = shortnames | longnames</v> 355 <v>Reason = {already_started, pid()} | term()</v> 356 </type> 357 <desc> 358 <p>Turns a non-distributed node into a distributed node by 359 starting <c>net_kernel</c> and other necessary processes.</p> 360 <p>Notice that the argument is a list with exactly one, two, or 361 three arguments. <c>NameType</c> defaults to <c>longnames</c> 362 and <c>Ticktime</c> to <c>15000</c>.</p> 363 </desc> 364 </func> 365 366 <func> 367 <name name="stop" arity="0" since=""/> 368 <fsummary>Turn a node into a non-distributed Erlang runtime system.</fsummary> 369 <desc> 370 <p>Turns a distributed node into a non-distributed node. For 371 other nodes in the network, this is the same as the node 372 going down. Only possible when the net kernel was started using 373 <seemfa marker="#start/1"><c>start/1</c></seemfa>, 374 otherwise <c>{error, not_allowed}</c> is returned. Returns 375 <c>{error, not_found}</c> if the local node is not alive.</p> 376 </desc> 377 </func> 378 </funcs> 379</erlref> 380 381