From: Tomek Mrugalski Date: Thu, 13 Apr 2017 12:16:25 +0000 (+0200) Subject: [4540] Docs, example configs updated X-Git-Tag: trac5087_base^2~1 X-Git-Url: http://git.ipfire.org/gitweb.cgi?a=commitdiff_plain;h=bca8fd23316e956cf4f012386baf9bda68d2b754;p=thirdparty%2Fkea.git [4540] Docs, example configs updated --- diff --git a/doc/examples/kea4/multiple-options.json b/doc/examples/kea4/multiple-options.json index 940c448547..0741fcfafc 100644 --- a/doc/examples/kea4/multiple-options.json +++ b/doc/examples/kea4/multiple-options.json @@ -1,61 +1,107 @@ -# 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": [ { diff --git a/doc/examples/kea6/multiple-options.json b/doc/examples/kea6/multiple-options.json index b0d2cf1be3..ed341d35d3 100644 --- a/doc/examples/kea6/multiple-options.json +++ b/doc/examples/kea6/multiple-options.json @@ -1,55 +1,79 @@ -# 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": [ { diff --git a/doc/guide/dhcp4-srv.xml b/doc/guide/dhcp4-srv.xml index 6c74a2fada..10c96f0d3e 100644 --- a/doc/guide/dhcp4-srv.xml +++ b/doc/guide/dhcp4-srv.xml @@ -923,22 +923,38 @@ temporarily override a list of interface names and listen on all interfaces. ... ] } - + + 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: + +"Dhcp4": { + "option-data": [ + { + "name": "domain-name-servers", + "data": "192.0.2.1, 192.0.2.2" + }, + ... + ] +} + - The name parameter specifies the - option name. For a list of currently supported names, see - below. - The code 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 name parameter specifies the option name. For a + list of currently supported names, see below. The code + 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 . 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. @@ -1009,8 +1025,7 @@ temporarily override a list of interface names and listen on all interfaces. The currently supported standard DHCPv4 options are - listed in - and . + listed in . 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 default-tcp-ttl37uint8falsefalse tcp-keepalive-interval38uint32falsefalse tcp-keepalive-garbage39booleanfalsefalse - - - - - - - - - List of standard DHCPv4 options (continued) - - - - - - - - - Name - Code - Type - Array? - Returned if not requested? - - - - nis-domain40stringfalsefalsenis-servers41ipv4-addresstruefalsentp-servers42ipv4-addresstruefalse diff --git a/doc/guide/dhcp6-srv.xml b/doc/guide/dhcp6-srv.xml index 166c932e66..0a2b1db696 100644 --- a/doc/guide/dhcp6-srv.xml +++ b/doc/guide/dhcp6-srv.xml @@ -951,9 +951,26 @@ temporarily override a list of interface names and listen on all interfaces. - Most of the parameters in the "option-data" structure are optional and - can be omitted in some circumstances as discussed in the - . + Most of the parameters in the "option-data" structure are + optional and can be omitted in some circumstances as discussed + in the . 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: + +"Dhcp4": { + "option-data": [ + { + "name": "dns-servers", + "data": "2001:db8::cafe, 2001:db8::babe" + }, + ... + ] +} +