Using Official ISC Packages for Kea

Overview

ISC provides binary packages and corresponding source code for Kea DHCP hosted on Cloudsmith. Packages and source code tarballs are provided for every release.

The open source packages in the current release provide the base Kea software and the following hook libraries:

• BOOTP
• Flexible Option
• High Availability
• Lease Commands
• MySQL Configuration Backend
• Performance Monitoring
• PostgreSQL Configuration Backend
• Run Script
• Statistics Commands

For a full list of hooks provided by the latest development release, please refer to the list of Available Hook Libraries in the Administrator Reference Manual (ARM). Other hooks are provided under a commercial license, in separate private repositories (see below).

Why Use ISC's Kea Packages?

ISC's Kea packages let you:

1. Update quickly and efficiently directly from our repository, in one step, and skip the added step of downloading and building binaries locally;
2. Get all the latest bug fixes and features immediately, without waiting for your OS distribution to pick up the changes and release them. We provide binary packages along with sources at the time of each release (sometimes the binaries are posted a few hours later, but generally the same day).

Supported Operating Systems

ISC has created packages for what we think are the most popular operating systems for production DHCP servers. If your preferred operating system is not packaged, you can still build from our published sources.

We provide the following types of packages:

• RPM for RHEL, CentOS, Fedora
• deb for Debian and Ubuntu
• apk for Alpine
• Docker images (introduced with Kea 2.4.0)

ISC-Provided Kea Packages

ISC provides packages for the open source components, as well as the commercially licensed hooks. The open source is included in both public and private repositories, but the commercially licensed software is included in the private repositories only. Access to private repositories is controlled with the use of access tokens that are provided to ISC subscribers.

ISC Packages vs. OS Packages

Kea binaries are available in several packages. RHEL, CentOS, Fedora, Debian, Ubuntu, and Alpine all provide their own Kea packages, which may not be packaged the same way as the ISC-provided packages. To avoid confusing ISC packages with those from other distributors, all ISC packages (with the exception of FreeRADIUS packages prior to Kea 2.5.4) start with the isc-kea- prefix.

Open Source Package Names

The table below lists the current open source packages for all supported systems:

Commercially Licensed Packages

ISC customers are entitled to additional hooks not included in the open source version of Kea. The commercially licensed hooks are distributed in three bundles:

• Premium for online purchasers of premium hooks without ISC support
• Subscription for customers with ISC subscriptions at the Basic and Bronze levels
• Enterprise for customers with ISC subscriptions at the Silver and Gold levels

The table below lists the current commercially licensed packages for all supported systems:

For more information about obtaining the commercially licensed Kea hook libraries, please contact us at https://www.isc.org/contact. All Kea hook libraries are described fully in the Kea ARM.

The names of the FreeRADIUS packages are specific to the package type used by your distribution of Linux, but they do not need to be installed explicitly. FreeRADIUS packages are installed automatically by packages that require them.

Using the Cloudsmith Repositories

All ISC binary packages for Kea are contained in our repositories on Cloudsmith. The source tarballs are also published there for Kea 2.2.0 and later versions. We have open source repositories which are available to anyone, and private repositories for ISC customers which require a security token to access.

Open Source Repositories

Packages can be downloaded from our public Cloudsmith repositories and installed by following the directions below. The examples use Kea version 2.6; use the table below to replace kea-2-6 with a different string for a different version, such as kea-2-4:

Set up the repository on Debian and Ubuntu

To install .deb packages, you can quickly setup the repository automatically (recommended):

curl -1sLf \
  'https://dl.cloudsmith.io/public/isc/kea-2-6/setup.deb.sh' \
  | sudo -E bash

You can remove the repository with:

