1kernel(7)                Erlang Application Definition               kernel(7)
2
3
4

NAME

6       kernel - The Kernel application.
7

DESCRIPTION

9       The  Kernel  application  has  all the code necessary to run the Erlang
10       runtime system: file servers, code servers, and so on.
11
12       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
16         * Start, stop, supervision, configuration, and distribution of appli‐
17           cations
18
19         * Code loading
20
21         * Logging
22
23         * Global name service
24
25         * Supervision of Erlang/OTP
26
27         * Communication with sockets
28
29         * Operating system interface
30

LOGGER HANDLERS

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

OS SIGNAL EVENT HANDLER

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
42         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
47         sigquit:
48           The default handler will halt Erlang immediately. This  is  equiva‐
49           lent to calling erlang:halt().
50
51         sigterm:
52           The default handler will terminate Erlang normally. This is equiva‐
53           lent to calling init:stop().
54
55   Events
56       Any event handler added to erl_signal_server must handle the  following
57       events.
58
59         sighup:
60           Hangup  detected  on  controlling  terminal or death of controlling
61           process
62
63         sigquit:
64           Quit from keyboard
65
66         sigabrt:
67           Abort signal from abort
68
69         sigalrm:
70           Timer signal from alarm
71
72         sigterm:
73           Termination signal
74
75         sigusr1:
76           User-defined signal 1
77
78         sigusr2:
79           User-defined signal 2
80
81         sigchld:
82           Child process stopped or terminated
83
84         sigstop:
85           Stop process
86
87         sigtstp:
88           Stop typed at terminal
89
90       Setting OS signals are described in os:set_signal/2.
91

CONFIGURATION

