source: networking/connect/kea.xml@ 6886d51

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 6886d51 was 6886d51, checked in by Bruce Dubbs <bdubbs@…>, 10 months ago

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