Kea files and directories

Introduction

This article identifies the major files and directories used by Kea, and addresses security aspects.

Administrators are expected to be familiar with the Unix permissions model. To maximize security, files and directories used by Kea should have the most restrictive ownership and permissions practical while still allowing desired function. Administrators should also read Kea Security for other essential security information.

Mandatory Access Control regimes like SELinux and AppArmor may also enforce access restrictions, separately from traditional Unix permissions. The theory and design behind such restrictions are generally specific to each distribution, and beyond the scope of this document. Administrators should familiarize themselves with whatever their distribution uses.

Various typical path names are given in this document. These paths are based on the paths used by the ISC packages for Kea. The actual path in your installation may vary. In particular, if Kea was built from source, the paths may be located under /usr/local, /usr/local/kea, or /opt/kea instead.

Directories

The major directories used by a typical Kea installation are listed below, organized by the type of file stored in that directory.

The rightward columns indicate the typical permissions required by:

• Kea: The user(s) running the Kea daemon processes
  • Kea packages generally provide a user and a group, both named kea or _kea
• Admins: User accounts of system administrators responsible for Kea
• Others: All users other than the above two categories of users

For the permission categories in the table above:

• Read-only: Also allows for execute, for directories and executable files

• Writable: Also includes read and execute permission, as appropriate

• Unless otherwise noted, permissions apply to both directories and the files in them

  Kea installed from ISC packages will use these permissions. Kea built from source will require the installing administrator to assign permissions manually.

Configuration Directory

Obviously, the Kea daemons need to be able to read their configuration files.

However, if the config-write API command is never used, Kea does not need write permission. Denying write can be a security measure against tampering. For example, ownership root:kea, permission rw-/r--/---.

If config-write is used, the Kea processes need to be able to write config files as well. For example, ownership kea:kea, permission rw-/rw-/---. Notably, the Stork management GUI uses the config-write command.

The Kea configuration directory and the files in it do not need to be accessible by users not involved with Kea. Anyone who can write to the config files can tell Kea to do bad things. Config files may contain database passwords, DDNS update keys, or other sensitive data. As such, removing world read permissions may be appropriate for security-conscious installations.

The configuration files are the most important files in most Kea installations. Older revisions should be retained for historical reference. They should also be included in a regular backup strategy.

Logs

Logs may contain information about DHCP clients, or overall Kea operation, that may be sensitive (customer identifying information) and/or useful to an attacker. As with config files, denying non-admin users even read access to logs may be appropriate.

In higher security environments, insider attack may be a concern. Denying most administrators write access to logs in normal circumstances can prevent tampering. A related technique is to log to another host, using the syslog network protocol.

Kea may be configured to log directly to files, typically under a directory like /var/log/kea. In such cases, Kea must be able to write to the directory. For example, ownership kea:kea and permissions rwx/rwx/---.

Alternatively, Kea may be configured to log to an external channel (stdout, stderr, or syslog). In such cases, the user running the Kea daemons can be denied all access to log files. Thus, even if an attacker compromises a Kea process, they will be denied access to log information. Likewise, administrators may be denied write. For example, ownership root:adm, directory permissions rwx/r-x/---, file permissions rw-/r--/---.

Transients

During execution, the various Kea daemons create files to indicate process status and facilitate inter-process communication. These files are only significant while the process is running, and are typically deleted upon program shutdown. These include:

• Lock files: Used to safely establish exclusive control over a resource
• PID files: Contain the process ID number of a running daemon
• Control sockets: Unix domain sockets (named sockets) for daemons and utilities to communicate with each other

The directory containing these transients must be writable by the Kea processes. It generally should not be writable by any other users (not even admins or Kea API clients). Denying read to non-admins is not strictly required, but is recommended. For example, ownership kea:kea, permissions rwx/r-x/---.

Note that on many systems, /var/run/kea is on a virtual filesystem, with the directory created automatically by systemd. Directory permissions will then be determined by systemd configuration.

Denying unnecessary access is recommended because the control sockets provide unrestricted access to the Kea API. Kea will assign appropriate read and write permission to the individual files it creates, but defense-in-depth recommends securing the directory as well.

Users or programs which need access to the Kea control sockets can be added to the kea group. The Stork management GUI may be one such program.

Alternatively to using the Unix domain sockets in the filesystem, API clients can connect to an HTTP listener provided by Kea. This will either be the Kea Control Agent (for Kea before 3.0), or a direct API listener (Kea 3.0 and later). If all API clients are using HTTP, no other programs should need access to this directory.

For more information, see Kea API and Control Sockets and Securing the Kea API.

Individual Files

Executables

Configuration Files

Each major daemon for Kea has a corresponding configuration file. Typically these are kept in /etc/kea, although variations in compilation and environment can change that. This directory and files should be protected per Configuration Directory above. The individual file names are:

kea-dhcp4.conf
kea-dhcp6.conf
kea-ctrl-agent.conf
kea-dhcp-ddns.conf

Config files may reference other files, either generically using the include mechanism, or as part of specific directives like password-file. Any such referenced files should also be protected.

Data Files

Kea can create and update a few data files of its own, typically in the /var/lib/kea directory.

The main files of interest are the lease data files. The file name and path are often defined in the lease-database section of the config file, but typically are kea-leases4.csv and kea-leases6.csv. Kea will create and maintain additional files with a numeric suffix (example, kea-leases4.csv.2) as part of lease file cleanup (LFC). All files together make up the lease database used with the memfile option.

Alternatively, lease data can be stored in a SQL database, in which case no lease files will seen in this directory.

Lease data may or may not deserve to be included in regular backups. On one hand, clients will generally request new leases if their old ones are not offered, so lease data can be rebuilt. On the other hand, some clients may misbehave, and knowing client lease assignments may be useful information. Ultimately this is up to the administrator to decide.

The other file that typically appears in this directory is kea-dhcp6-serverid, which is a tiny file storing the unique ID (UUID/GUID) Kea generates to identify each server.

Transient Files

As noted previously, Kea creates transient files while running. The typical names of individual files are listed here for reference. Most administrators do not need to concern themselves with this level of detail.

PID file names are constructed from:

1. The base name of the configuration file the daemon is using
2. The name of the daemon program itself
3. The extension pid
4. Each of the above components is separated by a dot

Examples: For the kea-dhcp4 daemon, the typical config file of /etc/kea/kea-dhcp4.conf yields a base name of kea-dhcp4, hence a PID of file of kea-dhcp4.kea-dhcp4.pid. If the config file was instead lab.json, the PID file would be lab.kea-dhcp4.pid.

Kea will assign appropriate ownership and permission to the transient files it creates. Kea does not provide a facility for administrators to modify the security parameters of individual transient files.