How to change Kea DHCP log level

Gertjan

I've been playing with JSON stuff for kea in the past, so I gave it a try.
On the Services > DHCP Server > Settings page, I added :

{
  "option-def": [
    {
      "name": "unifi",
      "code": 1,
      "space": "vendor-encapsulated-options-space",
      "type": "string"
    }
  ],
  "loggers": [
    {
      "name": "kea-dhcp4.alloc-engine",
      "output-options": [
        {
          "output": "/var/log/kea-dhcp.log",
          "maxver": 8,
          "maxsize": 204800,
          "flush": true,
          "pattern": "%d{%j %H:%M:%S.%q} %c %m\n"
        }
      ],
      "severity": "DEBUG",
      "debuglevel": 99
    }
  ]
}

The first part, called "option-def", handles a DHCP option for my "unifi" equipment.
The second part is what you wanted to add (I guess, read on).

Before you start to modify anything, first, have a look at the actual /usr/local/etc/kea/kea-dhcp4.conf file.
There is already a "option-def" section, set up by pfSense itself.
My idea was to add a sub section for ""kea-dhcp4.alloc-engine" as I thought that would add lease info in the r/log/kea-dhcp.log file. EDIT : bad idea, keep on reading, the perfect solution will be found shortly hereafter.

When you save, there shouldn't be any warning, double check the Status > System Logs > System > General page.
There should be no errors messages - also shown in the GUI in the top right.

Now, just to be sure, re check the /usr/local/etc/kea/kea-dhcp4.conf file. You should see what you've added.
For example, I see :

and the file "/var/log/kea-dhcp.log" now exists, and is populated :

....
233 06:27:54.843 kea-dhcp4.alloc-engine ALLOC_ENGINE_V4_NO_MORE_EXPIRED_LEASES all expired leases have been reclaimed
233 06:28:03.861 kea-dhcp4.alloc-engine ALLOC_ENGINE_V4_RECLAIMED_LEASES_DELETE begin deletion of reclaimed leases expired more than 3600 seconds ago
233 06:28:03.861 kea-dhcp4.alloc-engine ALLOC_ENGINE_V4_RECLAIMED_LEASES_DELETE_COMPLETE successfully deleted 0 expired-reclaimed leases
233 06:28:04.863 kea-dhcp4.alloc-engine ALLOC_ENGINE_V4_LEASES_RECLAMATION_START starting reclamation of expired leases (limit = 100 leases or 250 milliseconds)
233 06:28:04.863 kea-dhcp4.alloc-engine ALLOC_ENGINE_V4_LEASES_RECLAMATION_COMPLETE reclaimed 0 leases in 0.007 ms
233 06:28:04.863 kea-dhcp4.alloc-engine ALLOC_ENGINE_V4_NO_MORE_EXPIRED_LEASES all expired leases have been reclaimed
233 06:28:05.337 kea-dhcp4.alloc-engine ALLOC_ENGINE_V4_REQUEST_EXTEND_LEASE [hwtype=1 ee:fa:f2:08:1c:58], cid=[01:ee:fa:f2:08:1c:58], tid=0xae5c96bf: extending lifetime of the lease for address 192.168.2.25
233 06:28:15.708 kea-dhcp4.alloc-engine ALLOC_ENGINE_V4_LEASES_RECLAMATION_START starting reclamation of expired leases (limit = 100 leases or 250 milliseconds)
233 06:28:15.708 kea-dhcp4.alloc-engine ALLOC_ENGINE_V4_LEASES_RECLAMATION_COMPLETE reclaimed 0 leases in 0.007 ms
233 06:28:15.708 kea-dhcp4.alloc-engine ALLOC_ENGINE_V4_NO_MORE_EXPIRED_LEASES all expired leases have been reclaimed
233 06:28:25.773 kea-dhcp4.alloc-engine ALLOC_ENGINE_V4_LEASES_RECLAMATION_START starting reclamation of expired leases (limit = 100 leases or 250 milliseconds)
233 06:28:25.773 kea-dhcp4.alloc-engine ALLOC_ENGINE_V4_LEASES_RECLAMATION_COMPLETE reclaimed 0 leases in 0.011 ms
233 06:28:25.773 kea-dhcp4.alloc-engine ALLOC_ENGINE_V4_NO_MORE_EXPIRED_LEASES all expired leases have been reclaimed
233 06:28:29.792 kea-dhcp4.alloc-engine ALLOC_ENGINE_V4_RECLAIMED_LEASES_DELETE begin deletion of reclaimed leases expired more than 3600 seconds ago
233 06:28:29.793 kea-dhcp4.alloc-engine ALLOC_ENGINE_V4_RECLAIMED_LEASES_DELETE_COMPLETE successfully deleted 0 expired-reclaimed leases
.....

