1net_kernel(3)              Erlang Module Definition              net_kernel(3)
2
3
4

NAME

6       net_kernel - Erlang networking kernel.
7

DESCRIPTION

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
14       An Erlang node is started using command-line flag -name or -sname:
15
16       $ erl -sname foobar
17
18       It is also possible to call net_kernel:start(foobar, #{}) directly from
19       the normal Erlang shell prompt:
20
21       1> net_kernel:start(foobar, #{name_domain => shortnames}).
22       {ok,<0.64.0>}
23       (foobar@gringotts)2>
24
25       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
31       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
37       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
41   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
50

EXPORTS

52       allow(Nodes) -> ok | error
53
54              Types:
55
56                 Nodes = [node()]
57
58              Permits access to the specified set of nodes.
59
60              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
65              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
69              Returns error if any element in Nodes is not an atom.
70
71       connect_node(Node) -> boolean() | ignored
72
73              Types:
74
75                 Node = node()
76
77              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
82       get_net_ticktime() -> Res
83
84              Types:
85
86                 Res  =  NetTicktime  | {ongoing_change_to, NetTicktime} | ig‐
87                 nored
88                 NetTicktime = integer() >= 1
89
90              Returns currently used net tick time in seconds. For more infor‐
91              mation see the net_ticktime kernel(6) parameter.
92
93              Defined return values (Res):
94
95                NetTicktime:
96                  net_ticktime is NetTicktime seconds.
97
98                {ongoing_change_to, NetTicktime}:
99                  net_kernel is currently changing net_ticktime to NetTicktime
100                  seconds.
101
102                ignored:
103                  The local node is not alive.
104
105       getopts(Node, Options) ->
106                  {ok, OptionValues} | {error, Reason} | ignored
107
108              Types:
109
110                 Node = node()
111                 Options = [inet:socket_getopt()]
112                 OptionValues = [inet:socket_setopt()]
113                 Reason = inet:posix() | noconnection
114
115              Get one or more options for the distribution socket connected to
116              Node.
117
118              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
122              Returns ignored if the local node is not alive or {error, nocon‐
123              nection} if Node is not connected.
124
125       get_state() ->
126                    #{started => no | static | dynamic,
127                      name => atom(),
128                      name_type => static | dynamic,
129                      name_domain => shortnames | longnames}
130
131              Get the current state of the distribution for the local node.
132
133              Returns a map with (at least) the following key-value pairs:
134
135                started => Started:
136                  Valid values for Started:
137
138                  no:
139                    The distribution is not started. In this state none of the
140                    other keys below are present in the map.
141
142                  static:
143                    The  distribution  was started with command line arguments
144                    -name or -sname.
145
146                  dynamic:
147                    The distribution was started with  net_kernel:start/1  and
148                    can be stopped with net_kernel:stop/0.
149
150                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
155                name_type => NameType:
156                  Valid values for NameType:
157
158                  static:
159                    The node has a static node name set by the node itself.
160
161                  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
167                name_domain => NameDomain:
168                  Valid values for NameDomain:
169
170                  shortnames:
171                    The distribution was started to  use  node  names  with  a
172                    short host portion (not fully qualified).
173
174                  longnames:
175                    The distribution was started to use node names with a long
176                    fully qualified host portion.
177
178       monitor_nodes(Flag) -> ok | Error
179
180       monitor_nodes(Flag, Options) -> ok | Error
181
182              Types:
183
184                 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
196              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
201              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
206              Delivery guarantees of nodeup/nodedown messages:
207
208                * nodeup messages are delivered before delivery of any signals
209                  from  the  remote node through the newly established connec‐
210                  tion.
211
212                * nodedown messages are delivered after all the  signals  from
213                  the remote node over the connection have been delivered.
214
215                * nodeup  messages  are delivered after the corresponding node
216                  appears in results from erlang:nodes().
217
218                * nodedown messages are delivered after the corresponding node
219                  has disappeared in results from erlang:nodes().
220
221                * 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
226              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
230              {nodeup, Node} | {nodedown, Node}
231                Node = node()
232
233              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
237              If Options equals anything other than the empty list, the format
238              of the status change messages is as follows:
239
240              {nodeup, Node, Info} | {nodedown, Node, Info}
241                Node = node()
242                Info = #{Tag => Val} | [{Tag, Val}]
243
244              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
248              When  Options is a map, currently the following associations are
249              allowed:
250
251                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
259                node_type => NodeType:
260                  Valid values for NodeType:
261
262                  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
267                  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
272                  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
277                  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
282                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
287                  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
291                  connection_setup_failed:
292                    The connection setup failed (after  nodeup  messages  were
293                    sent).
294
295                  no_network:
296                    No network is available.
297
298                  net_kernel_terminated:
299                    The net_kernel process terminated.
300
301                  shutdown:
302                    Unspecified connection shutdown.
303
304                  connection_closed:
305                    The connection was closed.
306
307                  disconnect:
308                    The  connection  was disconnected (forced from the current
309                    node).
310
311                  net_tick_timeout:
312                    Net tick time-out.
313
314                  send_net_tick_failed:
315                    Failed to send net tick over the connection.
316
317                  get_status_failed:
318                    Status information retrieval from  the  Port  holding  the
319                    connection failed.
320
321              When  Options  is a list, currently ListOption can be one of the
322              following:
323
324                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
331                {node_type, NodeType}:
332                  Valid values for NodeType:
333
334                  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
339                  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
344                  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
349                  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
354                nodedown_reason:
355                  The  tuple {nodedown_reason, Reason} will be included in the
356                  Info list for nodedown messages.
357
358                  See the documentation of the  nodedown_reason  =>  boolean()
359                  association above for information about possible Reason val‐
360                  ues.
361
362              Example:
363
364              (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
382
383       set_net_ticktime(NetTicktime) -> Res
384
385       set_net_ticktime(NetTicktime, TransitionPeriod) -> Res
386
387              Types:
388
389                 NetTicktime = integer() >= 1
390                 TransitionPeriod = integer() >= 0
391                 Res =
392                     unchanged | change_initiated |
393                     {ongoing_change_to, NewNetTicktime}
394                 NewNetTicktime = integer() >= 1
395
396              Sets net_ticktime (see kernel(6)) to NetTicktime seconds.  Tran‐
397              sitionPeriod defaults to 60.
398
399              Some definitions:
400
401                Minimum transition traffic interval (MTTI):
402                  minimum(NetTicktime,  PreviousNetTicktime)*1000  div  4 mil‐
403                  liseconds.
404
405                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
411              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
417          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
423
424              Returns one of the following:
425
426                unchanged:
427                  net_ticktime already has the value  of  NetTicktime  and  is
428                  left unchanged.
429
430                change_initiated:
431                  net_kernel  initiated the change of net_ticktime to NetTick‐
432                  time seconds.
433
434                {ongoing_change_to, NewNetTicktime}:
435                  The request is ignored because net_kernel is  busy  changing
436                  net_ticktime to NewNetTicktime seconds.
437
438       setopts(Node, Options) -> ok | {error, Reason} | ignored
439
440              Types:
441
442                 Node = node() | new
443                 Options = [inet:socket_setopt()]
444                 Reason = inet:posix() | noconnection
445
446              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
450              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
453              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
457              Returns ignored if the local node is not alive.
458
459       start(Name, Options) -> {ok, pid()} | {error, Reason}
460
461              Types:
462
463                 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
475              Turns a non-distributed node into a distributed node by starting
476              net_kernel and other necessary processes.
477
478              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
483              Currently supported options:
484
485                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
491                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
500                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
509                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
515                  If undefined has been passed as Name, the dist_listen option
516                  will be overridden with dist_listen => false.
517
518                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
523                  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
527       start(Options) -> {ok, pid()} | {error, Reason}
528
529              Types:
530
531                 Options = [Name | NameDomain | TickTime, ...]
532                 Name = atom()
533                 NameDomain = shortnames | longnames
534                 TickTime = integer() >= 1
535                 Reason = {already_started, pid()} | term()
536
537          Warning:
538              start/1 is deprecated. Use start/2 instead.
539
540
541              Turns a non-distributed node into a distributed node by starting
542              net_kernel and other necessary processes.
543
544              Options list can only be exactly one of the following lists (or‐
545              der is imporant):
546
547                [Name]:
548                  The same as net_kernel:start([Name, longnames, 15000]).
549
550                [Name, NameDomain]:
551                  The same as net_kernel:start([Name, NameDomain, 15000]).
552
553                [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
560       stop() -> ok | {error, Reason}
561
562              Types:
563
564                 Reason = not_allowed | not_found
565
566              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.
571
572
573
574Ericsson AB                     kernel 8.5.4.2                   net_kernel(3)
Impressum