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 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 Gets net_ticktime (see kernel(6)).
91 Defined return values (Res):
93 NetTicktime:
95 net_ticktime is NetTicktime seconds.
96 {ongoing_change_to, NetTicktime}:
98 net_kernel is currently changing net_ticktime to NetTicktime
99 seconds.
100 ignored:
102 The local node is not alive.
103 getopts(Node, Options) ->
105 {ok, OptionValues} | {error, Reason} | ignored
106 Types:
108 Node = node()
110 Options = [inet:socket_getopt()]
111 OptionValues = [inet:socket_setopt()]
112 Reason = inet:posix() | noconnection
113 Get one or more options for the distribution socket connected to
115 Node.
116 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 Returns ignored if the local node is not alive or {error, nocon‐
122 nection} if Node is not connected.
123 monitor_nodes(Flag) -> ok | Error
125 monitor_nodes(Flag, Options) -> ok | Error
127 Types:
129 Flag = boolean()
131 Options = [Option]
132 Option = {node_type, NodeType} | nodedown_reason
133 NodeType = visible | hidden | all
134 Error = error | {error, term()}
135 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 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 As from Kernel version 2.11.4, and ERTS version 5.5.4, the fol‐
147 lowing is guaranteed:
148 * nodeup messages are delivered before delivery of any message
150 from the remote node passed through the newly established
151 connection.
152 * 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 Notice that this is not guaranteed for Kernel versions before
158 2.11.4.
159 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 As from Kernel version 2.13, and ERTS version 5.7, the following
165 is guaranteed:
166 * nodeup messages are delivered after the corresponding node
168 appears in results from erlang:nodes/X.
169 * nodedown messages are delivered after the corresponding node
171 has disappeared in results from erlang:nodes/X.
172 Notice that this is not guaranteed for Kernel versions before
174 2.13.
175 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 {nodeup, Node} | {nodedown, Node}
181 Node = node()
182 If Options is not [], the format is as follows:
184 {nodeup, Node, InfoList} | {nodedown, Node, InfoList}
186 Node = node()
187 InfoList = [{Tag, Val}]
188 InfoList is a list of tuples. Its contents depends on Options,
190 see below.
191 Also, when OptionList == [], only visible nodes, that is, nodes
193 that appear in the result of erlang:nodes/0, are monitored.
194 Option can be any of the following:
196 {node_type, NodeType}:
198 Valid values for NodeType:
199 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 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 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 nodedown_reason:
216 The tuple {nodedown_reason, Reason} is included in InfoList
217 in nodedown messages.
218 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 connection_setup_failed:
224 The connection setup failed (after nodeup messages were
225 sent).
226 no_network:
228 No network is available.
229 net_kernel_terminated:
231 The net_kernel process terminated.
232 shutdown:
234 Unspecified connection shutdown.
235 connection_closed:
237 The connection was closed.
238 disconnect:
240 The connection was disconnected (forced from the current
241 node).
242 net_tick_timeout:
244 Net tick time-out.
245 send_net_tick_failed:
247 Failed to send net tick over the connection.
248 get_status_failed:
250 Status information retrieval from the Port holding the
251 connection failed.
252 set_net_ticktime(NetTicktime) -> Res
254 set_net_ticktime(NetTicktime, TransitionPeriod) -> Res
256 Types:
258 NetTicktime = integer() >= 1
260 TransitionPeriod = integer() >= 0
261 Res =
262 unchanged | change_initiated |
263 {ongoing_change_to, NewNetTicktime}
264 NewNetTicktime = integer() >= 1
265 Sets net_ticktime (see kernel(6)) to NetTicktime seconds. Tran‐
267 sitionPeriod defaults to 60.
268 Some definitions:
270 Minimum transition traffic interval (MTTI):
272 minimum(NetTicktime, PreviousNetTicktime)*1000 div 4 mil‐
273 liseconds.
274 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 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 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 Returns one of the following:
295 unchanged:
297 net_ticktime already has the value of NetTicktime and is
298 left unchanged.
299 change_initiated:
301 net_kernel initiated the change of net_ticktime to NetTick‐
302 time seconds.
303 {ongoing_change_to, NewNetTicktime}:
305 The request is ignored because net_kernel is busy changing
306 net_ticktime to NewNetTicktime seconds.
307 setopts(Node, Options) -> ok | {error, Reason} | ignored
309 Types:
311 Node = node() | new
313 Options = [inet:socket_setopt()]
314 Reason = inet:posix() | noconnection
315 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 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 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 Returns ignored if the local node is not alive.
328 start([Name]) -> {ok, pid()} | {error, Reason}
330 start([Name, NameType]) -> {ok, pid()} | {error, Reason}
331 start([Name, NameType, Ticktime]) -> {ok, pid()} | {error, Reason}
332 Types:
334 Name = atom()
336 NameType = shortnames | longnames
337 Reason = {already_started, pid()} | term()
338 Turns a non-distributed node into a distributed node by starting
340 net_kernel and other necessary processes.
341 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 stop() -> ok | {error, Reason}
347 Types:
349 Reason = not_allowed | not_found
351 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.
357Ericsson AB kernel 8.1.3 net_kernel(3)