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