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_ticktime = TickTime:
269 Specifies the net_kernel tick time in seconds. This is the approxi‐
272 mate time a connected node may be unresponsive until it is consid‐
273 ered down and thereby disconnected.
274 Once every TickTime/4 seconds, each connected node is ticked if
276 nothing has been sent to it during that last TickTime/4 interval. A
277 tick is a small package sent on the connection. A connected node is
278 considered to be down if no ticks or payload packages have been re‐
279 ceived during the last four TickTime/4 intervals. This ensures that
280 nodes that are not responding, for reasons such as hardware errors,
281 are considered to be down.
282 As the availability is only checked every TickTime/4 seconds, the
284 actual time T a node have been unresponsive when detected may vary
285 between MinT and MaxT, where:
286 MinT = TickTime - TickTime / 4
288 MaxT = TickTime + TickTime / 4
289 TickTime defaults to 60 seconds. Thus, 45 < T < 75 seconds.
291 Notice that all communicating nodes are to have the same TickTime
293 value specified, as it determines both the frequency of outgoing
294 ticks and the expected frequency of incominging ticks.
295 Normally, a terminating node is detected immediately by the trans‐
297 port protocol (like TCP/IP).
298 shutdown_timeout = integer() | infinity:
300 Specifies the time application_controller waits for an application
301 to terminate during node shutdown. If the timer expires, applica‐
302 tion_controller brutally kills application_master of the hanging
303 application. If this parameter is undefined, it defaults to infin‐
304 ity.
305 sync_nodes_mandatory = [NodeName]:
307 Specifies which other nodes that must be alive for this node to
308 start properly. If some node in the list does not start within the
309 specified time, this node does not start either. If this parameter
310 is undefined, it defaults to [].
311 sync_nodes_optional = [NodeName]:
313 Specifies which other nodes that can be alive for this node to
314 start properly. If some node in this list does not start within the
315 specified time, this node starts anyway. If this parameter is unde‐
316 fined, it defaults to the empty list.
317 sync_nodes_timeout = integer() | infinity:
319 Specifies the time (in milliseconds) that this node waits for the
320 mandatory and optional nodes to start. If this parameter is unde‐
321 fined, no node synchronization is performed. This option ensures
322 that global is synchronized.
323 start_distribution = true | false:
325 Starts all distribution services, such as rpc, global, and net_ker‐
326 nel if the parameter is true. This parameter is to be set to false
327 for systems who want to disable all distribution functionality.
328 Defaults to true.
330 start_dist_ac = true | false:
332 Starts the dist_ac server if the parameter is true. This parameter
333 is to be set to true for systems using distributed applications.
334 Defaults to false. If this parameter is undefined, the server is
336 started if parameter distributed is set.
337 start_boot_server = true | false:
339 Starts the boot_server if the parameter is true (see
340 erl_boot_server(3)). This parameter is to be set to true in an em‐
341 bedded system using this service.
342 Defaults to false.
344 boot_server_slaves = [SlaveIP]:
346 If configuration parameter start_boot_server is true, this parame‐
347 ter can be used to initialize boot_server with a list of slave IP
348 addresses:
349 SlaveIP = string() | atom | {integer(),integer(),integer(),inte‐
351 ger()},
352 where 0 <= integer() <=255.
354 Examples of SlaveIP in atom, string, and tuple form:
356 '150.236.16.70', "150,236,16,70", {150,236,16,70}.
358 Defaults to [].
360 start_disk_log = true | false:
362 Starts the disk_log_server if the parameter is true (see
363 disk_log(3)). This parameter is to be set to true in an embedded
364 system using this service.
365 Defaults to false.
367 start_pg = true | false:
369 Starts the default pg scope server (see pg(3)) if the parameter is
372 true. This parameter is to be set to true in an embedded system
373 that uses this service.
374 Defaults to false.
376 start_timer = true | false:
378 Starts the timer_server if the parameter is true (see timer(3)).
379 This parameter is to be set to true in an embedded system using
380 this service.
381 Defaults to false.
383 shell_history = enabled | disabled | module():
385 Specifies whether shell history should be logged to disk between
386 usages of erl (enabled), not logged at all (disabled), or a user-
387 specified module will be used to log shell history. This module
388 should export load() -> [string()] returning a list of strings to
389 load in the shell when it starts, and add(iodata()) -> ok. called
390 every time new line is entered in the shell. By default logging is
391 disabled.
392 shell_history_drop = [string()]:
394 Specific log lines that should not be persisted. For example
395 ["q().", "init:stop()."] will allow to ignore commands that shut
396 the node down. Defaults to [].
397 shell_history_file_bytes = integer():
399 How many bytes the shell should remember. By default, the value is
400 set to 512kb, and the minimal value is 50kb.
401 shell_history_path = string():
403 Specifies where the shell history files will be stored. defaults to
404 the user's cache directory as returned by file‐
405 name:basedir(user_cache, "erlang-history").
406 shutdown_func = {Mod, Func}:
408 Where:
409 * Mod = atom()
411 * Func = atom()
413 Sets a function that application_controller calls when it starts to
415 terminate. The function is called as Mod:Func(Reason), where Reason
416 is the terminate reason for application_controller, and it must re‐
417 turn as soon as possible for application_controller to terminate
418 properly.
419 source_search_rules = [DirRule] | [SuffixRule] :
421 Where:
424 * DirRule = {ObjDirSuffix,SrcDirSuffix}
426 * SuffixRule = {ObjSuffix,SrcSuffix,[DirRule]}
428 * ObjDirSuffix = string()
430 * SrcDirSuffix = string()
432 * ObjSuffix = string()
434 * SrcSuffix = string()
436 Specifies a list of rules for use by filelib:find_file/2
438 filelib:find_source/2 If this is set to some other value than the
439 empty list, it replaces the default rules. Rules can be simple
440 pairs of directory suffixes, such as {"ebin", "src"}, which are
441 used by filelib:find_file/2, or triples specifying separate direc‐
442 tory suffix rules depending on file name extensions, for example
443 [{".beam", ".erl", [{"ebin", "src"}]}, which are used by
444 filelib:find_source/2. Both kinds of rules can be mixed in the
445 list.
446 The interpretation of ObjDirSuffix and SrcDirSuffix is as follows:
448 if the end of the directory name where an object is located matches
449 ObjDirSuffix, then the name created by replacing ObjDirSuffix with
450 SrcDirSuffix is expanded by calling filelib:wildcard/1, and the
451 first regular file found among the matches is the source file.
452
454 In Erlang/OTP 21.0, a new API for logging was added. The old error_log‐
455 ger event manager, and event handlers running on this manager, still
456 work, but they are no longer used by default.
457 The following application configuration parameters can still be set,
459 but they are only used if the corresponding configuration parameters
460 for Logger are not set.
461 error_logger:
463 Replaced by setting the type, and possibly file and modes parame‐
464 ters of the default logger_std_h handler. Example:
465 erl -kernel logger '[{handler,default,logger_std_h,#{config=>#{file=>"/tmp/erlang.log"}}}]'
467 error_logger_format_depth:
470 Replaced by setting the depth parameter of the default handlers
471 formatter. Example:
472 erl -kernel logger '[{handler,default,logger_std_h,#{formatter=>{logger_formatter,#{legacy_header=>true,template=>[{logger_formatter,header},"\n",msg,"\n"],depth=>10}}}]'
474 See Backwards compatibility with error_logger for more information.
477
479 app(4), application(3), code(3), disk_log(3), erl_boot_server(3),
480 erl_ddll(3), file(3), global(3), global_group(3), heart(3), inet(3),
481 logger(3), net_kernel(3), os(3), pg(3), rpc(3), seq_trace(3), user(3),
482 timer(3)
483Ericsson AB kernel 8.1.3 kernel(7)