Commit bca8fd23 authored by Tomek Mrugalski's avatar Tomek Mrugalski 🛰

[4540] Docs, example configs updated

parent 814b007e
# This is an example configuration file for the DHCPv4 server in Kea.
# It demonstrates simple configuration of the options for a subnet.
// This is an example configuration file for the DHCPv4 server in Kea.
// It demonstrates simple configuration of the options for a subnet.
{ "Dhcp4":
{
# Kea is told to listen on ethX interface only.
// Kea is told to listen on ethX interface only.
"interfaces-config": {
"interfaces": [ "ethX" ]
},
# We need to specify the the database used to store leases. As of
# September 2016, four database backends are supported: MySQL,
# PostgreSQL, Cassandra, and the in-memory database, Memfile.
# We'll use memfile because it doesn't require any prior set up.
// We need to specify the the database used to store leases. As of
// September 2016, four database backends are supported: MySQL,
// PostgreSQL, Cassandra, and the in-memory database, Memfile.
// We'll use memfile because it doesn't require any prior set up.
"lease-database": {
"type": "memfile"
},
# Addresses will be assigned with a lifetime of 4000 seconds.
// Addresses will be assigned with a lifetime of 4000 seconds.
"valid-lifetime": 4000,
# Renew and rebind timers are commented out. This implies that options
# 58 and 59 will not be sent to the client. In this case it is up to
# the client to pick the timer values according to RFC2131. Uncomment the
# timers to send these options to the client.
# "renew-timer": 1000,
# "rebind-timer": 2000,
// Renew and rebind timers are commented out. This implies that options
// 58 and 59 will not be sent to the client. In this case it is up to
// the client to pick the timer values according to RFC2131. Uncomment the
// timers to send these options to the client.
// "renew-timer": 1000,
// "rebind-timer": 2000,
# Defining a subnet. There are 3 DHCP options returned to the
# clients connected to this subnet. The first two options are
# identified by the name. The third option is identified by the
# option code.
// Defining a subnet. There are 3 DHCP options returned to the
// clients connected to this subnet. The first two options are
// identified by the name. The third option is identified by the
// option code.
"subnet4": [
{
"pools": [ { "pool": "192.0.2.10 - 192.0.2.200" } ],
"subnet": "192.0.2.0/24",
"interface": "ethX",
"option-data": [
{
"name": "domain-name-servers",
"data": "192.0.2.1, 192.0.2.2"
},
{
"name": "routers",
"data": "192.0.2.1"
},
{
"code": 15,
"data": "example.org"
}
"interface": "ethX",
// This is how option values are defined for this particular subnet.
"option-data": [
// When specifying options, you typically need to specify
// one of (name or code) and data. The full option specification
// covers name, code, space, csv-format and data.
// space defaults to "dhcp4" which is usually correct, unless you
// use encapsulate options. csv-format defaults to "true", so
// this is also correct, unless you want to specify the whole
// option value as long hex string. For example, to specify
// domain-name-servers you could do this:
// {
// "name": "domain-name-servers",
// "code": 6,
// "csv-format": "true",
// "space": "dhcp4",
// "data": "192.0.2.1, 192.0.2.2"
// }
// but it's a lot of writing, so it's easier to do this instead:
{
"name": "domain-name-servers",
"data": "192.0.2.1, 192.0.2.2"
},
// Note the Kea provides some of the options on its own. In
// particular:
// - IP address lease time (option 51) is governed by valid-lifetime
// parameter, so you don't need to specify it as option.
// - Subnet mask (option 1) is calculated automatically from the
// subnet parameter specified for each "subnet4" entry.
// - renewal-timer (option 58) is calculated from renew-timer
// parameter
// - rebind timer (option 59) is calculated from rebind-timer
// parameter
// For each IPv4 subnet you most likely need to specify at least
// one router.
{
"name": "routers",
"data": "192.0.2.1"
},
// Typically people prefer to refer to options by their names, so they
// don't need to remember the code names. However, some people like
// to use numerical values. For example, option "domain-name" uses
// option code 15, so you can reference to it either by
// "name": "domain-name" or "code": 15.
{
"code": 15,
"data": "example.org"
},
// Options that take integer values can either be specified in
// dec or hex format. Hex format could be either plain (e.g. abcd)
// or prefixed with 0x (e.g. 0xabcd).
{
"name": "default-ip-ttl",
"data": "0xf0"
}
]
}
]
},
# The following configures logging. It assumes that messages with at least
# informational level (info, warn, error and fatal) should be logged to stdout.
// The following configures logging. It assumes that messages with at least
// informational level (info, warn, error and fatal) should be logged to stdout.
"Logging": {
"loggers": [
{
......
# This is an example configuration file for DHCPv6 server in Kea.
# It demonstrates simple configuration of the options for a subnet.
// This is an example configuration file for DHCPv6 server in Kea.
// It demonstrates simple configuration of the options for a subnet.
{ "Dhcp6":
{
# Kea is told to listen on ethX interface only.
// Kea is told to listen on ethX interface only.
"interfaces-config": {
"interfaces": [ "ethX" ]
},
# We need to specify the the database used to store leases. As of
# September 2016, four database backends are supported: MySQL,
# PostgreSQL, Cassandra, and the in-memory database, Memfile.
# We'll use memfile because it doesn't require any prior set up.
// We need to specify the the database used to store leases. As of
// September 2016, four database backends are supported: MySQL,
// PostgreSQL, Cassandra, and the in-memory database, Memfile.
// We'll use memfile because it doesn't require any prior set up.
"lease-database": {
"type": "memfile"
},
# Addresses will be assigned with preferred and valid lifetimes
# being 3000 and 4000, respectively. Client is told to start
# renewing after 1000 seconds. If the server does not respond
# after 2000 seconds since the lease was granted, client is supposed
# to start REBIND procedure (emergency renewal that allows switching
# to a different server).
// Addresses will be assigned with preferred and valid lifetimes
// being 3000 and 4000, respectively. Client is told to start
// renewing after 1000 seconds. If the server does not respond
// after 2000 seconds since the lease was granted, client is supposed
// to start REBIND procedure (emergency renewal that allows switching
// to a different server).
"preferred-lifetime": 3000,
"valid-lifetime": 4000,
"renew-timer": 1000,
"rebind-timer": 2000,
# Defining a subnet. There are 2 DHCP options returned to the
# clients connected to this subnet. The first option is identified
# by the name. The second option is identified by the code.
# There are two address pools defined within this subnet. Pool
# specific value for option 12 is defined for the pool:
# 2001:db8:1::1 - 2001:db8:1::100. Clients obtaining an address
# from this pool will be assigned option 12 with a value of
# 3001:cafe::21. Clients belonging to this subnet but obtaining
# addresses from the other pool, or the clients obtaining
# stateless configuration will be assigned subnet specific value
# of option 12, i.e. 2001:db8:1:0:ff00::1.
// Defining a subnet. There are 2 DHCP options returned to the
// clients connected to this subnet. The first option is identified
// by the name. The second option is identified by the code.
// There are two address pools defined within this subnet. Pool
// specific value for option 12 is defined for the pool:
// 2001:db8:1::1 - 2001:db8:1::100. Clients obtaining an address
// from this pool will be assigned option 12 with a value of
// 3001:cafe::21. Clients belonging to this subnet but obtaining
// addresses from the other pool, or the clients obtaining
// stateless configuration will be assigned subnet specific value
// of option 12, i.e. 2001:db8:1:0:ff00::1.
"subnet6": [
{
"option-data": [
{
"name": "dns-servers",
"data": "2001:db8:2::45, 2001:db8:2::100"
},
{
"code": 12,
"data": "2001:db8:1:0:ff00::1"
}
// This is how option values are defined for this particular subnet.
"option-data": [
// When specifying options, you typically need to specify
// one of (name or code) and data. The full option specification
// covers name, code, space, csv-format and data.
// space defaults to "dhcp6" which is usually correct, unless you
// use encapsulate options. csv-format defaults to "true", so
// this is also correct, unless you want to specify the whole
// option value as long hex string. For example, to specify
// domain-name-servers you could do this:
// {
// "name": "dns-servers",
// "code": 23,
// "csv-format": "true",
// "space": "dhcp6",
// "data": "2001:db8:2::45, 2001:db8:2::100"
// }
// but it's a lot of writing, so it's easier to do this instead:
{
"name": "dns-servers",
"data": "2001:db8:2::45, 2001:db8:2::100"
},
// Typically people prefer to refer to options by their names, so they
// don't need to remember the code names. However, some people like
// to use numerical values. For example, DHCPv6 can optionally use
// server unicast communication, if extra option is present. Option
// "unicast" uses option code 12, so you can reference to it either
// by "name": "unicast" or "code": 12.
{
"code": 12,
"data": "2001:db8:1:0:ff00::1"
}
],
"pools": [
{
......@@ -62,7 +86,7 @@
]
},
{
"pool": "2001:db8:1::500 - 2001:db8:2::1000"
"pool": "2001:db8:1::500 - 2001:db8:1::1000"
}
],
"subnet": "2001:db8:1::/64",
......@@ -71,8 +95,8 @@
]
},
# The following configures logging. It assumes that messages with at least
# informational level (info, warn, error and fatal) should be logged to stdout.
// The following configures logging. It assumes that messages with at least
// informational level (info, warn, error and fatal) should be logged to stdout.
"Logging": {
"loggers": [
{
......
......@@ -923,22 +923,38 @@ temporarily override a list of interface names and listen on all interfaces.
...
]
}
</screen>
</screen>
Note that only one of name or code is required, you don't need to
specify both. Space has a default value of "dhcp4", so you can skip this
as well if you define a regular (not encapsulated) DHCPv4 option.
Finally, csv-format defaults to true, so it too can be skipped, unless
you want to specify the option value as hexstring. Therefore the
above example can be simplified to:
<screen>
"Dhcp4": {
"option-data": [
{
<userinput>"name": "domain-name-servers",
"data": "192.0.2.1, 192.0.2.2"</userinput>
},
...
]
} </screen>
</para>
<para>
The <command>name</command> parameter specifies the
option name. For a list of currently supported names, see
<xref linkend="dhcp4-std-options-list"/> below.
The <command>code</command> parameter specifies the option code, which must match one of the
values from that list. The next line specifies the option space, which must always
be set to "dhcp4" as these are standard DHCPv4 options. For
other option spaces, including custom option spaces, see <xref
The <command>name</command> parameter specifies the option name. For a
list of currently supported names, see <xref
linkend="dhcp4-std-options-list"/> below. The <command>code</command>
parameter specifies the option code, which must match one of the values
from that list. The next line specifies the option space, which must
always be set to "dhcp4" as these are standard DHCPv4 options. For other
option spaces, including custom option spaces, see <xref
linkend="dhcp4-option-spaces"/>. The next line specifies the format in
which the data will be entered: use of CSV (comma
separated values) is recommended. The sixth line gives the actual value to
be sent to clients. Data is specified as normal text, with
values separated by commas if more than one value is
allowed.
which the data will be entered: use of CSV (comma separated values) is
recommended. The sixth line gives the actual value to be sent to
clients. Data is specified as normal text, with values separated by commas
if more than one value is allowed.
</para>
<para>
......@@ -1009,8 +1025,7 @@ temporarily override a list of interface names and listen on all interfaces.
<para>
The currently supported standard DHCPv4 options are
listed in <xref linkend="dhcp4-std-options-list"/>
and <xref linkend="dhcp4-std-options-list-part2"/>.
listed in <xref linkend="dhcp4-std-options-list"/>.
The "Name" and "Code"
are the values that should be used as a name in the option-data
structures. "Type" designates the format of the data: the meanings of
......@@ -1101,32 +1116,6 @@ This rather belong to the DDNS configuration
<row><entry>default-tcp-ttl</entry><entry>37</entry><entry>uint8</entry><entry>false</entry><entry>false</entry></row>
<row><entry>tcp-keepalive-interval</entry><entry>38</entry><entry>uint32</entry><entry>false</entry><entry>false</entry></row>
<row><entry>tcp-keepalive-garbage</entry><entry>39</entry><entry>boolean</entry><entry>false</entry><entry>false</entry></row>
</tbody>
</tgroup>
</table>
</para>
<para>
<table frame="all" id="dhcp4-std-options-list-part2">
<title>List of standard DHCPv4 options (continued)</title>
<tgroup cols='5'>
<colspec colname='name'/>
<colspec colname='code' align='center'/>
<colspec colname='type' align='center'/>
<colspec colname='array' align='center'/>
<colspec colname='always-returned' align='center'/>
<thead>
<row>
<entry>Name</entry>
<entry>Code</entry>
<entry>Type</entry>
<entry>Array?</entry>
<entry>Returned if not requested?</entry>
</row>
</thead>
<tbody>
<row><entry>nis-domain</entry><entry>40</entry><entry>string</entry><entry>false</entry><entry>false</entry></row>
<row><entry>nis-servers</entry><entry>41</entry><entry>ipv4-address</entry><entry>true</entry><entry>false</entry></row>
<row><entry>ntp-servers</entry><entry>42</entry><entry>ipv4-address</entry><entry>true</entry><entry>false</entry></row>
......
......@@ -951,9 +951,26 @@ temporarily override a list of interface names and listen on all interfaces.
</para>
<para>
Most of the parameters in the "option-data" structure are optional and
can be omitted in some circumstances as discussed in the
<xref linkend="dhcp6-option-data-defaults"/>.
Most of the parameters in the "option-data" structure are
optional and can be omitted in some circumstances as discussed
in the <xref linkend="dhcp6-option-data-defaults"/>. Only one
of name or code is required, so you don't need to specify
both. Space has a default value of "dhcp6", so you can skip
this as well if you define a regular (not encapsulated) DHCPv6
option. Finally, csv-format defaults to true, so it too can
be skipped, unless you want to specify the option value as
hexstring. Therefore the above example can be simplified to:
<screen>
"Dhcp4": {
"option-data": [
{
<userinput>"name": "dns-servers",
"data": "2001:db8::cafe, 2001:db8::babe"</userinput>
},
...
]
} </screen>
</para>
......
Markdown is supported
0% or .
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment