Merge branch 'trac3536'

Makefile.am

@@ -119,6 +119,10 @@ cppcheck:
 		--template '{file}:{line}: check_fail: {message} ({severity},{id})' \
 		src
 
+# These steps are necessary during installation
+install-exec-hook:
+	mkdir -p $(DESTDIR)${localstatedir}/log/
+
 ### include tool to generate documentation from log message specifications
 ### in the distributed tarball:
 EXTRA_DIST = tools/system_messages.py

doc/guide/logging.xml

@@ -4,6 +4,18 @@
 <!ENTITY mdash  "&#x2014;" >
 ]>
 
+  <!-- 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
+    -->
+
   <chapter id="logging">
     <title>Logging</title>
 
@@ -11,161 +23,198 @@
       <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 module. All  modules will look at the
-        configuration in Logging to see what should be logged and
-        to where.
-
-<!-- TODO: what is context of Logging module for readers of this guide? -->
-
+        <replaceable>Logging</replaceable> structure in your configuration
+        file. All daemons (e.g. DHCPv4 and DHCPv6 servers) will use the
+        configuration in the <replaceable>Logging</replaceable> structure to see
+        what should be logged and to where. This allows for sharing identical
+        logging configuration between daemons.
       </para>
 
       <section>
         <title>Loggers</title>
 
         <para>
-
-          Within Kea, a message is logged through a component
-          called a "logger". Different parts of log messages
+          Within Kea, a message is logged through an entity
+          called a "logger". Different parts of the code log messages
           through different loggers, and each logger can be configured
-          independently of one another.
-
+          independently of one another. For example there are different
+          components that deal with hooks ("hooks" logger) and with
+          DHCP engine ("dhcpsrv" logger).
         </para>
 
         <para>
-
-          In the Logging module, you can specify the configuration
-          for zero or more loggers; any that are not specified will
-          take appropriate default values.
-
+          In the Logging structure in a configuration file you can
+          specify the configuration for zero or more loggers. If there are
+          no loggers specified, the code will use default values which
+          cause Kea to log messages on at least INFO severity to standard
+          output.
+          <!-- @todo: add reference to section about controlling default
+          behavior with env. variables, after #3591 is merged. -->
         </para>
 
         <para>
-
           The three most important elements of a logger configuration
           are the <option>name</option> (the component that is
           generating the messages), the <option>severity</option>
           (what to log), and the <option>output_options</option>
           (where to log).
-
         </para>
 
         <section>
           <title>name (string)</title>
 
           <para>
-            Each logger in the system has a name, the name being that
-            of the component using it to log messages. For instance,
-            if you want to configure logging for the Dhcp4 module,
-            you add an entry for a logger named <quote>Dhcp4</quote>. This
-            configuration will then be used by the loggers in the
-            Dhcp4 module, and all the libraries used by it (unless
-            a library defines its own logger).
+            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).
           </para>
 
-<!-- TODO: later we will have a way to know names of all modules
-
-Right now you can only see what their names are if they are running
-(a simple 'help' without anything else in bindctl for instance).
-
- -->
           <para>
+            If you want to specify logging for one specific library within a
+            daemon, you set the name to
+            <replaceable>daemon.library</replaceable>.  For example, the logger
+            used by the code from libdhcpsrv used in kea-dhcp4 binary has the
+            full name of <quote>kea-dhcp4.dhcpsrv</quote>. If there is no entry
+            in Logging for a particular library, it will use the configuration
+            given for the whole daemon.
+          </para>
 
-          If you want to specify logging for one specific library
-          within the module, you set the name to
-          <replaceable>module.library</replaceable>.  For example, the
-          logger used by the nameserver address store component
-          has the full name of <quote>Dhcp4.dhcpsrv</quote>. If
-          there is no entry in Logging for a particular library,
-          it will use the configuration given for the module.
-        </para>
-
-       <para>
-
-          To illustrate this, suppose you want the dhcpsrv library
-          to log messages of severity DEBUG, and the rest of the
-          Dhcp4 code to log messages of severity INFO. To achieve
-          this you specify two loggers, one with the name
-          <quote>Dhcp4</quote> and severity INFO, and one with
-          the name <quote>Dhcp4.dhcpsrv</quote> with severity
-          DEBUG. As there are no entries for other libraries,
-          they will use the configuration for the module
-          (<quote>Dhcp4</quote>), so giving the desired behavior.
-
-        </para>
+          <para>
+            To illustrate this, suppose you want the dhcpsrv library
+            to log messages of severity DEBUG, and the rest of the
+            DHCPv4 server code to log messages of severity INFO. To achieve
+            this you specify two loggers, one with the name
+            <quote>kea-dhcp4</quote> and severity INFO, and one with
+            the name <quote>kea-dhcp4.dhcpsrv</quote> with severity
+            DEBUG. As there are no entries for other libraries,
+            they will use the configuration for the daemon
+            (<quote>kea-dhcp4</quote>), so giving the desired behavior.
+          </para>
 