Humm. this is to much info. To show only the leases, as we used to see them when using ISC, the severity and debug level needs some modification - I guess.

Be aware : the GUI does minimum JSON format checking, as this ts done by 'linting' the JSON info by kea itself. The slights 'JSON' syntax error will be flagged in the system log with an indication what was found to be wrong.

edit : I'm using Plus 25.07.1 - I presume 2.8.0 (or 2.8.1) uses the same 'kea'.

keyser

@Gertjan Thank you Gertjan. But I think the real need is a logging option for leases only. Having KEA in its entirety running at debugging log level adds WAY to much log noise.

Gertjan

@keyser said in How to change Kea DHCP log level:

Having KEA in its entirety running at debugging log level adds WAY to much log noise

I picked "kea-dhcp4.alloc-engine", presuming that this alloc-engine sub part would be responsible for the leases business. I might be wrong of course.
I picked "DEBUG" and debuglevel "99", so everything would be shown. I get it : to much.
The thing is : is the needed info also in there ?
If so, as the JSON format is now ok, you could 'play' with the settings and pattern, and see what combination gives you the info you want.

I gave it a try :

...
  "loggers": [
    {
      "name": "kea-dhcp4.dhcp4",
      "output-options": [
        {
          "output": "/var/log/kea-dhcp.log",
          "maxver": 8,
          "maxsize": 204800,
          "flush": true
        }
      ],
      "severity": "INFO"
    }
  ]
...

Note : I changed the "name" to "kea-dhcp4.dhcp4" (more options are avialable, see the manual)

Now I see :

233 11:44:07.740 kea-dhcp4.dhcp4 DHCP4_QUERY_LABEL received query: [hwtype=1 fa:df:15:6d:66:d7], cid=[01:fa:df:15:6d:66:d7], tid=0x4d995992
233 11:44:08.100 kea-dhcp4.dhcp4 DHCP4_QUERY_LABEL received query: [hwtype=1 fa:df:15:6d:66:d7], cid=[01:fa:df:15:6d:66:d7], tid=0x4d995992
233 11:44:08.635 kea-dhcp4.dhcp4 DHCP4_QUERY_LABEL received query: [hwtype=1 fa:df:15:6d:66:d7], cid=[01:fa:df:15:6d:66:d7], tid=0x4d995992
233 11:44:15.130 kea-dhcp4.dhcp4 DHCP4_QUERY_LABEL received query: [hwtype=1 a4:bb:6d:ba:16:a1], cid=[01:a4:bb:6d:ba:16:a1], tid=0x9c56f5ad
233 11:44:33.993 kea-dhcp4.dhcp4 DHCP4_QUERY_LABEL received query: [hwtype=1 f0:03:8c:bd:82:51], cid=[01:f0:03:8c:bd:82:51], tid=0x2916e732
233 11:44:38.000 kea-dhcp4.dhcp4 DHCP4_QUERY_LABEL received query: [hwtype=1 f0:03:8c:bd:82:51], cid=[01:f0:03:8c:bd:82:51], tid=0xec99167b

luckman212

Think I nailed it!

Here's my working config (no need for DEBUG level, INFO is fine):

{
  "loggers": [
    {
      "name": "kea-dhcp4.leases",
      "output-options": [
        {
          "output": "/var/log/kea-dhcp-leases.log",
          "maxver": 5,
          "maxsize": 10240000,
          "flush": true,
          "pattern": "%D{%Y-%m-%d %H:%M:%S.%q} [%i] %m\n"
        }
      ],
      "severity": "INFO",
      "debuglevel": 0
    }
  ]
}

This will generate DHCP assignment logs at /var/log/kea-dhcp-leases.log. The logfiles will be capped at 10MB each, and a maximum of (5) log rotations should be produced (which seems to align with the rest of the pfSense defaults). A custom string formatter is also used to show enough detail without being overly verbose.