93       The following configuration  parameters  are  defined  for  the  Kernel
94       application.  For  more information about configuration parameters, see
95       file app(4).
96
97         distributed = [Distrib]:
98           Specifies which applications that  are  distributed  and  on  which
99           nodes they are allowed to execute. In this parameter:
100
101           * Distrib = {App,Nodes} | {App,Time,Nodes}
102
103           * App = atom()
104
105           * Time = integer()>0
106
107           * Nodes = [node() | {node(),...,node()}]
108
109           The parameter is described in application:load/2.
110
111         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
117           never:
118             Connections are never automatically  established,  they  must  be
119             explicitly connected. See net_kernel(3).
120
121           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
126         permissions = [Perm]:
127           Specifies  the  default  permission  for applications when they are
128           started. In this parameter:
129
130           * Perm = {ApplName,Bool}
131
132           * ApplName = atom()
133
134           * Bool = boolean()
135
136           Permissions are described in application:permit/2.
137
138         logger = [Config]:
139           Specifies the configuration for  Logger,  except  the  primary  log
140           level,  which is specified with logger_level, and the compatibility
141           with SASL Error Logging, which is specified  with  logger_sasl_com‐
142           patible.
143
144           The  logger  parameter is described in section  Logging in the Ker‐
145           nel User's Guide.
146
147         logger_level = Level:
148           Specifies the primary log level for Logger.  Log  events  with  the
149           same,  or  a  more severe level, pass through the primary log level
150           check. See section Logging in the  Kernel  User's  Guide  for  more
151           information about Logger and log levels.
152
153           Level  =  emergency | alert | critical | error | warning | notice |
154           info | debug | all | none
155
156           To change the primary log level  at  runtime,  use  logger:set_pri‐
157           mary_config(level, Level).
158
159           Defaults to notice.
160
161         logger_sasl_compatible = true | false:
162           Specifies  if  Logger  behaves  backwards  compatible with the SASL
163           error logging functionality from releases prior to Erlang/OTP 21.0.
164
165           If this parameter is set to true, the default Logger  handler  does
166           not  log  any progress-, crash-, or supervisor reports. If the SASL
167           application is then started, it adds a Logger handler  named  sasl,
168           which  logs these events according to values of the SASL configura‐
169           tion parameter sasl_error_logger and sasl_errlog_type.
170
171           See section  Deprecated Error Logger Event Handlers and  Configura‐
172           tion in the sasl(6) manual page for information about the SASL con‐
173           figuration parameters.
174
175           See section SASL Error Logging in the SASL User's Guide,  and  sec‐
176           tion Backwards Compatibility with error_logger in the Kernel User's
177           Guide for information about the SASL error  logging  functionality,
178           and how Logger can be backwards compatible with this.
179
180           Defaults to false.
181
182     Note:
183         If  this  parameter  is  set to true, sasl_errlog_type indicates that
184         progress reports shall be logged,  and  the  configured  primary  log
185         level is notice or more severe, then SASL automatically sets the pri‐
186         mary log level to info. That is, this setting can  potentially  over‐
187         write  the  value of the Kernel configuration parameter logger_level.
188         This is to allow progress reports, which have log level info,  to  be
189         forwarded to the handlers.
190
191
192         global_groups = [GroupTuple]:
193
194
195           Defines global groups, see global_group(3). In this parameter:
196
197           * GroupTuple  =  {GroupName,  [Node]}  |  {GroupName,  PublishType,
198             [Node]}
199
200           * GroupName = atom()
201
202           * PublishType = normal | hidden
203
204           * Node = node()
205
206         inet_default_connect_options = [{Opt, Val}]:
207           Specifies default options for connect sockets, see inet(3).
208
209         inet_default_listen_options = [{Opt, Val}]:
210           Specifies default options for  listen  (and  accept)  sockets,  see
211           inet(3).
212
213         {inet_dist_use_interface, ip_address()}:
214           If  the  host  of  an Erlang node has many network interfaces, this
215           parameter specifies which one to listen on. For the type definition
216           of ip_address(), see inet(3).
217
218         {inet_dist_listen_min, First} and {inet_dist_listen_max, Last}:
219           Defines  the  First..Last  port  range for the listener socket of a
220           distributed Erlang node.
221
222         {inet_dist_listen_options, Opts}:
223
224
225           Defines a list of extra socket options to be used when opening  the
226           listening  socket  for  a distributed Erlang node. See gen_tcp:lis‐
227           ten/2.
228
229         {inet_dist_connect_options, Opts}:
230
231
232           Defines a list of extra socket options to be used  when  connecting
233           to other distributed Erlang nodes. See gen_tcp:connect/4.
234
235         inet_parse_error_log = silent:
236           If set, no log events are issued when erroneous lines are found and
237           skipped in the various Inet configuration files.
238
239         inetrc = Filename:
240           The name (string) of an Inet user configuration file. For  details,
241           see section Inet Configuration in the ERTS User's Guide.
242
243         net_setuptime = SetupTime:
244
245
246           SetupTime  must be a positive integer or floating point number, and
247           is interpreted as the maximum allowed time for each network  opera‐
248           tion  during  connection  setup to another Erlang node. The maximum
249           allowed value is 120. If higher values are specified, 120 is  used.
250           Default  is  7  seconds if the variable is not specified, or if the
251           value is incorrect (for example, not a number).
252
253           Notice that this value does not limit the  total  connection  setup
254           time,  but rather each individual network operation during the con‐
255           nection setup and handshake.
256
257         net_ticktime = TickTime:
258
259
260           Specifies the net_kernel tick time in seconds. This is the approxi‐
261           mate  time a connected node may be unresponsive until it is consid‐
262           ered down and thereby disconnected.
263
264           Once every TickTime/4 seconds, each connected  node  is  ticked  if
265           nothing has been sent to it during that last TickTime/4 interval. A
266           tick is a small package sent on the connection. A connected node is
267           considered  to  be  down  if no ticks or payload packages have been
268           received during the last four TickTime/4  intervals.  This  ensures
269           that  nodes  that  are not responding, for reasons such as hardware
270           errors, are considered to be down.
271
272           As the availability is only checked every TickTime/4  seconds,  the
273           actual  time T a node have been unresponsive when detected may vary
274           between MinT and MaxT, where:
275
276         MinT = TickTime - TickTime / 4
277         MaxT = TickTime + TickTime / 4
278
279           TickTime defaults to 60 seconds. Thus, 45 < T < 75 seconds.
280
281           Notice that all communicating nodes are to have the  same  TickTime
282           value  specified,  as  it determines both the frequency of outgoing
283           ticks and the expected frequency of incominging ticks.
284
285           Normally, a terminating node is detected immediately by the  trans‐
286           port protocol (like TCP/IP).
287
288         shutdown_timeout = integer() | infinity:
289           Specifies  the time application_controller waits for an application
290           to terminate during node shutdown. If the timer  expires,  applica‐
291           tion_controller  brutally  kills  application_master of the hanging
292           application. If this parameter is undefined, it defaults to  infin‐
293           ity.
294
295         sync_nodes_mandatory = [NodeName]:
296           Specifies  which  other  nodes  that must be alive for this node to
297           start properly. If some node in the list does not start within  the
298           specified  time, this node does not start either. If this parameter
299           is undefined, it defaults to [].
300
301         sync_nodes_optional = [NodeName]:
302           Specifies which other nodes that can be  alive  for  this  node  to
303           start properly. If some node in this list does not start within the
304           specified time, this node starts anyway. If this parameter is unde‐
305           fined, it defaults to the empty list.
306
307         sync_nodes_timeout = integer() | infinity:
308           Specifies  the  time (in milliseconds) that this node waits for the
309           mandatory and optional nodes to start. If this parameter  is  unde‐
310           fined,  no  node  synchronization is performed. This option ensures
311           that global is synchronized.
312
313         start_distribution = true | false:
314           Starts all distribution services, such as rpc, global, and net_ker‐
315           nel  if the parameter is true. This parameter is to be set to false
316           for systems who want to disable all distribution functionality.
317
318           Defaults to true.
319
320         start_dist_ac = true | false:
321           Starts the dist_ac server if the parameter is true. This  parameter
322           is to be set to true for systems using distributed applications.
323
324           Defaults  to  false.  If this parameter is undefined, the server is
325           started if parameter distributed is set.
326
327         start_boot_server = true | false:
328           Starts  the   boot_server   if   the   parameter   is   true   (see
329           erl_boot_server(3)).  This  parameter  is  to  be set to true in an
330           embedded system using this service.
331
332           Defaults to false.
333
334         boot_server_slaves = [SlaveIP]:
335           If configuration parameter start_boot_server is true, this  parame‐
336           ter  can  be used to initialize boot_server with a list of slave IP
337           addresses:
338
339           SlaveIP = string() |  atom  |  {integer(),integer(),integer(),inte‐
340           ger()},
341
342           where 0 <= integer() <=255.
343
344           Examples of SlaveIP in atom, string, and tuple form:
345
346           '150.236.16.70', "150,236,16,70", {150,236,16,70}.
347
348           Defaults to [].
349
350         start_disk_log = true | false:
351           Starts   the   disk_log_server   if  the  parameter  is  true  (see
352           disk_log(3)). This parameter is to be set to true  in  an  embedded
353           system using this service.
354
355           Defaults to false.
356
357         start_pg2 = true | false:
358
359
360           Starts  the  pg2 server (see pg2(3)) if the parameter is true. This
361           parameter is to be set to true in an embedded system that uses this
362           service.
363
364           Defaults to false.
365
366         start_timer = true | false:
367           Starts  the  timer_server  if the parameter is true (see timer(3)).
368           This parameter is to be set to true in  an  embedded  system  using
369           this service.
370
371           Defaults to false.
372
373         shell_history = enabled | disabled :
374           Specifies  whether  shell  history should be logged to disk between
375           usages of erl.
376
377         shell_history_drop = [string()]:
378           Specific log lines  that  should  not  be  persisted.  For  example
379           ["q().",  "init:stop()."]  will  allow to ignore commands that shut
380           the node down. Defaults to [].
381
382         shell_history_file_bytes = integer():
383           how many bytes the shell should remember. By default, the value  is
384           set to 512kb, and the minimal value is 50kb.
385
386         shell_history_path = string():
387           Specifies where the shell history files will be stored. defaults to
388           the   user's    cache    directory    as    returned    by    file‐
389           name:basedir(user_cache, "erlang-history").
390
391         shutdown_func = {Mod, Func}:
392           Where:
393
394           * Mod = atom()
395
396           * Func = atom()
397
398           Sets a function that application_controller calls when it starts to
399           terminate. The function is called as Mod:Func(Reason), where Reason
400           is  the  terminate  reason  for application_controller, and it must
401           return as soon as possible for application_controller to  terminate
402           properly.
403
404         source_search_rules = [DirRule] | [SuffixRule] :
405
406
407           Where:
408
409           * DirRule = {ObjDirSuffix,SrcDirSuffix}
410
411           * SuffixRule = {ObjSuffix,SrcSuffix,[DirRule]}
412
413           * ObjDirSuffix = string()
414
415           * SrcDirSuffix = string()
416
417           * ObjSuffix = string()
418
419           * SrcSuffix = string()
420
421           Specifies   a   list   of  rules  for  use  by  filelib:find_file/2
422           filelib:find_source/2 If this is set to some other value  than  the
423           empty  list,  it  replaces  the  default rules. Rules can be simple
424           pairs of directory suffixes, such as  {"ebin",  "src"},  which  are
425           used  by filelib:find_file/2, or triples specifying separate direc‐
426           tory suffix rules depending on file name  extensions,  for  example
427           [{".beam",   ".erl",   [{"ebin",   "src"}]},   which  are  used  by
428           filelib:find_source/2. Both kinds of rules  can  be  mixed  in  the
429           list.
430
431           The  interpretation of ObjDirSuffix and SrcDirSuffix is as follows:
432           if the end of the directory name where an object is located matches
433           ObjDirSuffix,  then the name created by replacing ObjDirSuffix with
434           SrcDirSuffix is expanded by  calling  filelib:wildcard/1,  and  the
435           first regular file found among the matches is the source file.
436

DEPRECATED CONFIGURATION PARAMETERS

438       In Erlang/OTP 21.0, a new API for logging was added. The old error_log‐
439       ger event manager, and event handlers running on  this  manager,  still
440       work, but they are no longer used by default.
441
442       The  following  application  configuration parameters can still be set,
443       but they are only used if the  corresponding  configuration  parameters
444       for Logger are not set.
445
446         error_logger:
447           Replaced  by  setting the type, and possibly file and modes parame‐
448           ters of the default logger_std_h handler. Example:
449
450         erl -kernel logger '[{handler,default,logger_std_h,#{config=>#{file=>"/tmp/erlang.log"}}}]'
451
452
453         error_logger_format_depth:
454           Replaced by setting the depth parameter  of  the  default  handlers
455           formatter. Example:
456
457         erl -kernel logger '[{handler,default,logger_std_h,#{formatter=>{logger_formatter,#{legacy_header=>true,template=>[{logger_formatter,header},"\n",msg,"\n"],depth=>10}}}]'
458
459
460       See Backwards compatibility with error_logger for more information.
461

SEE ALSO

463       app(4),   application(3),   code(3),  disk_log(3),  erl_boot_server(3),
464       erl_ddll(3), file(3), global(3),  global_group(3),  heart(3),  inet(3),
465       logger(3), net_kernel(3), os(3), pg2(3), rpc(3), seq_trace(3), user(3),
466       timer(3)
467
468
469
470Ericsson AB                       kernel 6.5                         kernel(7)
Impressum