+        <!-- we don't support asterisk anymore.
         <para>
-
-          One special case is that of a module name of <quote>*</quote>
+          One special case is that of a component name of <quote>*</quote>
           (asterisks), which is interpreted as <emphasis>any</emphasis>
-          module. You can set global logging options by using this,
+          component. You can set global logging options by using this,
           including setting the logging configuration for a library
-          that is used by multiple modules (e.g. <quote>*.config</quote>
+          that is used by multiple daemons (e.g. <quote>*.config</quote>
           specifies the configuration library code in whatever
-          module is using it).
+          daemon is using it).
+        </para> -->
 
-        </para>
-
-        <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>*</quote> and <quote>Dhcp4</quote>, the
-          Dhcp4 module &mdash; and all libraries it uses &mdash;
-          will log messages according to the configuration in the
-          second entry (<quote>Dhcp4</quote>). All other modules
-          will use the configuration of the first entry
-          (<quote>*</quote>).
-
-        </para>
-
-        <para>
+          <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>
 
-          One final note about the naming. When specifying the
-          module name within a logger, use the name of the binary file,
-          e.g. <quote>kea-dhcp4</quote> for the DHCPv4 module,
-          <quote>kea-dhcp6</quote> for the DHCPv6 module, etc. When
-          the message is logged, the message will include the name
-          of the logger generating the message, but with the module
-          name replaced by the name of the process implementing
-          the module (so for example, a message generated by the
-          <quote>DHCPv4</quote> logger will appear in the output
-          with a logger name of <quote>kea-dhcp4</quote>).
+          <para>
+            One final note about the naming. When specifying the daemon name
+            within a logger, use the name of the binary file,
+            e.g. <quote>kea-dhcp4</quote> for the DHCPv4 server,
+            <quote>kea-dhcp6</quote> for the DHCPv6 server, etc. When the
+            message is logged, the message will include the name of the process
+            (e.g. <quote>kea-dhcp4</quote>) followed by the specific component
+            in that process, e.g. <quote>hooks</quote>.  It is possible to
+            specify either just the process name (<quote>kea-dhcp4</quote>, will
+            apply to everything logged within that process) or process name
+            followed by specific logger,
+            e.g. <quote>kea-dhcp4.hooks</quote>. That will apply only to
+            messages originating from that component.
+          </para>
 
-        </para>
+          <para>
+            Currently defined loggers are:
+          </para>
 
-        <para>
-          Currently defined loggers are:
-        </para>
         <itemizedlist>
           <listitem>
-            <simpara>kea-dhcp4.dhcp4</simpara>
+            <simpara><command>kea-dhcp4</command> - this is the root logger for
+            the DHCPv4 server. All components used by the DHCPv4 server inherit
+            the settings from this logger if there is no specialized logger
+            provided.</simpara>
+          </listitem>
+          <listitem>
+            <simpara><command>kea-dhcp4.dhcp4</command> - this is the logger
+            used solely by the DHCPv4 server deamon. This logger does not
+            specify logging settings for libraries used by the deamon.</simpara>
+          </listitem>
+          <listitem>
+            <simpara><command>kea-dhcp4.dhcpsrv</command> - this logger is used
+            by the libdhcpsrv library. This covers mostly DHCP engine (the lease
+            allocation and renewal process), database operations and
+            configuration.</simpara>
+          </listitem>
+          <listitem>
+            <simpara><command>kea-dhcp4.hooks</command> - this logger is used
+            during DHCPv4 hooks operation, i.e. anything related to user
+            libraries will be logged using this logger.</simpara>
           </listitem>
           <listitem>
-            <simpara>kea-dhcp6.dhcp6</simpara>
+            <simpara><command>kea-dhcp6</command> - this is 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>
           </listitem>
           <listitem>
