From: Stephen Morris Date: Wed, 18 Jun 2014 17:14:40 +0000 (+0100) Subject: [3418] Corrections and minor alterations to DHCP4 Server Guide during review X-Git-Tag: trac3473_base~12^2~2 X-Git-Url: http://git.ipfire.org/gitweb.cgi?a=commitdiff_plain;h=9bb16e0b664bfacff8d4f184af7a6a7e9c9853da;p=thirdparty%2Fkea.git [3418] Corrections and minor alterations to DHCP4 Server Guide during review --- diff --git a/doc/guide/dhcp4-srv.xml b/doc/guide/dhcp4-srv.xml index beaf2f2a2c..dffdf02930 100644 --- a/doc/guide/dhcp4-srv.xml +++ b/doc/guide/dhcp4-srv.xml @@ -60,11 +60,13 @@
Configuring the DHCPv4 Server +
+ Introduction - This section explains how to configure DHCPv4 server that uses + This section explains how to configure the DHCPv4 server using the Kea configuration backend. Kea configuration using any other backends is outside of scope for this document. Before DHCPv4 - is started, its configuration file has to be prepared. The + is started, its configuration file has to be created. The basic configuration looks as follows: { @@ -94,83 +96,92 @@ } } -Note that line numbers are specified for easier reference only and -are not part of the configuration. The examples in following sections do not -have reference numbers. + -The following paragraphs provide brief overview of the parameters and -their format. Following sections in this chapter go into much greater details -for aforementioned parameters and also introduce new ones. +The following paragraphs provide a brief overview of the parameters in +the above example and +their format. Subsequent sections of this chapter go into much greater detail +for these and other parameters. -The lines starting with a hash (#) are comments and do not impact the server +The lines starting with a hash (#) are comments and are ignored by +the server; they do not impact its operation in any way. -The configuration starts in the first line with the initial opening curly -bracket. Each configuration consists of one or more objects. In this specific -example, we have only one object called Dhcp4. This is a simplified -configuration, as usually there will be additional objects, like -Logging or DhcpDns, but we omit them now -for clarity. The Dhcp4 configuration starts after the first comment -("Dhcp4": {) and ends after the last comment (}). Everything -defined between those lines is considered Dhcp4 configuration. - -In general case, the order in which those parameters appear doesn't -matter. There are two caveats here, though. The first one is to remember that +The configuration starts in the first line with the initial +opening curly bracket (or brace). Each configuration consists of +one or more objects. In this specific example, we have only one +object called Dhcp4. This is a simplified configuration, as usually +there will be additional objects, like Logging or +DhcpDns, but we omit them now for clarity. The Dhcp4 +configuration starts with the the "Dhcp4: {" line +and ends with the corresponding closing brace (in the above example, +the brace after the last comment). Everything defined between those +lines is considered to be the Dhcp4 configuration. + +In general case, the order in which those parameters appear does not +matter. There are two caveats here though. The first one is to remember that the configuration file must be a well formed JSON. That means that parameters -for any given scope must be separate by a coma and there must not be a coma +for any given scope must be separate by a comma and there must not be a comma after the last parameter. When reordering configuration file, keep in mind that moving a parameter to or from the last position in a given scope may require -moving the coma as well. The second caveat is that it is uncommon, but legal to -repeat the same parameter multiple times. In that case the last occurrence of a +moving the comma as well. The second caveat is that it is uncommon - although +legal JSON - to +repeat the same parameter multiple times. If that appears, the last occurrence of a given parameter in a given scope is used while all previous instances are -ignored. That is unlikely to cause any confusion, as there are no real life +ignored. This is unlikely to cause any confusion as there are no real life reasons to keep multiple copies of the same parameter in your configuration file. -The line defining interfaces parameter specifies a list -of network interfaces, over which the server should listen. Please note the -notation. Lists are opened and closed with square brackets, with elements -separated by comas. Had we wanted to listen on two interfaces, the line could +Moving onto the DHCPv4 configuration elements, +the line defining interfaces parameter specifies a list +of network interfaces on which the server should listen. +Lists are opened and closed with square brackets, with elements +separated by commas. Had we wanted to listen on two interfaces, the line could look like this: "interfaces": [ "eth0", "eth1" ], -As "interfaces" is not the last parameter and there are -others that follow, a trailing coma is required. A number of other parameters -follow. Valid lifetime defines how long the addresses (leases) given out by the +As "interfaces" is not the last parameter in the configuration, +a trailing comma is required.i +A number of other parameters +follow. valid-lifetime defines how long the addresses (leases) given out by the server are valid. If nothing changes, client that got the address is allowed to -use it for 4000 seconds. Please note that integer numbers are specified as is, -without any quotes around them. Renew-timer and rebind-timer are values that +use it for 4000 seconds. (Note that integer numbers are specified as is, +without any quotes around them.) renew-timer and +rebind-timer are values that define T1 and T2 timers that govern when the client will begin renewal and rebind procedures. -The next couple lines define lease database. It informs the server where -to store its leases information. This specific example tells the server to use +The next couple lines define the lease database, the place where the server +stores its lease information. This particular example tells the server to use memfile, which is the simplest (and fastest) database -backend. It uses in-memory database and stores leases on disk using CSV +backend. It uses in-memory database and stores leases on disk in a CSV file. This is a very simple configuration. Usually, lease database configuration -is more extensive and contains additional parameters. Note that lease-database -is defined as an object and it opens up a new scope, using opening curly -bracket. Its parameters (just one in this example -- called "type") -follow. Had there been more than one, they would be separated by comas. This -scope is closed with closing curly bracket. As more parameters follow, trailing -coma is present. - -Finally, we need to define a list of IPv4 subnets. This is the most -important DHCPv4 configuration structure as the server uses that information to -process clients' requests. It defines all subnets that the server is expected to -receive DHCP requests from. It is a list, so it start and ends with square -brackets. In this example we have only one subnet defined. Subnet itself has -several parameters, hence it is a structure, so it is opened and closed using -curly brackets. Each subnet has to have at least two parameters: subnet (that -defines the whole subnet) and pool (which is a list of dynamically allocated -pools that are governed by the DHCP server. Subnet4 list is closed with closing -square bracket at the end of line 35. As this is the last parameter in Dhcp4 -context, there is no trailing coma. - -Had there been more than one subnet defined, additional subnet4 objects -would be specified and separated by comas. For example, to define 3 subnets, the -following syntax should be used: +is more extensive and contains additional parameters. Note that +lease-database +is an object and opens up a new scope, using an opening brace. +Its parameters (just one in this example -- type) +follow. Had there been more than one, they would be separated by commas. This +scope is closed with a closing brace. As more parameters follow, a trailing +comma is present. + +Finally, we need to define a list of IPv4 subnets. This is the +most important DHCPv4 configuration structure as the server uses that +information to process clients' requests. It defines all subnets that +the server is expected to receive DHCP requests from. The subnets are +specified with the subnet4 parameter. It is a list, +so it starts and ends with square brackets. Each subnet definition in +the list has several attributes associated with it, so is a structure +and is opened and closed with braces. At minimum, a subnet definition +has to have at least two parameters: subnet (that +defines the whole subnet) and pool (which is a list of +dynamically allocated pools that are governed by the DHCP server. + +The example contains a single subnet. Had more than one been defined, +additional elements +in the subnet4 parameter would be specified and +separated by commas. For example, to define three subnets, the following +syntax would be used: "subnet4": [ { @@ -189,11 +200,11 @@ following syntax should be used: -After all parameters are specified, we have two contexts open: global and -Dhcp4, hence we need two closing curly brackets to close them. In a real life -configuration file there likely would be additional components defined, like -Logging or DhcpDdns, so after the first bracket would have a coma behind it and -a new object definition would follow. +After all parameters are specified, we have two contexts open: +global and Dhcp4, hence we need two closing curly brackets to close them. +In a real life configuration file there likely would be additional +components defined like Logging or DhcpDdns, so the closing brace would +be followed by a comma and another object definition. Kea 0.9 does not have configuration syntax validation implemented yet. Such a feature is planned for the near future. For @@ -202,25 +213,30 @@ viewers to check whether the syntax is correct. One example of such a JSON validator is available at . +
- Memfile - a basic storage for leases + Lease Storage + All leases issued by the server are stored in the lease database. + Currently there are three database backends available: + memfile (which is the default backend), MySQL and PostgreSQL. +
+ Memfile - Basic Storage for Leases The server is able to store lease data in different repositories. Larger deployments may elect to store leases in a database. describes one way to do it. In typical - smaller deployments the server will use a CSV file rather than a database to - store lease information. One of the advantages of using a file is that it - eliminates dependency on third party database software. + linkend="database-configuration4"/> describes this option. In typical + smaller deployments though, the server will use a CSV file rather than a database to + store lease information. As well as requiring less administration, an + advantage of using a file for storage is that it + eliminates a dependency on third-party database software. The configuration of the file backend (Memfile) is controlled through the Dhcp4/lease-database parameters. - - It is possible to alter the default location of the lease file. The - following configuration: + [kea-install-dir]/var/kea/kea-leases4.csv. --> + The following configuration: "Dhcp4": { "lease-database": { @@ -231,19 +247,20 @@ url="http://jsonviewer.stack.hu/"/>. ... } - will change the default location of the lease file to /tmp/kea-leases4.csv. + ...sets the name of the lease file to /tmp/kea-leases4.csv. The "persist" parameter controls whether the leases are written to disk. It is strongly recommended that this parameter is set to "true" at all times - during the normal operation of the server + during the normal operation of the server. (Not writing leases to disk will + mean that if a server is restarted (e.g. after a power failure), it will not + know what addresses have been assigned. As a result, it may hand out addresses + to new clients that are already in use.) +
Database Configuration - All leases issued by the server are stored in the lease database. - Currently there are 3 database backends available: MySQL, PostgreSQL and - memfile (which is the default backend). Database access information must be configured for the DHCPv4 server, @@ -253,10 +270,10 @@ url="http://jsonviewer.stack.hu/"/>. Database configuration is controlled through the Dhcp4/lease-database - parameters. The type of the database must be set to "mysql", "postgresql" or - "memfile": + parameters. The type of the database must be set to "mysql" or "postgresql", + e.g. -"Dhcp4": { "lease-database": { "type": "memfile", ... }, ... } +"Dhcp4": { "lease-database": { "type": "mysql", ... }, ... } Next, the name of the database is to hold the leases must be set: this is the name used when the lease database was created (see @@ -265,7 +282,7 @@ url="http://jsonviewer.stack.hu/"/>. "Dhcp4": { "lease-database": { "name": "database-name" , ... }, ... } If the database is located on a different system to the DHCPv4 server, the - database host name must also be specified (although note that this + database host name must also be specified (although it should be noted that this configuration may have a severe impact on server performance): "Dhcp4": { "lease-database": { "host": remote-host-name", ... }, ... } @@ -287,17 +304,17 @@ url="http://jsonviewer.stack.hu/"/>. If there is no password to the account, set the password to the empty string "". (This is also the default.)
+
Interface selection - DHCPv4 server has to be configured to listen on specific network + The DHCPv4 server has to be configured to listen on specific network interfaces. The simplest network interface configuration tells the server to listen on all available interfaces: "Dhcp4": { "interfaces": ["*"], ... } - An asterisk sign plays a role of the wildcard and means "listen on all interfaces". - - It is usually a good idea to explicitly specify interface names: + The asterisk plays the role of a wildcard and means "listen on all interfaces". + However, it is usually a good idea to explicitly specify interface names: "Dhcp4": { "interfaces": [ "eth1", "eth3" ], ... } @@ -305,17 +322,17 @@ url="http://jsonviewer.stack.hu/"/>. with explicit interface names: "Dhcp4": { "interfaces": [ "eth1", "eth3", "*" ], ... } -This configuration will tell the server to listen on all interfaces. It may be useful -to temporary add asterisk and retain the list of interface names. +It is anticipated that this will form of usage only be used where it is desired to +temporarily override a list of interface names and listen on all interfaces.
IPv4 Subnet Identifier - Subnet identifier is a unique number associated with a particular subnet. + The subnet identifier is a unique number associated with a particular subnet. In principle, it is used to associate clients' leases with respective subnets. - When subnet identifier is not specified for a subnet being configured, it will + When a subnet identifier is not specified for a subnet being configured, it will be automatically assigned by the configuration mechanism. The identifiers are assigned from 1 and are monotonically increased for each subsequent subnet: 1, 2, 3 .... @@ -323,13 +340,14 @@ to temporary add asterisk and retain the list of interface names. If there are multiple subnets configured with auto-generated identifiers and one of them is removed, the subnet identifiers may be renumbered. For example: - if there are 4 subnets and 3rd is removed the last subnet will be assigned - identifier that the 3rd subnet had before removal. As a result, the leases - stored in the lease database for subnet 3 are now associated with the - subnet 4, which may have unexpected consequences. In the future it is planned - to implement the mechanism to preserve auto-generated subnet ids upon removal - of one of the subnets. Currently, the only remedy for this issue is to - manually specify the unique subnet identifier for each subnet. + if there are four subnets and third is removed the last subnet will be assigned + identifier that the third subnet had before removal. As a result, the leases + stored in the lease database for subnet 3 are now associated with + subnet 4, something that may have unexpected consequences. It is planned + to implement the mechanism to preserve auto-generated subnet ids in a + future version of Kea. However, the only remedy for this issue + at present is to + manually specify a unique identifier for each subnet. The following configuration: @@ -343,8 +361,8 @@ to temporary add asterisk and retain the list of interface names. } will assign the arbitrary subnet identifier to the newly configured subnet. - This identifier will not change for this subnet until "id" parameter is - removed or set to 0. The value of 0 forces auto-generation of subnet + This identifier will not change for this subnet unless the "id" parameter is + removed or set to 0. The value of 0 forces auto-generation of the subnet identifier.
Server Identifier in DHCPv4 - The DHCPv4 protocol uses a "server identifier" for clients to be able + The DHCPv4 protocol uses a "server identifier" to allow clients to discriminate between several servers present on the same link: this value is an IPv4 address of the server. The server chooses the IPv4 address of the interface on which the message from the client (or relay) has been @@ -1537,7 +1563,7 @@ to temporary add asterisk and retain the list of interface names.
- How DHCPv4 server selects a subnet for the client + How the DHCPv4 Server Selects a Subnet for the Client The DHCPv4 server differentiates between the directly connected clients, clients trying to renew leases and clients sending their messages through @@ -1545,10 +1571,10 @@ to temporary add asterisk and retain the list of interface names. configuration of the interface on which the message has been received, and if the server configuration doesn't match any configured subnet the message is discarded. - Assuming that the server's interface is configured with the 192.0.2.3 - IPv4 address, the server will only process messages received through - this interface from the directly connected client, if there is a subnet - configured, to which this IPv4 address belongs, e.g. 192.0.2.0/24. + Assuming that the server's interface is configured with the + IPv4 address 192.0.2.3, the server will only process messages received through + this interface from a directly connected client if there is a subnet + configured to which this IPv4 address belongs, e.g. 192.0.2.0/24. The server will use this subnet to assign IPv4 address for the client. @@ -1575,25 +1601,25 @@ to temporary add asterisk and retain the list of interface names.
- Using specific relay agent for a subnet + Using a Specific Relay Agent for a Subnet The relay has to have an interface connected to the link on which the clients are being configured. Typically the relay has an IPv4 address configured on that interface that belongs to the subnet that the server will assign addresses from. In such typical case, the - server is able to use IPv4 address inserted by the relay (in GIADDR - field of the DHCPv4 packet) to select appropriate subnet. + server is able to use IPv4 address inserted by the relay (in the giaddr + field of the DHCPv4 packet) to select the appropriate subnet. - However, that is not always the case. In certain uncommon, but - valid deployments, the relay address may not match the subnet. This + However, that is not always the case. In certain uncommon - but + valid - deployments, the relay address may not match the subnet. This usually means that there is more than one subnet allocated for a given - link. Two most common examples where this is the case are long lasting + link. The two most common examples where this is the case are long lasting network renumbering (where both old and new address space is still being used) and a cable network. In a cable network both cable modems and the devices behind them are physically connected to the same link, yet they use distinct addressing. In such case, the DHCPv4 server needs - additional information (IPv4 address of the relay) to properly select + additional information (the IPv4 address of the relay) to properly select an appropriate subnet. @@ -1622,7 +1648,7 @@ to temporary add asterisk and retain the list of interface names.
- Segregating IPv4 clients in a cable network + Segregating IPv4 Clients in a Cable Network In certain cases, it is useful to mix relay address information, introduced in with client @@ -1636,7 +1662,7 @@ to temporary add asterisk and retain the list of interface names. with one CM MAC (a physical link that modems are connected to). We want the modems to get addresses from the 10.1.1.0/24 subnet, while everything connected behind modems should get addresses from another - subnet (192.0.2.0/24). The CMTS that acts as a relay an uses address + subnet (192.0.2.0/24). The CMTS that acts as a relay uses address 10.1.1.1. The following configuration can serve that configuration: "Dhcp4": { @@ -1668,8 +1694,7 @@ to temporary add asterisk and retain the list of interface names.
Supported Standards - The following standards and draft standards are currently - supported: + The following standards and draft standards are currently supported: RFC 2131: Supported messages are DISCOVER, OFFER, @@ -1715,7 +1740,7 @@ to temporary add asterisk and retain the list of interface names. - Host reservation (statis addresses) is not supported yet. + Host reservation (static addresses) is not supported yet. Full featured client classification is not supported yet.