logging.xml 35.4 KB
Newer Older
1
2
3
4
5
6
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN"
"http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd" [
<!ENTITY mdash  "&#x2014;" >
]>

Tomek Mrugalski's avatar
Tomek Mrugalski committed
7
8
9
10
11
12
13
14
15
16
17
18
  <!-- Note: Please use the following terminology:
       - daemon - one process (e.g. kea-dhcp4)
       - component - one piece of code within a daemon (e.g. libdhcp or hooks)
       - server - currently equal to daemon, but the difference will be more
                  prominent once we add client or relay support
       - logger - one instance of isc::log::Logger
       - structure - an element in config file (e.g. "Dhcp4")

       Do not use:
       - module => daemon
    -->

19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
<chapter id="logging">
  <title>Logging</title>

  <section>
    <title>Logging Configuration</title>
    <para>
      During its operation Kea may produce many messages. They differ in
      severity (some are more important than others) and source (some are
      produced by specific components, e.g. hooks). It is useful to understand
      which log messages are needed and which are not, and configure your
      logging appropriately. For example, debug level messages can be safely
      ignored in a typical deployment. They are, however, very useful when
      debugging a problem.
    </para>

    <para>
      The logging system in Kea is configured through the
      Logging section in your configuration
      file. All daemons (e.g. DHCPv4 and DHCPv6 servers) will use the
      configuration in the Logging section to see
      what should be logged and to where. This allows for sharing identical
      logging configuration between daemons.
    </para>
42
43

    <section>
44
45
46
47
48
49
50
51
52
53
54
55
56
57
      <title>Loggers</title>
      <para>
        Within Kea, a message is logged through an entity called a
        "logger". Different components log messages through different
        loggers, and each logger can be configured independently of
        one another. Some components, in particular the DHCP server
        processes, may use multiple loggers to log messages pertaining
        to different logical functions of the component. For example,
        the DHCPv4 server uses one logger for messages
        pertaining to packet reception and transmission, another
        logger for messages related to lease allocation and so on.
        Some of the libraries used by the Kea servers, e.g. libdhcpsrv,
        use their own loggers.
      </para>
58
59

      <para>
60
61
62
63
        Users implementing hooks libraries (code attached to the server at
        runtime) are responsible for creating the loggers used by those
        libraries. Such loggers should have unique names, different
        from the logger names used by Kea. In this way the
Francis Dupont's avatar
Francis Dupont committed
64
        messages output by the hooks library can be distinguished from
65
66
67
68
69
        messages issued by the core Kea code. Unique names also allow
        the loggers to be configured independently of loggers used
        by Kea.  Whenever it makes sense, a hook library can use multiple
        loggers to log messages pertaining to different logical parts
        of the library.
70
      </para>
71

72
      <para>
73
74
75
76
        In the Logging section of a configuration file you can specify the
        configuration for zero or more loggers (including loggers used by the
        proprietary hooks libraries). If there are no loggers specified, the
        code will use default values: these cause Kea to log messages of INFO
77
78
79
80
        severity or greater to standard output. There is also a small
        time window after Kea has been started, but has not yet read its
        configuration. Logging in this short period can be controlled
        using environment variables. For details, see <xref linkend="logging-during-startup"></xref>.
81
82
      </para>

83
84
85
86
87
88
89
90
      <para>
        The three main elements of a logger configuration are:
        <command>name</command> (the component that is generating the messages),
        the <command>severity</command> (what to log), and the
        <command>output_commands</command> (where to log).  There is also a
        <command>debuglevel</command> element, which is only relevant if
        debug-level logging has been selected.
      </para>
91

92
93
      <section>
        <title>name (string)</title>
94
        <para>
95
96
97
98
99
100
101
          Each logger in the system has a name, the name being that of the
          component binary file using it to log messages. For instance, if you
          want to configure logging for the DHCPv4 server, you add an entry
          for a logger named <quote>kea-dhcp4</quote>. This configuration will
          then be used by the loggers in the DHCPv4 server, and all the
          libraries used by it (unless a library defines its own logger and
          there is specific logger configuration that applies to that logger).
