source: networking/connect/kea.xml@ c5d6597

12.0 12.1 ken/TL2024 ken/tuningfonts lazarus plabs/newcss python3.11 rahul/power-profiles-daemon renodr/vulkan-addition trunk xry111/llvm18
Last change on this file since c5d6597 was 0c76f3cf, checked in by Douglas R. Reno <renodr@…>, 11 months ago

Typo fixes from rhubarbpieguy
  • Property mode set to 100644
File size: 20.8 KB
Line 
1<?xml version="1.0" encoding="ISO-8859-1"?>
2<!DOCTYPE sect1 PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN"
3 "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd" [
4 <!ENTITY % general-entities SYSTEM "../../general.ent">
5 %general-entities;
6
7 <!ENTITY kea-download-http "https://downloads.isc.org/isc/kea/&kea-dhcp-version;/kea-&kea-dhcp-version;.tar.gz">
8 <!ENTITY kea-download-ftp "ftp://ftp.isc.org/isc/kea/&kea-dhcp-version;/kea-&kea-dhcp-version;.tar.gz">
9 <!ENTITY kea-md5sum "e01bdc8d68cfaca1cae17b20b26e09b6">
10 <!ENTITY kea-size "9.9 MB">
11 <!ENTITY kea-buildsize "1.1 GB">
12 <!ENTITY kea-time "14 SBU"><!-- Thats unexpectedly long -->
13 <!ENTITY kea-arm-vers "&kea-dhcp-version;">
14]>
15
16<sect1 id="kea" xreflabel="KEA-&kea-dhcp-version;">
17 <?dbhtml filename="kea.html"?>
18
19
20 <title>Kea &kea-dhcp-version;</title>
21
22 <indexterm zone="kea">
23 <primary sortas="a-KEA">Kea</primary>
24 </indexterm>
25
26 <sect2 role="package">
27 <title>Introduction to ISC Kea</title>
28
29 <para>
30 The <application>ISC Kea</application> package contains the
31 server programs for DHCP. It is the successor of the
32 old ISC DHCP server which is end-of-life since December 2022.
33 </para>
34
35 &lfs113_checked;
36
37 <bridgehead renderas="sect3">Package Information</bridgehead>
38 <itemizedlist spacing="compact">
39 <listitem>
40 <para>
41 Download (HTTP): <ulink url="&kea-download-http;"/>
42 </para>
43 </listitem>
44 <listitem>
45 <para>
46 Download (FTP): <ulink url="&kea-download-ftp;"/>
47 </para>
48 </listitem>
49 <listitem>
50 <para>
51 Download MD5 sum: &kea-md5sum;
52 </para>
53 </listitem>
54 <listitem>
55 <para>
56 Download size: &kea-size;
57 </para>
58 </listitem>
59 <listitem>
60 <para>
61 Estimated disk space required: &kea-buildsize;
62 </para>
63 </listitem>
64 <listitem>
65 <para>
66 Estimated build time: &kea-time;
67 </para>
68 </listitem>
69 </itemizedlist>
70
71 <bridgehead renderas="sect3">Kea Dependencies</bridgehead>
72
73 <bridgehead renderas="sect4">Required</bridgehead>
74 <para role="required">
75 <xref linkend="boost"/>,
76 <xref linkend="log4cplus"/>
77 </para>
78
79 <bridgehead renderas="sect4">Optional</bridgehead>
80 <para role="optional">
81 <xref linkend="mitkrb"/>, for documentation
82 <xref linkend="doxygen"/>,
83 <xref linkend="graphviz"/>,
84 <xref linkend="sphinx_rtd_theme"/>
85 </para>
86
87 <bridgehead renderas="sect4">Optional database backends</bridgehead>
88 <para role="optional">
89 <xref linkend="mariadb"/> or <ulink url="https://www.mysql.com/">MySQL</ulink>,
90 <xref linkend="postgresql"/>
91 </para>
92<!--
93 <para condition="html" role="usernotes">Editor Notes:
94 <ulink url="&blfs-wiki;/kea"/>
95 </para>
96-->
97 </sect2>
98
99 <sect2 role="kernel" id="kea-dhcp-kernel">
100 <title>Kernel Configuration</title>
101
102 <para>
103 You must have Packet Socket support. IPv6 support is optional.
104 </para>
105
106 <xi:include xmlns:xi="http://www.w3.org/2001/XInclude"
107 href="kea-kernel.xml"/>
108
109 <indexterm zone="kea kea-dhcp-kernel">
110 <primary sortas="k-KEA">Kea</primary>
111 </indexterm>
112
113 </sect2>
114
115 <sect2 role="installation">
116 <title>Installation of ISC Kea DHCP</title>
117
118 <para>
119 Install <application>ISC Kea DHCP</application> by running
120 the following commands:
121 </para>
122
123<screen><userinput>./configure --prefix=/usr \
124 --sysconfdir=/etc \
125 --docdir=/usr/share/doc/kea-&kea-dhcp-version; \
126 --localstatedir=/var \
127 --enable-shell \
128 --with-openssl \
129 --disable-static &amp;&amp;
130make</userinput></screen>
131
132 <para>
133 To test the results, issue: <command>make check</command>.
134 </para>
135
136 <para>
137 To install the <application>ISC Kea DHCP</application> suite,
138 issue the following commands as the
139 <systemitem class="username">root</systemitem> user:
140 </para>
141
142<screen role="root"><userinput>make -j1 install</userinput></screen>
143
144 </sect2>
145
146 <sect2 role="commands">
147 <title>Command Explanations</title>
148
149 <para>
150 <parameter>--with-pgsql</parameter> or <parameter>--with-mysql</parameter>:
151 <application>ISC Kea</application> can store the leases on a
152 database. This might be useful in large environments running
153 a cluster of DHCP servers. Using the <emphasis>memfile</emphasis>
154 backend (which is a CSV file stored locally) is possible anyhow.
155 </para>
156
157 <para>
158 <parameter>--enable-generate-docs</parameter>:
159 If documentation is to be rebuilt, add that option. Several
160 dependencies must be installed for generating the documentation.
161 </para>
162
163 <para>
164 <parameter>make -j1 install</parameter>: ISC does not recommend
165 any form of parallel or job server options when doing the install.
166 </para>
167
168 </sect2>
169
170 <sect2 role="configuration">
171 <title>Configuring ISC Kea DHCP</title>
172
173 <para>The support of IPv4, IPv6 and DDNS has been split into
174 separate servers which runs independently from each other. Each
175 of them has its own configuration file. Additional configuration
176 files come from the keactrl agent which is uses to control the
177 servers in an easy way.</para>
178
179 <para>Consult the
180 <ulink url="https://kea.readthedocs.io/en/kea-&kea-arm-vers;/">Kea Administrator Reference Manual</ulink>
181 for detailed information about the configuration of <application>ISC Kea</application>
182 as it is a quite capable system. The configuration shown a bare
183 minimum to get a DHCP server running but it already includes
184 configuration for DDNS (Dynamic DNS). That setup might be working
185 for small networks with a few clients and low traffic. For greater
186 installations with thousands of clients, <application>ISC Kea</application>
187 can be configured to use databases (mariadb or postgresql) to store
188 the leases and build a cluster with multiple nodes. It can
189 be integrated to <ulink url="https://www.isc.org/categories/stork/">ISC Stork</ulink>
190 which is a management dashboard to <application>ISC Kea</application>.</para>
191
192 <para>
193 If you want to start the DHCP Server at boot, install the
194 <phrase revision="sysv"><filename>/etc/rc.d/init.d/kea-dhcpd</filename>
195 init script</phrase>
196 <phrase revision="systemd"><filename>kea-dhcpd.service</filename>
197 unit</phrase> included in the
198 <xref linkend="bootscripts" revision="sysv"/>
199 <xref linkend="systemd-units" revision="systemd"/>
200 package:
201 </para>
202
203<screen role="root"><userinput>make install-kea-dhcpd</userinput></screen>
204
205 <sect3 id="kea-dhcp-config">
206 <title>Config Files</title>
207
208 <para>
209 <filename>/etc/kea/keactrl.conf</filename>,
210 <filename>/etc/kea/kea-ctrl-agent.conf</filename>,
211 <filename>/etc/kea/kea-dhcp4.conf</filename>,
212 <filename>/etc/kea/kea-dhcp6.conf</filename> and
213 <filename>/etc/kea/kea-dhcp-ddns.conf</filename>
214 </para>
215
216 <indexterm zone="kea keactrl-config">
217 <primary sortas="e-etc-kea-keactrl.conf">/etc/kea/keactrl.conf</primary>
218 </indexterm>
219
220 <indexterm zone="kea kea-ctrl-agent-config">
221 <primary sortas="e-etc-kea-kea-ctrl-agent.conf">/etc/kea/kea-ctrl-agent.conf</primary>
222 </indexterm>
223
224 <indexterm zone="kea kea-dhcp4-config">
225 <primary sortas="e-etc-kea-dhcp4.conf">/etc/kea/kea-dhcp4.conf</primary>
226 </indexterm>
227<!--
228 <indexterm zone="kea kea-dhcp6-config">
229 <primary sortas="e-etc-kea-dhcp6.conf">/etc/kea/kea-dhcp6.conf</primary>
230 </indexterm>
231-->
232 <indexterm zone="kea kea-dhcp-ddns-config">
233 <primary sortas="e-etc-kea-dhcp-ddns.conf">/etc/kea/kea-dhcp-ddns.conf</primary>
234 </indexterm>
235 </sect3>
236
237 <sect3 id="keactrl-config">
238 <title>Kea Control Configuration</title>
239
240 <para><command>keactrl</command> is used to control the
241 independent servers (IPv4, IPv6, DDNS). Its configuration file
242 <filename>/etc/kea/keactrl.conf</filename> is installed by
243 default and includes many path settings which are defined
244 due to the <command>configure</command> at build time. It also
245 includes settings to specify which of the servers should be
246 started.</para>
247
248 <itemizedlist>
249 <listitem>
250 <para>Control Agent</para>
251 <para>The Control Agent is a daemon which allows the
252 (re)configuration of the Kea DHCP service via REST API.
253 Set <literal>ctrl_agent=yes</literal> to start the
254 control agent (service providing a REST API), set
255 <literal>ctrl_agent=no</literal> in case the control agent
256 is not needed.</para>
257 </listitem>
258 <listitem>
259 <para>IPv4 DHCP server</para>
260 <para>This daemon handles requests for IPv4 addresses.
261 Set <literal>dhcp4=yes</literal> to start it, set
262 <literal>dhcp4=no</literal> in case DHCP service for IPv4
263 is not wanted.</para>
264 </listitem>
265 <listitem>
266 <para>IPv6 DHCP server</para>
267 <para>This daemon handles requests for IPv6 addresses.
268 Set <literal>dhcp6=yes</literal> to start it, set
269 <literal>dhcp6=no</literal> in case DHCP service for IPv6
270 is not wanted.</para>
271 </listitem>
272 <listitem>
273 <para>Dynamic DNS</para>
274 <para>This daemon is used to update a DNS server dynamically
275 when Kea assigns an IP address to a device.
276 Set <literal>dhcp_ddns=yes</literal> to enable it, set
277 <literal>dhcp_ddns=no</literal> in case dynamic DNS updates
278 are not wanted.</para>
279 </listitem>
280 </itemizedlist>
281
282 <para>The Netconf service is not installed because required
283 dependencies are not covered by the current BLFS book.</para>
284
285 <para>With the following command, Kea will be configured to
286 start the dhcp service for IPv4 and the
287 dynamic DNS update, while the control agent and
288 the dhcp service for IPv6 remains down. Tweak the command to
289 match your needs on started services and execute as the
290 <systemitem class="username">root</systemitem> user:</para>
291
292<screen><userinput role="root">sed -e "s/^dhcp4=.*/dhcp4=yes/" \
293 -e "s/^dhcp6=.*/dhcp6=no/" \
294 -e "s/^dhcp_ddns=.*/dhcp_ddns=yes/" \
295 -e "s/^ctrl_agent=.*/ctrl_agent=no/" \
296 -i /etc/kea/keactrl.conf
297</userinput></screen>
298
299 </sect3>
300
301 <sect3 id="kea-ctrl-agent-config">
302 <title>Control Agent Configuration</title>
303
304 <para>
305 The provided configuration could be used without changes
306 but in BLFS objects like sockets are stored in
307 <filename class="directory">/run</filename>
308 rather than in
309 <filename class="directory">/tmp</filename>.
310 </para>
311
312<screen role="nodump"><userinput>cat &gt; /etc/kea/kea-ctrl-agent.conf &lt;&lt; "EOF"
313<literal>// Begin /etc/kea/kea-ctrl-agent.conf
314{
315 // This is a basic configuration for the Kea Control Agent.
316 // RESTful interface to be available at http://127.0.0.1:8000/
317 "Control-agent": {
318 "http-host": "127.0.0.1",
319 "http-port": 8000,
320 "control-sockets": {
321 "dhcp4": {
322 "socket-type": "unix",
323 "socket-name": "/run/kea4-ctrl-socket"
324 },
325 "dhcp6": {
326 "socket-type": "unix",
327 "socket-name": "/run/kea6-ctrl-socket"
328 },
329 "d2": {
330 "socket-type": "unix",
331 "socket-name": "/run/kea-ddns-ctrl-socket"
332 }
333 },
334
335 "loggers": [
336 {
337 "name": "kea-ctrl-agent",
338 "output_options": [
339 {
340 "output": "/var/log/kea-ctrl-agent.log"
341 "pattern": "%D{%Y-%m-%d %H:%M:%S.%q} %-5p %m\n"
342 }
343 ],
344 "severity": "INFO",
345 "debuglevel": 0
346 }
347 ]
348 }
349}
350// End /etc/kea/kea-ctrl-agent.conf</literal>
351EOF</userinput></screen>
352
353 </sect3>
354
355 <sect3 id="kea-dhcp4-config">
356 <title>IPv4 DHCP Server Configuration</title>
357
358 <para>
359 A sample configuration file is created in <filename>/etc/kea/kea-dhcp4.conf</filename>.
360 Adjust the file to suit your needs or overwrite it by using
361 the following sample as the <systemitem class="username">root</systemitem>
362 user:
363 </para>
364
365<screen role="nodump"><userinput>cat &gt; /etc/kea/kea-dhcp4.conf &lt;&lt; "EOF"
366<literal>// Begin /etc/kea/kea-dhcp4.conf
367{
368 "Dhcp4": {
369 // Add names of your network interfaces to listen on.
370 "interfaces-config": {
371 "interfaces": [ "eth0", "eth2" ]
372 },
373
374 "control-socket": {
375 "socket-type": "unix",
376 "socket-name": "/run/kea4-ctrl-socket"
377 },
378
379 "lease-database": {
380 "type": "memfile",
381 "lfc-interval": 3600
382 },
383
384 "expired-leases-processing": {
385 "reclaim-timer-wait-time": 10,
386 "flush-reclaimed-timer-wait-time": 25,
387 "hold-reclaimed-time": 3600,
388 "max-reclaim-leases": 100,
389 "max-reclaim-time": 250,
390 "unwarned-reclaim-cycles": 5
391 },
392
393 "renew-timer": 900,
394 "rebind-timer": 1800,
395 "valid-lifetime": 3600,
396
397 // Enable DDNS - Kea will dynamically update the DNS
398 "ddns-send-updates" : true,
399 "ddns-qualifying-suffix": "your.domain.tld",
400 "dhcp-ddns" : {
401 "enable-updates": true
402 },
403
404 "subnet4": [
405 {
406 "subnet": "192.168.56.0/24",
407 "pools": [ { "pool": "192.168.56.16 - 192.168.56.254" } ],
408 "option-data": [
409 {
410 "name": "domain-name",
411 "data": "your.domain.tld"
412 },
413 {
414 "name": "domain-name-servers",
415 "data": "192.168.56.2, 192.168.3.7"
416 },
417 {
418 "name": "domain-search",
419 "data": "your.domain.tld"
420 },
421 {
422 "name": "routers",
423 "data": "192.168.56.2"
424 }
425 ]
426 }
427 ],
428
429 "loggers": [
430 {
431 "name": "kea-dhcp4",
432 "output_options": [
433 {
434 "output": "/var/log/kea-dhcp4.log",
435 "pattern": "%D{%Y-%m-%d %H:%M:%S.%q} %-5p %m\n"
436 }
437 ],
438 "severity": "INFO",
439 "debuglevel": 0
440 }
441 ]
442 }
443}
444// End /etc/kea/kea-dhcp4.conf</literal>
445EOF</userinput></screen>
446
447 <para>
448 The configuration for IPv6 is similar to the configuration
449 of IPv4. The configuration file is
450 <filename>/etc/kea/kea-dhcp6.conf</filename>.
451 </para>
452
453 </sect3>
454
455 <sect3 id="kea-dhcp-ddns-config">
456 <title>Dynamic DNS Configuration</title>
457
458 <para>
459 If there is a <xref linkend="bind"/> server running,
460 <application>ISC Kea</application> can update the DNS when
461 it gives an IP address to a client. A sample configuration
462 file is created in <filename>/etc/kea/kea-dhcp-ddns.conf</filename>.
463 Adjust the file to suit your needs or overwrite it by using
464 the following sample as the <systemitem class="username">root</systemitem>
465 user:
466 </para>
467
468<screen role="nodump" ><userinput>cat &gt; /etc/kea/kea-dhcp-ddns.conf &lt;&lt; "EOF"
469<literal>// Begin /etc/kea/kea-dhcp-ddns.conf
470{
471 "DhcpDdns": {
472 "ip-address": "127.0.0.1",
473 "port": 53001,
474 "control-socket": {
475 "socket-type": "unix",
476 "socket-name": "/run/kea-ddns-ctrl-socket"
477 },
478
479 "tsig-keys": [
480 {
481 "name" : "rndc-key",
482 "algorithm" : "hmac-sha256",
483 "secret" : "1FU5hD7faYaajQCjSdA54JkTPQxbbPrRnzOKqHcD9cM="
484 }
485 ],
486
487 "forward-ddns" : {
488 "ddns-domains" : [
489 {
490 "name" : "your.domain.tld.",
491 "key-name": "rndc-key",
492 "dns-servers" : [
493 {
494 "ip-address" : "127.0.0.1",
495 "port" : 53
496 }
497 ]
498 }
499 ]
500 },
501
502 "reverse-ddns" : {
503 "ddns-domains" : [
504 {
505 "name" : "56.168.192.in-addr.arpa.",
506 "key-name": "rndc-key",
507 "dns-servers" : [
508 {
509 "ip-address" : "127.0.0.1",
510 "port" : 53
511 }
512 ]
513 }
514 ]
515 },
516
517 "loggers": [
518 {
519 "name": "kea-dhcp-ddns",
520 "output_options": [
521 {
522 "output": "/var/log/kea-ddns.log",
523 "pattern": "%D{%Y-%m-%d %H:%M:%S.%q} %-5p %m\n"
524 }
525 ],
526 "severity": "INFO",
527 "debuglevel": 0
528 }
529 ]
530 }
531}
532// End /etc/kea/kea-dhcp-ddns.conf</literal>
533EOF</userinput></screen>
534
535 <note>
536 <para>
537 The value of <literal>secret</literal> is just an example.
538 Generate the key for your installation by using the
539 <command>rndc-confgen -a</command> command or the
540 <command>tsig-keygen</command> command which both are
541 provided by <xref linkend="bind"/>.
542 </para>
543 <para>
544 In this sample config it is assumed that the DNS server
545 runs on the same machine as Kea does (accessable via
546 <literal>127.0.0.1</literal>) and that this machine has
547 the IP <literal>192.168.56.2</literal>.
548 </para>
549 </note>
550
551 </sect3>
552
553 </sect2>
554
555 <sect2 role="content">
556 <title>Contents</title>
557
558 <segmentedlist>
559 <segtitle>Installed Programs</segtitle>
560 <segtitle>Installed Libraries</segtitle>
561 <segtitle>Installed Directories</segtitle>
562
563 <seglistitem>
564 <seg>
565 keactrl, kea-admin, kea-ctrl-agent, kea-dhcp4, kea-dhcp6,
566 kea-dhcp-ddns, kea-lfc, kea-shell
567 </seg>
568 <seg>
569 libkea-*
570 </seg>
571 <seg>
572 /etc/kea,
573 /usr/include/kea,
574 /var/lib/kea
575 </seg>
576 </seglistitem>
577 </segmentedlist>
578
579 <variablelist>
580 <bridgehead renderas="sect3">Short Descriptions</bridgehead>
581 <?dbfo list-presentation="list"?>
582 <?dbhtml list-presentation="table"?>
583
584 <varlistentry id="keactrl">
585 <term><command>keactrl</command></term>
586 <listitem>
587 <para>
588 Tool to control (start/stop) the server processes.
589 </para>
590 <indexterm zone="kea keactrl">
591 <primary sortas="b-keactrl">keactrl</primary>
592 </indexterm>
593 </listitem>
594 </varlistentry>
595 <varlistentry id="kea-admin">
596 <term><command>kea-admin</command></term>
597 <listitem>
598 <para>
599 kea-admin is a shell script which offers database maintenance.
600 </para>
601 <indexterm zone="kea kea-admin">
602 <primary sortas="b-kea-admin">kea-admin</primary>
603 </indexterm>
604 </listitem>
605 </varlistentry>
606 <varlistentry id="kea-ctrl-agent">
607 <term><command>kea-ctrl-agent</command></term>
608 <listitem>
609 <para>
610 Daemon which exposes a RESTful control interface for
611 managing Kea servers.
612 </para>
613 <indexterm zone="kea kea-ctrl-agent">
614 <primary sortas="b-kea-ctrl-agent">kea-ctrl-agent</primary>
615 </indexterm>
616 </listitem>
617 </varlistentry>
618 <varlistentry id="kea-dhcp4">
619 <term><command>kea-dhcp4</command></term>
620 <listitem>
621 <para>
622 The server daemon providing IPv4 addresses.
623 </para>
624 <indexterm zone="kea kea-dhcp4">
625 <primary sortas="b-kea-dhcp4">kea-dhcp4</primary>
626 </indexterm>
627 </listitem>
628 </varlistentry>
629 <varlistentry id="kea-dhcp6">
630 <term><command>kea-dhcp6</command></term>
631 <listitem>
632 <para>
633 The server daemon providing IPv6 addresses.
634 </para>
635 <indexterm zone="kea kea-dhcp6">
636 <primary sortas="b-kea-dhcp6">kea-dhcp6</primary>
637 </indexterm>
638 </listitem>
639 </varlistentry>
640 <varlistentry id="kea-dhcp-ddns">
641 <term><command>kea-dhcp-ddns</command></term>
642 <listitem>
643 <para>
644 The server daemon performing the dynamic DNS updates.
645 </para>
646 <indexterm zone="kea kea-dhcp-ddns">
647 <primary sortas="b-kea-dhcp-ddns">kea-dhcp-ddns</primary>
648 </indexterm>
649 </listitem>
650 </varlistentry>
651 <varlistentry id="kea-lfc">
652 <term><command>kea-lfc</command></term>
653 <listitem>
654 <para>
655 The kea-lfc service process removes redundant information
656 from the files used to provide persistent storage for the
657 memfile database backend. It is run by the Kea DHCP server.
658 </para>
659 <indexterm zone="kea kea-lfc">
660 <primary sortas="b-kea-lfc">kea-lfc</primary>
661 </indexterm>
662 </listitem>
663 </varlistentry>
664 <varlistentry id="keashell">
665 <term><command>keashell</command></term>
666 <listitem>
667 <para>
668 RESTful client to the <application>ISC Kea</application>
669 services.
670 </para>
671 <indexterm zone="kea keashell">
672 <primary sortas="b-keashell">keashell</primary>
673 </indexterm>
674 </listitem>
675 </varlistentry>
676
677 </variablelist>
678
679 </sect2>
680
681</sect1>
Note: See TracBrowser for help on using the repository browser.