source: server/major/kea.xml@ 0ff4c32

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 0ff4c32 was eb0031c, checked in by Xi Ruoyao <xry111@…>, 9 months ago

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