102
103
104
        </para>

        <para>
105
106
107
108
109
110
111
112
113
114
115
116
          When tracking down an issue with the server's operation, use of
          DEBUG logging is required to obtain the verbose output needed for
          problems diagnosis.  However, the high verbosity is likely to
          overwhelm the logging system in cases when the server
          is processing high volume traffic. To mitigate this problem, use
          can be made of the fact that Kea uses multiple loggers for different
          functional parts of the server and that each of these can be configured independently.
          If the user is reasonably confident that a problem originates
          in a specific function of the server, or that the problem is related
          to the specific type of operation, they may enable high verbosity
          only for the relevant logger, so limiting the debug messages
          to the required minimum.
117
118
119
        </para>

        <para>
120
121
122
123
124
          The loggers are associated with a particular library or binary
          of Kea. However, each library or binary may (and usually does)
          include multiple loggers. For example, the DHCPv4 server binary
          contains separate loggers for: packet parsing, for dropped packets,
          for callouts etc.
125
126
127
        </para>

        <para>
128
129
130
131
132
133
          The loggers form a hierarchy.  For each program in Kea, there is
          a "root" logger, named after the program (e.g. the root logger for
          kea-dhcp (the DHCPv4 server) is named kea-dhcp4.  All other loggers
          are children of this logger, and are named accordingly, e.g. the
          the allocation engine in the DHCPv4 server logs messages using
          a logger called kea-dhcp4.alloc-engine.
134
135
        </para>

136
137
138
139
140
141
142
143
144
        <para>
          This relationship is important as each child logger derives its
          default configuration from its parent root logger.
          In the typical case, the root logger configuration
          is the only logging configuration specified in the configuration
          file and so applies to all loggers. If an entry is made for
          a given logger, any attributes specified override those of
          the root logger, whereas any not specified are inherited from it.
        </para>
145

146
147
148
149
150
151
152
        <para>
          To illustrate this, suppose you are using the DHCPv4 server
          with the root logger <quote>kea-dhcp4</quote> logging at the
          INFO level. In order to enable DEBUG verbosity for the DHCPv4
          packet drops, you must create configuration entry for the
          logger called <quote>kea-dhcp4.bad-packets</quote> and specify
          severity DEBUG for this logger. All other configuration
Francis Dupont's avatar
Francis Dupont committed
153
          parameters may be omitted for this logger if the logger should
154
155
156
          use the default values specified in the root logger's
          configuration.
        </para>
157

Tomek Mrugalski's avatar
Tomek Mrugalski committed
158
        <!-- we don't support asterisk anymore.
159
        <para>
Tomek Mrugalski's avatar
Tomek Mrugalski committed
160
          One special case is that of a component name of <quote>*</quote>
161
          (asterisks), which is interpreted as <emphasis>any</emphasis>
Tomek Mrugalski's avatar
Tomek Mrugalski committed
162
          component. You can set global logging options by using this,
163
          including setting the logging configuration for a library
Tomek Mrugalski's avatar
Tomek Mrugalski committed
164
          that is used by multiple daemons (e.g. <quote>*.config</quote>
165
          specifies the configuration library code in whatever
Tomek Mrugalski's avatar
Tomek Mrugalski committed
166
          daemon is using it).
167
        </para> -->
168

169
170
171
172
173
174
175
176
177
178
        <para>
          If there are multiple logger specifications in the configuration
          that might match a particular logger, the specification with the
          more specific logger name takes precedence. For example, if there
          are entries for both <quote>kea-dhcp4</quote> and
          <quote>kea-dhcp4.dhcpsrv</quote>, the DHCPv4 server &mdash; and all
          libraries it uses that are not dhcpsrv &mdash; will log messages
          according to the configuration in the first entry
          (<quote>kea-dhcp4</quote>).
        </para>
179

180
181
182
        <para>
          Currently defined loggers are:
        </para>
Tomek Mrugalski's avatar
Tomek Mrugalski committed
183
        <itemizedlist>
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
          <listitem>
            <simpara>
              <command>kea-ctrl-agent</command> - the root logger for the
              Control Agent exposing RESTful control API. All components used
              by the Control Agent inherit the settings from this logger.
            </simpara>
          </listitem>

          <listitem>
            <simpara>
              <command>kea-ctrl-agent.http</command> - a logger which outputs
              log messages related to receiving, parsing and sending HTTP
              messages.
            </simpara>
          </listitem>

200
          <listitem>
201
202
203
204
205
            <simpara>
              <command>kea-dhcp4</command> - the root logger for the DHCPv4
              server. All components used by the DHCPv4 server inherit the
              settings from this logger.
            </simpara>
206
          </listitem>
207

208
          <listitem>
209
210
211
212
213
214
            <simpara>
              <command>kea-dhcp4.alloc-engine</command> - used by the lease
              allocation engine, which is responsible for managing leases in the
              lease database, i.e. create, modify and remove DHCPv4 leases as a
              result of processing messages from the clients.
            </simpara>
215
          </listitem>
216

217
          <listitem>
218
219
220
221
222
223
224
            <simpara>
              <command>kea-dhcp4.bad-packets</command> - used by the DHCPv4
              server daemon for logging inbound client packets that were dropped
              or to which the server responded with a DHCPNAK. It allows
              administrators to configure a separate log output that contains
              only packet drop and reject entries.
            </simpara>
225
          </listitem>
226

227
          <listitem>
228
229
230
231
            <simpara>
              <command>kea-dhcp4.callouts</command> - used to log messages
              pertaining to the callouts registration and execution for the
              particular hook point.
232
            </simpara>
Tomek Mrugalski's avatar
Tomek Mrugalski committed
233
          </listitem>
234

235
          <listitem>
236
237
238
239
            <simpara>
              <command>kea-dhcp4.commands</command> - used to log messages
              relating to the handling of commands received by the the DHCPv4
              server over the command channel.
240
241
            </simpara>
          </listitem>
242

243
          <listitem>
244
245
246
247
248
249
            <simpara>
              <command>kea-dhcp4.ddns</command> - used by the DHCPv4 server to
              log messages related to the Client FQDN and Hostname option
              processing. It also includes log messages related to the relevant
              DNS updates.
            </simpara>
Tomek Mrugalski's avatar
Tomek Mrugalski committed
250
          </listitem>
251

252
          <listitem>
253
254
255
256
            <simpara>
              <command>kea-dhcp4.dhcp4</command> - used by the DHCPv4 server
              daemon to log basic operations.
            </simpara>
257
          </listitem>
258

259
          <listitem>
260
261
262
263
            <simpara>
              <command>kea-dhcp4.dhcpsrv</command> - the base logger for the
              libdhcpsrv library.
            </simpara>
264
          </listitem>
265

266
          <listitem>
267
268
269
270
            <simpara>
              <command>kea-dhcp4.eval</command> - used to log messages relating
              to the client classification expression evaluation code.
            </simpara>
271
          </listitem>
272

273
          <listitem>
274
275
276
277
278
279
280
            <simpara>
              <command>kea-dhcp4.hooks</command> - used to log messages related
              to management of hooks libraries, e.g.  registration and
              deregistration of the libraries, and to the initialization of the
              callouts execution for various hook points within the DHCPv4
              server.
            </simpara>
281
          </listitem>
282

283
          <listitem>
284
285
286
287
288
289
            <simpara>
              <command>kea-dhcp4.hosts</command> - used within the libdhcpsrv
              and it logs messages related to the management of the DHCPv4 host
              reservations, i.e. retrieval of the reservations and adding new
              reservations.
            </simpara>
290
          </listitem>
291

292
          <listitem>
293
294
295
296
297
            <simpara>
              <command>kea-dhcp4.leases</command> - used by the DHCPv4 server to
              log messages related to the lease allocation.  The messages
              include detailed information about the allocated or offered
              leases, errors during the lease allocation etc.
298
299
            </simpara>
          </listitem>
300

301
          <listitem>
302
303
304
305
306
307
308
            <simpara>
              <command>kea-dhcp4.options</command> - used by the DHCPv4 server
              to log messages related to processing of the options in the DHCPv4
              messages, i.e. parsing options, encoding options into on-wire
              format and packet classification using options contained in the
              received packets.
            </simpara>
309
          </listitem>
310

311
          <listitem>
312
313
314
315
316
317
318
319
320
321
            <simpara>
              <command>kea-dhcp4.packets</command> - this logger is mostly used
              to log messages related to transmission of the DHCPv4 packets,
              i.e. packet reception and sending a response. Such messages
              include information about the source and destination IP addresses
              and interfaces used to transmit packets. The logger is also used
              to log messages related to subnet selection, as this selection is
              usually based on the IP addresses and/or interface names, which
              can be retrieved from the received packet, even before the DHCPv4
              message carried in the packet is parsed.
322
323
            </simpara>
          </listitem>
324

Tomek Mrugalski's avatar
Tomek Mrugalski committed
325
          <listitem>
326
327
328
329
330
331
            <simpara>
              <command>kea-dhcp6</command> - the root logger for the DHCPv6
              server. All components used by the DHCPv6 server inherit the
              settings from this logger if there is no specialized logger
              provided.
            </simpara>
332
          </listitem>
333

334
          <listitem>
335
336
337
338
339
340
            <simpara>
              <command>kea-dhcp6.alloc-engine</command> - used used by the lease
              allocation engine, which is responsible for managing leases in the
              lease database, i.e. create, modify and remove DHCPv6 leases as a
              result of processing messages from the clients.
            </simpara>
341
          </listitem>
342

343
          <listitem>
344
345
346
347
348
            <simpara>
              <command>kea-dhcp6.bad-packets</command> - used used by the DHCPv6
              server daemon for logging inbound client packets that were
              dropped.
            </simpara>
349
          </listitem>
350

351
          <listitem>
352
353
354
355
            <simpara>
              <command>kea-dhcp6.callouts</command> - used to log messages
              pertaining to the callouts registration and execution for the
              particular hook point.
356
            </simpara>
357
          </listitem>
358

359
          <listitem>
360
361
362
363
            <simpara>
              <command>kea-dhcp6.commands</command> - used to log messages
              relating to the handling of commands received by the the DHCPv6
              server over the command channel.
364
365
            </simpara>
          </listitem>
366

367
          <listitem>
368
369
370
371
372
373
            <simpara>
              <command>kea-dhcp6.ddns</command> - this logger is used by the
              DHCPv6 server to log messages related to the Client FQDN option
              processing. It also includes log messages related to the relevant
              DNS updates.
            </simpara>
374
          </listitem>
375

376
          <listitem>
377
378
379
380
            <simpara>
              <command>kea-dhcp6.dhcp6</command> - used DHCPv6 server daemon to
              log basic operations.
            </simpara>
381
          </listitem>
382

383
          <listitem>
384
385
386
387
            <simpara>
              <command>kea-dhcp6.dhcpsrv</command> - the base logger for the
              libdhcpsrv library.
            </simpara>
388
          </listitem>
389

390
          <listitem>
391
392
393
394
            <simpara>
              <command>kea-dhcp6.eval</command> - used to log messages relating
              to the client classification expression evaluation code.
            </simpara>
395
          </listitem>
396

397
          <listitem>
398
399
400
401
402
403
404
            <simpara>
              <command>kea-dhcp6.hooks</command> - this logger is used to log
              messages related to management of hooks libraries, e.g.
              registration and deregistration of the libraries, and to the
              initialization of the callouts execution for various hook points
              within the DHCPv6 server.
            </simpara>
405
          </listitem>
406

407
          <listitem>
408
409
410
411
412
413
            <simpara>
              <command>kea-dhcp6.hosts</command> - used within the libdhcpsrv
              and it logs messages related to the management of the DHCPv6 host
              reservations, i.e. retrieval of the reservations and adding new
              reservations.
            </simpara>
414
          </listitem>
415

416
          <listitem>
417
418
419
420
421
            <simpara>
              <command>kea-dhcp6.leases</command> - used by the DHCPv6 server to
              log messages related to the lease allocation.  The messages
              include detailed information about the allocated or offered
              leases, errors during the lease allocation etc.
422
423
            </simpara>
          </listitem>
424

425
          <listitem>
426
427
428
429
430
431
432
            <simpara>
              <command>kea-dhcp6.options</command> - used by the DHCPv6 server
              to log messages related to processing of the options in the DHCPv6
              messages, i.e. parsing options, encoding options into on-wire
              format and packet classification using options contained in the
              received packets.
            </simpara>
433
          </listitem>
434

435
          <listitem>
436
437
438
439
440
441
442
443
444
445
            <simpara>
              <command>kea-dhcp6.packets</command> - this logger is mostly used
              to log messages related to transmission of the DHCPv6 packets,
              i.e. packet reception and sending a response. Such messages
              include the information about the source and destination IP
              addresses and interfaces used to transmit packets. This logger is
              also used to log messages related to subnet selection, as this
              selection is usually based on the IP addresses and/or interface
              names, which can be retrieved from the received packet, even
              before the DHCPv6 message carried in the packet is parsed.
446
447
            </simpara>
          </listitem>
448

449
          <listitem>
450
451
452
453
454
455
            <simpara>
              <command>kea-dhcp-ddns</command> - the root logger for the
              kea-dhcp-ddns daemon. All components used by this daemon inherit
              the settings from this logger if there is no specialized logger
              provided.
            </simpara>
456
          </listitem>
457

458
459
460
461
462
463
464
465
          <listitem>
            <simpara>
              <command>kea-dhcp-ddns.dctl</command> - the logger used by the
              kea-dhcp-ddns daemon for logging basic information about the
              process, received signals and triggered reconfigurations.
            </simpara>
          </listitem>

466
          <listitem>
467
468
            <simpara>
              <command>kea-dhcp-ddns.dhcpddns</command> - the logger used by the
469
              kea-dhcp-ddns daemon for logging events related to DDNS operations.
470
            </simpara>
471
          </listitem>
472

473
          <listitem>
474
475
476
477
478
479
            <simpara>
              <command>kea-dhcp-ddns.dhcp-to-d2</command> - used by the
              kea-dhcp-ddns daemon for logging information about events dealing
              with receiving messages from the DHCP servers and adding them to
              the queue for processing.
            </simpara>
480
          </listitem>
481

482
          <listitem>
483
484
485
486
            <simpara>
              <command>kea-dhcp-ddns.d2-to-dns</command> - used by the
              kea-dhcp-ddns daemon for logging information about events dealing
              with sending and receiving messages with the DNS servers.
487
488
            </simpara>
          </listitem>
Tomek Mrugalski's avatar
Tomek Mrugalski committed
489
490
        </itemizedlist>

491
        <para>
492
          Note that user-defined hook libraries should not use any of those
493
494
495
          loggers but should define new loggers with names that correspond to
          the libraries using them. Suppose that the user created the library
          called <quote>libpacket-capture</quote> to dump packets received and
496
          transmitted by the server to the file. The appropriate name for the
497
498
499
500
501
502
503
          logger could be <command>kea-dhcp4.packet-capture</command>. (Note
          that the hook library implementor only specifies the second part of
          this name, i.e. <quote>packet-capture</quote>. The first part is a
          root logger name and is prepended by the Kea logging system.) It is
          also important to note that since this new logger is a child of a root
          logger, it inherits the configuration from the root logger, something
          that can be overridden by an entry in the configuration file.
504
505
506
507
        </para>

        <para>
          The list of loggers above excludes any loggers implemented in hooks
508
509
          libraries. Please consult the documentation for the libraries for the
          names of the loggers they define.
510
511
        </para>

512
513
514
515
516
517
518
        <para>
          Additional loggers may be defined in future versions of Kea. The
          easiest way to find out the logger name is to configure all logging to
          go to a single destination and look for specific logger names. See
          <xref linkend="logging-message-format"/> for details.
        </para>
      </section>
519

520
521
      <section>
        <title>severity (string)</title>
522
        <para>
523
524
525
          This specifies the category of messages logged.  Each message is
          logged with an associated severity which may be one of the following
          (in descending order of severity):
526
527
528
529
        </para>

        <itemizedlist>
          <listitem>
530
531
532
533
            <simpara>
              FATAL - associated with messages generated by a condition that is
              so serious that the server cannot continue executing.
            </simpara>
534
535
536
          </listitem>

          <listitem>
537
538
539
540
541
            <simpara>
              ERROR- associated with messages generated by an error condition.
              The server will continue executing, but the results may not be as
              expected.
            </simpara>
542
543
544
          </listitem>

          <listitem>
545
546
547
548
            <simpara>
              WARN - indicates an out of the ordinary condition.  However, the
              server will continue executing normally.
            </simpara>
549
550
551
          </listitem>

          <listitem>
552
553
554
            <simpara>
              INFO - an informational message marking some event.
            </simpara>
555
556
557
          </listitem>

          <listitem>
558
559
560
            <simpara>
              DEBUG - messages produced for debugging purposes.
            </simpara>
561
562
563
564
          </listitem>
        </itemizedlist>

        <para>
565
566
567
568
569
          When the severity of a logger is set to one of these values, it will
          only log messages of that severity and above (e.g. setting the logging
          severity to INFO will log INFO, WARN, ERROR and FATAL messages).  The
          severity may also be set to NONE, in which case all messages from that
          logger are inhibited.
570
571
        </para>

572
573
574
        <note>
          <para>
            The keactrl tool, described in <xref linkend="keactrl"/>, can be
575
576
577
578
579
580
581
582
            configured to start the servers in the verbose mode. If this is the
            case, the settings of the logging severity in the configuration file
            will have no effect, i.e. the servers will use logging severity of
            DEBUG regardless of the logging settings specified in the
            configuration file. If you need to control severity via
            configuration file, please make sure that the
            <parameter>kea_verbose</parameter> value is set to "no" within the
            keactrl configuration.
583
584
          </para>
        </note>
585
      </section>
586

587
588
      <section>
        <title>debuglevel (integer)</title>
589
        <para>
590
591
592
593
          When a logger's severity is set to DEBUG, this value specifies what
          level of debug messages should be printed. It ranges from 0 (least
          verbose) to 99 (most verbose). If severity for the logger is not
          DEBUG, this value is ignored.
594
595
596
597
        </para>
      </section>

      <section>
598
        <title>output_options (list)</title>
599
        <para>
600
601
602
          Each logger can have zero or more <option>output_options</option>.
          These specify where log messages are sent. These are explained in
          detail below.
603
604
605
        </para>

        <section>
606
          <title>output (string)</title>
607
          <para>
608
609
610
611
612
613
614
            This value determines the type of output. There are several special
            values allowed here: <command>stdout</command> (messages are printed
            on standard output), <command>stderr</command> (messages are printed
            on stderr), <command>syslog</command> (messages are logged to syslog
            using default name, <command>syslog:name</command> (messages are
            logged to syslog using specified name). Any other value is
            interpreted as a filename to which messages should be written.
615
616
617
618
619
620
          </para>
        </section>

        <section>
          <title>flush (true of false)</title>
          <para>
621
622
623
624
            Flush buffers after each log message. Doing this will reduce
            performance but will ensure that if the program terminates
            abnormally, all messages up to the point of termination are output.
            The default is "true".
625
          </para>
626
        </section>
627
628
629
630

        <section>
          <title>maxsize (integer)</title>
          <para>
631
632
633
634
            Only relevant when destination is file, this is maximum file size of
            output files in bytes. When the maximum size is reached, the file is
            renamed and a new file opened.  (For example, a ".1" is appended to
            the name &mdash; if a ".1" file exists, it is renamed ".2", etc.)
635
636
          </para>
          <para>
637
            If this is set to 0 or omitted, no maximum file size is used.
638
639
640
641
          </para>

          <note>
            <simpara>
642
643
644
645
646
647
648
649
650
651
652
              Due to a limitation of the underlying logging library (log4cplus),
              rolling over the log files (from ".1" to ".2", etc) may show odd
              results: There can be multiple small files at the timing of roll
              over.  This can happen when multiple processes try to roll over
              the files simultaneously.  Version 1.1.0 of log4cplus solved this
              problem, so if this version or later of log4cplus is used to
              build Kea, it should not happen.  Even for older versions it is
              normally expected to happen rarely unless the log messages are
              produced very frequently by multiple different processes.
            </simpara>
          </note>
653
654
655
656
657
        </section>

        <section>
          <title>maxver (integer)</title>
          <para>
658
659
660
            Maximum number of old log files to keep around when rolling the
            output file. Only relevant when <option>output</option> is
            <quote>file</quote>.
661
662
663
664
665
          </para>
        </section>
      </section>

      <section>
666
        <title>Example Logger Configurations</title>
667
        <para>
668
669
          In this example we want to set the global logging to write to the
          console using standard output.
Tomek Mrugalski's avatar
Tomek Mrugalski committed
670
671
        </para>

672
<screen><userinput>"Logging": {
Tomek Mrugalski's avatar
Tomek Mrugalski committed
673
674
    "loggers": [
        {
Tomek Mrugalski's avatar
Tomek Mrugalski committed
675
            "name": "kea-dhcp4",
Tomek Mrugalski's avatar
Tomek Mrugalski committed
676
677
678
679
            "output_options": [
                {
                    "output": "stdout"
                }
680
            ],
Tomek Mrugalski's avatar
Tomek Mrugalski committed
681
682
683
            "severity": "WARN"
        }
    ]
684
}</userinput> </screen>
685

686
687
688
689
690
691
        <para>
          In this second example, we want to store debug log messages in a file
          that is at most 2MB and keep up to 8 copies of old logfiles.  Once the
          logfile grows to 2MB, it will be renamed and a new file file be
          created.
        </para>
Tomek Mrugalski's avatar
Tomek Mrugalski committed
692

693
<screen><userinput>"Logging": {
Tomek Mrugalski's avatar
Tomek Mrugalski committed
694
695
    "loggers": [
        {
Tomek Mrugalski's avatar
Tomek Mrugalski committed
696
            "name": "kea-dhcp6",
Tomek Mrugalski's avatar
Tomek Mrugalski committed
697
698
699
700
701
            "output_options": [
                {
                    "output": "/var/log/kea-debug.log",
                    "maxver": 8,
                    "maxsize": 204800,
702
                    "flush": true
Tomek Mrugalski's avatar
Tomek Mrugalski committed
703
                }
704
            ],
Tomek Mrugalski's avatar
Tomek Mrugalski committed
705
706
707
708
709
            "severity": "DEBUG",
            "debuglevel": 99
        }
   ]
}</userinput></screen>
710
711
712
713
      </section>

    </section>

714
    <section id="logging-message-format">
715
716
      <title>Logging Message Format</title>
      <para>
717
718
719
720
        Each message written  to the configured logging destinations comprises a
        number of components that identify the origin of the message and, if the
        message indicates a problem, information about the problem that may be
        useful in fixing it.
721
722
723
      </para>

      <para>
724
725
726
        Consider the message below logged to a file:

<screen>2014-04-11 12:58:01.005 INFO  [kea-dhcp4.dhcpsrv/27456]
727
728
729
730
    DHCPSRV_MEMFILE_DB opening memory file lease database: type=memfile universe=4</screen>
      </para>

      <para>
731
732
733
734
        Note: the layout of messages written to the system logging file (syslog)
        may be slightly different.  This message has been split across two lines
        here for display reasons; in the logging file, it will appear on one
        line.
735
736
737
738
739
      </para>

      <para>
        The log message comprises a number of components:

740
741
742
       <variablelist>
         <varlistentry>
           <term>2014-04-11 12:58:01.005</term>
743
<!-- TODO: timestamp repeated even if using syslog? -->
744
745
746
747
748
           <listitem>
             <para>
               The date and time at which the message was generated.
              </para>
            </listitem>
749
750
751
          </varlistentry>

          <varlistentry>
752
753
754
755
756
757
            <term>INFO</term>
            <listitem>
              <para>
                The severity of the message.
              </para>
            </listitem>
758
759
760
          </varlistentry>

          <varlistentry>
761
762
763
764
765
766
767
768
769
770
771
772
            <term>[kea-dhcp4.dhcpsrv/27456]</term>
            <listitem>
              <para>
                The source of the message.  This comprises two elements: the Kea
                process generating the message (in this case,
                <command>kea-dhcp4</command>) and the component within the
                program from which the message originated
                (<command>dhcpsrv</command>, which is the name of the common
                library used by DHCP server implementations). The number after
                the slash is a process id (pid).
              </para>
            </listitem>
773
774
775
          </varlistentry>

          <varlistentry>
776
777
778
779
780
781
782
783
784
785
786
            <term>DHCPSRV_MEMFILE_DB</term>
            <listitem>
              <para>
                The message identification.  Every message in Kea has a unique
                identification, which can be used as an index into the
                <ulink url="kea-messages.html"><citetitle>Kea Messages
                Manual</citetitle></ulink>
                (<ulink url="http://kea.isc.org/docs/kea-messages.html" />)
                from which more information can be obtained.
              </para>
            </listitem>
787
788
789
          </varlistentry>

          <varlistentry>
790
791
792
793
794
795
796
797
798
799
            <term>opening memory file lease database: type=memfile universe=4</term>
            <listitem>
              <para>
                A brief description.  Within this text, information relating to
                the condition that caused the message to be logged will be
                included.  In this example, the information is logged that the
                in-memory lease database backend will be used to store DHCP
                leases.
              </para>
            </listitem>
800
          </varlistentry>
801
        </variablelist>
802
803
804
      </para>
    </section>

805
    <section id="logging-during-startup">
806
      <title>Logging During Kea Startup</title>
807
      <para>
808
809
        The logging configuration is specified in the configuration file.
        However, when Kea starts, the file is not read until some way into the
810
811
812
813
814
815
        initialization process.  Prior to that, the logging settings are set to
        default values, although it is possible to modify some aspects of the
        settings by means of environment variables. Note that in the absence of
        any logging configuration in the configuration file, the settings of
        (possibly modified) default configuration will persist while the program
        is running.
816
817
      </para>
      <para>
818
819
        The following environment variables can be used to control the behavior
        of logging during startup:
820
821
      </para>

822
823
      <variablelist>
        <varlistentry>
824
          <term>KEA_LOCKFILE_DIR</term>
825
826
          <listitem>
            <para>
827
              Specifies a directory where the logging system should create its
828
829
              lock file. If not specified, it is
              <replaceable>prefix</replaceable>/var/run/kea, where
830
831
832
833
834
835
836
              <replaceable>prefix</replaceable> defaults to /usr/local.  This
              variable must not end with a slash. There is one special value:
              "none", which instructs Kea to not create lock file at all. This
              may cause issues if several processes log to the same file.
            </para>
          </listitem>
        </varlistentry>
837

838
        <varlistentry>
839
          <term>KEA_LOGGER_DESTINATION</term>
840
841
          <listitem>
            <para>
842
              Specifies logging output. There are several special values.
843
              <variablelist>
844
845
846
847
848
849
850
851
852
853
854
855
856
857
858
859
860
861
862
863
864
865
866
867
868
869
870
871
872
873
                <varlistentry>
                  <term>stdout</term>
                  <listitem>
                    <para>
                      Log to standard output.
                    </para>
                  </listitem>
                </varlistentry>

                <varlistentry>
                  <term>stderr</term>
                  <listitem>
                    <para>
                      Log to standard error.
                    </para>
                  </listitem>
                </varlistentry>

                <varlistentry>
                  <term>syslog<optional>:<replaceable>fac</replaceable></optional></term>
                  <listitem>
                    <para>
                      Log via syslog. The optional
                      <replaceable>fac</replaceable> (which is separated from
                      the word "syslog" by a colon) specifies the facility to be
                      used for the log messages. Unless specified, messages will
                      be logged using the facility "local0".
                    </para>
                  </listitem>
                </varlistentry>
874
              </variablelist>
875
876
877
878
879
880
              Any other value is treated as a name of the output file. If not
              specified otherwise, Kea will log to standard output.
            </para>
          </listitem>
        </varlistentry>
      </variablelist>
881
    </section>
882
883
  </section>
</chapter>