1.. _quickstart:
2
3***********
4Quick Start
5***********
6
7This section describes the basic steps needed to get Kea up and running.
8For further details, full customizations, and troubleshooting, see the
9respective chapters elsewhere in this Kea Administrator Reference Manual (ARM).
10
11.. _quick-start-tarball:
12
13Quick Start Guide Using tarball
14===============================
15
161.  Install required run-time and build dependencies. See
17    :ref:`build-requirements` for details.
18
192.  Download the Kea source tarball from the `ISC.org downloads
20    page <https://www.isc.org/download/>`__ or the `ISC downloads site
21    <https://downloads.isc.org/isc/kea/>`__.
22
233.  Extract the tarball. For example:
24
25    .. parsed-literal::
26
27       $ tar -xvzf kea-|release|.tar.gz
28
294.  Go into the source directory and run the configure script:
30
31    .. parsed-literal::
32
33       $ cd kea-|release|
34       $ ./configure [your extra parameters]
35
365.  Build it:
37
38    .. code-block:: console
39
40       $ make
41
426.  Install it (by default it will be placed in ``/usr/local/``, so
43    root privileges are likely required for this step):
44
45    .. code-block:: console
46
47       $ make install
48
49.. _quick-start-repo:
50
51Quick Start Guide Using Native Packages
52=======================================
53
54As of Kea 1.6.0, ISC provides native RPM, deb, and APK
55packages, which make Kea installation much easier. Unless
56specific compilation options are desired, it is usually easier to install
57Kea using native packages.
58
591. Go to `Kea on cloudsmith.io <https://cloudsmith.io/~isc/repos/>`__,
60   choose the Kea version, and enter the repository.
61
622. Use ``Set Me Up`` and follow instructions to add the repository
63   to the local system.
64
653. Update system repositories. For example:
66
67    .. code-block:: console
68
69        $ apt-get update
70
714. Kea is split into various packages. The entire list is available on
72   `cloudsmith.io <https://cloudsmith.io/~isc/repos/>`__  or using apt/yum/dnf.
73   For example:
74
75    .. code-block:: console
76
77        $ apt-cache search isc-kea
78
795. Install specific packages:
80
81    .. code-block:: console
82
83        $ sudo apt-get install isc-kea-dhcp6-server
84
85   or all packages:
86
87    .. code-block:: console
88
89        $ sudo apt-get install isc-kea*
90
91   or all packages with a specified version number:
92
93    .. code-block:: console
94
95        $ sudo apt-get install isc-kea*=1.8.1-isc0000920201106154401
96
976. All installed packages should be now available directly; for example:
98
99    .. code-block:: console
100
101       # kea-dhcp6 -c /path/to/your/kea6/config/file.json
102
103   or using systemd:
104
105    .. code-block:: console
106
107       # systemctl restart isc-kea-dhcp6-server
108
109   ``keactrl`` is not available in packages as similar functionality is provided
110   by the native systemctl scripts.
111
112.. _quick-start-services:
113
114Quick Start Guide for DHCPv4 and DHCPv6 Services
115================================================
1161.  Edit the Kea configuration files, which by default are installed in
117    the ``[kea-install-dir]/etc/kea/`` directory. These are:
118    ``kea-dhcp4.conf``, ``kea-dhcp6.conf``, ``kea-dhcp-ddns.conf`` and
119    ``kea-ctrl-agent.conf``, ``keactrl.conf`` for DHCPv4 server, DHCPv6 server,
120    D2, Control Agent, and the keactrl script, respectively.
121
1222.  To start the DHCPv4 server in the background, run the
123    following command (as root):
124
125    .. code-block:: console
126
127       # keactrl start -s dhcp4
128
129    Or run the following command to start the DHCPv6 server:
130
131    .. code-block:: console
132
133       # keactrl start -s dhcp6
134
135    Note that it is also possible to start all servers simultaneously:
136
137    .. code-block:: console
138
139       # keactrl start
140
1413.  Verify that the Kea server(s) is/are running:
142
143    .. code-block:: console
144
145       # keactrl status
146
147    A server status of "inactive" may indicate a configuration error.
148    Please check the log file (by default named
149    ``[kea-install-dir]/var/log/kea-dhcp4.log``,
150    ``[kea-install-dir]/var/log/kea-dhcp6.log``,
151    ``[kea-install-dir]/var/log/kea-ddns.log``, or
152    ``[kea-install-dir]/var/log/kea-ctrl-agent.log``) for the details of
153    any errors.
154
1554.  If the server has started successfully, test that it is
156    responding to DHCP queries and that the client receives a
157    configuration from the server; for example, use the `ISC DHCP
158    client <https://www.isc.org/download/>`__.
159
1605.  To stop running the server(s):
161
162    .. code-block:: console
163
164       # keactrl stop
165
166For system-specific instructions, please read the
167`system-specific notes <https://kb.isc.org/docs/installing-kea>`__,
168available in the Kea section of `ISC's
169Knowledgebase <https://kb.isc.org/docs>`__.
170
171The details of ``keactrl`` script usage can be found in :ref:`keactrl`.
172
173Once Kea services are up and running, consider deploying a dashboard solution
174to monitor running services. For more details, see :ref:`stork`.
175
176.. _quick-start-direct-run:
177
178Running the Kea Servers Directly
179================================
180
181The Kea servers can be started directly, without the need to use
182``keactrl`` or ``systemctl``. To start the DHCPv4 server run the following command:
183
184.. code-block:: console
185
186   # kea-dhcp4 -c /path/to/your/kea4/config/file.json
187
188Similarly, to start the DHCPv6 server, run the following command:
189
190.. code-block:: console
191
192   # kea-dhcp6 -c /path/to/your/kea6/config/file.json
193