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
45 erlang: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
94 application. 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
114 example, when a message is to be sent to that node. Value is one
115 of:
116 never:
118 Connections are never automatically established, they must be
119 explicitly connected. See net_kernel(3).
120 once:
122 Connections are established automatically, but only once per
123 node. If a node goes down, it must thereafter be explicitly con‐
124 nected. See net_kernel(3).
125 dist_listen = boolean():
127 Specifies whether this node should be listening for incoming dis‐
128 tribution connections. Using this option implies that the node also
129 is -hidden.
130 permissions = [Perm]:
132 Specifies the default permission for applications when they are
133 started. In this parameter:
134 * Perm = {ApplName,Bool}
136 * ApplName = atom()
138 * Bool = boolean()
140 Permissions are described in application:permit/2.
142 logger = [Config]:
144 Specifies the configuration for Logger, except the primary log
145 level, which is specified with logger_level, and the compatibility
146 with SASL Error Logging, which is specified with logger_sasl_com‐
147 patible.
148 The logger parameter is described in section Logging in the Ker‐
150 nel User's Guide.
151 logger_level = Level:
153 Specifies the primary log level for Logger. Log events with the
154 same, or a more severe level, pass through the primary log level
155 check. See section Logging in the Kernel User's Guide for more
156 information about Logger and log levels.
157 Level = emergency | alert | critical | error | warning | notice |
159 info | debug | all | none
160 To change the primary log level at runtime, use logger:set_pri‐
162 mary_config(level, Level).
163 Defaults to notice.
165 logger_sasl_compatible = true | false:
167 Specifies if Logger behaves backwards compatible with the SASL
168 error logging functionality from releases prior to Erlang/OTP 21.0.
169 If this parameter is set to true, the default Logger handler does
171 not log any progress-, crash-, or supervisor reports. If the SASL
172 application is then started, it adds a Logger handler named sasl,
173 which logs these events according to values of the SASL configura‐
174 tion parameter sasl_error_logger and sasl_errlog_type.
175 See section Deprecated Error Logger Event Handlers and Configura‐
177 tion in the sasl(6) manual page for information about the SASL con‐
178 figuration parameters.
179 See section SASL Error Logging in the SASL User's Guide, and sec‐
181 tion Backwards Compatibility with error_logger in the Kernel User's
182 Guide for information about the SASL error logging functionality,
183 and how Logger can be backwards compatible with this.
184 Defaults to false.
186 Note:
188 If this parameter is set to true, sasl_errlog_type indicates that
189 progress reports shall be logged, and the configured primary log
190 level is notice or more severe, then SASL automatically sets the pri‐
191 mary log level to info. That is, this setting can potentially over‐
192 write the value of the Kernel configuration parameter logger_level.
193 This is to allow progress reports, which have log level info, to be
194 forwarded to the handlers.
195 global_groups = [GroupTuple]:
198 Defines global groups, see global_group(3). In this parameter:
201 * GroupTuple = {GroupName, [Node]} | {GroupName, PublishType,
203 [Node]}
204 * GroupName = atom()
206 * PublishType = normal | hidden
208 * Node = node()
210 inet_default_connect_options = [{Opt, Val}]:
212 Specifies default options for connect sockets, see inet(3).
213 inet_default_listen_options = [{Opt, Val}]:
215 Specifies default options for listen (and accept) sockets, see
216 inet(3).
217 {inet_dist_use_interface, ip_address()}:
219 If the host of an Erlang node has many network interfaces, this
220 parameter specifies which one to listen on. For the type definition
221 of ip_address(), see inet(3).
222 {inet_dist_listen_min, First} and {inet_dist_listen_max, Last}:
224 Defines the First..Last port range for the listener socket of a
225 distributed Erlang node.
226 {inet_dist_listen_options, Opts}:
228 Defines a list of extra socket options to be used when opening the
231 listening socket for a distributed Erlang node. See gen_tcp:lis‐
232 ten/2.
233 {inet_dist_connect_options, Opts}:
235 Defines a list of extra socket options to be used when connecting
238 to other distributed Erlang nodes. See gen_tcp:connect/4.
239 inet_parse_error_log = silent:
241 If set, no log events are issued when erroneous lines are found and
242 skipped in the various Inet configuration files.
243 inetrc = Filename:
245 The name (string) of an Inet user configuration file. For details,
246 see section Inet Configuration in the ERTS User's Guide.
247 net_setuptime = SetupTime:
249 SetupTime must be a positive integer or floating point number, and
252 is interpreted as the maximum allowed time for each network opera‐
253 tion during connection setup to another Erlang node. The maximum
254 allowed value is 120. If higher values are specified, 120 is used.
255 Default is 7 seconds if the variable is not specified, or if the
256 value is incorrect (for example, not a number).
257 Notice that this value does not limit the total connection setup
259 time, but rather each individual network operation during the con‐
260 nection setup and handshake.
261 net_ticktime = TickTime:
263 Specifies the net_kernel tick time in seconds. This is the approxi‐
266 mate time a connected node may be unresponsive until it is consid‐
267 ered down and thereby disconnected.
268 Once every TickTime/4 seconds, each connected node is ticked if
270 nothing has been sent to it during that last TickTime/4 interval. A
271 tick is a small package sent on the connection. A connected node is
272 considered to be down if no ticks or payload packages have been
273 received during the last four TickTime/4 intervals. This ensures
274 that nodes that are not responding, for reasons such as hardware
275 errors, are considered to be down.
276 As the availability is only checked every TickTime/4 seconds, the
278 actual time T a node have been unresponsive when detected may vary
279 between MinT and MaxT, where:
280 MinT = TickTime - TickTime / 4
282 MaxT = TickTime + TickTime / 4
283 TickTime defaults to 60 seconds. Thus, 45 < T < 75 seconds.
285 Notice that all communicating nodes are to have the same TickTime
287 value specified, as it determines both the frequency of outgoing
288 ticks and the expected frequency of incominging ticks.
289 Normally, a terminating node is detected immediately by the trans‐
291 port protocol (like TCP/IP).
292 shutdown_timeout = integer() | infinity:
294 Specifies the time application_controller waits for an application
295 to terminate during node shutdown. If the timer expires, applica‐
296 tion_controller brutally kills application_master of the hanging
297 application. If this parameter is undefined, it defaults to infin‐
298 ity.
299 sync_nodes_mandatory = [NodeName]:
301 Specifies which other nodes that must be alive for this node to
302 start properly. If some node in the list does not start within the
303 specified time, this node does not start either. If this parameter
304 is undefined, it defaults to [].
305 sync_nodes_optional = [NodeName]:
307 Specifies which other nodes that can be alive for this node to
308 start properly. If some node in this list does not start within the
309 specified time, this node starts anyway. If this parameter is unde‐
310 fined, it defaults to the empty list.
311 sync_nodes_timeout = integer() | infinity:
313 Specifies the time (in milliseconds) that this node waits for the
314 mandatory and optional nodes to start. If this parameter is unde‐
315 fined, no node synchronization is performed. This option ensures
316 that global is synchronized.
317 start_distribution = true | false:
319 Starts all distribution services, such as rpc, global, and net_ker‐
320 nel if the parameter is true. This parameter is to be set to false
321 for systems who want to disable all distribution functionality.
322 Defaults to true.
324 start_dist_ac = true | false:
326 Starts the dist_ac server if the parameter is true. This parameter
327 is to be set to true for systems using distributed applications.
328 Defaults to false. If this parameter is undefined, the server is
330 started if parameter distributed is set.
331 start_boot_server = true | false:
333 Starts the boot_server if the parameter is true (see
334 erl_boot_server(3)). This parameter is to be set to true in an
335 embedded system using this service.
336 Defaults to false.
338 boot_server_slaves = [SlaveIP]:
340 If configuration parameter start_boot_server is true, this parame‐
341 ter can be used to initialize boot_server with a list of slave IP
342 addresses:
343 SlaveIP = string() | atom | {integer(),integer(),integer(),inte‐
345 ger()},
346 where 0 <= integer() <=255.
348 Examples of SlaveIP in atom, string, and tuple form:
350 '150.236.16.70', "150,236,16,70", {150,236,16,70}.
352 Defaults to [].
354 start_disk_log = true | false:
356 Starts the disk_log_server if the parameter is true (see
357 disk_log(3)). This parameter is to be set to true in an embedded
358 system using this service.
359 Defaults to false.
361 start_pg = true | false:
363 Starts the default pg scope server (see pg(3)) if the parameter is
366 true. This parameter is to be set to true in an embedded system
367 that uses this service.
368 Defaults to false.
370 start_pg2 = true | false:
372 Starts the pg2 server (see pg2(3)) if the parameter is true. This
375 parameter is to be set to true in an embedded system that uses this
376 service.
377 Defaults to false.
379 start_timer = true | false:
381 Starts the timer_server if the parameter is true (see timer(3)).
382 This parameter is to be set to true in an embedded system using
383 this service.
384 Defaults to false.
386 shell_history = enabled | disabled :
388 Specifies whether shell history should be logged to disk between
389 usages of erl.
390 shell_history_drop = [string()]:
392 Specific log lines that should not be persisted. For example
393 ["q().", "init:stop()."] will allow to ignore commands that shut
394 the node down. Defaults to [].
395 shell_history_file_bytes = integer():
397 How many bytes the shell should remember. By default, the value is
398 set to 512kb, and the minimal value is 50kb.
399 shell_history_path = string():
401 Specifies where the shell history files will be stored. defaults to
402 the user's cache directory as returned by file‐
403 name:basedir(user_cache, "erlang-history").
404 shutdown_func = {Mod, Func}:
406 Where:
407 * Mod = atom()
409 * Func = atom()
411 Sets a function that application_controller calls when it starts to
413 terminate. The function is called as Mod:Func(Reason), where Reason
414 is the terminate reason for application_controller, and it must
415 return as soon as possible for application_controller to terminate
416 properly.
417 source_search_rules = [DirRule] | [SuffixRule] :
419 Where:
422 * DirRule = {ObjDirSuffix,SrcDirSuffix}
424 * SuffixRule = {ObjSuffix,SrcSuffix,[DirRule]}
426 * ObjDirSuffix = string()
428 * SrcDirSuffix = string()
430 * ObjSuffix = string()
432 * SrcSuffix = string()
434 Specifies a list of rules for use by filelib:find_file/2
436 filelib:find_source/2 If this is set to some other value than the
437 empty list, it replaces the default rules. Rules can be simple
438 pairs of directory suffixes, such as {"ebin", "src"}, which are
439 used by filelib:find_file/2, or triples specifying separate direc‐
440 tory suffix rules depending on file name extensions, for example
441 [{".beam", ".erl", [{"ebin", "src"}]}, which are used by
442 filelib:find_source/2. Both kinds of rules can be mixed in the
443 list.
444 The interpretation of ObjDirSuffix and SrcDirSuffix is as follows:
446 if the end of the directory name where an object is located matches
447 ObjDirSuffix, then the name created by replacing ObjDirSuffix with
448 SrcDirSuffix is expanded by calling filelib:wildcard/1, and the
449 first regular file found among the matches is the source file.
450
452 In Erlang/OTP 21.0, a new API for logging was added. The old error_log‐
453 ger event manager, and event handlers running on this manager, still
454 work, but they are no longer used by default.
455 The following application configuration parameters can still be set,
457 but they are only used if the corresponding configuration parameters
458 for Logger are not set.
459 error_logger:
461 Replaced by setting the type, and possibly file and modes parame‐
462 ters of the default logger_std_h handler. Example:
463 erl -kernel logger '[{handler,default,logger_std_h,#{config=>#{file=>"/tmp/erlang.log"}}}]'
465 error_logger_format_depth:
468 Replaced by setting the depth parameter of the default handlers
469 formatter. Example:
470 erl -kernel logger '[{handler,default,logger_std_h,#{formatter=>{logger_formatter,#{legacy_header=>true,template=>[{logger_formatter,header},"\n",msg,"\n"],depth=>10}}}]'
472 See Backwards compatibility with error_logger for more information.
475
477 app(4), application(3), code(3), disk_log(3), erl_boot_server(3),
478 erl_ddll(3), file(3), global(3), global_group(3), heart(3), inet(3),
479 logger(3), net_kernel(3), os(3), pg(3), pg2(3), rpc(3), seq_trace(3),
480 user(3), timer(3)
481Ericsson AB kernel 7.3 kernel(7)