How to change Kea DHCP log level

LaUs3r

Dear all,

today I was struggling with the log level of the Kea DHCP server.
I wanted to add a new client (smoke detector) to my environment with a static IP mapping. As I had no information about the MAC address, I was relying on the logs of the DHCP server to get the MAC first. From ISC I am used to pretty clear and easy to read log entries.
With Kea I got no usable information as the log level is set to WARNINGS only.

After doing some research, I couldn't find any straight info how to change the log level in pfSense, but in the end I managed to achieve it.

There are 2 files you need to change on the pfSense box:

keactrl.conf:
file location: /usr/local/etc/kea/keactrl.conf
Change the verbosity level, i.e. change "kea_verbose=no" --> "kea_verbose=yes".
If you do not change this entry, all changes in the next file regarding the log level are not taken into account
kea-dhcp4.conf
file location: /usr/local/etc/kea/kea-dhcp4.conf
Change in section "loggers" the entry for "severity". In my case, the level was set to "WARN". Based on the Kea documentation there are 5 different log levels: DEBUG, INFO, WARN, ERROR, FATAL (https://kea.readthedocs.io/en/kea-2.2.0/arm/logging.html).
My final entry was: "severity": "INFO"
Restart Kea

keactrl reload

The change to the kea-dhcp.conf is not persistent, i.e. does not survive a reboot

Maybe this is helpful to the one or other.

Cheers

Gertjan

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

keactrl.conf:

Afaik, the process (program) keactrl isn't used by pfSense.
The GUI starts "/usr/local/sbin/kea-dhcp4" (with config file /usr/local/etc/kea/kea-dhcp4.conf)
and
/usr/local/sbin/kea-dhcp6 with config file /usr/local/etc/kea/kea-dhcp6.conf

if you have IPv6 LAN(s) directly.

Your 2) is .... well ... will work only ones.

You've said it yourself :

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

The change to the kea-dhcp.conf is not persistent, i.e. does not survive a reboot

Consider this over simplified description of pfSense - the GUI.
It's a nice looking super config file creator.
So the very next time a process, like the DHCPv4 server kea-dhcp4, gets restarted, first, the config file is re created using GUI stored settings, and then the process is started.
At that moment, your own edits of a file like /usr/local/etc/kea/kea-dhcp4.conf are gone.

So, it won't survive a reboot, and it won't survive the very next process restart, for example when you save the DHCPv4 server settings page, for example.

If you want to change the log "severity", have a look at /etc/inc/services.inc
I presume you use 24.11 - pfSense Plus.

Look here.
Change you /etc/inc/services.inc, locate the same line, change WARN for INFO, save, restart DHCPv4 (kea) and voila.

Btw :
I've myself this :

so the "severity" setting gets its info from the kea/loglevel pfSense config file - but I never bothered to change also the GUI pages to select from an INFO, WARN ERROR etc list.

These edit won't survive a pfSense version upgrade. But that's not an issue as the next update will include this option in the GUI for sure.

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

I was relying on the logs of the DHCP server to get the MAC first

Lol, I always do exactly that.
And maybe the kea DHCPv4 logs are less detailed.
But : you'll would find the lease (MAC) here :

and this works out of the box ^^

LaUs3r

@Gertjan, thx very much for your awesome reply. I really appreciate it as I learned something new
To be honest, it's the first time I read something about the services.inc-file. Super interesting!!

Of course, I tried it and it works like a charm.

luckman212

This should work according to the docs (but it doesn't seem to!) ... add to Custom Configuration section at the bottom of Kea options:

{
  "name": "kea-dhcp4",
  "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": "INFO",
  "debuglevel": 0
}

Not sure why it's not working. The file does get created but its size remains 0 bytes—nothing is logged. pfSense 25.07.

I also tried, btw

  "severity": "DEBUG",
  "debuglevel": 99

keyser

@luckman212 Following this @luckman212 - I would like the same log entries on leases as you are attemting to resurface (like ISC did).

It would be nice though if one could add an entry to do log leases specifically instead of changing the loglevel of KEA intirely (will increase log spam a lot).

Gertjan

@luckman212

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