-            <simpara>kea-dhcp-ddns.dhcpddns</simpara>
+            <simpara><command>kea-dhcp6.dhcp6</command> - this is the logger
+            used solely by the DHCPv6 server deamon. This logger does not
+            specify logging settings for libraries used by the daemon.</simpara>
           </listitem>
           <listitem>
-            <simpara>kea-dhcp4.dhcpsrv</simpara>
+            <simpara><command>kea-dhcp6.dhcpsrv</command> - this logger is used
+            by the libdhcpsrv library. This covers mostly DHCP engine (the lease
+            allocation and renewal process), database operations and
+            configuration.</simpara>
           </listitem>
           <listitem>
-            <simpara>kea-dhcp6.dhcpsrv</simpara>
+            <simpara><command>kea-dhcp6.hooks</command> - this logger is used
+            during DHCPv6 hooks operation, i.e. anything related to user
+            libraries will be logged using this logger.</simpara>
+          </listitem>
+          <listitem>
+            <simpara><command>kea-dhcp-ddns</command> - this is the root logger for
+            the kea-dhcp-ddns deamon. All components used by this deamon inherit
+            the settings from this logger if there is no specialized logger
+            provided.</simpara>
+          </listitem>
+          <listitem>
+            <simpara><command>kea-dhcp-ddns.dhcpddns</command> - this is the logger
+            used solely by the kea-dhcp-ddns deamon. This logger does not
+            specify logging settings for libraries used by the deamon.</simpara>
           </listitem>
         </itemizedlist>
 
-        <para>Additional loggers may be defined in the future.</para>
+        <para>Additional loggers may be defined in the future. 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>
 
         <section>
           <title>severity (string)</title>
 
         <para>
-
           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
@@ -253,26 +302,6 @@ TODO; there's a ticket to determine these levels, see #1074
         </para>
 
         </section>
-
-        <section>
-          <title>additive (true or false)</title>
-
-        <para>
-
-          If this is true, the <option>output_options</option> from
-          the parent will be used. For example, if there are two
-          loggers configured; <quote>Dhcp4</quote> and
-          <quote>Dhcp4.dhcpsrv</quote>, and <option>additive</option>
-          is true in the second, it will write the log messages
-          not only to the destinations specified for
-          <quote>Dhcp4.dhcpsrv</quote>, but also to the destinations
-          as specified in the <option>output_options</option> in
-          the logger named <quote>Dhcp4</quote>.
-
-      </para>
-
-      </section>
-
       </section>
 
       <section>
@@ -448,7 +477,7 @@ file be created.</para>
 
     </section>
 
-    <section>
+    <section id="logging-message-format">
       <title>Logging Message Format</title>
 
       <para>
@@ -494,12 +523,13 @@ file be created.</para>
           <varlistentry>
           <term>[kea-dhcp4.dhcpsrv/27456]</term>
           <listitem><para>
-            The source of the message.  This comprises two components:
+            The source of the message.  This comprises two elements:
             the Kea process generating the message (in this
-            case, <command>kea-dhcp4</command>) and the module
+            case, <command>kea-dhcp4</command>) and the component
             within the program from which the message originated
             (which is the name of the common library used by DHCP server
-            implementations).
+            implementations). The number after the slash is a process id
+            (pid).
           </para></listitem>
           </varlistentry>
 

src/bin/keactrl/kea.conf.pre

@@ -77,10 +77,30 @@
 {
   "loggers": [
     {
-      "name": "kea",
+      "name": "kea-dhcp4",
       "output_options": [
           {
-            "output": "@localstatedir@/log/kea.log"
+            "output": "@localstatedir@/log/kea-dhcp4.log"
+          }
+      ],
+      "severity": "INFO",
+      "debuglevel": 0
+    },
+    {
+      "name": "kea-dhcp6",
+      "output_options": [
+          {
+            "output": "@localstatedir@/log/kea-dhcp6.log"
+          }
+      ],
+      "severity": "INFO",
+      "debuglevel": 0
+    },
+    {
+      "name": "kea-dhcp-ddns",
+      "output_options": [
+          {
+            "output": "@localstatedir@/log/kea-ddns.log"
           }
       ],
       "severity": "INFO",

src/bin/keactrl/keactrl.conf.in

@@ -21,7 +21,7 @@ dhcp4=yes
 dhcp6=yes
 
 # Start DHCP DDNS server?
-dhcp_ddns=yes
+dhcp_ddns=no
 
 # Be verbose?
 kea_verbose=no