rm /etc/apt/sources.list.d/isc-kea-2-6.list
apt-get clean
rm -rf /var/lib/apt/lists/*
apt-get update

Set up the repository on Fedora/RHEL

To install RPM packages, you can quickly setup the repository automatically (recommended):

curl -1sLf \
  'https://dl.cloudsmith.io/public/isc/kea-2-6/setup.rpm.sh' \
  | sudo -E bash

You can remove the repository with:

rm /etc/yum.repos.d/isc-kea-2-6.repo
rm /etc/yum.repos.d/isc-kea-2-6-source.repo

Set up the repository on Alpine

To install APK packages, you can quickly setup the repository automatically (recommended):

sudo apk add --no-cache bash
curl -1sLf \
  'https://dl.cloudsmith.io/public/isc/kea-2-6/setup.alpine.sh' \
  | sudo -E bash

You can remove the repository by editing the repositories file:

$EDITOR /etc/apk/repositories

Remove the /alpine/v3.18/main line and save the file, then run these two commands:

rm -f /etc/apk/keys/kea-2-6*
apk update

Private Repositories for Commercially Licensed Hooks

These instructions provide information on accessing the private Cloudsmith repositories with a token, indicated with your_token_goes_here in the commands. If you are an ISC Kea support customer and need a token, please log into our support portal to obtain yours. If you have purchased the Premium hooks bundle online, you should have received a token via email. If you have lost your token, please send an email to info@isc.org to request your token.

The instructions are very similar to the ones for the open source repositories, given above. In the URLs, replace public with your token and append -prv to the repository name, such as changing kea-2-6 to kea-2-6-prv.

Set up the repository on Debian and Ubuntu

To install .deb packages, you can quickly setup the repository automatically (recommended):

curl -1sLf \
  'https://dl.cloudsmith.io/your_token_goes_here/isc/kea-2-6-prv/setup.deb.sh' \
  | sudo -E bash

You can remove the repository with:

rm /etc/apt/sources.list.d/isc-kea-2-6-prv.list
apt-get clean
rm -rf /var/lib/apt/lists/*
apt-get update

Set up the repository on Fedora/RHEL

curl -1sLf \
  'https://dl.cloudsmith.io/your_token_goes_here/isc/kea-2-6-prv/setup.rpm.sh' \
  | sudo -E bash

You can remove the repository with:

rm /etc/yum.repos.d/isc-kea-2-6-prv.repo
rm /etc/yum.repos.d/isc-kea-2-6-prv-source.repo

Set up the repository on Alpine

sudo apk add --no-cache bash
curl -1sLf \
  'https://dl.cloudsmith.io/your_token_goes_here/isc/kea-2-6-prv/setup.alpine.sh' \
  | sudo -E bash

You can remove the repository by editing the repositories file:

$EDITOR /etc/apk/repositories

Remove the /alpine/v3.18/main line and save the file, then run these two commands:

rm -f /etc/apk/keys/kea-2-6*
apk update

The current private repositories on Cloudsmith are:

Private Repositories for Web-Based Purchases

If you have purchased Kea Premium hooks from ISC's website and do not have a support contract, you can access them through Cloudsmith. For more information, please consult the Private Repositories for Commercially Licensed Hooks section. Please note that the Premium hook packages only contain the hooks listed as part of the Premium bundle in this table.

Installing Kea Packages

Once the repositories are configured on a system, the Kea packages can be installed. As there are several packages, you can choose to install only the parts of Kea that you require. The dependencies between packages are set up so any dependent packages will be automatically installed.

The following examples will install the main Kea package isc-kea, which depends on (and automatically installs) all of the packages in the open source bundle.

Deb version:

apt install isc-kea

This command lists all available packages:

apt-cache search isc-kea

RPM version:

dnf install isc-kea

This command lists all available packages:

dnf list isc-kea*

Alpine version:

apk add isc-kea

This command lists all available packages:

apk search isc-kea

Installing only specific components is also possible. Please refer to the list of packages above to determine which specific packages you need.

Once Kea is installed, configure it as desired via the files located in the /etc/kea/ folder.

Problem: cannot install the best candidate for the job
  - nothing provides liblog4cplus-2.0.so.3()(64bit) needed by isc-kea-common-2.6.1-isc20240725093407.el9.x86_64 from isc-kea-2-6
(try to add '--skip-broken' to skip uninstallable packages or '--nobest' to use not only best candidate packages)

Installing Premium Hooks

After setting up the private hooks repository, you should be able to install the Kea premium hooks with your platform's package manager.

The following example installs the Flexible Identifier Kea premium hook library; the same commands can be used for the other libraries, after substituting the appropriate library name.

Deb version:

apt install isc-kea-premium-flex-id

This command lists all available premium hooks:

apt-cache search isc-kea-premium

RPM version:

yum install isc-kea-premium-flex-id

This command lists all available premium hooks:

dnf list isc-kea-premium*

Alpine version:

apk add isc-kea-premium-flex-id

This command lists all available premium hooks:

apk search isc-kea-premium

Please refer to the Premium Packages section above for the names of the other premium hooks.

Managing Kea Services

When using the ISC-provided packages, Kea services should be managed using the service manager of your OS.

Service Names

RPM and Alpine Systems

Debian Systems

Service Management

To start, stop, or restart Kea daemons, systemctl should be used on Debian/Ubuntu and RPM based systems, and OpenRC should be used on Alpine.

In the following examples, the kea-dhcp4 service is being enabled, started, and stopped. Adjust the commands to the service you wish to manage.

deb version:

systemctl enable isc-kea-dhcp4-server
systemctl start isc-kea-dhcp4-server
systemctl stop isc-kea-dhcp4-server

RPM version:

systemctl enable kea-dhcp4
systemctl start kea-dhcp4
systemctl stop kea-dhcp4

Alpine version:

rc-update add kea-dhcp4
service kea-dhcp4 start
service kea-dhcp4 stop

Source Tarballs in the Package Repository

Since Kea 2.2.0, source tarballs are available alongside the binary packages in the Cloudsmith repository. This is a convenience for our support subscribers, who can now use the same token to download the source that they have already been using to install the packages.

To download the source tarball and its signatures from Cloudsmith, use the following set of commands, replacing the version string with the current version you wish to download:

version=2.6.0; \
  for file in kea-$version.tar.gz kea-$version.tar.gz.asc kea-$version.tar.gz.sha1.asc kea-$version.tar.gz.sha256.asc kea-$version.tar.gz.sha512.asc Kea-$version-ReleaseNotes.txt;  do \
  curl -O https://dl.cloudsmith.io/public/isc/kea-2-6/raw/versions/$version/$file; \
done

or just a single file:

curl -O https://dl.cloudsmith.io/public/isc/kea-2-6/raw/versions/2.6.0/kea-2.6.0.tar.gz

The tarballs (in contrast to the binary packages) have been signed using ISC's code-signing key. To verify the signatures for the open source software, please run this set of commands after importing the ISC key from https://www.isc.org/pgpkey/:

version=2.6.0; \
for i in .asc .sha1.asc .sha256.asc .sha512.asc; do \
  gpg --verify kea-enterprise-$version.tar.gz$i kea-enterprise-$version.tar.gz; \
done

For ISC support subscribers, add -prv to the repository name and insert your token into the request. Change the keyword to specify which hooks to download; the possible values include premium, subscription, and enterprise.

version=2.6.0 hooks=premium; \
  for file in kea-$hooks-$version.tar.gz kea-$hooks-$version.tar.gz.asc kea-$hooks-$version.tar.gz.sha1.asc kea-$hooks-$version.tar.gz.sha256.asc kea-$hooks-$version.tar.gz.sha512.asc;  do \
  curl -O https://dl.cloudsmith.io/<your-customer-token-here>/isc/kea-2-6-prv/raw/versions/$version/$file; \
done

and use a similar script to verify signatures:

version=2.6.0 hooks=premium; \
for i in .asc .sha1.asc .sha256.asc .sha512.asc; do \
  gpg --verify kea-$hooks-$version.tar.gz$i kea-$hooks-$version.tar.gz; \
done

In the examples above, replace kea-2-6 and 2.6.0 with the version that you will use.

Accessing Cloudsmith From Behind a Proxy Server

Systems that are required to use a proxy server for Internet access can use any of the methods described below when configuring repositories and downloading packages. In the examples below, the proxy server IP address is 192.0.2.1 and the proxy listens on port 3128 (expressed as 192.0.2.1:3128).

The first step involves fetching a setup shell script from Cloudsmith, then running the configuration script. Since both the fetching of the setup script and the HTTP requests from inside the script are done with curl, we can use curl's proxy support.

Set the HTTPS_PROXY environment variable either like this:

HTTPS_PROXY=192.0.2.1:3128 curl -1sLf \
  'https://dl.cloudsmith.io/public/isc/kea-2-6/setup.alpine.sh' \
  | sudo -E bash

or like this:

export HTTPS_PROXY=192.0.2.1:3128
curl -1sLf \
  'https://dl.cloudsmith.io/public/isc/kea-2-6/setup.alpine.sh' \
  | sudo -E bash

Or configure curl to use this proxy persistently with a .curlrc file. Note that this affects all curl calls for any user whose environment reads the .curlrc file:

echo 'proxy = 192.0.2.1:3128' >> ~/.curlrc

If you want package downloads to be proxied as well, proxy settings can be configured for the package manager:

Pulling and Using Docker Images

Docker images available in the open source repository include:

• kea-dhcp4
• kea-dhcp6
• kea-dhcp-ddns

Pulling (downloading) an image from the Cloudsmith Docker registry can be done using the standard docker pull command:

docker pull docker.cloudsmith.io/isc/docker/your-image:version

Note: You should replace your-image with one of the image names (e.g. kea-dhcp4), and version with a Kea image name and version string (e.g. 2.6.0)

To refer to images after pulling a Dockerfile, specify the following:

FROM docker.cloudsmith.io/isc/docker/your-image:version

Using the Docker Image

Using a Docker image for Kea DHCP is complicated! We strongly encourage you to read the README in the Docker repository.

Pulling and Using Private Docker Images

Docker images available in the private repository correspond to the three levels of commercially licensed software: Premium (typically purchased from the ISC website, Subscription (available to all ISC technical support subscribers), and Enterprise (available to ISC support subscribers at the highest levels).

• kea-dhcp4-enterprise
• kea-dhcp4-premium
• kea-dhcp4-subscription
• kea-dhcp6-enterprise
• kea-dhcp6-premium
• kea-dhcp6-subscription
• kea-dhcp-ddns-premium
• kea-dhcp-ddns-subscription

As this is a private registry, you'll need to authenticate to pull images, using the access token issued to you either when you purchased the Premium hooks package or when you subscribed for support from ISC. Use your access token when prompted for a password:

docker login docker.cloudsmith.io
Username: isc/docker-prv
Password: your_token_goes_here
Login Succeeded

Pulling (downloading) an image from the Cloudsmith Docker registry can be done using the standard docker pull command:

docker pull docker.cloudsmith.io/isc/docker-prv/your-image:version

Note: You should replace your-image and version in the above with a Kea image name, such as kea-dhcp4-premium, and a version number, such as 2.6.0.

To refer to images after pulling a Dockerfile, specify the following:

FROM docker.cloudsmith.io/isc/docker-prv/your-image:version