Opened 3 years ago

Closed 3 years ago

#3536 closed defect (fixed)

User's Guide section about Logging configuration is invalid

Reported by: marcin Owned by: tomek
Priority: high Milestone: Kea0.9.1beta
Component: documentation Version: git
Keywords: Cc:
CVSS Scoring: Parent Tickets:
Sensitive: no Defect Severity: Medium
Sub-Project: DHCP Feature Depending on Ticket: 3534
Estimated Difficulty: 0 Add Hours to Ticket: 0
Total Hours: 0 Internal?: no

Description

I have found that section 10.1.1.1 (Loggers/name) in the Kea User's guide is wrong:

  • Apparently there is no way to use logger names like ''Dhcp4'' to set the logger for the DHCPv4 server. The ''kea-dhcp4'' logger name should be used instead.
  • The asterisk (*) used to work for BIND10 but it doesn't work for Kea, but the user guide still describes an asterisk as a possible value for the logger name.

In addition to this, I found that the kea.conf contains an invalid logger definition. This definition uses ''kea'' as a name of the logger. Since this is not a valid name, this setting is ignored and the defaults are used. As a result, the logger outputs to stdout.

I am thinking I can fix the kea.conf in #3534 which I am working on. But, if I don't the kea.conf should be updated with this ticket.

I am setting priority to high because it affects the released Kea 0.9.

Subtickets

Change History (12)

comment:1 Changed 3 years ago by marcin

One additional issue just found is this.... The default kea.conf file instructs the logger to store log messages in the var/log/kea.log. However, the var/log folder doesn't exist in the Kea installation dir. As a result the log file is never created (even when configured properly). Creating a directory manually solves the problem but it should work without manual intervention.

comment:2 Changed 3 years ago by tomek

  • Milestone changed from Kea-proposed to Kea0.9.1

comment:3 Changed 3 years ago by marcin

  • Defect Severity changed from N/A to Medium
  • Feature Depending on Ticket set to 3534

This ticket better waits until the #3534 is reviewed because it introduces some changes to the logging configuration.

comment:4 Changed 3 years ago by tomek

  • Owner set to tomek
  • Status changed from new to assigned

comment:5 Changed 3 years ago by tomek

  • Owner changed from tomek to UnAssigned
  • Status changed from assigned to reviewing

Code is now ready for review. Proposed changelog:

8XX.	[bug,doc]		tomek
	Logging in kea.conf example in keactrl fixed. Also updated
        Kea documentation for logging.
	(Trac #3536, git tbd)

comment:6 Changed 3 years ago by marcin

  • Owner changed from UnAssigned to marcin

comment:7 follow-up: Changed 3 years ago by marcin

  • Owner changed from marcin to tomek

Reviewed commit 065949da28cdd5b56bf36fc71599cd4145a167ce

doc/guide/logging.xml

It appears to me that we should probably clean up the terminology being used in the user's guide. In particular it should be clear what is the "component" and what is a "module". In fact, we should probably stick to one of them.

For example, this sentences:

"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. This allows sharing identical logging configuration between components."

use module and components which probably refer to the same thing.

In addition to this. I think that logging mechanism is not really a module/component in the same sense as the DHCPv4 module/component. Since we removed the BIND10 infrastructure the configuration parsing and the actual setup of the log4cplus structure is the responsibility of the Kea deamons?/modules?/components? The Logging is merely a library. Or, maybe the module refers to the binary or library that is capable of logging something?

There is also a term "logger" which makes it even more difficult to understand the difference between different terms used here.

Also, in some cases the text refers to Dhcp4 component/module, while it should rather refer to the DHCPv4 server or kea-dhcp4 deamon.

OLD:

For instance, if you want to configure logging for the Dhcp4 module, you add an entry for a logger named “kea-dhcp4”

NEW:
For instance, if you want to configure logging for the DHCPv4 server, you add an entry for a logger named “kea-dhcp4”

OLD:
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

NEW:
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.

With regards to the list of currently defined loggers. It lists a logger like this one kea-dhcp4.dhcp4. There is no mention of this logger in the text above. The text above says that the logger names are constructred like this: module.library. So, is the "dhcp4" a library? Defining the logger as "kea-dhcp4.dhcp4" is equal to defining a logger for "kea-dhcp4"? Should the logger for "kea-dhcp4" and "kea-dhcp6" be listed here too?

Also, it would be useful to add a one line of text after each logger to say what this logger is for.

kea.conf.pre
There is a missing comma between logger entry for DHCPv6 and D2, which results in the failure to start the server.

    {
      "name": "kea-dhcp6",
      "output_options": [
          {
            "output": "@localstatedir@/log/kea-dhcp6.log"
          }
      ],
      "severity": "INFO",
      "debuglevel": 0
    }   <<----- here is a problem
    {
      "name": "kea-dhcp-ddns",
      "output_options": [
          {
            "output": "@localstatedir@/log/kea-ddns.log"
          }
      ],
      "severity": "INFO",
      "debuglevel": 0
    }

As mentioned in this comment in the ticket: http://kea.isc.org/ticket/3536#comment:1

there is an issue that the log files are not created in the directories specified in the "output" because the log directory doesn't exist. Only when I create the directory manually the log files are actually created and something is logged to them.

I think this directory needs to be created if it doesn't exist.

ChangeLog
Something is wrong here. Shouldn't it be:

8XX.	[bug,doc]		tomek
	Logging configuration examples in kea.conf fixed. Also updated
    Kea documentation for logging.
	(Trac #3536, git tbd)

comment:8 in reply to: ↑ 7 Changed 3 years ago by tomek

  • Owner changed from tomek to marcin

Replying to marcin:

Reviewed commit 065949da28cdd5b56bf36fc71599cd4145a167ce

doc/guide/logging.xml

It appears to me that we should probably clean up the terminology being used in the user's guide. In particular it should be clear what is the "component" and what is a "module". In fact, we should probably stick to one of them.

Cleaned up the terminology. Also added a comment at the beginning explaining what the terminology is. One day we'll need to go through all the docs and make the terminology consistent. Until that day I hope it is ok to keep that comment in logging.xml, even though it really applies to all other chapters.

use module and components which probably refer to the same thing.

There is reference to module anymore. Depending on what the context was, it was replaced by either component or daemon.

In addition to this. I think that logging mechanism is not really a module/component in the same sense as the DHCPv4 module/component. Since we removed the BIND10 infrastructure the configuration parsing and the actual setup of the log4cplus structure is the responsibility of the Kea deamons?/modules?/components? The Logging is merely a library. Or, maybe the module refers to the binary or library that is capable of logging something?

True. Updated the code. See if it is any better than the old one. I tried to explain what a logger is, without delving into too much technical details.

There is also a term "logger" which makes it even more difficult to understand the difference between different terms used here.

I'm afraid we'll need to keep the "logger" terminology. I tried to explain what it is.

Also, in some cases the text refers to Dhcp4 component/module, while it should rather refer to the DHCPv4 server or kea-dhcp4 deamon.

I hope I picked them all. Let me know if I missed any.

With regards to the list of currently defined loggers. It lists a logger like this one kea-dhcp4.dhcp4. There is no mention of this logger in the text above. The text above

says that the logger names are constructred like this: module.library. So, is the "dhcp4" a library? Defining the logger as "kea-dhcp4.dhcp4" is equal to defining a logger for "kea-dhcp4"? Should the logger for "kea-dhcp4" and "kea-dhcp6" be listed here too?
The text was simply not updated, so it was inconsistent. I hope the text now reads better.

Also, it would be useful to add a one line of text after each logger to say what this logger is for.

Good idea, added.


kea.conf.pre
There is a missing comma between logger entry for DHCPv6 and D2, which results in the failure to start the server.

    {
      "name": "kea-dhcp6",
      "output_options": [
          {
            "output": "@localstatedir@/log/kea-dhcp6.log"
          }
      ],
      "severity": "INFO",
      "debuglevel": 0
    }   <<----- here is a problem
    {
      "name": "kea-dhcp-ddns",
      "output_options": [
          {
            "output": "@localstatedir@/log/kea-ddns.log"
          }
      ],
      "severity": "INFO",
      "debuglevel": 0
    }

Fixed.

As mentioned in this comment in the ticket: http://kea.isc.org/ticket/3536#comment:1

there is an issue that the log files are not created in the directories specified in the "output" because the log directory doesn't exist. Only when I create the directory manually the log files are actually created and something is logged to them.

I think this directory needs to be created if it doesn't exist.

It is now created during make install.

ChangeLog
Something is wrong here. Shouldn't it be:

8XX.	[bug,doc]		tomek
	Logging configuration examples in kea.conf fixed. Also updated
    Kea documentation for logging.
	(Trac #3536, git tbd)

Ok. Will use your proposal.

Hopefully this addresses all comments.

comment:9 Changed 3 years ago by tomek

One minor change after hackathon: ddns used to enabled in keactrl.conf.in, but there was no Ddns section in kea.conf, so it was not usable. I disabled ddns in keactrl.conf.in.

comment:10 Changed 3 years ago by marcin

  • Owner changed from marcin to tomek

I reviewed your changes. The text now looks a lot better and cleaner.

I fixed a couple of nits and pushed the changes to the branch. Please pull my changes before merge.

There is one outstanding thing which I previously signalled. That is, the list of loggers comprises the loggers like "kea-dhcp4.dhcp4", "kea-dhcp6.dhcp6" and "kea-dhcp-ddns.dhcpddns". But, in the examples above you always mention short form "kea-dhcp4" and "kea-dhcp6". If I understand that correctly, "kea-dhcp4.dhcp4" is just a different name for the same logger "kea-dhcp4". Isn't it? If so, maybe we should include the short form on the list of loggers like this:

* kea-dhcp4.dhcp4 (or kea-dhcp4) - this is the logger used by DHCPv4 server code in cases, where there is no more specialized logger

and so on...

comment:11 Changed 3 years ago by marcin

I updated the docs on the trac3536 branch with the propose change to add root loggers to the list of defined loggers.

comment:12 Changed 3 years ago by tomek

  • Resolution set to fixed
  • Status changed from reviewing to closed

Merged. Code pushed. Thanks for the review. Closing ticket.

Note: See TracTickets for help on using tickets.