1net_kernel(3) Erlang Module Definition net_kernel(3)
2
6 net_kernel - Erlang networking kernel.
7
9 The net kernel is a system process, registered as net_kernel, which
10 must be operational for distributed Erlang to work. The purpose of this
11 process is to implement parts of the BIFs spawn/4 and spawn_link/4, and
12 to provide monitoring of the network.
13 An Erlang node is started using command-line flag -name or -sname:
15 $ erl -sname foobar
17 It is also possible to call net_kernel:start(foobar, #{}) directly from
19 the normal Erlang shell prompt:
20 1> net_kernel:start(foobar, #{name_domain => shortnames}).
22 {ok,<0.64.0>}
23 (foobar@gringotts)2>
24 If the node is started with command-line flag -sname, the node name is
26 foobar@Host, where Host is the short name of the host (not the fully
27 qualified domain name). If started with flag -name, the node name is
28 foobar@Host, where Host is the fully qualified domain name. For more
29 information, see erl.
30 Normally, connections are established automatically when another node
32 is referenced. This functionality can be disabled by setting Kernel
33 configuration parameter dist_auto_connect to never, see kernel(6). In
34 this case, connections must be established explicitly by calling con‐
35 nect_node/1.
36 Which nodes that are allowed to communicate with each other is handled
38 by the magic cookie system, see section Distributed Erlang in the Er‐
39 lang Reference Manual.
40 Warning:
42 Starting a distributed node without also specifying -proto_dist
43 inet_tls will expose the node to attacks that may give the attacker
44 complete access to the node and in extension the cluster. When using
45 un-secure distributed nodes, make sure that the network is configured
46 to keep potential attackers out. See the Using SSL for Erlang Distri‐
47 bution User's Guide for details on how to setup a secure distributed
48 node.
49
52 allow(Nodes) -> ok | error
53 Types:
55 Nodes = [node()]
57 Permits access to the specified set of nodes.
59 Before the first call to allow/1, any node with the correct
61 cookie can be connected. When allow/1 is called, a list of al‐
62 lowed nodes is established. Any access attempts made from (or
63 to) nodes not in that list will be rejected.
64 Subsequent calls to allow/1 will add the specified nodes to the
66 list of allowed nodes. It is not possible to remove nodes from
67 the list.
68 Returns error if any element in Nodes is not an atom.
70 connect_node(Node) -> boolean() | ignored
72 Types:
74 Node = node()
76 Establishes a connection to Node. Returns true if a connection
78 was established or was already established or if Node is the lo‐
79 cal node itself. Returns false if the connection attempt failed,
80 and ignored if the local node is not alive.
81 get_net_ticktime() -> Res
83 Types:
85 Res = NetTicktime | {ongoing_change_to, NetTicktime} | ig‐
87 nored
88 NetTicktime = integer() >= 1
89 Returns currently used net tick time in seconds. For more infor‐
91 mation see the net_ticktime kernel(6) parameter.
92 Defined return values (Res):
94 NetTicktime:
96 net_ticktime is NetTicktime seconds.
97 {ongoing_change_to, NetTicktime}:
99 net_kernel is currently changing net_ticktime to NetTicktime
100 seconds.
101 ignored:
103 The local node is not alive.
104 getopts(Node, Options) ->
106 {ok, OptionValues} | {error, Reason} | ignored
107 Types:
109 Node = node()
111 Options = [inet:socket_getopt()]
112 OptionValues = [inet:socket_setopt()]
113 Reason = inet:posix() | noconnection
114 Get one or more options for the distribution socket connected to
116 Node.
117 If Node is a connected node the return value is the same as from
119 inet:getopts(Sock, Options) where Sock is the distribution
120 socket for Node.
121 Returns ignored if the local node is not alive or {error, nocon‐
123 nection} if Node is not connected.
124 get_state() ->
126 #{started => no | static | dynamic,
127 name => atom(),
128 name_type => static | dynamic,
129 name_domain => shortnames | longnames}
130 Get the current state of the distribution for the local node.
132 Returns a map with (at least) the following key-value pairs:
134 started => Started:
136 Valid values for Started:
137 no:
139 The distribution is not started. In this state none of the
140 other keys below are present in the map.
141 static:
143 The distribution was started with command line arguments
144 -name or -sname.
145 dynamic:
147 The distribution was started with net_kernel:start/1 and
148 can be stopped with net_kernel:stop/0.
149 name => Name:
151 The name of the node. Same as returned by erlang:node/0 ex‐
152 cept when name_type is dynamic in which case Name may be un‐
153 defined (instead of nonode@nohost).
154 name_type => NameType:
156 Valid values for NameType:
157 static:
159 The node has a static node name set by the node itself.
160 dynamic:
162 The distribution was started in dynamic node name mode,
163 and will get its node name assigned from the first node it
164 connects to. If key name has value undefined that has not
165 happened yet.
166 name_domain => NameDomain:
168 Valid values for NameDomain:
169 shortnames:
171 The distribution was started to use node names with a
172 short host portion (not fully qualified).
173 longnames:
175 The distribution was started to use node names with a long
176 fully qualified host portion.
177 monitor_nodes(Flag) -> ok | Error
179 monitor_nodes(Flag, Options) -> ok | Error
181 Types:
183 Flag = boolean()
185 Options = OptionsList | OptionsMap
186 OptionsList = [ListOption]
187 ListOption =
188 connection_id | {node_type, NodeType} | nodedown_reason
189 OptionsMap =
190 #{connection_id => boolean(),
191 node_type => NodeType,
192 nodedown_reason => boolean()}
193 NodeType = visible | hidden | all
194 Error = error | {error, term()}
195 The calling process subscribes or unsubscribes to node status
197 change messages. A nodeup message is delivered to all subscrib‐
198 ing processes when a new node is connected, and a nodedown mes‐
199 sage is delivered when a node is disconnected.
200 If Flag is true, a new subscription is started. If Flag is
202 false, all previous subscriptions started with the same Options
203 are stopped. Two option lists are considered the same if they
204 contain the same set of options.
205 Delivery guarantees of nodeup/nodedown messages:
207 * nodeup messages are delivered before delivery of any signals
209 from the remote node through the newly established connec‐
210 tion.
211 * nodedown messages are delivered after all the signals from
213 the remote node over the connection have been delivered.
214 * nodeup messages are delivered after the corresponding node
216 appears in results from erlang:nodes().
217 * nodedown messages are delivered after the corresponding node
219 has disappeared in results from erlang:nodes().
220 * As of OTP 23.0, a nodedown message for a connection being
222 taken down will be delivered before a nodeup message due to
223 a new connection to the same node. Prior to OTP 23.0, this
224 was not guaranteed to be the case.
225 The format of the node status change messages depends on Op‐
227 tions. If Options is the empty list or if net_kernel:moni‐
228 tor_nodes/1 is called, the format is as follows:
229 {nodeup, Node} | {nodedown, Node}
231 Node = node()
232 When Options is the empty map or empty list, the caller will
234 only subscribe for status change messages for visible nodes.
235 That is, only nodes that appear in the result of erlang:nodes/0.
236 If Options equals anything other than the empty list, the format
238 of the status change messages is as follows:
239 {nodeup, Node, Info} | {nodedown, Node, Info}
241 Node = node()
242 Info = #{Tag => Val} | [{Tag, Val}]
243 Info is either a map or a list of 2-tuples. Its content depends
245 on Options. If Options is a map, Info will also be a map. If Op‐
246 tions is a list, Info will also be a list.
247 When Options is a map, currently the following associations are
249 allowed:
250 connection_id => boolean():
252 If the value of the association equals true, a connection_id
253 => ConnectionId association will be included in the Info map
254 where ConnectionId is the connection identifier of the con‐
255 nection coming up or going down. For more info about this
256 connection identifier see the documentation of er‐
257 lang:nodes/2.
258 node_type => NodeType:
260 Valid values for NodeType:
261 visible:
263 Subscribe to node status change messages for visible nodes
264 only. The association node_type => visible will be in‐
265 cluded in the Info map.
266 hidden:
268 Subscribe to node status change messages for hidden nodes
269 only. The association node_type => hidden will be included
270 in the Info map.
271 all:
273 Subscribe to node status change messages for both visible
274 and hidden nodes. The association node_type => visible |
275 hidden will be included in the Info map.
276 If no node_type => NodeType association is included in the
278 Options map, the caller will subscribe for status change
279 messages for visible nodes only, but no node_type => visi‐
280 ble association will be included in the Info map.
281 nodedown_reason => boolean():
283 If the value of the association equals true, a nodedown_rea‐
284 son => Reason association will be included in the Info map
285 for nodedown messages.
286 Reason can, depending on which distribution module or
288 process that is used, be any term, but for the standard TCP
289 distribution module it is one of the following:
290 connection_setup_failed:
292 The connection setup failed (after nodeup messages were
293 sent).
294 no_network:
296 No network is available.
297 net_kernel_terminated:
299 The net_kernel process terminated.
300 shutdown:
302 Unspecified connection shutdown.
303 connection_closed:
305 The connection was closed.
306 disconnect:
308 The connection was disconnected (forced from the current
309 node).
310 net_tick_timeout:
312 Net tick time-out.
313 send_net_tick_failed:
315 Failed to send net tick over the connection.
316 get_status_failed:
318 Status information retrieval from the Port holding the
319 connection failed.
320 When Options is a list, currently ListOption can be one of the
322 following:
323 connection_id:
325 A {connection_id, ConnectionId} tuple will be included in
326 Info where ConnectionId is the connection identifier of the
327 connection coming up or going down. For more info about this
328 connection identifier see the documentation of er‐
329 lang:nodes/2.
330 {node_type, NodeType}:
332 Valid values for NodeType:
333 visible:
335 Subscribe to node status change messages for visible nodes
336 only. The tuple {node_type, visible} will be included in
337 the Info list.
338 hidden:
340 Subscribe to node status change messages for hidden nodes
341 only. The tuple {node_type, hidden} will be included in
342 the Info list.
343 all:
345 Subscribe to node status change messages for both visible
346 and hidden nodes. The tuple {node_type, visible | hidden}
347 will be included in the Info list.
348 If no {node_type, NodeType} option has been given. The
350 caller will subscribe for status change messages for visible
351 nodes only, but no {node_type, visible} tuple will be in‐
352 cluded in the Info list.
353 nodedown_reason:
355 The tuple {nodedown_reason, Reason} will be included in the
356 Info list for nodedown messages.
357 See the documentation of the nodedown_reason => boolean()
359 association above for information about possible Reason val‐
360 ues.
361 Example:
363 (a@localhost)1> net_kernel:monitor_nodes(true, #{connection_id=>true, node_type=>all, nodedown_reason=>true}).
365 ok
366 (a@localhost)2> flush().
367 Shell got {nodeup,b@localhost,
368 #{connection_id => 3067552,node_type => visible}}
369 Shell got {nodeup,c@localhost,
370 #{connection_id => 13892107,node_type => hidden}}
371 Shell got {nodedown,b@localhost,
372 #{connection_id => 3067552,node_type => visible,
373 nodedown_reason => connection_closed}}
374 Shell got {nodedown,c@localhost,
375 #{connection_id => 13892107,node_type => hidden,
376 nodedown_reason => net_tick_timeout}}
377 Shell got {nodeup,b@localhost,
378 #{connection_id => 3067553,node_type => visible}}
379 ok
380 (a@localhost)3>
381 set_net_ticktime(NetTicktime) -> Res
384 set_net_ticktime(NetTicktime, TransitionPeriod) -> Res
386 Types:
388 NetTicktime = integer() >= 1
390 TransitionPeriod = integer() >= 0
391 Res =
392 unchanged | change_initiated |
393 {ongoing_change_to, NewNetTicktime}
394 NewNetTicktime = integer() >= 1
395 Sets net_ticktime (see kernel(6)) to NetTicktime seconds. Tran‐
397 sitionPeriod defaults to 60.
398 Some definitions:
400 Minimum transition traffic interval (MTTI):
402 minimum(NetTicktime, PreviousNetTicktime)*1000 div 4 mil‐
403 liseconds.
404 Transition period:
406 The time of the least number of consecutive MTTIs to cover
407 TransitionPeriod seconds following the call to set_net_tick‐
408 time/2 (that is, ((TransitionPeriod*1000 - 1) div MTTI +
409 1)*MTTI milliseconds).
410 If NetTicktime < PreviousNetTicktime, the net_ticktime change is
412 done at the end of the transition period; otherwise at the be‐
413 ginning. During the transition period, net_kernel ensures that
414 there is outgoing traffic on all connections at least every MTTI
415 millisecond.
416 Note:
418 The net_ticktime changes must be initiated on all nodes in the
419 network (with the same NetTicktime) before the end of any tran‐
420 sition period on any node; otherwise connections can erroneously
421 be disconnected.
422 Returns one of the following:
425 unchanged:
427 net_ticktime already has the value of NetTicktime and is
428 left unchanged.
429 change_initiated:
431 net_kernel initiated the change of net_ticktime to NetTick‐
432 time seconds.
433 {ongoing_change_to, NewNetTicktime}:
435 The request is ignored because net_kernel is busy changing
436 net_ticktime to NewNetTicktime seconds.
437 setopts(Node, Options) -> ok | {error, Reason} | ignored
439 Types:
441 Node = node() | new
443 Options = [inet:socket_setopt()]
444 Reason = inet:posix() | noconnection
445 Set one or more options for distribution sockets. Argument Node
447 can be either one node name or the atom new to affect the dis‐
448 tribution sockets of all future connected nodes.
449 The return value is the same as from inet:setopts/2 or {error,
451 noconnection} if Node is not a connected node or new.
452 If Node is new the Options will then also be added to kernel
454 configuration parameters inet_dist_listen_options and
455 inet_dist_connect_options.
456 Returns ignored if the local node is not alive.
458 start(Name, Options) -> {ok, pid()} | {error, Reason}
460 Types:
462 Options =
464 #{name_domain => NameDomain,
465 net_ticktime => NetTickTime,
466 net_tickintensity => NetTickIntensity,
467 dist_listen => boolean(),
468 hidden => boolean()}
469 Name = atom()
470 NameDomain = shortnames | longnames
471 NetTickTime = integer() >= 1
472 NetTickIntensity = 4..1000
473 Reason = {already_started, pid()} | term()
474 Turns a non-distributed node into a distributed node by starting
476 net_kernel and other necessary processes.
477 If Name is set to undefined the distribution will be started to
479 request a dynamic node name from the first node it connects to.
480 See Dynamic Node Name. Setting Name to undefined implies op‐
481 tions dist_listen => false and hidden => true.
482 Currently supported options:
484 name_domain => NameDomain:
486 Determines the host name part of the node name. If NameDo‐
487 main equals longnames, fully qualified domain names will be
488 used which also is the default. If NameDomain equals short‐
489 names, only the short name of the host will be used.
490 net_ticktime => NetTickTime:
492 Net tick time to use in seconds. Defaults to the value of
493 the net_ticktime kernel(6) parameter. For more information
494 about net tick time , see the kernel parameter. However,
495 note that if the value of the kernel parameter is invalid,
496 it will silently be replaced by a valid value, but if an in‐
497 valid NetTickTime value is passed as option value to this
498 function, the call will fail.
499 net_tickintensity => NetTickIntensity:
501 Net tick intensity to use. Defaults to the value of the
502 net_tickintensity kernel(6) parameter. For more information
503 about net tick intensity , see the kernel parameter. How‐
504 ever, note that if the value of the kernel parameter is in‐
505 valid, it will silently be replaced by a valid value, but if
506 an invalid NetTickIntensity value is passed as option value
507 to this function, the call will fail.
508 dist_listen => boolean():
510 Enable or disable listening for incoming connections. De‐
511 faults to the value of the -dist_listen erl command line ar‐
512 gument. Note that dist_listen => false implies hidden =>
513 true.
514 If undefined has been passed as Name, the dist_listen option
516 will be overridden with dist_listen => false.
517 hidden => boolean():
519 Enable or disable hidden node. Defaults to true if the -hid‐
520 den erl command line argument has been passed; otherwise
521 false.
522 If undefined has been passed as Name, or the option
524 dist_listen equals false, the hidden option will be overrid‐
525 den with hidden => true.
526 start(Options) -> {ok, pid()} | {error, Reason}
528 Types:
530 Options = [Name | NameDomain | TickTime, ...]
532 Name = atom()
533 NameDomain = shortnames | longnames
534 TickTime = integer() >= 1
535 Reason = {already_started, pid()} | term()
536 Warning:
538 start/1 is deprecated. Use start/2 instead.
539 Turns a non-distributed node into a distributed node by starting
542 net_kernel and other necessary processes.
543 Options list can only be exactly one of the following lists (or‐
545 der is imporant):
546 [Name]:
548 The same as net_kernel:start([Name, longnames, 15000]).
549 [Name, NameDomain]:
551 The same as net_kernel:start([Name, NameDomain, 15000]).
552 [Name, NameDomain, TickTime]:
554 The same as net_kernel:start(Name, #{name_domain => NameDo‐
555 main, net_ticktime => ((TickTime*4-1) div 1000) + 1,
556 net_tickintensity => 4}). Note that TickTime is not the
557 same as net tick time expressed in milliseconds. TickTime is
558 the time between ticks when net tick intensity equals 4.
559 stop() -> ok | {error, Reason}
561 Types:
563 Reason = not_allowed | not_found
565 Turns a distributed node into a non-distributed node. For other
567 nodes in the network, this is the same as the node going down.
568 Only possible when the net kernel was started using start/2,
569 otherwise {error, not_allowed} is returned. Returns {error,
570 not_found} if the local node is not alive.
571Ericsson AB kernel 8.5.3 net_kernel(3)