1kernel(7) Erlang Application Definition kernel(7)
2
6 kernel - The Kernel application.
7
9 The Kernel application has all the code necessary to run the Erlang
10 runtime system: file servers, code servers, and so on.
11 The Kernel application is the first application started. It is manda‐
13 tory in the sense that the minimal system based on Erlang/OTP consists
14 of Kernel and STDLIB. Kernel contains the following functional areas:
15 * Start, stop, supervision, configuration, and distribution of appli‐
17 cations
18 * Code loading
20 * Logging
22 * Global name service
24 * Supervision of Erlang/OTP
26 * Communication with sockets
28 * Operating system interface
30
32 Two standard logger handlers are defined in the Kernel application.
33 These are described in the Kernel User's Guide, and in the log‐
34 ger_std_h(3) and logger_disk_log_h(3) manual pages.
35
37 Asynchronous OS signals may be subscribed to via the Kernel applica‐
38 tions event manager (see OTP Design Principles and gen_event(3)) regis‐
39 tered as erl_signal_server. A default signal handler is installed which
40 handles the following signals:
41 sigusr1:
43 The default handler will halt Erlang and produce a crashdump with
44 slogan "Received SIGUSR1". This is equivalent to calling er‐
45 lang:halt("Received SIGUSR1").
46 sigquit:
48 The default handler will halt Erlang immediately. This is equiva‐
49 lent to calling erlang:halt().
50 sigterm:
52 The default handler will terminate Erlang normally. This is equiva‐
53 lent to calling init:stop().
54 Events
56 Any event handler added to erl_signal_server must handle the following
57 events.
58 sighup:
60 Hangup detected on controlling terminal or death of controlling
61 process
62 sigquit:
64 Quit from keyboard
65 sigabrt:
67 Abort signal from abort
68 sigalrm:
70 Timer signal from alarm
71 sigterm:
73 Termination signal
74 sigusr1:
76 User-defined signal 1
77 sigusr2:
79 User-defined signal 2
80 sigchld:
82 Child process stopped or terminated
83 sigstop:
85 Stop process
86 sigtstp:
88 Stop typed at terminal
89 Setting OS signals are described in os:set_signal/2.
91
93 The following configuration parameters are defined for the Kernel ap‐
94 plication. For more information about configuration parameters, see
95 file app(4).
96 connect_all = true | false:
98 If enabled (true), which also is the default, global(3) will ac‐
99 tively connect to all nodes that becomes known to it. Note that you
100 also want to enable prevent_overlapping_partitions in order for
101 global to ensure that a fully connected network is maintained. pre‐
102 vent_overlapping_partitions will also prevent inconsistencies in
103 global's name registration and locking.
104 The now deprecated command line argument -connect_all <boolean> has
106 the same effect as the connect_all configuration parameter. If this
107 configuration parameter is defined, it will override the command
108 line argument.
109 distributed = [Distrib]:
111 Specifies which applications that are distributed and on which
112 nodes they are allowed to execute. In this parameter:
113 * Distrib = {App,Nodes} | {App,Time,Nodes}
115 * App = atom()
117 * Time = integer()>0
119 * Nodes = [node() | {node(),...,node()}]
121 The parameter is described in application:load/2.
123 dist_auto_connect = Value:
125 Specifies when nodes are automatically connected. If this parameter
126 is not specified, a node is always automatically connected, for ex‐
127 ample, when a message is to be sent to that node. Value is one of:
128 never:
130 Connections are never automatically established, they must be ex‐
131 plicitly connected. See net_kernel(3).
132 once:
134 Connections are established automatically, but only once per
135 node. If a node goes down, it must thereafter be explicitly con‐
136 nected. See net_kernel(3).
137 permissions = [Perm]:
139 Specifies the default permission for applications when they are
140 started. In this parameter:
141 * Perm = {ApplName,Bool}
143 * ApplName = atom()
145 * Bool = boolean()
147 Permissions are described in application:permit/2.
149 logger = [Config]:
151 Specifies the configuration for Logger, except the primary log
152 level, which is specified with logger_level, and the compatibility
153 with SASL Error Logging, which is specified with logger_sasl_com‐
154 patible.
155 The logger parameter is described in section Logging in the Ker‐
157 nel User's Guide.
158 logger_level = Level:
160 Specifies the primary log level for Logger. Log events with the
161 same, or a more severe level, pass through the primary log level
162 check. See section Logging in the Kernel User's Guide for more in‐
163 formation about Logger and log levels.
164 Level = emergency | alert | critical | error | warning | notice |
166 info | debug | all | none
167 To change the primary log level at runtime, use logger:set_pri‐
169 mary_config(level, Level).
170 Defaults to notice.
172 logger_metadata = Metadata:
174 Specifies primary metadata for log events.
175 Metadata = map()
177 Defaults to #{}.
179 logger_sasl_compatible = true | false:
181 Specifies if Logger behaves backwards compatible with the SASL er‐
182 ror logging functionality from releases prior to Erlang/OTP 21.0.
183 If this parameter is set to true, the default Logger handler does
185 not log any progress-, crash-, or supervisor reports. If the SASL
186 application is then started, it adds a Logger handler named sasl,
187 which logs these events according to values of the SASL configura‐
188 tion parameter sasl_error_logger and sasl_errlog_type.
189 See section Deprecated Error Logger Event Handlers and Configura‐
191 tion in the sasl(6) manual page for information about the SASL con‐
192 figuration parameters.
193 See section SASL Error Logging in the SASL User's Guide, and sec‐
195 tion Backwards Compatibility with error_logger in the Kernel User's
196 Guide for information about the SASL error logging functionality,
197 and how Logger can be backwards compatible with this.
198 Defaults to false.
200 Note:
202 If this parameter is set to true, sasl_errlog_type indicates that
203 progress reports shall be logged, and the configured primary log
204 level is notice or more severe, then SASL automatically sets the pri‐
205 mary log level to info. That is, this setting can potentially over‐
206 write the value of the Kernel configuration parameter logger_level.
207 This is to allow progress reports, which have log level info, to be
208 forwarded to the handlers.
209 global_groups = [GroupTuple]:
212 Defines global groups, see global_group(3). In this parameter:
213 * GroupTuple = {GroupName, [Node]} | {GroupName, PublishType,
215 [Node]}
216 * GroupName = atom()
218 * PublishType = normal | hidden
220 * Node = node()
222 inet_default_connect_options = [{Opt, Val}]:
224 Specifies default options for connect sockets, see inet(3).
225 inet_default_listen_options = [{Opt, Val}]:
227 Specifies default options for listen (and accept) sockets, see
228 inet(3).
229 inet_dist_use_interface = ip_address():
231 If the host of an Erlang node has many network interfaces, this pa‐
232 rameter specifies which one to listen on. For the type definition
233 of ip_address(), see inet(3).
234 inet_dist_listen_min = First
236 inet_dist_listen_max = Last: Defines the First..Last port range for
237 the listener socket of a distributed Erlang node.
238 inet_dist_listen_options = Opts:
240 Defines a list of extra socket options to be used when opening the
241 listening socket for a distributed Erlang node. See gen_tcp:lis‐
242 ten/2.
243 inet_dist_connect_options = Opts:
245 Defines a list of extra socket options to be used when connecting
246 to other distributed Erlang nodes. See gen_tcp:connect/4.
247 inet_parse_error_log = silent:
249 If set, no log events are issued when erroneous lines are found and
250 skipped in the various Inet configuration files.
251 inetrc = Filename:
253 The name (string) of an Inet user configuration file. For details,
254 see section Inet Configuration in the ERTS User's Guide.
255 net_setuptime = SetupTime:
257 SetupTime must be a positive integer or floating point number, and
260 is interpreted as the maximum allowed time for each network opera‐
261 tion during connection setup to another Erlang node. The maximum
262 allowed value is 120. If higher values are specified, 120 is used.
263 Default is 7 seconds if the variable is not specified, or if the
264 value is incorrect (for example, not a number).
265 Notice that this value does not limit the total connection setup
267 time, but rather each individual network operation during the con‐
268 nection setup and handshake.
269 net_ticker_spawn_options = Opts:
271 Defines a list of extra spawn options for net ticker processes.
272 There exist one such process for each connection to another node. A
273 net ticker process is responsible for supervising the connection it
274 is associated with. These processes also execute the distribution
275 handshake protocol when setting up connections. When there is a
276 large number of distribution connections, setting up garbage col‐
277 lection options can be helpful to reduce memory usage. Default is
278 [link, {priority, max}], and these two options cannot be changed.
279 The monitor and {monitor, MonitorOpts} options are not allowed and
280 will be dropped if present. See the documentation of the er‐
281 lang:spawn_opt/4 BIF for information about valid options. If the
282 Opts list is not a proper list, or containing invalid options the
283 setup of connections will fail.
284 Note that the behavior described above is only true if the distri‐
286 bution carrier protocol used is implemented as described in ERTS
287 User's Guide ➜ How to implement an Alternative Carrier for the Er‐
288 lang Distribution ➜ Distribution Module without further alter‐
289 ations. The implementer of the distribution carrier protocol used,
290 may have chosen to ignore the net_ticker_spawn_options parameter or
291 altered its behavior. Currently all distribution modules shipped
292 with OTP do, however, behave as described above.
293 net_tickintensity = NetTickIntensity:
295 Net tick intensity specifies how many ticks to send during a net
296 tick time period when no other data is sent over a connection to
297 another node. This also determines how often to check for data from
298 the other node. The higher net tick intensity, the closer to the
299 chosen net tick time period the node will detect an unresponsive
300 node. The net tick intensity defaults to 4. The value of NetTickIn‐
301 tensity should be an integer in the range 4..1000. If the NetTick‐
302 Intensity is not an integer or an integer less than 4, 4 will
303 silently be used. If NetTickIntensity is an integer larger than
304 1000, 1000 will silently be used.
305 Note:
307 Note that all communicating nodes are expected to use the same net
308 tick intensity as well as the same net tick time .
309 Warning:
312 Be careful not to set a too high net tick intensity, since you can
313 overwhelm the node with work if it is set too high.
314 net_ticktime = NetTickTime:
317 Specifies the net tick time in seconds. This is the approximate
318 time a connected node may be unresponsive until it is considered
319 down and thereby disconnected.
320 Net tick time together with net tick intensity determines an inter‐
322 val TickInterval = NetTickTime/NetTickIntensity. Once every TickIn‐
323 terval seconds, each connected node is ticked if nothing has been
324 sent to it during that last TickInterval seconds. A tick is a small
325 package sent on the connection. A connected node is considered to
326 be down if no ticks or payload packages have been received during
327 the last NetTickIntensity number of TickInterval seconds intervals.
328 This ensures that nodes that are not responding, for reasons such
329 as hardware errors, are considered to be down.
330 As the availability is only checked every TickInterval seconds, the
332 actual time T a node have been unresponsive when detected may vary
333 between MinT and MaxT, where:
334 MinT = NetTickTime - NetTickTime / NetTickIntensity
336 MaxT = NetTickTime + NetTickTime / NetTickIntensity
337 NetTickTime defaults to 60 seconds and NetTickIntensity defaults to
339 4. Thus, 45 < T < 75 seconds.
340 Note:
342 Notice that all communicating nodes are to have the same NetTickTime
343 and NetTickIntensity values specified, as it determines both the fre‐
344 quency of outgoing ticks and the expected frequency of incominging
345 ticks.
346 NetTickTime needs to be a multiple of NetTickIntensity. If the con‐
349 figured values are not, NetTickTime will internally be rounded up
350 to the nearest millisecond. net_kernel:get_net_ticktime() will,
351 however, report net tick time truncated to the nearest second.
352 Normally, a terminating node is detected immediately by the trans‐
354 port protocol (like TCP/IP).
355 prevent_overlapping_partitions = true | false:
357 If enabled (true), global will actively prevent overlapping parti‐
358 tions from forming when connections are lost between nodes. This
359 fix is enabled by default. If you are about to disable this fix,
360 make sure to read the global(3) documentation about this fix for
361 more important information about this.
362 shutdown_timeout = integer() | infinity:
364 Specifies the time application_controller waits for an application
365 to terminate during node shutdown. If the timer expires, applica‐
366 tion_controller brutally kills application_master of the hanging
367 application. If this parameter is undefined, it defaults to infin‐
368 ity.
369 sync_nodes_mandatory = [NodeName]:
371 Specifies which other nodes that must be alive for this node to
372 start properly. If some node in the list does not start within the
373 specified time, this node does not start either. If this parameter
374 is undefined, it defaults to [].
375 sync_nodes_optional = [NodeName]:
377 Specifies which other nodes that can be alive for this node to
378 start properly. If some node in this list does not start within the
379 specified time, this node starts anyway. If this parameter is unde‐
380 fined, it defaults to the empty list.
381 sync_nodes_timeout = integer() | infinity:
383 Specifies the time (in milliseconds) that this node waits for the
384 mandatory and optional nodes to start. If this parameter is unde‐
385 fined, no node synchronization is performed. This option ensures
386 that global is synchronized.
387 start_distribution = true | false:
389 Starts all distribution services, such as rpc, global, and net_ker‐
390 nel if the parameter is true. This parameter is to be set to false
391 for systems who want to disable all distribution functionality.
392 Defaults to true.
394 start_dist_ac = true | false:
396 Starts the dist_ac server if the parameter is true. This parameter
397 is to be set to true for systems using distributed applications.
398 Defaults to false. If this parameter is undefined, the server is
400 started if parameter distributed is set.
401 start_boot_server = true | false:
403 Starts the boot_server if the parameter is true (see
404 erl_boot_server(3)). This parameter is to be set to true in an em‐
405 bedded system using this service.
406 Defaults to false.
408 boot_server_slaves = [SlaveIP]:
410 If configuration parameter start_boot_server is true, this parame‐
411 ter can be used to initialize boot_server with a list of slave IP
412 addresses:
413 SlaveIP = string() | atom | {integer(),integer(),integer(),inte‐
415 ger()},
416 where 0 <= integer() <=255.
418 Examples of SlaveIP in atom, string, and tuple form:
420 '150.236.16.70', "150,236,16,70", {150,236,16,70}.
422 Defaults to [].
424 start_disk_log = true | false:
426 Starts the disk_log_server if the parameter is true (see
427 disk_log(3)). This parameter is to be set to true in an embedded
428 system using this service.
429 Defaults to false.
431 start_pg = true | false:
433 Starts the default pg scope server (see pg(3)) if the parameter is
436 true. This parameter is to be set to true in an embedded system
437 that uses this service.
438 Defaults to false.
440 start_timer = true | false:
442 Starts the timer_server if the parameter is true (see timer(3)).
443 This parameter is to be set to true in an embedded system using
444 this service.
445 Defaults to false.
447 shell_history = enabled | disabled | module():
449 Specifies whether shell history should be logged to disk between
450 usages of erl (enabled), not logged at all (disabled), or a user-
451 specified module will be used to log shell history. This module
452 should export load() -> [string()] returning a list of strings to
453 load in the shell when it starts, and add(iodata()) -> ok. called
454 every time new line is entered in the shell. By default logging is
455 disabled.
456 shell_history_drop = [string()]:
458 Specific log lines that should not be persisted. For example
459 ["q().", "init:stop()."] will allow to ignore commands that shut
460 the node down. Defaults to [].
461 shell_history_file_bytes = integer():
463 How many bytes the shell should remember. By default, the value is
464 set to 512kb, and the minimal value is 50kb.
465 shell_history_path = string():
467 Specifies where the shell history files will be stored. defaults to
468 the user's cache directory as returned by file‐
469 name:basedir(user_cache, "erlang-history").
470 shutdown_func = {Mod, Func}:
472 Where:
473 * Mod = atom()
475 * Func = atom()
477 Sets a function that application_controller calls when it starts to
479 terminate. The function is called as Mod:Func(Reason), where Reason
480 is the terminate reason for application_controller, and it must re‐
481 turn as soon as possible for application_controller to terminate
482 properly.
483 source_search_rules = [DirRule] | [SuffixRule] :
485 Where:
488 * DirRule = {ObjDirSuffix,SrcDirSuffix}
490 * SuffixRule = {ObjSuffix,SrcSuffix,[DirRule]}
492 * ObjDirSuffix = string()
494 * SrcDirSuffix = string()
496 * ObjSuffix = string()
498 * SrcSuffix = string()
500 Specifies a list of rules for use by filelib:find_file/2
502 filelib:find_source/2 If this is set to some other value than the
503 empty list, it replaces the default rules. Rules can be simple
504 pairs of directory suffixes, such as {"ebin", "src"}, which are
505 used by filelib:find_file/2, or triples specifying separate direc‐
506 tory suffix rules depending on file name extensions, for example
507 [{".beam", ".erl", [{"ebin", "src"}]}, which are used by
508 filelib:find_source/2. Both kinds of rules can be mixed in the
509 list.
510 The interpretation of ObjDirSuffix and SrcDirSuffix is as follows:
512 if the end of the directory name where an object is located matches
513 ObjDirSuffix, then the name created by replacing ObjDirSuffix with
514 SrcDirSuffix is expanded by calling filelib:wildcard/1, and the
515 first regular file found among the matches is the source file.
516 standard_io_encoding = Encoding:
518 Set whether bytes sent or received via standard_io should be inter‐
519 preted as unicode or latin1. By default input and output is inter‐
520 preted as Unicode if it is supported on the host. With this flag
521 you may configure the encoding on startup.
522 This works similarly to io:setopts(standard_io, {encoding, Encod‐
524 ing}) but is applied before any bytes on standard_io may have been
525 read.
526 Encoding is one of:
528 unicode:
530 Configure standard_io to use unicode mode.
531 latin1:
533 Configure standard_io to use latin1 mode.
534 _:
536 Anything other than unicode or latin1 will be ignored and the
537 system will configure the encoding by itself, typically unicode
538 on modern systems.
539 See Escripts and non-interactive I/O in Unicode Usage in Erlang
541 for more details.
542
544 In Erlang/OTP 21.0, a new API for logging was added. The old error_log‐
545 ger event manager, and event handlers running on this manager, still
546 work, but they are no longer used by default.
547 The following application configuration parameters can still be set,
549 but they are only used if the corresponding configuration parameters
550 for Logger are not set.
551 error_logger:
553 Replaced by setting the type, and possibly file and modes parame‐
554 ters of the default logger_std_h handler. Example:
555 erl -kernel logger '[{handler,default,logger_std_h,#{config=>#{file=>"/tmp/erlang.log"}}}]'
557 error_logger_format_depth:
560 Replaced by setting the depth parameter of the default handlers
561 formatter. Example:
562 erl -kernel logger '[{handler,default,logger_std_h,#{formatter=>{logger_formatter,#{legacy_header=>true,template=>[{logger_formatter,header},"\n",msg,"\n"],depth=>10}}}]'
564 See Backwards compatibility with error_logger for more information.
567
569 app(4), application(3), code(3), disk_log(3), erl_boot_server(3),
570 erl_ddll(3), file(3), global(3), global_group(3), heart(3), inet(3),
571 logger(3), net_kernel(3), os(3), pg(3), rpc(3), seq_trace(3), timer(3)
572Ericsson AB kernel 9.1 kernel(7)