Result

# tail -f /var/log/kea-dhcp-leases.log
2025-08-21 08:51:20.444 [2945] DHCP4_INIT_REBOOT [hwtype=1 d0:11:e5:1b:e0:70], cid=[01:d0:11:e5:1b:e0:70], tid=0xdd81b257: client is in INIT-REBOOT state and requests address 192.168.20.41
2025-08-21 08:51:20.452 [2945] DHCP4_LEASE_ALLOC [hwtype=1 d0:11:e5:1b:e0:70], cid=[01:d0:11:e5:1b:e0:70], tid=0xdd81b257: lease 192.168.20.41 has been allocated for 14400 seconds

Gertjan

@luckman212 said in How to change Kea DHCP log level:

"name": "kea-dhcp4.leases",

hummm.
It was right in front of me :

For the record, for those who read this thread later on :

"/var/log/kea-dhcp-leases.log" - do not pick a file name that exists = used and maintained by pfSense !
This file will have a "maxsize" of : 10240000 bytes,
and
If the file "/var/log/kea-dhcp-leases.log" size becomes bigger, the file is rotated, and the maximum number of copied are limited to "maxver": 5.
Nice ! coming back to pfSense in 2026 and find your disk totally saturated with "kea-dhcp-leases.log-xxx" files is a nice thing to have. A set-it-and-forget-it-solution.

Btw : the "debuglevel": 0 can be removed, as "debuglevel" is only used when "severity" is set to "DEBUG". Don't forget to remove the comma after "severity": "INFO".

keyser

@Gertjan @luckman212 This is excellent detective work and very nice to know is possible. Now the only remaining issue is the lack of being able to syslog the activity. Since the log file is not part of pfSense’s “built-in” logfiles, any syslog settings used in pfSense has no effect on this log file. The same problem is actually present in pfBlockerNG.

I wish pfSense had a native way to add package logfiles to the builtin Syslog!

I know it can be done with the Syslog-ng package, but thats somewhat cumbersome and “double confetti” considering there already is a syslog running that it would be nice to tap into.

luckman212

@keyser Here you go...

{
  "loggers": [
    {
      "name": "kea-dhcp4.leases",
      "output-options": [
        {
          "output": "syslog:kea-dhcp4",
          "pattern": "%m\n"
        }
      ],
      "severity": "INFO",
      "debuglevel": 0
    }
  ]
}

Logs will be handled by syslog, and written to /var/log/dhcpd.log:

e6580979-b1ab-49f8-a898-94abffb3ef4a-screenshot_5BBqkEzO.png

keyser

@luckman212 Whooaaa, I thought @Gertjan stated that you could not use a pfSense managed log file, but it of course makes sense that it can log to that file as that is the default log file of KEA in pfSense. So if nothing is stated and size managed like in your JSON, then it's in the default location.

EXCELLENT work gents! Thank you very much for the investigative work :-)

PS. Perhaps Netgate (@stephenw10) should consider adding that logging part to the default KEA config in the builtin setup - to mimic the logging setup of ISC?

Gertjan

@keyser said in How to change Kea DHCP log level:

I thought @Gertjan stated that you could not use a pfSense managed log file,

This - you see the file name ? :

don't pick a (log) file name that pfSense (syslog actually) already uses.

On the other hand : this :

is not a file ^^

will send the log lines not to a file, but to the syslog socket, and from then on syslog will sift it out. Syslog discovers that it is a DHCP log line, and outputs it to the syslog/pfSense DHCP log.

@keyser said in How to change Kea DHCP log level:

should consider adding that logging part to the default KEA config in the builtin setup - to mimic the logging setup of ISC?

Well, this thread now exists
Other DHCP-kea forum threads explain how to add 'options' like ISC offered, etc.
If you have special needs, you have to do special work ^^
That said, a DHCP server logging leases it serves, ... that should be be at least an option.

The default pfSense kea loggers is set up with this :

where "kea-dhcp4" supersedes "kea-dhcp4.leases" so only WARNing are logged.
This helps making the DHCP log less noisy.

mcury

@luckman212 Testing the latest version, with syslog:kea-dhcp4 output.
Working perfectly, so far.
Logs are being sent to my syslog server.

Thanks @luckman212

stephenw10

Ooo, missed this. You are just adding that section to the custom Kea json config?

Edit: Yup