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 distributed = [Distrib]:
98 Specifies which applications that are distributed and on which
99 nodes they are allowed to execute. In this parameter:
100 * Distrib = {App,Nodes} | {App,Time,Nodes}
102 * App = atom()
104 * Time = integer()>0
106 * Nodes = [node() | {node(),...,node()}]
108 The parameter is described in application:load/2.
110 dist_auto_connect = Value:
112 Specifies when nodes are automatically connected. If this parameter
113 is not specified, a node is always automatically connected, for ex‐
114 ample, when a message is to be sent to that node. Value is one of:
115 never:
117 Connections are never automatically established, they must be ex‐
118 plicitly connected. See net_kernel(3).
119 once:
121 Connections are established automatically, but only once per
122 node. If a node goes down, it must thereafter be explicitly con‐
123 nected. See net_kernel(3).
124 dist_listen = boolean():
126 Specifies whether this node should be listening for incoming dis‐
127 tribution connections. Using this option implies that the node also
128 is -hidden.
129 permissions = [Perm]:
131 Specifies the default permission for applications when they are
132 started. In this parameter:
133 * Perm = {ApplName,Bool}
135 * ApplName = atom()
137 * Bool = boolean()
139 Permissions are described in application:permit/2.
141 logger = [Config]:
143 Specifies the configuration for Logger, except the primary log
144 level, which is specified with logger_level, and the compatibility
145 with SASL Error Logging, which is specified with logger_sasl_com‐
146 patible.
147 The logger parameter is described in section Logging in the Ker‐
149 nel User's Guide.
150 logger_level = Level:
152 Specifies the primary log level for Logger. Log events with the
153 same, or a more severe level, pass through the primary log level
154 check. See section Logging in the Kernel User's Guide for more in‐
155 formation about Logger and log levels.
156 Level = emergency | alert | critical | error | warning | notice |
158 info | debug | all | none
159 To change the primary log level at runtime, use logger:set_pri‐
161 mary_config(level, Level).
162 Defaults to notice.
164 logger_metadata = Metadata:
166 Specifies primary metadata for log events.
167 Metadata = map()
169 Defaults to #{}.
171 logger_sasl_compatible = true | false:
173 Specifies if Logger behaves backwards compatible with the SASL er‐
174 ror logging functionality from releases prior to Erlang/OTP 21.0.
175 If this parameter is set to true, the default Logger handler does
177 not log any progress-, crash-, or supervisor reports. If the SASL
178 application is then started, it adds a Logger handler named sasl,
179 which logs these events according to values of the SASL configura‐
180 tion parameter sasl_error_logger and sasl_errlog_type.
181 See section Deprecated Error Logger Event Handlers and Configura‐
183 tion in the sasl(6) manual page for information about the SASL con‐
184 figuration parameters.
185 See section SASL Error Logging in the SASL User's Guide, and sec‐
187 tion Backwards Compatibility with error_logger in the Kernel User's
188 Guide for information about the SASL error logging functionality,
189 and how Logger can be backwards compatible with this.
190 Defaults to false.
192 Note:
194 If this parameter is set to true, sasl_errlog_type indicates that
195 progress reports shall be logged, and the configured primary log
196 level is notice or more severe, then SASL automatically sets the pri‐
197 mary log level to info. That is, this setting can potentially over‐
198 write the value of the Kernel configuration parameter logger_level.
199 This is to allow progress reports, which have log level info, to be
200 forwarded to the handlers.
201 global_groups = [GroupTuple]:
204 Defines global groups, see global_group(3). In this parameter:
207 * GroupTuple = {GroupName, [Node]} | {GroupName, PublishType,
209 [Node]}
210 * GroupName = atom()
212 * PublishType = normal | hidden
214 * Node = node()
216 inet_default_connect_options = [{Opt, Val}]:
218 Specifies default options for connect sockets, see inet(3).
219 inet_default_listen_options = [{Opt, Val}]:
221 Specifies default options for listen (and accept) sockets, see
222 inet(3).
223 {inet_dist_use_interface, ip_address()}:
225 If the host of an Erlang node has many network interfaces, this pa‐
226 rameter specifies which one to listen on. For the type definition
227 of ip_address(), see inet(3).
228 {inet_dist_listen_min, First} and {inet_dist_listen_max, Last}:
230 Defines the First..Last port range for the listener socket of a
231 distributed Erlang node.
232 {inet_dist_listen_options, Opts}:
234 Defines a list of extra socket options to be used when opening the
237 listening socket for a distributed Erlang node. See gen_tcp:lis‐
238 ten/2.
239 {inet_dist_connect_options, Opts}:
241 Defines a list of extra socket options to be used when connecting
244 to other distributed Erlang nodes. See gen_tcp:connect/4.
245 inet_parse_error_log = silent:
247 If set, no log events are issued when erroneous lines are found and
248 skipped in the various Inet configuration files.
249 inetrc = Filename:
251 The name (string) of an Inet user configuration file. For details,
252 see section Inet Configuration in the ERTS User's Guide.
253 net_setuptime = SetupTime:
255 SetupTime must be a positive integer or floating point number, and
258 is interpreted as the maximum allowed time for each network opera‐
259 tion during connection setup to another Erlang node. The maximum
260 allowed value is 120. If higher values are specified, 120 is used.
261 Default is 7 seconds if the variable is not specified, or if the
262 value is incorrect (for example, not a number).
263 Notice that this value does not limit the total connection setup
265 time, but rather each individual network operation during the con‐
266 nection setup and handshake.
267 net_tickintensity = NetTickIntensity:
269 Net tick intensity specifies how many ticks to send during a net
270 tick time period when no other data is sent over a connection to
271 another node. This also determines how often to check for data from
272 the other node. The higher net tick intensity, the closer to the
273 chosen net tick time period the node will detect an unresponsive
274 node. The net tick intensity defaults to 4. The value of NetTickIn‐
275 tensity should be an integer in the range 4..1000. If the NetTick‐
276 Intensity is not an integer or an integer less than 4, 4 will
277 silently be used. If NetTickIntensity is an integer larger than
278 1000, 1000 will silently be used.
279 Note:
281 Note that all communicating nodes are expected to use the same net
282 tick intensity as well as the same net tick time .
283 Warning:
286 Be careful not to set a too high net tick intensity, since you can
287 overwhelm the node with work if it is set too high.
288 net_ticktime = NetTickTime:
291 Specifies the net tick time in seconds. This is the approximate
292 time a connected node may be unresponsive until it is considered
293 down and thereby disconnected.
294 Net tick time together with net tick intensity determines an inter‐
296 val TickInterval = NetTickTime/NetTickIntensity. Once every TickIn‐
297 terval seconds, each connected node is ticked if nothing has been
298 sent to it during that last TickInterval seconds. A tick is a small
299 package sent on the connection. A connected node is considered to
300 be down if no ticks or payload packages have been received during
301 the last NetTickIntensity number of TickInterval seconds intervals.
302 This ensures that nodes that are not responding, for reasons such
303 as hardware errors, are considered to be down.
304 As the availability is only checked every TickInterval seconds, the
306 actual time T a node have been unresponsive when detected may vary
307 between MinT and MaxT, where:
308 MinT = NetTickTime - NetTickTime / NetTickIntensity
310 MaxT = NetTickTime + NetTickTime / NetTickIntensity
311 NetTickTime defaults to 60 seconds and NetTickIntensity defaults to
313 4. Thus, 45 < T < 75 seconds.
314 Note:
316 Notice that all communicating nodes are to have the same NetTickTime
317 and NetTickIntensity values specified, as it determines both the fre‐
318 quency of outgoing ticks and the expected frequency of incominging
319 ticks.
320 NetTickTime needs to be a multiple of NetTickIntensity. If the con‐
323 figured values are not, NetTickTime will internally be rounded up
324 to the nearest millisecond. net_kernel:get_net_ticktime() will,
325 however, report net tick time truncated to the nearest second.
326 Normally, a terminating node is detected immediately by the trans‐
328 port protocol (like TCP/IP).
329 prevent_overlapping_partitions = true | false:
331 If enabled (true), global will actively prevent overlapping parti‐
332 tions from forming when connections are lost between nodes. This
333 fix is, however, currently disabled by default. See the global(3)
334 documentation for more information.
335 shutdown_timeout = integer() | infinity:
337 Specifies the time application_controller waits for an application
338 to terminate during node shutdown. If the timer expires, applica‐
339 tion_controller brutally kills application_master of the hanging
340 application. If this parameter is undefined, it defaults to infin‐
341 ity.
342 sync_nodes_mandatory = [NodeName]:
344 Specifies which other nodes that must be alive for this node to
345 start properly. If some node in the list does not start within the
346 specified time, this node does not start either. If this parameter
347 is undefined, it defaults to [].
348 sync_nodes_optional = [NodeName]:
350 Specifies which other nodes that can be alive for this node to
351 start properly. If some node in this list does not start within the
352 specified time, this node starts anyway. If this parameter is unde‐
353 fined, it defaults to the empty list.
354 sync_nodes_timeout = integer() | infinity:
356 Specifies the time (in milliseconds) that this node waits for the
357 mandatory and optional nodes to start. If this parameter is unde‐
358 fined, no node synchronization is performed. This option ensures
359 that global is synchronized.
360 start_distribution = true | false:
362 Starts all distribution services, such as rpc, global, and net_ker‐
363 nel if the parameter is true. This parameter is to be set to false
364 for systems who want to disable all distribution functionality.
365 Defaults to true.
367 start_dist_ac = true | false:
369 Starts the dist_ac server if the parameter is true. This parameter
370 is to be set to true for systems using distributed applications.
371 Defaults to false. If this parameter is undefined, the server is
373 started if parameter distributed is set.
374 start_boot_server = true | false:
376 Starts the boot_server if the parameter is true (see
377 erl_boot_server(3)). This parameter is to be set to true in an em‐
378 bedded system using this service.
379 Defaults to false.
381 boot_server_slaves = [SlaveIP]:
383 If configuration parameter start_boot_server is true, this parame‐
384 ter can be used to initialize boot_server with a list of slave IP
385 addresses:
386 SlaveIP = string() | atom | {integer(),integer(),integer(),inte‐
388 ger()},
389 where 0 <= integer() <=255.
391 Examples of SlaveIP in atom, string, and tuple form:
393 '150.236.16.70', "150,236,16,70", {150,236,16,70}.
395 Defaults to [].
397 start_disk_log = true | false:
399 Starts the disk_log_server if the parameter is true (see
400 disk_log(3)). This parameter is to be set to true in an embedded
401 system using this service.
402 Defaults to false.
404 start_pg = true | false:
406 Starts the default pg scope server (see pg(3)) if the parameter is
409 true. This parameter is to be set to true in an embedded system
410 that uses this service.
411 Defaults to false.
413 start_timer = true | false:
415 Starts the timer_server if the parameter is true (see timer(3)).
416 This parameter is to be set to true in an embedded system using
417 this service.
418 Defaults to false.
420 shell_history = enabled | disabled | module():
422 Specifies whether shell history should be logged to disk between
423 usages of erl (enabled), not logged at all (disabled), or a user-
424 specified module will be used to log shell history. This module
425 should export load() -> [string()] returning a list of strings to
426 load in the shell when it starts, and add(iodata()) -> ok. called
427 every time new line is entered in the shell. By default logging is
428 disabled.
429 shell_history_drop = [string()]:
431 Specific log lines that should not be persisted. For example
432 ["q().", "init:stop()."] will allow to ignore commands that shut
433 the node down. Defaults to [].
434 shell_history_file_bytes = integer():
436 How many bytes the shell should remember. By default, the value is
437 set to 512kb, and the minimal value is 50kb.
438 shell_history_path = string():
440 Specifies where the shell history files will be stored. defaults to
441 the user's cache directory as returned by file‐
442 name:basedir(user_cache, "erlang-history").
443 shutdown_func = {Mod, Func}:
445 Where:
446 * Mod = atom()
448 * Func = atom()
450 Sets a function that application_controller calls when it starts to
452 terminate. The function is called as Mod:Func(Reason), where Reason
453 is the terminate reason for application_controller, and it must re‐
454 turn as soon as possible for application_controller to terminate
455 properly.
456 source_search_rules = [DirRule] | [SuffixRule] :
458 Where:
461 * DirRule = {ObjDirSuffix,SrcDirSuffix}
463 * SuffixRule = {ObjSuffix,SrcSuffix,[DirRule]}
465 * ObjDirSuffix = string()
467 * SrcDirSuffix = string()
469 * ObjSuffix = string()
471 * SrcSuffix = string()
473 Specifies a list of rules for use by filelib:find_file/2
475 filelib:find_source/2 If this is set to some other value than the
476 empty list, it replaces the default rules. Rules can be simple
477 pairs of directory suffixes, such as {"ebin", "src"}, which are
478 used by filelib:find_file/2, or triples specifying separate direc‐
479 tory suffix rules depending on file name extensions, for example
480 [{".beam", ".erl", [{"ebin", "src"}]}, which are used by
481 filelib:find_source/2. Both kinds of rules can be mixed in the
482 list.
483 The interpretation of ObjDirSuffix and SrcDirSuffix is as follows:
485 if the end of the directory name where an object is located matches
486 ObjDirSuffix, then the name created by replacing ObjDirSuffix with
487 SrcDirSuffix is expanded by calling filelib:wildcard/1, and the
488 first regular file found among the matches is the source file.
489
491 In Erlang/OTP 21.0, a new API for logging was added. The old error_log‐
492 ger event manager, and event handlers running on this manager, still
493 work, but they are no longer used by default.
494 The following application configuration parameters can still be set,
496 but they are only used if the corresponding configuration parameters
497 for Logger are not set.
498 error_logger:
500 Replaced by setting the type, and possibly file and modes parame‐
501 ters of the default logger_std_h handler. Example:
502 erl -kernel logger '[{handler,default,logger_std_h,#{config=>#{file=>"/tmp/erlang.log"}}}]'
504 error_logger_format_depth:
507 Replaced by setting the depth parameter of the default handlers
508 formatter. Example:
509 erl -kernel logger '[{handler,default,logger_std_h,#{formatter=>{logger_formatter,#{legacy_header=>true,template=>[{logger_formatter,header},"\n",msg,"\n"],depth=>10}}}]'
511 See Backwards compatibility with error_logger for more information.
514
516 app(4), application(3), code(3), disk_log(3), erl_boot_server(3),
517 erl_ddll(3), file(3), global(3), global_group(3), heart(3), inet(3),
518 logger(3), net_kernel(3), os(3), pg(3), rpc(3), seq_trace(3), user(3),
519 timer(3)
520Ericsson AB kernel 8.3.2 kernel(7)