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 monitor_nodes(Flag) -> ok | Error
126 monitor_nodes(Flag, Options) -> ok | Error
128 Types:
130 Flag = boolean()
132 Options = [Option]
133 Option = {node_type, NodeType} | nodedown_reason
134 NodeType = visible | hidden | all
135 Error = error | {error, term()}
136 The calling process subscribes or unsubscribes to node status
138 change messages. A nodeup message is delivered to all subscrib‐
139 ing processes when a new node is connected, and a nodedown mes‐
140 sage is delivered when a node is disconnected.
141 If Flag is true, a new subscription is started. If Flag is
143 false, all previous subscriptions started with the same Options
144 are stopped. Two option lists are considered the same if they
145 contain the same set of options.
146 As from Kernel version 2.11.4, and ERTS version 5.5.4, the fol‐
148 lowing is guaranteed:
149 * nodeup messages are delivered before delivery of any message
151 from the remote node passed through the newly established
152 connection.
153 * nodedown messages are not delivered until all messages from
155 the remote node that have been passed through the connection
156 have been delivered.
157 Notice that this is not guaranteed for Kernel versions before
159 2.11.4.
160 As from Kernel version 2.11.4, subscriptions can also be made
162 before the net_kernel server is started, that is, net_ker‐
163 nel:monitor_nodes/[1,2] does not return ignored.
164 As from Kernel version 2.13, and ERTS version 5.7, the following
166 is guaranteed:
167 * nodeup messages are delivered after the corresponding node
169 appears in results from erlang:nodes/X.
170 * nodedown messages are delivered after the corresponding node
172 has disappeared in results from erlang:nodes/X.
173 Notice that this is not guaranteed for Kernel versions before
175 2.13.
176 The format of the node status change messages depends on Op‐
178 tions. If Options is [], which is the default, the format is as
179 follows:
180 {nodeup, Node} | {nodedown, Node}
182 Node = node()
183 If Options is not [], the format is as follows:
185 {nodeup, Node, InfoList} | {nodedown, Node, InfoList}
187 Node = node()
188 InfoList = [{Tag, Val}]
189 InfoList is a list of tuples. Its contents depends on Options,
191 see below.
192 Also, when OptionList == [], only visible nodes, that is, nodes
194 that appear in the result of erlang:nodes/0, are monitored.
195 Option can be any of the following:
197 {node_type, NodeType}:
199 Valid values for NodeType:
200 visible:
202 Subscribe to node status change messages for visible nodes
203 only. The tuple {node_type, visible} is included in In‐
204 foList.
205 hidden:
207 Subscribe to node status change messages for hidden nodes
208 only. The tuple {node_type, hidden} is included in In‐
209 foList.
210 all:
212 Subscribe to node status change messages for both visible
213 and hidden nodes. The tuple {node_type, visible | hidden}
214 is included in InfoList.
215 nodedown_reason:
217 The tuple {nodedown_reason, Reason} is included in InfoList
218 in nodedown messages.
219 Reason can, depending on which distribution module or
221 process that is used be any term, but for the standard TCP
222 distribution module it is any of the following:
223 connection_setup_failed:
225 The connection setup failed (after nodeup messages were
226 sent).
227 no_network:
229 No network is available.
230 net_kernel_terminated:
232 The net_kernel process terminated.
233 shutdown:
235 Unspecified connection shutdown.
236 connection_closed:
238 The connection was closed.
239 disconnect:
241 The connection was disconnected (forced from the current
242 node).
243 net_tick_timeout:
245 Net tick time-out.
246 send_net_tick_failed:
248 Failed to send net tick over the connection.
249 get_status_failed:
251 Status information retrieval from the Port holding the
252 connection failed.
253 set_net_ticktime(NetTicktime) -> Res
255 set_net_ticktime(NetTicktime, TransitionPeriod) -> Res
257 Types:
259 NetTicktime = integer() >= 1
261 TransitionPeriod = integer() >= 0
262 Res =
263 unchanged | change_initiated |
264 {ongoing_change_to, NewNetTicktime}
265 NewNetTicktime = integer() >= 1
266 Sets net_ticktime (see kernel(6)) to NetTicktime seconds. Tran‐
268 sitionPeriod defaults to 60.
269 Some definitions:
271 Minimum transition traffic interval (MTTI):
273 minimum(NetTicktime, PreviousNetTicktime)*1000 div 4 mil‐
274 liseconds.
275 Transition period:
277 The time of the least number of consecutive MTTIs to cover
278 TransitionPeriod seconds following the call to set_net_tick‐
279 time/2 (that is, ((TransitionPeriod*1000 - 1) div MTTI +
280 1)*MTTI milliseconds).
281 If NetTicktime < PreviousNetTicktime, the net_ticktime change is
283 done at the end of the transition period; otherwise at the be‐
284 ginning. During the transition period, net_kernel ensures that
285 there is outgoing traffic on all connections at least every MTTI
286 millisecond.
287 Note:
289 The net_ticktime changes must be initiated on all nodes in the
290 network (with the same NetTicktime) before the end of any tran‐
291 sition period on any node; otherwise connections can erroneously
292 be disconnected.
293 Returns one of the following:
296 unchanged:
298 net_ticktime already has the value of NetTicktime and is
299 left unchanged.
300 change_initiated:
302 net_kernel initiated the change of net_ticktime to NetTick‐
303 time seconds.
304 {ongoing_change_to, NewNetTicktime}:
306 The request is ignored because net_kernel is busy changing
307 net_ticktime to NewNetTicktime seconds.
308 setopts(Node, Options) -> ok | {error, Reason} | ignored
310 Types:
312 Node = node() | new
314 Options = [inet:socket_setopt()]
315 Reason = inet:posix() | noconnection
316 Set one or more options for distribution sockets. Argument Node
318 can be either one node name or the atom new to affect the dis‐
319 tribution sockets of all future connected nodes.
320 The return value is the same as from inet:setopts/2 or {error,
322 noconnection} if Node is not a connected node or new.
323 If Node is new the Options will then also be added to kernel
325 configration parameters inet_dist_listen_options and
326 inet_dist_connect_options.
327 Returns ignored if the local node is not alive.
329 start(Name, Options) -> {ok, pid()} | {error, Reason}
331 Types:
333 Options =
335 #{name_domain => NameDomain,
336 net_ticktime => NetTickTime,
337 net_tickintensity => NetTickIntensity}
338 Name = atom()
339 NameDomain = shortnames | longnames
340 NetTickTime = integer() >= 1
341 NetTickIntensity = 4..1000
342 Reason = {already_started, pid()} | term()
343 Turns a non-distributed node into a distributed node by starting
345 net_kernel and other necessary processes.
346 If Name is set to undefined the distribution will be started to
348 request a dynamic node name from the first node it connects to.
349 See Dynamic Node Name.
350 Currently supported options:
352 name_domain => NameDomain:
354 Determines the host name part of the node name. If NameDo‐
355 main equals longnames, fully qualified domain names will be
356 used which also is the default. If NameDomain equals short‐
357 names, only the short name of the host will be used.
358 net_ticktime => NetTickTime:
360 Net tick time to use in seconds. Defaults to the value of
361 the net_ticktime kernel(6) parameter. For more information
362 about net tick time , see the kernel parameter. However,
363 note that if the value of the kernel parameter is invalid,
364 it will silently be replaced by a valid value, but if an in‐
365 valid NetTickTime value is passed as option value to this
366 function, the call will fail.
367 net_tickintensity => NetTickIntensity:
369 Net tick intensity to use. Defaults to the value of the
370 net_tickintensity kernel(6) parameter. For more information
371 about net tick intensity , see the kernel parameter. How‐
372 ever, note that if the value of the kernel parameter is in‐
373 valid, it will silently be replaced by a valid value, but if
374 an invalid NetTickIntensity value is passed as option value
375 to this function, the call will fail.
376 start(Options) -> {ok, pid()} | {error, Reason}
378 Types:
380 Options = [Name | NameDomain | TickTime, ...]
382 Name = atom()
383 NameDomain = shortnames | longnames
384 TickTime = integer() >= 1
385 Reason = {already_started, pid()} | term()
386 Warning:
388 start/1 is deprecated. Use start/2 instead.
389 Turns a non-distributed node into a distributed node by starting
392 net_kernel and other necessary processes.
393 Options list can only be exactly one of the following lists (or‐
395 der is imporant):
396 [Name]:
398 The same as net_kernel:start([Name, longnames, 15000]).
399 [Name, NameDomain]:
401 The same as net_kernel:start([Name, NameDomain, 15000]).
402 [Name, NameDomain, TickTime]:
404 The same as net_kernel:start(Name, #{name_domain => NameDo‐
405 main, net_ticktime => ((TickTime*4-1) div 1000) + 1,
406 net_tickintensity => 4}). Note that TickTime is not the
407 same as net tick time expressed in milliseconds. TickTime is
408 the time between ticks when net tick intensity equals 4.
409 stop() -> ok | {error, Reason}
411 Types:
413 Reason = not_allowed | not_found
415 Turns a distributed node into a non-distributed node. For other
417 nodes in the network, this is the same as the node going down.
418 Only possible when the net kernel was started using start/2,
419 otherwise {error, not_allowed} is returned. Returns {error,
420 not_found} if the local node is not alive.
421Ericsson AB kernel 8.3.2 net_kernel(3)