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, 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              Gets net_ticktime (see kernel(6)).
91
92              Defined return values (Res):
93
94                NetTicktime:
95                  net_ticktime is NetTicktime seconds.
96
97                {ongoing_change_to, NetTicktime}:
98                  net_kernel is currently changing net_ticktime to NetTicktime
99                  seconds.
100
101                ignored:
102                  The local node is not alive.
103
104       getopts(Node, Options) ->
105                  {ok, OptionValues} | {error, Reason} | ignored
106
107              Types:
108
109                 Node = node()
110                 Options = [inet:socket_getopt()]
111                 OptionValues = [inet:socket_setopt()]
112                 Reason = inet:posix() | noconnection
113
114              Get one or more options for the distribution socket connected to
115              Node.
116
117              If Node is a connected node the return value is the same as from
118              inet:getopts(Sock,  Options)  where  Sock  is  the  distribution
119              socket for Node.
120
121              Returns ignored if the local node is not alive or {error, nocon‐
122              nection} if Node is not connected.
123
124       monitor_nodes(Flag) -> ok | Error
125
126       monitor_nodes(Flag, Options) -> ok | Error
127
128              Types:
129
130                 Flag = boolean()
131                 Options = [Option]
132                 Option = {node_type, NodeType} | nodedown_reason
133                 NodeType = visible | hidden | all
134                 Error = error | {error, term()}
135
136              The  calling  process  subscribes or unsubscribes to node status
137              change messages. A nodeup message is delivered to all  subscrib‐
138              ing  processes when a new node is connected, and a nodedown mes‐
139              sage is delivered when a node is disconnected.
140
141              If Flag is true, a new  subscription  is  started.  If  Flag  is
142              false,  all previous subscriptions started with the same Options
143              are stopped. Two option lists are considered the  same  if  they
144              contain the same set of options.
145
146              As  from Kernel version 2.11.4, and ERTS version 5.5.4, the fol‐
147              lowing is guaranteed:
148
149                * nodeup messages are delivered before delivery of any message
150                  from  the  remote  node passed through the newly established
151                  connection.
152
153                * nodedown messages are not delivered until all messages  from
154                  the remote node that have been passed through the connection
155                  have been delivered.
156
157              Notice that this is not guaranteed for  Kernel  versions  before
158              2.11.4.
159
160              As  from  Kernel  version 2.11.4, subscriptions can also be made
161              before the net_kernel  server  is  started,  that  is,  net_ker‐
162              nel:monitor_nodes/[1,2] does not return ignored.
163
164              As from Kernel version 2.13, and ERTS version 5.7, the following
165              is guaranteed:
166
167                * nodeup messages are delivered after the  corresponding  node
168                  appears in results from erlang:nodes/X.
169
170                * nodedown messages are delivered after the corresponding node
171                  has disappeared in results from erlang:nodes/X.
172
173              Notice that this is not guaranteed for  Kernel  versions  before
174              2.13.
175
176              The  format  of  the  node status change messages depends on Op‐
177              tions. If Options is [], which is the default, the format is  as
178              follows:
179
180              {nodeup, Node} | {nodedown, Node}
181                Node = node()
182
183              If Options is not [], the format is as follows:
184
185              {nodeup, Node, InfoList} | {nodedown, Node, InfoList}
186                Node = node()
187                InfoList = [{Tag, Val}]
188
189              InfoList  is  a list of tuples. Its contents depends on Options,
190              see below.
191
192              Also, when OptionList == [], only visible nodes, that is,  nodes
193              that appear in the result of erlang:nodes/0, are monitored.
194
195              Option can be any of the following:
196
197                {node_type, NodeType}:
198                  Valid values for NodeType:
199
200                  visible:
201                    Subscribe to node status change messages for visible nodes
202                    only. The tuple {node_type, visible} is  included  in  In‐
203                    foList.
204
205                  hidden:
206                    Subscribe  to node status change messages for hidden nodes
207                    only. The tuple {node_type, hidden}  is  included  in  In‐
208                    foList.
209
210                  all:
211                    Subscribe  to node status change messages for both visible
212                    and hidden nodes. The tuple {node_type, visible |  hidden}
213                    is included in InfoList.
214
215                nodedown_reason:
216                  The  tuple {nodedown_reason, Reason} is included in InfoList
217                  in nodedown messages.
218
219                  Reason  can,  depending  on  which  distribution  module  or
220                  process  that  is used be any term, but for the standard TCP
221                  distribution module it is any of the following:
222
223                  connection_setup_failed:
224                    The connection setup failed (after  nodeup  messages  were
225                    sent).
226
227                  no_network:
228                    No network is available.
229
230                  net_kernel_terminated:
231                    The net_kernel process terminated.
232
233                  shutdown:
234                    Unspecified connection shutdown.
235
236                  connection_closed:
237                    The connection was closed.
238
239                  disconnect:
240                    The  connection  was disconnected (forced from the current
241                    node).
242
243                  net_tick_timeout:
244                    Net tick time-out.
245
246                  send_net_tick_failed:
247                    Failed to send net tick over the connection.
248
249                  get_status_failed:
250                    Status information retrieval from  the  Port  holding  the
251                    connection failed.
252
253       set_net_ticktime(NetTicktime) -> Res
254
255       set_net_ticktime(NetTicktime, TransitionPeriod) -> Res
256
257              Types:
258
259                 NetTicktime = integer() >= 1
260                 TransitionPeriod = integer() >= 0
261                 Res =
262                     unchanged | change_initiated |
263                     {ongoing_change_to, NewNetTicktime}
264                 NewNetTicktime = integer() >= 1
265
266              Sets  net_ticktime (see kernel(6)) to NetTicktime seconds. Tran‐
267              sitionPeriod defaults to 60.
268
269              Some definitions:
270
271                Minimum transition traffic interval (MTTI):
272                  minimum(NetTicktime, PreviousNetTicktime)*1000  div  4  mil‐
273                  liseconds.
274
275                Transition period:
276                  The  time  of the least number of consecutive MTTIs to cover
277                  TransitionPeriod seconds following the call to set_net_tick‐
278                  time/2  (that  is,  ((TransitionPeriod*1000  - 1) div MTTI +
279                  1)*MTTI milliseconds).
280
281              If NetTicktime < PreviousNetTicktime, the net_ticktime change is
282              done  at  the end of the transition period; otherwise at the be‐
283              ginning. During the transition period, net_kernel  ensures  that
284              there is outgoing traffic on all connections at least every MTTI
285              millisecond.
286
287          Note:
288              The net_ticktime changes must be initiated on all nodes  in  the
289              network  (with the same NetTicktime) before the end of any tran‐
290              sition period on any node; otherwise connections can erroneously
291              be disconnected.
292
293
294              Returns one of the following:
295
296                unchanged:
297                  net_ticktime  already  has  the  value of NetTicktime and is
298                  left unchanged.
299
300                change_initiated:
301                  net_kernel initiated the change of net_ticktime to  NetTick‐
302                  time seconds.
303
304                {ongoing_change_to, NewNetTicktime}:
305                  The  request  is ignored because net_kernel is busy changing
306                  net_ticktime to NewNetTicktime seconds.
307
308       setopts(Node, Options) -> ok | {error, Reason} | ignored
309
310              Types:
311
312                 Node = node() | new
313                 Options = [inet:socket_setopt()]
314                 Reason = inet:posix() | noconnection
315
316              Set one or more options for distribution sockets. Argument  Node
317              can  be  either one node name or the atom new to affect the dis‐
318              tribution sockets of all future connected nodes.
319
320              The return value is the same as from inet:setopts/2  or  {error,
321              noconnection} if Node is not a connected node or new.
322
323              If  Node  is  new  the Options will then also be added to kernel
324              configration     parameters     inet_dist_listen_options     and
325              inet_dist_connect_options.
326
327              Returns ignored if the local node is not alive.
328
329       start([Name]) -> {ok, pid()} | {error, Reason}
330       start([Name, NameType]) -> {ok, pid()} | {error, Reason}
331       start([Name, NameType, Ticktime]) -> {ok, pid()} | {error, Reason}
332
333              Types:
334
335                 Name = atom()
336                 NameType = shortnames | longnames
337                 Reason = {already_started, pid()} | term()
338
339              Turns a non-distributed node into a distributed node by starting
340              net_kernel and other necessary processes.
341
342              Notice that the argument is a list with  exactly  one,  two,  or
343              three  arguments. NameType defaults to longnames and Ticktime to
344              15000.
345
346       stop() -> ok | {error, Reason}
347
348              Types:
349
350                 Reason = not_allowed | not_found
351
352              Turns a distributed node into a non-distributed node. For  other
353              nodes  in  the network, this is the same as the node going down.
354              Only possible when the net kernel  was  started  using  start/1,
355              otherwise  {error,  not_allowed}  is  returned.  Returns {error,
356              not_found} if the local node is not alive.
357
358
359
360Ericsson AB                      kernel 8.1.3                    net_kernel(3)
Impressum