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 er‐
45           lang: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  ap‐
94       plication.  For  more  information  about configuration parameters, see
95       file app(4).
96
97         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
105           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
110         distributed = [Distrib]:
111           Specifies which applications that  are  distributed  and  on  which
112           nodes they are allowed to execute. In this parameter:
113
114           * Distrib = {App,Nodes} | {App,Time,Nodes}
115
116           * App = atom()
117
118           * Time = integer()>0
119
120           * Nodes = [node() | {node(),...,node()}]
121
122           The parameter is described in application:load/2.
123
124         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
129           never:
130             Connections are never automatically established, they must be ex‐
131             plicitly connected. See net_kernel(3).
132
133           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
138         permissions = [Perm]:
139           Specifies the default permission for  applications  when  they  are
140           started. In this parameter:
141
142           * Perm = {ApplName,Bool}
143
144           * ApplName = atom()
145
146           * Bool = boolean()
147
148           Permissions are described in application:permit/2.
149
150         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
156           The logger  parameter is described in section  Logging in the  Ker‐
157           nel User's Guide.
158
159         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
165           Level = emergency | alert | critical | error | warning |  notice  |
166           info | debug | all | none
167
168           To  change  the  primary  log level at runtime, use logger:set_pri‐
169           mary_config(level, Level).
170
171           Defaults to notice.
172
173         logger_metadata = Metadata:
174           Specifies primary metadata for log events.
175
176           Metadata = map()
177
178           Defaults to #{}.
179
180         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
184           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
190           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
194           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
199           Defaults to false.
200
201     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
210
211         global_groups = [GroupTuple]:
212           Defines global groups, see global_group(3). In this parameter:
213
214           * GroupTuple  =  {GroupName,  [Node]}  |  {GroupName,  PublishType,
215             [Node]}
216
217           * GroupName = atom()
218
219           * PublishType = normal | hidden
220
221           * Node = node()
222
223         inet_default_connect_options = [{Opt, Val}]:
224           Specifies default options for connect sockets, see inet(3).
225
226         inet_default_listen_options = [{Opt, Val}]:
227           Specifies  default  options  for  listen  (and accept) sockets, see
228           inet(3).
229
230         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
235         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
239         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
244         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
248         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
252         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
256         net_setuptime = SetupTime:
257
258
259           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
266           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
270         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
285           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
294         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
306     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
310
311     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
315
316         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
321           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
331           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
335         MinT = NetTickTime - NetTickTime / NetTickIntensity
336         MaxT = NetTickTime + NetTickTime / NetTickIntensity
337
338           NetTickTime defaults to 60 seconds and NetTickIntensity defaults to
339           4. Thus, 45 < T < 75 seconds.
340
341     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
347
348           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
353           Normally, a terminating node is detected immediately by the  trans‐
354           port protocol (like TCP/IP).
355
356         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
363         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
370         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
376         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
382         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
388         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
393           Defaults to true.
394
395         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
399           Defaults  to  false.  If this parameter is undefined, the server is
400           started if parameter distributed is set.
401
402         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
407           Defaults to false.
408
409         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
414           SlaveIP = string() |  atom  |  {integer(),integer(),integer(),inte‐
415           ger()},
416
417           where 0 <= integer() <=255.
418
419           Examples of SlaveIP in atom, string, and tuple form:
420
421           '150.236.16.70', "150,236,16,70", {150,236,16,70}.
422
423           Defaults to [].
424
425         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
430           Defaults to false.
431
432         start_pg = true | false:
433
434
435           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
439           Defaults to false.
440
441         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
446           Defaults to false.
447
448         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
457         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
462         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
466         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
471         shutdown_func = {Mod, Func}:
472           Where:
473
474           * Mod = atom()
475
476           * Func = atom()
477
478           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
484         source_search_rules = [DirRule] | [SuffixRule] :
485
486
487           Where:
488
489           * DirRule = {ObjDirSuffix,SrcDirSuffix}
490
491           * SuffixRule = {ObjSuffix,SrcSuffix,[DirRule]}
492
493           * ObjDirSuffix = string()
494
495           * SrcDirSuffix = string()
496
497           * ObjSuffix = string()
498
499           * SrcSuffix = string()
500
501           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
511           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
517         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
523           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
527           Encoding is one of:
528
529           unicode:
530             Configure standard_io to use unicode mode.
531
532           latin1:
533             Configure standard_io to use latin1 mode.
534
535           _:
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
540           See   Escripts  and  non-interactive I/O in Unicode Usage in Erlang
541           for more details.
542

DEPRECATED CONFIGURATION PARAMETERS

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
548       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
552         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
556         erl -kernel logger '[{handler,default,logger_std_h,#{config=>#{file=>"/tmp/erlang.log"}}}]'
557
558
559         error_logger_format_depth:
560           Replaced  by  setting  the  depth parameter of the default handlers
561           formatter. Example:
562
563         erl -kernel logger '[{handler,default,logger_std_h,#{formatter=>{logger_formatter,#{legacy_header=>true,template=>[{logger_formatter,header},"\n",msg,"\n"],depth=>10}}}]'
564
565
566       See Backwards compatibility with error_logger for more information.
567

SEE ALSO

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)
572
573
574
575Ericsson AB                       kernel 9.1                         kernel(7)
Impressum