2. Quick Start

This section describes the basic steps needed to get Kea up and running.
For
further details, full customizations, and troubleshooting, see the
respective chapters elsewhere in this Kea Administrator Reference Manual
(ARM).



2.1. Quick Start Guide Using tarball

Install required runtime and build dependencies. See Build Requirements
for
details.
Download the Kea source tarball from the ISC.org downloads page or the ISC
downloads site.
Extract the tarball. For example:
$ tar -xvzf kea- 2.3.9-git.tar.gz

Go into the source directory and run the configure script:
$ cd kea- 2.3.9-git
    $ ./configure [your extra parameters]

Build it:
make

Install it (by default it will be placed in /usr/local/, so root
privileges
are likely required for this step):
make install




2.2. Quick Start Guide Using Native Packages

ISC provides native Alpine, deb, and RPM packages, which make Kea
installation much easier. Unless specific compilation options are desired,
it is usually easier to install Kea using native packages.

Go to Kea on cloudsmith.io, choose the Kea version, and enter the
repository.
Use Set Me Up and follow instructions to add the repository to the local
system.

Note
For example, the Debian setup instructions for Kea 2.3 can be found here: 
https://cloudsmith.io/~isc/repos/kea-2-3/setup/#formats-deb 

The dropdown near the top of the page offers instructions for other
operating systems.

Update system repositories. For example, on Debian/Ubuntu:
sudo apt update

On CentOS/Fedora:
sudo yum update

On Alpine:
apk update

Kea is split into various packages. The entire list is available on
cloudsmith.io or using apt/yum/dnf. For example, on Debian/Ubuntu:

apt search isc-kea

On CentOS/Fedora:
yum search isc-kea

On Alpine:
apk search isc-kea

Install the metapackage containing all of the tools, services, and open
source hooks:

sudo apt install isc-kea

or specific packages:
sudo apt install isc-kea-dhcp6

or every single Kea-related package, including development headers, debug
symbols, and premium hooks (if available):

sudo apt install isc-kea*

or all packages with a specified version number:

sudo apt install isc-kea*=2.4.0-isc20230531000000

Note
Not all package managers support installing packages with a glob (*),
please

refer to the specific package manager's manual before attempting this.
    On CentOS/Fedora systems, replace apt install with yum install.
    On Alpine systems, replace apt install with apk add.


All installed packages should be now available directly; for example:
kea-dhcp6 -c /path/to/your/kea6/config/file.json

or using systemd:

systemctl restart kea-dhcp6

or using OpenRC on Alpine:

service kea-dhcp6 restart

Note
keactrl is not available in packages, as similar functionality is provided
by 
the native systemctl scripts.

On CentOS, Fedora, and Alpine, the service must be enabled at boot time if
desired; this is done automatically at package installation time on Debian
and Ubuntu systems. For example, with systemd on CentOS/Fedora:

systemctl enable kea-dhcp6

With OpenRC on Alpine:

rc-update add kea-dhcp6




2.3. Quick Start Guide for DHCPv4 and DHCPv6 Services

Edit the Kea configuration files, which by default are installed in the
[kea-install-dir]/etc/kea/ directory. These are: kea-dhcp4.conf, kea
-dhcp6.conf, kea-dhcp-ddns.conf and kea-ctrl-agent.conf, keactrl.conf for
DHCPv4 server, DHCPv6 server, D2, Control Agent, and the keactrl script,
respectively.

To start the DHCPv4 server in the background, run the following command
(as
root):

keactrl start -s dhcp4

Or run the following command to start the DHCPv6 server:
keactrl start -s dhcp6

Note that it is also possible to start all servers simultaneously:
keactrl start

 that the Kea server(s) is/are running:
keactrl status

A server status of "inactive" may indicate a configuration error. Please
check the log file (by default named [kea-install-dir]/var/log/kea
-dhcp4.log, [kea-install-dir]/var/log/kea-dhcp6.log, [kea-install
-dir]/var/log/kea-ddns.log, or [kea-install-dir]/var/log/kea-ctrl
-agent.log)
for the details of any errors.

If the server has started successfully, test that it is responding to DHCP
queries and that the client receives a configuration from the server; for
example, use the ISC DHCP client.

To stop running the server(s):
keactrl stop


For system-specific instructions, please read the system-specific notes,
available in the Kea section of ISC's Knowledgebase.

The details of keactrl script usage can be found in Managing Kea with
keactrl.

Once Kea services are up and running, consider deploying a dashboard
solution to monitor running services. For more details, see Monitoring Kea
With Stork.



2.4. Running the Kea Servers Directly

The Kea servers can be started directly, without the need to use keactrl or
systemctl. To start the DHCPv4 server run the following command:

kea-dhcp4 -c /path/to/your/kea4/config/file.json

Similarly, to start the DHCPv6 server, run the following command:

kea-dhcp6 -c /path/to/your/kea6/config/file.json