diff options
Diffstat (limited to '')
26 files changed, 7539 insertions, 0 deletions
diff --git a/doc/examples/kea4/advanced.json b/doc/examples/kea4/advanced.json new file mode 100644 index 0000000..16a9498 --- /dev/null +++ b/doc/examples/kea4/advanced.json @@ -0,0 +1,208 @@ +// This is an example configuration file for DHCPv4 server in Kea. +// It covers some of the more advanced features. This file may not be coherent +// as its main purpose is to demonstrate the features. They don't necessarily +// have to make sense used together. + +// The new parser supports 3 comment styles: + +// This is C++ style. + +# This is a bash style. + +/* This is a C style comment. */ + +/* C style comment + can span + multiple lines */ + +{ "Dhcp4": + +{ + // Kea is told to listen on eth0 interface only. + "interfaces-config": { + "interfaces": [ "eth0" ], + + // This specifies what type of socket Kea uses. Currently supported + // are 'raw' (which is the default) and 'udp'. Raw has the benefit + // of receiving all traffic every time and a downside of bypassing + // all firewall rules and having marginally bigger performance impact. + // 'udp' is generally better if you have only relayed traffic. Kea + // than opens up normal UDP socket and the kernel does all the + // Ethernet/IP stack processing. + "dhcp-socket-type": "udp", + + // Typically the DHCP server will send its response back on the same + // interface the query came in. This is the default ("same-as-inbound"). + // However, sometimes it is useful to have the ability to send the + // packet as plain UDP packet and let the kernel and the routing tables + // determine the right interface ("use-routing"). This option only works + // for "dhcp-socket-type" set to "udp" and is ignored otherwise. + "outbound-interface": "use-routing", + + // This makes interfaces to be re-detected at each (re-)configuration. + // By default it is true. + "re-detect": true + }, + + "sanity-checks": { + // This parameter determines what to do when a new lease appears in the + // system (i.e. either is read from disk during memfile startup or is + // added via lease commands). There are five modes supported: + // none - do nothing, accept them as is + // warn - if subnet-id problems are detected, print a warning, but + // otherwise load the lease as is. This is the default value. + // fix - attempt to fix the lease by finding appropriate subnet-id value. + // if there is no suitable subnet, the lease is loaded as is. + // fix-del - attempt to fix the lease by finding appropriate subnet-id + // value. If there is no suitable subnet, the lease is deleted. + // del - delete leases that have incorrect subnet-id values. + "lease-checks": "fix-del" + }, + + // Option 43 last resort definition can make well-formed messages + // to be rejected because they use not compatible "raw" value, + // and different vendors may define different sub-options. + // The option definition should be applied to avoid these problems, + // for instance by defining at the global scope the option as binary. + // In client-classes the option may be redefined as carrying vendor + // dependent sub-options. + "option-def": [ { + "name": "vendor-encapsulated-options", + "code": 43, + "type": "binary" + } ], + + // We need to specify the database used to store leases. As of + // June 2022, three database backends are supported: MySQL, + // PostgreSQL and the in-memory database, Memfile. + // We'll use memfile because it doesn't require any prior set up. + // For memfile, it's important to always specify lfc-interval, so + // the lease file would not grow without bounds and be sanitized + // once per hour. + "lease-database": { + "type": "memfile", + "lfc-interval": 3600 + }, + + // This defines a control socket. If defined, Kea will open a UNIX socket + // and will listen for incoming commands. See section 15 of the Kea User's + // Guide for list of supported commands. + "control-socket": { + "socket-type": "unix", + "socket-name": "/tmp/kea4-ctrl-socket" + }, + + // Addresses will be assigned with a lifetime of 4000 seconds. + // The client is told to start renewing after 1000 seconds. If the server + // does not respond within 2000 seconds of the lease being granted, client + // is supposed to start REBIND procedure (emergency renewal that allows + // switching to a different server). + "valid-lifetime": 4000, + "renew-timer": 1000, + "rebind-timer": 2000, + + // RFC6842 says that the server is supposed to echo back client-id option. + // However, some older clients do not support this and are getting confused + // when they get their own client-id. Kea can disable RFC6842 support. + "echo-client-id": false, + + // Some clients don't use stable client identifier, but rather + // generate them during each boot. This may cause a client that + // reboots frequently to get multiple leases, which may not be + // desirable. As such, sometimes admins prefer to tell their DHCPv4 + // server to ignore client-id value altogether and rely exclusively + // on MAC address. This is a parameter that is defined globally, but + // can be overridden on a subnet level. + "match-client-id": true, + + // By default, Kea ignores requests by clients for unknown IP addresses, + // because other non-cooperating DHCP servers could reside on the same + // network (RFC 2131). This parameter is defined globally, but can be + // overridden on a subnet level + "authoritative": false, + + // The following list defines subnets. Each subnet consists of at + // least subnet and pool entries. One extra feature that requires + // some explanation is user-context. This is a structure that you can + // define in subnets, pools and others. It is parsed by Kea, but not + // used directly. It is intended to keep anything you may want to + // put there - comments, extra designations, floor or department + // names etc. These structures will be made available to Kea hooks. + // A comment entry is translated into a user-context with a + // "comment" property so you can include comments inside the + // configuration itself. + "subnet4": [ + { + "pools": [ { + "pool": "192.0.2.1 - 192.0.2.200", + "user-context": { "info": "what a large pool" } + } ], + "id": 1, + "subnet": "192.0.2.0/24", + "user-context": { + "comment": "Our first subnet!" + } + // Equivalent using smart parser + // "comment": "Our first subnet!" + }, + { + // This particular subnet has match-client-id value changed. + // This causes Kea to ignore client-id values in this subnet + // and rely exclusively on MAC addresses. + "pools": [ { "pool": "192.0.3.100 - 192.0.3.200" } ], + "id": 2, + "subnet": "192.0.3.0/24", + "match-client-id": false + }, + { + "pools": [ { "pool": "192.0.4.1 - 192.0.4.254" } ], + "id": 3, + "subnet": "192.0.4.0/24", + + // Sometimes the relay may use an IPv4 address that does + // not match the subnet. This is discouraged, but there are + // valid cases when it makes sense. One case is when there + // is a shared subnet. + "relay": { + "ip-address": "192.168.1.1" + } + }, + { + // This particular subnet has the authoritative value changed. + // This causes Kea to reply to requests for unknown IP addresses + // with a DHCPNAK message. + "pools": [ { "pool": "192.0.5.100 - 192.0.5.200" } ], + "id": 4, + "subnet": "192.0.5.0/24", + "authoritative": true + } + ], + + // The following configures logging. It assumes that messages with + // at least informational level (info, warn, error and fatal) should + // be logged to stdout. + "loggers": [ + { + "name": "kea-dhcp4", + "output-options": [ + { + "output": "stdout", + // Several additional parameters are possible in addition + // to the typical output. Flush determines whether logger + // flushes output to a file. Maxsize determines maximum + // filesize before the file is rotated. maxver + // specifies the maximum number of rotated files being + // kept. + "flush": true, + "maxsize": 204800, + "maxver": 4, + // We use pattern to specify custom log message layout + "pattern": "%d{%y.%m.%d %H:%M:%S.%q} %-5p [%c/%i] %m\n" + } + ], + "severity": "INFO" + } + ] + } + +} diff --git a/doc/examples/kea4/all-keys-netconf.json b/doc/examples/kea4/all-keys-netconf.json new file mode 100644 index 0000000..c5cf903 --- /dev/null +++ b/doc/examples/kea4/all-keys-netconf.json @@ -0,0 +1,1245 @@ +// WARNING: This example configuration is not meant for production use. +// The Kea DHCPv4 server will refuse this configuration because it contains +// mutually exclusive configuration parameters. +// +// The primary purpose of the example file is to provide a comprehensive +// list of parameters supported by the Kea DHCPv4 server, along with a brief +// description of each parameter. +// +// This stable version is used for YANG, as we do not want to update code +// and models each time a keyword is added to the syntax. +{ + // Kea DHCPv4 server configuration begins here. + "Dhcp4": { + // Global flag selecting an IP address allocation strategy for all + // subnets. Use "random" for a random allocation strategy. + "allocator": "iterative", + + // Global authoritative flag to handle requests by clients for + // unknown IP addresses (ignore if disabled, NAK if enabled). + "authoritative": false, + + // Global bootfile name to be set in the 'file' field. + "boot-file-name": "/dev/null", + + // Ordered list of client classes used by the DHCPv4 server. + "client-classes": [ + { + // Class-specific bootfile name to be set in the 'file' field. + "boot-file-name": "/tmp/bootfile.efi", + + // Class name. + "name": "phones_server1", + + // Class-specific next server address to use in bootstrap, which + // is set in 'siaddr' field. + "next-server": "10.2.3.4", + + // Class-specific DHCPv4 options list. + "option-data": [], + + // Class-specific DHCPv4 option definitions, i.e. custom formats + // specified for non-standard options. + "option-def": [], + + // Class-specific optional server hostname, which is set in + // 'sname' field. + "server-hostname": "", + + // Class selection expression. The DHCP packet is assigned to this + // class when the given expression evaluates to true. + "test": "member('HA_server1')", + + // Class valid lifetime. + "valid-lifetime": 6000, + + // Class min valid lifetime. + "min-valid-lifetime": 4000, + + // Class max valid lifetime. + "max-valid-lifetime": 8000, + + // If greater than zero, it is the lifetime of leases temporarily allocated + // on DISCOVER. When zero (the default), leases are not allocated on DISCOVER. + "offer-lifetime" : 65 + }, + { + // Default value of the class-specific bootfile name. An empty name + // means that the bootfile name is unspecified. + "boot-file-name": "", + + // Second class name. + "name": "phones_server2", + + // Default value of the class-specific next server address. The + // zero IPv4 address means that it is unspecified. + "next-server": "0.0.0.0", + + // Class-specific DHCPv4 options list. + "option-data": [], + + // Class-specific DHCPv4 option definitions, i.e. custom formats + // specified for non-standard options. + "option-def": [], + + // Class-specific optional server hostname, which is set in + // 'sname' field. + "server-hostname": "", + + // Class selection expression. The DHCP packet is assigned to this + // class when the given expression evaluates to true. + "test": "member('HA_server2')" + }, + { + // Third class name. + "name": "late", + + // Boolean flag indicating whether the class expression is only evaluated + // when the class is required, e.g. the selected address pool configuration + // includes this class name in its "require-client-classes" list. The + // default value false means that the class test expression must + // always be evaluated. + "only-if-required": true, + + // Class selection expression. + "test": "member('ALL')" + }, + { + // Fourth class name. + "name": "my-template-class", + + // Template class flag that holds the expression used to generate the names for all + // the spawned subclasses. In this case, the classes are named after the client ID. + "template-test": "substring(option[61].hex, 0, all)" + } + ], + + // Parameters for triggering behaviors compatible with broken or + // non-compliant clients, relays, or other agents + "compatibility": { + // Ignore DHCP Server Identifier option if set to true. + // Enabling this will cause Kea to accept any query, even + // if the address in the option belongs to another server, + // instead of dropping it. This config option defaults to + // false, as enabling it breaks RFC compliance. + "ignore-dhcp-server-identifier": false, + + // Ignore Relay Agent Information Link Selection suboption if set + // to true. Enabling this will cause Kea to use normal subnet + // selection logic instead of attempting to use the subnet + // specified in the suboption. This config option defaults to + // false, as enabling it breaks RFC compliance. + "ignore-rai-link-selection": false, + + // Parse options more leniently where fields can be deduced + // deterministically, even if against RFC or common practice. + "lenient-option-parsing": true, + + // Boolean flag indicating whether .0 and .255 addresses + // must be considered as never free in subnets with a prefix length + // of 24 or less. The default is false, as these addresses are not + // special; only the first and the last addresses are. + "exclude-first-last-24": false + }, + + // Command control socket configuration parameters for the Kea DHCPv4 server. + "control-socket": { + // Location of the UNIX domain socket file the DHCPv4 server uses + // to receive control commands from the Kea Control Agent or the + // local server administrator. + "socket-name": "/tmp/kea4-ctrl-socket", + + // Control socket type used by the Kea DHCPv4 server. The 'unix' + // socket is currently the only supported type. + "socket-type": "unix" + }, + + // Specifies a prefix to be prepended to the generated Client FQDN. + // It may be specified at the global, shared-network, and subnet levels. + "ddns-generated-prefix": "myhost", + + // Boolean flag indicating whether the server should ignore DHCP client + // wishes to update DNS on its own. With that flag set to true, + // the server will send DNS updates for both forward and + // reverse DNS data. The default value is false, which indicates + // that the server will delegate a DNS update to the client when + // requested. It may be specified at the global, shared-network, + // and subnet levels. + "ddns-override-client-update": false, + + // Boolean flag indicating whether the server should override the DHCP + // client's wish to not update the DNS. With this parameter + // set to true, the server will send a DNS update even when + // the client requested no update. It may be specified at the + // global, shared-network, and subnet levels. + "ddns-override-no-update": false, + + // Suffix appended to the partial name sent to the DNS. The + // default value is an empty string, which indicates that no + // suffix is appended. It may be specified at the global, + // shared-network, and subnet levels. + "ddns-qualifying-suffix": "", + + // Enumeration specifying whether the server should honor + // the hostname or Client FQDN sent by the client or replace + // this name. The acceptable values are: "never" (use the + // name the client sent), "always" (replace the name the + // client sent), "when-present" (replace the name the client + // sent, but do not generate one when the client didn't send + // the name), "when-not-present" (generate the name when + // client didn't send one, otherwise leave the name the + // client sent). The default value is "never". It may be + // specified at the global, shared-network, and subnet levels. + "ddns-replace-client-name": "never", + + // Boolean flag which enables or disables DDNS updating. It + // defaults to true. It may be specified at the global, shared- + // network, and subnet levels. It works in conjunction with + // dhcp-ddns:enable-updates, which must be true to enable connectivity + // to kea-dhcp-ddns. + "ddns-send-updates": true, + + // Boolean flag, which when true instructs the server to always + // update DNS when leases are renewed, even if the DNS information + // has not changed. The server's default behavior (i.e. flag is false) + // is to only update DNS if the DNS information has changed. It + // may be specified at the global, shared-network, and subnet levels. + "ddns-update-on-renew": true, + + // Boolean flag which is passed to kea-dhcp-ddns with each DDNS + // update request, to indicate whether DNS update conflict + // resolution as described in RFC 4703 should be employed for the + // given update request. The default value for this flag is true. + // It may be specified at the global, shared-network, and subnet levels. + "ddns-use-conflict-resolution": true, + + // When greater than 0.0, it is the percent of the lease's lifetime + // to use for the DNS TTL. + "ddns-ttl-percent": 0.75, + + // Time in seconds specifying how long a declined lease should be + // excluded from DHCP assignments. The default value is 86400 (24 hours). + "decline-probation-period": 86400, + + // Name Change Request forwarding configuration for the Kea DHCPv4 server. + // NCRs are sent to the Kea D2 module to update DNS upon allocation of + // DHCP leases. + "dhcp-ddns": { + // Boolean flag indicating whether Kea DHCPv4 server should connect to + // kea-dhcp-ddns. This must be true for NCRs to be created and + // sent to kea-dhcp-ddns. By default, NCRs are not generated. + "enable-updates": false, + + // Specifies maximum number of NCRs to queue waiting to be sent + // to the Kea D2 server. + "max-queue-size": 1024, + + // Packet format to use when sending NCRs to the Kea D2 server. + // Currently, only JSON format is supported. + "ncr-format": "JSON", + + // Socket protocol to use when sending NCRs to D2. Currently, + // only UDP is supported. + "ncr-protocol": "UDP", + + // IP address that the Kea DHCPv4 server should use to send + // NCRs to D2. The default value of zero indicates that Kea + // should pick a suitable address. + "sender-ip": "0.0.0.0", + + // Port number that the Kea DHCPv4 server should use to send + // NCRs to D2. The default value of zero indicates that Kea + // should pick a suitable port. + "sender-port": 0, + + // IP address on which D2 listens for NCRs. + "server-ip": "127.0.0.1", + + // Port number on which D2 listens for NCRs. + "server-port": 53001, + + // The following parameters are DEPRECATED. They have been + // replaced with parameters that may be set at the global, + // shared-network, and subnet4 scopes. They are listed here + // as configuration parsing still accepts them. Eventually + // support for them will be removed. + "generated-prefix": "myhost", + "hostname-char-replacement": "x", + "hostname-char-set": "[^A-Za-z0-9.-]", + "override-client-update": false, + "override-no-update": false, + "qualifying-suffix": "", + "replace-client-name": "never" + }, + + // Specifies the first of the two consecutive ports of the UDP + // sockets used for communication between DHCPv6 and DHCPv4 + // servers. See RFC 7341. + "dhcp4o6-port": 6767, + + // Boolean flag indicating whether the Kea DHCPv4 server + // should send back the Client Identifier option in its responses. + // The default value is true, which indicates that the option + // must be sent back if the client included it. The false + // value instructs the server to not send this option for + // backward compatibility with older DHCP specifications, which + // stated that Client Identifier must not be sent back. + "echo-client-id": true, + + // Collection of Kea DHCPv4 server parameters configuring how + // the server should process expired DHCP leases. + "expired-leases-processing": { + // Specifies the number of seconds since the last removal of + // the expired leases, when the next removal should occur. + // If both "flush-reclaimed-timer-wait-time" and + // "hold-reclaimed-time" are not 0, when the client sends a release + // message the lease is expired instead of being deleted from + // lease storage. + "flush-reclaimed-timer-wait-time": 25, + + // Specifies the length of time in seconds to keep expired + // leases in the lease database (lease affinity). + // If both "flush-reclaimed-timer-wait-time" and + // "hold-reclaimed-time" are not 0, when the client sends a release + // message the lease is expired instead of being deleted from + // lease storage. + "hold-reclaimed-time": 3600, + + // Specifies the maximum number of expired leases that can be + // processed in a single attempt to clean up expired leases + // from the lease database. If there are more + // expired leases, they will be processed during the next + // cleanup attempt. + "max-reclaim-leases": 100, + + // Specifies the maximum time in milliseconds that a single attempt + // to clean up expired leases from the lease database may take. + "max-reclaim-time": 250, + + // Specifies the length of time in seconds since the last attempt + // to process expired leases before initiating the next attempt. + "reclaim-timer-wait-time": 10, + + // Specifies the maximum number of expired lease-processing cycles + // which didn't result in full cleanup of exired leases from the + // lease database, after which a warning message is issued. + "unwarned-reclaim-cycles": 5 + }, + + // List of hook libraries and their specific configuration parameters + // to be loaded by Kea DHCPv4 server. + "hooks-libraries": [ + { + // Location of the hook library to be loaded. + "library": "/opt/lib/kea/hooks/libdhcp_lease_cmds.so", + + // Hook library-specific configuration parameters. + "parameters": { } + } + ], + + // List of access credentials to external sources of IPv4 reservations, + "hosts-databases": [ + { + // Name of the database to connect to. + "name": "keatest", + + // Host on which the database resides. + "host": "localhost", + + // Database password. + "password": "keatest", + + // Port on which the database is available. + "port": 3306, + + // Type of database, e.g. "mysql", "postgresql". + "type": "mysql", + + // Username to be used to access the database. + "user": "keatest", + + // Read-only mode. + "readonly": false, + + // The next entries are for OpenSSL support in MySQL. + + // Trust anchor aka certificate authority file or directory. + "trust-anchor": "my-ca", + + // Client certificate file name. + "cert-file": "my-cert", + + // Private key file name. + "key-file": "my-key", + + // Cipher list (see the OpenSSL ciphers command manual). + "cipher-list": "AES", + + // Connection reconnect wait time. + // This parameter governs how long Kea waits before attempting + // to reconnect. Expressed in milliseconds. The default is 0 + // (disabled) for MySQL and PostgreSQL. + "reconnect-wait-time": 3000, + + // Connection maximum reconnect tries. + "max-reconnect-tries": 3, + + // Action to take when connection recovery fails. + // Supported values: stop-retry-exit, serve-retry-exit, + // serve-retry-continue + "on-fail": "stop-retry-exit", + + // Connection connect timeout in seconds. + "connect-timeout": 100, + + // Timeout of database read operations in seconds. + "read-timeout": 120, + + // Timeout of database write operations in seconds. + "write-timeout": 180 + }, + { + // Name of the database to connect to. + "name": "keatest", + + // Host on which the database resides. + "host": "localhost", + + // Database password. + "password": "keatest", + + // Port on which the database is available. + "port": 5432, + + // Type of database, e.g. "mysql", "postgresql". + "type": "postgresql", + + // Username to be used to access the database. + "user": "keatest", + + // TCP user timeout while communicating with the database. + // It is specified in seconds. + "tcp-user-timeout": 100 + } + ], + + // List of host reservation identifier types to be used by the + // Kea DHCPv4 server to fetch static reservations for + // DHCP clients. All identifiers are used by default, which + // means that the server will issue multiple queries to the + // database to find if there is a reservation for a particular + // client. If a particular deployment uses only a subset, e.g. + // one identifier type, this identifier should be only listed + // here to prevent unnecessary queries to the database. + "host-reservation-identifiers": [ + "hw-address", + "duid", + "circuit-id", + "client-id", + "flex-id" + ], + + // Specifies configuration of interfaces on which the Kea DHCPv4 + // server is listening to the DHCP queries. + "interfaces-config": { + // Specifies whether the server should use "udp" sockets or + // "raw" sockets to listen to DHCP traffic. The "raw" + // sockets are useful when direct DHCP traffic is being + // received. + "dhcp-socket-type": "udp", + + // Specifies a list of interfaces on which the Kea DHCPv4 + // server should listen to DHCP requests. + "interfaces": [ + "eth0" + ], + + // Enumeration which indicates what interface should be used + // to send DHCP responses to the client. The default value is + // "same-as-inbound", which indicates that the response should + // be sent via the interface on which the client's query + // was received. The "use-routing" value indicates that the + // Kea server should use the kernel's routing table to find a + // suitable interface. + "outbound-interface": "same-as-inbound", + + // Boolean flag indicating whether the available interfaces should + // be re-detected upon server reconfiguration. The default value + // is true, which means that the interfaces are always + // re-detected. + "re-detect": true, + + // Kea tries to bind the service sockets during initialization, but it may + // fail due to a port being already opened or a misconfiguration. Kea can + // suppress these errors and only log them. This flag prevents starting + // the DHCP server without binding all sockets. If unspecified, it + // defaults to false. + "service-sockets-require-all": true, + + // Kea tries to bind the service sockets during initialization. This + // option specifies how many times binding to interface will be retried. + // The default value is 0, which means that the operation will not be + // repeated. + "service-sockets-max-retries": 5, + + // The time interval in milliseconds to wait before the next attempt to + // retry opening a service socket. + "service-sockets-retry-wait-time": 5000 + }, + + // Boolean parameter which controls whether an early global host + // reservations lookup should be performed. This lookup takes place + // before subnet selection and when a global reservation is found + // with some client classes, it triggers a second phase classification. + // It can also be used to drop queries using host reservations as a + // decision table indexed by reservation identifiers. + "early-global-reservations-lookup": true, + + // Boolean parameter which controls the DHCP server's behavior with respect + // to creating host reservations for the same IP address. By default + // this flag is set to true, in which case the server prevents creation + // of multiple host reservations for the same IP address. When this + // parameter is set to false, the server allows for creating multiple + // reservations for the same IP address within a subnet. This setting + // is useful in deployments in which a given host may be communicating + // with a DHCP server over multiple interfaces and, depending on the + // chosen interface, a different MAC address (or other identifier) will + // be used to identify the host. Note that some host backends do not + // support the mode in which multiple reservations for the same IP + // address are used. If these backends are in use and this setting + // is attempted, a configuration error will occur. The MySQL and + // PostgreSQL backends do support this mode. + "ip-reservations-unique": true, + + // Boolean parameter which controls whether host reservations lookup + // should be performed before lease lookup. This parameter has effect + // only when multi-threading is disabled. When multi-threading is + // enabled, host reservations lookup is always performed first to avoid + // lease-lookup resource locking. + "reservations-lookup-first": true, + + // Specifies credentials to access lease database. + "lease-database": { + // memfile backend-specific parameter specifying the interval + // in seconds at which the lease file should be cleaned up (outdated + // lease entries are removed to prevent the lease file from growing + // infinitely). + "lfc-interval": 3600, + + // Maximum number of lease-file read errors allowed before + // loading the file is abandoned. Defaults to 0 (no limit). + "max-row-errors": 100, + + // Name of the lease file. In the case of a database it specifies the + // database name. + "name": "/tmp/kea-dhcp4.csv", + + // memfile-specific parameter indicating whether leases should + // be saved on persistent storage (disk) or not. The true value + // is the default and it indicates that leases are stored in + // persistent storage. This setting must be used in production. + // The false value should only be used for testing purposes + // because non-stored leases will be lost upon Kea server restart. + "persist": true, + + // Lease database backend type, i.e. "memfile", "mysql" or + // "postgresql". + "type": "memfile" + }, + + // Boolean value indicating whether the Kea DHCPv4 server should use the client + // identifier value sent by the client or ignore it. The default value + // is true, which indicates that the server should use the client identifier + // and that it takes precedence over the client's MAC address. In deployments + // where MAC address should take precedence, this value can be set to + // false, in which case the clients will be identified by MAC address. + // This is specifically useful when clients don't generate unique + // identifiers or these identifiers are not stable, etc. + "match-client-id": false, + + // Global value of the next server address set in 'siaddr' field. + // The global value may be overridden in lower-level configuration + // scopes. + "next-server": "192.0.2.123", + + // Global value which limits the number of client packets (e.g. + // DHCPREQUESTs) that may be parked while waiting for hook library + // work to complete, prior to a response (e.g. DHCPACK) being sent + // back to the client. A typical example is when kea-dhcp4 parks a + // DHCPREQUEST while it sends the lease update(s) to its HA peer(s). + // The packet is unparked once the update(s) have been acknowledged. + // This value limits the number of packets that can be held pending + // the updates. In times of heavy client traffic, this value can keep + // kea-dhcp4 from building an insurmountable backlog of updates. + "parked-packet-limit": 128, + + // List of global DHCP options that the Kea DHCPv4 server assigns to + // clients. + "option-data": [ + { + // Boolean flag indicating whether the given option is always + // sent in response or only when requested. The default + // value of false indicates that it is only sent when + // requested. + "always-send": false, + + // Option code. It is not required if the option name is + // provided. + "code": 6, + + // Boolean value indicating whether the option data specified + // in the "data" field is specified as a string of hexadecimal + // digits or in human-readable CSV format. + "csv-format": true, + + // Option data to be stored in the option payload. + "data": "192.0.3.1, 192.0.3.2", + + // Option name. It is not required if the option code is + // provided. + "name": "domain-name-servers", + + // Boolean flag indicating whether the given option is never + // sent in response. The default value of false indicates + // that it is sent when it should be. When true, the option + // is not sent despite any other setting, i.e. it is + // a final flag. + "never-send": false, + + // Option space. The default is the "dhcp4" option space which + // groups top-level DHCPv4 options. + "space": "dhcp4" + } + ], + + // List of global option definitions, i.e. option formats, that the + // Kea DHCPv4 server is using. + "option-def": [ + { + // Boolean flag indicating whether the option definition comprises + // an array of values of some type, e.g. an array of IPv4 addresses. + // The default value of false means that the option does not + // comprise an array of values. + "array": false, + + // Option code. + "code": 6, + + // Holds a name of the option space encapsulated by this option. + // All options that belong to this option space will be sent + // as sub-options of this option. An empty string means that this + // option doesn't encapsulate any option. + "encapsulate": "", + + // Option name. + "name": "my-option", + + // Specifies the types of fields within the option if the option + // is said to be a "record" (see "type"). In this particular example + // this option comprises two fields, 1 byte and 2 bytes long. + "record-types": "uint8, uint16", + + // Name of the option space to which this option belongs. + "space": "my-space", + + // Option type. All possible types are listed in the Kea + // Administrator Reference Manual. + "type": "record" + } + ], + + // Global value for the rebind timer, i.e. the time after which the + // DHCP client enters the rebind state if it fails to renew the lease. + "rebind-timer": 40, + + // Global value for the renew timer, i.e. the time after which the + // DHCP client renews the lease. + "renew-timer": 30, + + // Global value to store extended information (e.g. relay agent + // information) with each lease. + "store-extended-info": true, + + // Statistics keep some samples per observation point. + // There are two default values: maximum count and maximum age. + // Setting the maximum count to zero disables it. + "statistic-default-sample-count": 0, + + // When the maximum count is 0 the maximum age (in seconds) applies. + "statistic-default-sample-age": 60, + + // Multi-threading parameters. + "multi-threading": { + // By default, Kea processes packets on multiple threads if the hardware permits. + "enable-multi-threading": true, + + // When multi-threading is enabled, Kea will process packets on a + // number of multiple threads configurable through this option. The + // value must be a positive integer (0 means auto-detect). + "thread-pool-size": 0, + + // When multi-threading is enabled, Kea will read packets from the + // interface and append a working item to the thread pool. This + // option configures the maximum number of items that can be queued. + // The value must be a positive integer (0 means unlimited). + "packet-queue-size": 0 + }, + + // Governs how the Kea DHCPv4 server should deal with invalid + // data received from the client. + "sanity-checks": { + // Specifies how the Kea DHCPv4 server should behave when invalid + // data is read for a lease from the lease file. The following + // values are supported: "none" (don't attempt to correct the + // lease information), "warn" (print a warning for subnet-id + // related inconsistencies), "fix" (correct the subnet id by + // trying to find the suitable subnet), "fix-del" (similar + // to "fix" but delete the lease if no suitable subnet found), + // "del" (delete the lease if the lease has invalid subnet + // identifier value). + "lease-checks": "warn", + + // Specifies how Kea DHCPv4 server should behave when invalid + // extended info is read for a lease from the lease file, or + // whether to upgrade from the old format. The following values + // are supported: "none" (don't attempt to correct or upgrade + // the extended info), "fix" (fix common inconsistencies and + // upgrade from the old format; this is the default), "strict" + // (fix inconsistencies with an impact on Leasequery), + // "pedantic" (enforce full Kea code format). + "extended-info-checks": "fix" + }, + + // List of shared networks used by the Kea DHCPv4 server. The shared + // networks group subnets together. + "shared-networks": [ + { + // A flag selecting an IP address allocation strategy for all + // subnets in this shared network. + "allocator": "random", + + // Shared-network level authoritative flag. + "authoritative": false, + + // Shared-network level bootfile name. + "boot-file-name": "/dev/null", + + // Restricts this shared network to allow only clients + // that belong to a particular client class. If an + // empty string is provided, no restriction is applied. + "client-class": "", + + // Shared-network level value. See description at the global level. + "ddns-generated-prefix": "myhost", + + // Shared-network level value. See description at the global level. + "ddns-override-client-update": false, + + // Shared-network level value. See description at the global level. + "ddns-override-no-update": false, + + // Shared-network level value. See description at the global level. + "ddns-qualifying-suffix": "", + + // Shared-network level value. See description at the global level. + "ddns-replace-client-name": "never", + + // Shared-network level value. See description at the global level. + "ddns-send-updates": true, + + // Shared-network level value. See description at the global level. + "ddns-update-on-renew": true, + + // Shared-network level value. See description at the global level. + "ddns-use-conflict-resolution": true, + + // Shared-network level value. See description at the global level. + "ddns-ttl-percent": 0.65, + + // Shared-network level value. See description at the global level. + "hostname-char-replacement": "x", + + // Shared-network level value. See description at the global level. + "hostname-char-set": "[^A-Za-z0-9.-]", + + // Specifies that this shared network is selected for + // requests received on a particular interface. + "interface": "eth0", + + // Shared-network level flag specifying whether the client + // identifier should be used for identifying clients. + "match-client-id": true, + + // Shared network name. + "name": "my-secret-network", + + // Shared-network level specification of the next server + // to be sent in 'siaddr'. + "next-server": "192.0.2.123", + + // If greater than zero, it is the lifetime of leases temporarily allocated + // on DISCOVER. When zero (the default), leases are not allocated on DISCOVER. + "offer-lifetime" : 60, + + // List of shared network-specific DHCP options. + "option-data": [], + + // List of IPv4 relay addresses for which this shared + // network is selected. + "relay": { + "ip-addresses": [] + }, + + // Shared-network level rebind timer. + "rebind-timer": 41, + + // Shared-network level renew timer. + "renew-timer": 31, + + // Shared-network level compute T1 and T2 timers. + "calculate-tee-times": true, + + // T1 = valid lifetime * .5. + "t1-percent": .5, + + // T2 = valid lifetime * .75. + "t2-percent": .75, + + // Cache threshold = valid lifetime * .25. + "cache-threshold": .25, + + // Cache maximum: when the client last-transmission time + // is close enough, the lease is not renewed and the current + // lease is returned as it was "cached". + "cache-max-age": 1000, + + // Enumeration specifying the server's mode of operation when it + // fetches host reservations. + // "reservation-mode": "all", + // It is replaced by the "reservations-global", + // "reservations-in-subnet", and "reservations-out-of-pool" + // parameters. + + // Specify whether the server should look up global reservations. + "reservations-global": false, + + // Specify whether the server should look up in-subnet reservations. + "reservations-in-subnet": true, + + // Specify whether the server can assume that all reserved addresses + // are out-of-pool. + // Ignored when reservations-in-subnet is false. + // If specified, it is inherited by "subnet4" levels. + "reservations-out-of-pool": false, + + // List of client classes which must be evaluated when this shared + // network is selected for client assignments. + "require-client-classes": [ "late" ], + + // Turn off storage of extended information (e.g. relay agent + // information) with each lease for this shared network. + "store-extended-info": false, + + // Shared-network level server hostname set in 'sname' field. + "server-hostname": "", + + // List of IPv4 subnets belonging to this shared network. + "subnet4": [ + { + // Interface name matched against inbound interface name. + // Used in DHCPv4o6. See RFC 7341. + "4o6-interface": "", + + // Interface ID option value. See RFC 7341. + "4o6-interface-id": "", + + // Prefix matched against source address. See RFC7341. + "4o6-subnet": "2001:db8:1:1::/64", + + // A flag selecting an IP address allocation strategy for + // the subnet. + "allocator": "iterative", + + // Subnet-level authoritative flag. + "authoritative": false, + + // Subnet-level bootfile name, set in 'file' field. + "boot-file-name": "", + + // Restricts this subnet to allow only clients that belong + // to a particular client class. If an empty string is + // provided, no restriction is applied. + "client-class": "", + + // Subnet-level value. See description at the global level. + "ddns-generated-prefix": "myhost", + + // Subnet-level value. See description at the global level. + "ddns-override-client-update": false, + + // Subnet-level value. See description at the global level. + "ddns-override-no-update": false, + + // Subnet-level value. See description at the global level. + "ddns-qualifying-suffix": "", + + // Subnet-level value. See description at the global level. + "ddns-replace-client-name": "never", + + // Subnet-level value. See description at the global level. + "ddns-send-updates": true, + + // Subnet-level value. See description at the global level. + "ddns-update-on-renew": true, + + // Subnet-level value. See description at the global level. + "ddns-use-conflict-resolution": true, + + // Subnet-level value. See description at the global level. + "ddns-ttl-percent": 0.55, + + // Subnet-level value. See description at the global level. + "hostname-char-replacement": "x", + + // Subnet-level value. See description at the global level. + "hostname-char-set": "[^A-Za-z0-9.-]", + + // Subnet unique identifier. + "id": 1, + + // Specifies that this subnet is selected for requests + // received on a particular interface. + "interface": "eth0", + + // Subnet-level flag specifying whether the client identifier + // should be used for identifying clients. + "match-client-id": true, + + // Subnet-level specification of the next server to be sent + // in 'siaddr'. + "next-server": "0.0.0.0", + + // If greater than zero, it is the lifetime of leases temporarily allocated + // on DISCOVER. When zero (the default), leases are not allocated on DISCOVER. + "offer-lifetime" : 60, + + // Turn on storage of extended information (e.g. relay agent + // information) with each lease for this subnet. + "store-extended-info": true, + + // Subnet-level list of DHCP options. + "option-data": [ + { + // Boolean flag indicating whether the particular option + // should be always sent or sent only when requested. + "always-send": false, + + // Option code. + "code": 3, + + // Boolean flag indicating whether the option value specified + // in "data" is a string of hexadecimal values or human-readable + // CSV value. + "csv-format": true, + + // Option data to be included in the option payload. + "data": "192.0.3.1", + + // Option name. + "name": "routers", + + // Boolean flag indicating whether the given option is never + // sent in response. + "never-send": false, + + // Option space. The default value "dhcp4" designates the + // top-level option space. + "space": "dhcp4" + } + ], + + // List of IP address pools belonging to the subnet. + "pools": [ + { + // Restricts this pool to only be used for client + // requests belonging to a particular client class. + "client-class": "phones_server1", + + // Pool-level list of DHCP options. + "option-data": [], + + // Address range used for client assignments. + "pool": "192.1.0.1 - 192.1.0.200", + + // List of client classes which must be evaluated when this pool + // is selected for client assignments. + "require-client-classes": [ "late" ] + }, + { + // Restricts this pool to only be used for client + // requests belonging to a particular client class. + "client-class": "phones_server2", + + // Pool-level list of DHCP options. + "option-data": [], + + // Address range used for client assignments. + "pool": "192.3.0.1 - 192.3.0.200", + + // List of client classes which must be evaluated when this pool + // is selected for client assignments. + "require-client-classes": [], + + // Pool identifier used to enable statistics for this pool. + // The pool ID does not need to be unique within the subnet + // or across subnets. + // If not unconfigured, it defaults to 0. The statistics + // regarding this pool will be combined with the other statistics + // of all other pools with the same pool ID in this subnet. + "pool-id": 1 + } + ], + + // Subnet-level value of the rebind timer. + "rebind-timer": 40, + + // List of IPv4 relay addresses for which this subnet is selected. + "relay": { + "ip-addresses": [ + "192.168.56.1" + ] + }, + + // Subnet-level value of the renew timer. + "renew-timer": 30, + + // Enumeration specifying the server's mode of operation when it + // fetches host reservations. + // "reservation-mode": "all", + // It is replaced by the "reservations-global", + // "reservations-in-subnet", and + // "reservations-out-of-pool" parameters. + + // Specify whether the server should look up global reservations. + "reservations-global": false, + + // Specify whether the server should look up in-subnet reservations. + "reservations-in-subnet": true, + + // Specify whether the server can assume that all reserved + // addresses are out-of-pool. + // Ignored when reservations-in-subnet is false. + "reservations-out-of-pool": false, + + // Subnet-level compute T1 and T2 timers. + "calculate-tee-times": true, + + // T1 = valid lifetime * .5. + "t1-percent": .5, + + // T2 = valid lifetime * .75. + "t2-percent": .75, + + // Cache threshold = valid lifetime * .25. + "cache-threshold": .25, + + // Subnet-level cache maximum. + "cache-max-age": 1000, + + // List of static IPv4 reservations assigned to clients belonging + // to this subnet. For a detailed example, see reservations.json. + "reservations": [ + { + // Identifier used for client matching. Supported values are + // "hw-address", "client-id", "duid", "circuit-id", "flex-id". + "circuit-id": "01:11:22:33:44:55:66", + + // Reserved IP address. + "ip-address": "192.0.2.204", + + // Hostname. + "hostname": "foo.example.org", + + // Reservation-specific option data. + "option-data": [ + { + // Option name. + "name": "vivso-suboptions", + + // Option data. + "data": "4491" + } + ] + } + ], + + // List of client classes which must be evaluated when this subnet + // is selected for client assignments. + "require-client-classes": [ "late" ], + + // Subnet-level server hostname set in 'sname' field. + "server-hostname": "", + + // Subnet prefix. + "subnet": "192.0.0.0/8", + + // Subnet-level (default) valid lifetime. + "valid-lifetime": 6000, + + // Subnet-level min valid lifetime. + "min-valid-lifetime": 4000, + + // Subnet-level max valid lifetime. + "max-valid-lifetime": 8000 + } + ], + + // Shared-network level (default) valid lifetime. + "valid-lifetime": 6001, + + // Shared-network level min valid lifetime. + "min-valid-lifetime": 4001, + + // Shared-network level max valid lifetime. + "max-valid-lifetime": 8001 + } + ], + + // Global server hostname set in the 'sname' field. + "server-hostname": "", + + // List of IPv4 subnets which don't belong to any shared network. + "subnet4": [], + + // Global valid lifetime value. + "valid-lifetime": 6000, + + // Global min valid lifetime value. + "min-valid-lifetime": 4000, + + // Global max valid lifetime value. + "max-valid-lifetime": 8000, + + // Reservations (examples are in other files). + "reservations": [], + + // Configuration control (currently not used, i.e. this syntax + // is already defined but the corresponding feature is not implemented). + "config-control": { + // Only the configuration databases entry is defined. + "config-databases": [ + { + // Name of the database to connect to. + "name": "config", + + // Type of database, e.g. "mysql", "postgresql". + "type": "mysql" + } + ], + // Interval between attempts to fetch configuration updates + // via the configuration backends used. + "config-fetch-wait-time": 30 + }, + + // Server tag. + "server-tag": "my DHCPv4 server", + + // DHCP queue-control parameters. + "dhcp-queue-control": { + // Enable queue is mandatory. + "enable-queue": true, + + // Queue type is mandatory. + "queue-type": "kea-ring4", + + // Capacity is optional. + "capacity": 64 + }, + + // Fetches host reservations. + // "reservation-mode": "all", + // It is replaced by the "reservations-global", + // "reservations-in-subnet", and "reservations-out-of-pool" parameters. + + // Specify whether the server should look up global reservations. + "reservations-global": false, + + // Specify whether the server should look up in-subnet reservations. + "reservations-in-subnet": true, + + // Specify whether the server can assume that all reserved addresses + // are out-of-pool. + // Ignored when reservations-in-subnet is false. + // If specified, it is inherited by "shared-networks" and + // "subnet4" levels. + "reservations-out-of-pool": false, + + // Global compute T1 and T2 timers. + "calculate-tee-times": true, + + // T1 = valid lifetime * .5. + "t1-percent": .5, + + // T2 = valid lifetime * .75. + "t2-percent": .75, + + // Cache threshold = valid lifetime * .25. + "cache-threshold": .25, + + // Global cache maximum. + "cache-max-age": 1000, + + // String of zero or more characters with which to replace each + // invalid character in the hostname or Client FQDN. The default + // value is an empty string, which will cause invalid characters + // to be omitted rather than replaced. + "hostname-char-replacement": "x", + + // Regular expression describing the invalid character set in + // the hostname or Client FQDN. + "hostname-char-set": "[^A-Za-z0-9.-]", + + // List of loggers used by the servers using this configuration file. + "loggers": [ + { + // Debug level, a value between 0..99. The greater the value + // the more detailed the debug log. + "debuglevel": 99, + + // Name of the logger. + "name": "kea-dhcp4", + + // Configures how the log should be output. + "output-options": [ + { + // Determines whether the log should be flushed to a file. + "flush": true, + + // Specifies maximum filesize before the file is rotated. + "maxsize": 10240000, + + // Specifies the maximum number of rotated files to be kept. + "maxver": 1, + + // Specifies the logging destination. + "output": "stdout", + + // Specifies log entry content + "pattern": "%D{%Y-%m-%d %H:%M:%S.%q} %-5p [%c/%i] %m\n" + } + ], + + // Specifies logging severity, i.e. "ERROR", "WARN", "INFO", "DEBUG". + "severity": "INFO" + } + ], + + // If greater than zero, it is the lifetime of leases temporarily allocated + // on DISCOVER. When zero (the default), leases are not allocated on DISCOVER. + "offer-lifetime" : 60, + + // Look at advanced examples for the use of user-contexts. + "user-context": { } + } +} diff --git a/doc/examples/kea4/all-keys.json b/doc/examples/kea4/all-keys.json new file mode 100644 index 0000000..d5e0a02 --- /dev/null +++ b/doc/examples/kea4/all-keys.json @@ -0,0 +1,1277 @@ +// WARNING: This example configuration is not meant for production use. +// The Kea DHCPv4 server will refuse this configuration because it contains +// mutually exclusive configuration parameters. +// +// The primary purpose of the example file is to provide a comprehensive +// list of parameters supported by the Kea DHCPv4 server, along with a brief +// description of each parameter. +// +// This current version should be up to date, i.e. new keywords should be +// added in this file at the same time as in the parser specification. +{ + // Kea DHCPv4 server configuration begins here. + "Dhcp4": { + // Global flag selecting an IP address allocation strategy for all + // subnets. Use "random" for a random allocation strategy. + "allocator": "iterative", + + // Global authoritative flag to handle requests by clients for + // unknown IP addresses (ignore if disabled, NAK if enabled). + "authoritative": false, + + // Global bootfile name to be set in the 'file' field. + "boot-file-name": "/dev/null", + + // Ordered list of client classes used by the DHCPv4 server. + "client-classes": [ + { + // Class-specific bootfile name to be set in the 'file' field. + "boot-file-name": "/tmp/bootfile.efi", + + // Class name. + "name": "phones_server1", + + // Class-specific next server address to use in bootstrap, which + // is set in 'siaddr' field. + "next-server": "10.2.3.4", + + // Class-specific DHCPv4 options list. + "option-data": [], + + // Class-specific DHCPv4 option definitions, i.e. custom formats + // specified for non-standard options. + "option-def": [], + + // Class-specific optional server hostname, which is set in + // 'sname' field. + "server-hostname": "", + + // Class selection expression. The DHCP packet is assigned to this + // class when the given expression evaluates to true. + "test": "member('HA_server1')", + + // Class valid lifetime. + "valid-lifetime": 6000, + + // Class min valid lifetime. + "min-valid-lifetime": 4000, + + // Class max valid lifetime. + "max-valid-lifetime": 8000, + + // If greater than zero, it is the lifetime of leases temporarily allocated + // on DISCOVER. When zero (the default), leases are not allocated on DISCOVER. + "offer-lifetime" : 65 + }, + { + // Default value of the class-specific bootfile name. An empty name + // means that the bootfile name is unspecified. + "boot-file-name": "", + + // Second class name. + "name": "phones_server2", + + // Default value of the class-specific next server address. The + // zero IPv4 address means that it is unspecified. + "next-server": "0.0.0.0", + + // Class-specific DHCPv4 options list. + "option-data": [], + + // Class-specific DHCPv4 option definitions, i.e. custom formats + // specified for non-standard options. + "option-def": [], + + // Class-specific optional server hostname, which is set in + // 'sname' field. + "server-hostname": "", + + // Class selection expression. The DHCP packet is assigned to this + // class when the given expression evaluates to true. + "test": "member('HA_server2')" + }, + { + // Third class name. + "name": "late", + + // Boolean flag indicating whether the class expression is only evaluated + // when the class is required, e.g. the selected address pool configuration + // includes this class name in its "require-client-classes" list. The + // default value false means that the class test expression must + // always be evaluated. + "only-if-required": true, + + // Class selection expression. + "test": "member('ALL')" + }, + { + // Fourth class name. + "name": "my-template-class", + + // Template class flag that holds the expression used to generate the names for all + // the spawned subclasses. In this case, the classes are named after the client ID. + "template-test": "substring(option[61].hex, 0, all)" + } + ], + + // Parameters for triggering behaviors compatible with broken or + // non-compliant clients, relays, or other agents + "compatibility": { + // Ignore DHCP Server Identifier option if set to true. + // Enabling this will cause Kea to accept any query, even + // if the address in the option belongs to another server, + // instead of dropping it. This config option defaults to + // false, as enabling it breaks RFC compliance. + "ignore-dhcp-server-identifier": false, + + // Ignore Relay Agent Information Link Selection suboption if set + // to true. Enabling this will cause Kea to use normal subnet + // selection logic instead of attempting to use the subnet + // specified in the suboption. This config option defaults to + // false, as enabling it breaks RFC compliance. + "ignore-rai-link-selection": false, + + // Parse options more leniently where fields can be deduced + // deterministically, even if against RFC or common practice. + "lenient-option-parsing": true, + + // Boolean flag indicating whether .0 and .255 addresses + // must be considered as never free in subnets with a prefix length + // of 24 or less. The default is false, as these addresses are not + // special; only the first and the last addresses are. + "exclude-first-last-24": false + }, + + // Command control socket configuration parameters for the Kea DHCPv4 server. + "control-socket": { + // Location of the UNIX domain socket file the DHCPv4 server uses + // to receive control commands from the Kea Control Agent or the + // local server administrator. + "socket-name": "/tmp/kea4-ctrl-socket", + + // Control socket type used by the Kea DHCPv4 server. The 'unix' + // socket is currently the only supported type. + "socket-type": "unix" + }, + + // Specifies a prefix to be prepended to the generated Client FQDN. + // It may be specified at the global, shared-network, and subnet levels. + "ddns-generated-prefix": "myhost", + + // Boolean flag indicating whether the server should ignore DHCP client + // wishes to update DNS on its own. With that flag set to true, + // the server will send DNS updates for both forward and + // reverse DNS data. The default value is false, which indicates + // that the server will delegate a DNS update to the client when + // requested. It may be specified at the global, shared-network, + // and subnet levels. + "ddns-override-client-update": false, + + // Boolean flag indicating whether the server should override the DHCP + // client's wish to not update the DNS. With this parameter + // set to true, the server will send a DNS update even when + // the client requested no update. It may be specified at the + // global, shared-network, and subnet levels. + "ddns-override-no-update": false, + + // Suffix appended to the partial name sent to the DNS. The + // default value is an empty string, which indicates that no + // suffix is appended. It may be specified at the global, + // shared-network, and subnet levels. + "ddns-qualifying-suffix": "", + + // Enumeration specifying whether the server should honor + // the hostname or Client FQDN sent by the client or replace + // this name. The acceptable values are: "never" (use the + // name the client sent), "always" (replace the name the + // client sent), "when-present" (replace the name the client + // sent, but do not generate one when the client didn't send + // the name), "when-not-present" (generate the name when + // client didn't send one, otherwise leave the name the + // client sent). The default value is "never". It may be + // specified at the global, shared-network, and subnet levels. + "ddns-replace-client-name": "never", + + // Boolean flag which enables or disables DDNS updating. It + // defaults to true. It may be specified at the global, shared- + // network, and subnet levels. It works in conjunction with + // dhcp-ddns:enable-updates, which must be true to enable connectivity + // to kea-dhcp-ddns. + "ddns-send-updates": true, + + // Boolean flag, which when true instructs the server to always + // update DNS when leases are renewed, even if the DNS information + // has not changed. The server's default behavior (i.e. flag is false) + // is to only update DNS if the DNS information has changed. It + // may be specified at the global, shared-network, and subnet levels. + "ddns-update-on-renew": true, + + // Boolean flag which is passed to kea-dhcp-ddns with each DDNS + // update request, to indicate whether DNS update conflict + // resolution as described in RFC 4703 should be employed for the + // given update request. The default value for this flag is true. + // It may be specified at the global, shared-network, and subnet levels. + // This field has been replaced by ddns-conflict-resolution-mode. + // Parsing is maintained only for backwards compatibility. + // "ddns-use-conflict-resolution": true, + + // Enumeration, which is passed to kea-dhcp-ddns with each DDNS + // update request to indicate the mode used for resolving conflicts + // while performing DDNS updates. The acceptable values are: + // check-with-dhcid (this includes adding a DHCID record and checking + // that record via conflict detection as per RFC 4703, + // no-check-with-dhcid (this will ignore conflict detection but add + // a DHCID record when creating/updating an entry), + // check-exists-with-dhcid (this will check if there is an existing + // DHCID record but does not verify the value of the record matches + // the update. This will also update the DHCID record for the entry), + // no-check-without-dhcid (this ignores conflict detection and will + // not add a DHCID record when creating/updating a DDNS entry). + // The default value is "check-with-dhcid". It may be + // specified at the global, shared-network and subnet levels. + "ddns-conflict-resolution-mode": "check-with-dhcid", + + // When greater than 0.0, it is the percent of the lease's lifetime + // to use for the DNS TTL. + "ddns-ttl-percent": 0.75, + + // Time in seconds specifying how long a declined lease should be + // excluded from DHCP assignments. The default value is 86400 (24 hours). + "decline-probation-period": 86400, + + // Name Change Request forwarding configuration for the Kea DHCPv4 server. + // NCRs are sent to the Kea D2 module to update DNS upon allocation of + // DHCP leases. + "dhcp-ddns": { + // Boolean flag indicating whether Kea DHCPv4 server should connect to + // kea-dhcp-ddns. This must be true for NCRs to be created and + // sent to kea-dhcp-ddns. By default, NCRs are not generated. + "enable-updates": false, + + // Specifies maximum number of NCRs to queue waiting to be sent + // to the Kea D2 server. + "max-queue-size": 1024, + + // Packet format to use when sending NCRs to the Kea D2 server. + // Currently, only JSON format is supported. + "ncr-format": "JSON", + + // Socket protocol to use when sending NCRs to D2. Currently, + // only UDP is supported. + "ncr-protocol": "UDP", + + // IP address that the Kea DHCPv4 server should use to send + // NCRs to D2. The default value of zero indicates that Kea + // should pick a suitable address. + "sender-ip": "0.0.0.0", + + // Port number that the Kea DHCPv4 server should use to send + // NCRs to D2. The default value of zero indicates that Kea + // should pick a suitable port. + "sender-port": 0, + + // IP address on which D2 listens for NCRs. + "server-ip": "127.0.0.1", + + // Port number on which D2 listens for NCRs. + "server-port": 53001, + + // The following parameters are DEPRECATED. They have been + // replaced with parameters that may be set at the global, + // shared-network, and subnet4 scopes. They are listed here + // as configuration parsing still accepts them. Eventually + // support for them will be removed. + "generated-prefix": "myhost", + "hostname-char-replacement": "x", + "hostname-char-set": "[^A-Za-z0-9.-]", + "override-client-update": false, + "override-no-update": false, + "qualifying-suffix": "", + "replace-client-name": "never" + }, + + // Specifies the first of the two consecutive ports of the UDP + // sockets used for communication between DHCPv6 and DHCPv4 + // servers. See RFC 7341. + "dhcp4o6-port": 6767, + + // Boolean flag indicating whether the Kea DHCPv4 server + // should send back the Client Identifier option in its responses. + // The default value is true, which indicates that the option + // must be sent back if the client included it. The false + // value instructs the server to not send this option for + // backward compatibility with older DHCP specifications, which + // stated that Client Identifier must not be sent back. + "echo-client-id": true, + + // Collection of Kea DHCPv4 server parameters configuring how + // the server should process expired DHCP leases. + "expired-leases-processing": { + // Specifies the number of seconds since the last removal of + // the expired leases, when the next removal should occur. + // If both "flush-reclaimed-timer-wait-time" and + // "hold-reclaimed-time" are not 0, when the client sends a release + // message the lease is expired instead of being deleted from + // lease storage. + "flush-reclaimed-timer-wait-time": 25, + + // Specifies the length of time in seconds to keep expired + // leases in the lease database (lease affinity). + // If both "flush-reclaimed-timer-wait-time" and + // "hold-reclaimed-time" are not 0, when the client sends a release + // message the lease is expired instead of being deleted from + // lease storage. + "hold-reclaimed-time": 3600, + + // Specifies the maximum number of expired leases that can be + // processed in a single attempt to clean up expired leases + // from the lease database. If there are more + // expired leases, they will be processed during the next + // cleanup attempt. + "max-reclaim-leases": 100, + + // Specifies the maximum time in milliseconds that a single attempt + // to clean up expired leases from the lease database may take. + "max-reclaim-time": 250, + + // Specifies the length of time in seconds since the last attempt + // to process expired leases before initiating the next attempt. + "reclaim-timer-wait-time": 10, + + // Specifies the maximum number of expired lease-processing cycles + // which didn't result in full cleanup of exired leases from the + // lease database, after which a warning message is issued. + "unwarned-reclaim-cycles": 5 + }, + + // List of hook libraries and their specific configuration parameters + // to be loaded by Kea DHCPv4 server. + "hooks-libraries": [ + { + // Location of the hook library to be loaded. + "library": "/opt/lib/kea/hooks/libdhcp_lease_cmds.so", + + // Hook library-specific configuration parameters. + "parameters": { } + } + ], + + // List of access credentials to external sources of IPv4 reservations, + "hosts-databases": [ + { + // Name of the database to connect to. + "name": "keatest", + + // Host on which the database resides. + "host": "localhost", + + // Database password. + "password": "keatest", + + // Port on which the database is available. + "port": 3306, + + // Type of database, e.g. "mysql", "postgresql". + "type": "mysql", + + // Username to be used to access the database. + "user": "keatest", + + // Read-only mode. + "readonly": false, + + // The next entries are for OpenSSL support in MySQL. + + // Trust anchor aka certificate authority file or directory. + "trust-anchor": "my-ca", + + // Client certificate file name. + "cert-file": "my-cert", + + // Private key file name. + "key-file": "my-key", + + // Cipher list (see the OpenSSL ciphers command manual). + "cipher-list": "AES", + + // Connection reconnect wait time. + // This parameter governs how long Kea waits before attempting + // to reconnect. Expressed in milliseconds. The default is 0 + // (disabled) for MySQL and PostgreSQL. + "reconnect-wait-time": 3000, + + // Connection maximum reconnect tries. + "max-reconnect-tries": 3, + + // Action to take when connection recovery fails. + // Supported values: stop-retry-exit, serve-retry-exit, + // serve-retry-continue + "on-fail": "stop-retry-exit", + + // Flag which indicates if the DB recovery should be attempted + // at server startup and on reconfiguration events. + "retry-on-startup": false, + + // Connection connect timeout in seconds. + "connect-timeout": 100, + + // Timeout of database read operations in seconds. + "read-timeout": 120, + + // Timeout of database write operations in seconds. + "write-timeout": 180 + }, + { + // Name of the database to connect to. + "name": "keatest", + + // Host on which the database resides. + "host": "localhost", + + // Database password. + "password": "keatest", + + // Port on which the database is available. + "port": 5432, + + // Type of database, e.g. "mysql", "postgresql". + "type": "postgresql", + + // Username to be used to access the database. + "user": "keatest", + + // TCP user timeout while communicating with the database. + // It is specified in seconds. + "tcp-user-timeout": 100 + } + ], + + // List of host reservation identifier types to be used by the + // Kea DHCPv4 server to fetch static reservations for + // DHCP clients. All identifiers are used by default, which + // means that the server will issue multiple queries to the + // database to find if there is a reservation for a particular + // client. If a particular deployment uses only a subset, e.g. + // one identifier type, this identifier should be only listed + // here to prevent unnecessary queries to the database. + "host-reservation-identifiers": [ + "hw-address", + "duid", + "circuit-id", + "client-id", + "flex-id" + ], + + // Specifies configuration of interfaces on which the Kea DHCPv4 + // server is listening to the DHCP queries. + "interfaces-config": { + // Specifies whether the server should use "udp" sockets or + // "raw" sockets to listen to DHCP traffic. The "raw" + // sockets are useful when direct DHCP traffic is being + // received. + "dhcp-socket-type": "udp", + + // Specifies a list of interfaces on which the Kea DHCPv4 + // server should listen to DHCP requests. + "interfaces": [ + "eth0" + ], + + // Enumeration which indicates what interface should be used + // to send DHCP responses to the client. The default value is + // "same-as-inbound", which indicates that the response should + // be sent via the interface on which the client's query + // was received. The "use-routing" value indicates that the + // Kea server should use the kernel's routing table to find a + // suitable interface. + "outbound-interface": "same-as-inbound", + + // Boolean flag indicating whether the available interfaces should + // be re-detected upon server reconfiguration. The default value + // is true, which means that the interfaces are always + // re-detected. + "re-detect": true, + + // Kea tries to bind the service sockets during initialization, but it may + // fail due to a port being already opened or a misconfiguration. Kea can + // suppress these errors and only log them. This flag prevents starting + // the DHCP server without binding all sockets. If unspecified, it + // defaults to false. + "service-sockets-require-all": true, + + // Kea tries to bind the service sockets during initialization. This + // option specifies how many times binding to interface will be retried. + // The default value is 0, which means that the operation will not be + // repeated. + "service-sockets-max-retries": 5, + + // The time interval in milliseconds to wait before the next attempt to + // retry opening a service socket. + "service-sockets-retry-wait-time": 5000 + }, + + // Boolean parameter which controls whether an early global host + // reservations lookup should be performed. This lookup takes place + // before subnet selection and when a global reservation is found + // with some client classes, it triggers a second phase classification. + // It can also be used to drop queries using host reservations as a + // decision table indexed by reservation identifiers. + "early-global-reservations-lookup": true, + + // Boolean parameter which controls the DHCP server's behavior with respect + // to creating host reservations for the same IP address. By default + // this flag is set to true, in which case the server prevents creation + // of multiple host reservations for the same IP address. When this + // parameter is set to false, the server allows for creating multiple + // reservations for the same IP address within a subnet. This setting + // is useful in deployments in which a given host may be communicating + // with a DHCP server over multiple interfaces and, depending on the + // chosen interface, a different MAC address (or other identifier) will + // be used to identify the host. Note that some host backends do not + // support the mode in which multiple reservations for the same IP + // address are used. If these backends are in use and this setting + // is attempted, a configuration error will occur. The MySQL and + // PostgreSQL backends do support this mode. + "ip-reservations-unique": true, + + // Boolean parameter which controls whether host reservations lookup + // should be performed before lease lookup. This parameter has effect + // only when multi-threading is disabled. When multi-threading is + // enabled, host reservations lookup is always performed first to avoid + // lease-lookup resource locking. + "reservations-lookup-first": true, + + // Specifies credentials to access lease database. + "lease-database": { + // memfile backend-specific parameter specifying the interval + // in seconds at which the lease file should be cleaned up (outdated + // lease entries are removed to prevent the lease file from growing + // infinitely). + "lfc-interval": 3600, + + // Maximum number of lease-file read errors allowed before + // loading the file is abandoned. Defaults to 0 (no limit). + "max-row-errors": 100, + + // Name of the lease file. In the case of a database it specifies the + // database name. + "name": "/tmp/kea-dhcp4.csv", + + // memfile-specific parameter indicating whether leases should + // be saved on persistent storage (disk) or not. The true value + // is the default and it indicates that leases are stored in + // persistent storage. This setting must be used in production. + // The false value should only be used for testing purposes + // because non-stored leases will be lost upon Kea server restart. + "persist": true, + + // Lease database backend type, i.e. "memfile", "mysql" or + // "postgresql". + "type": "memfile" + }, + + // Boolean value indicating whether the Kea DHCPv4 server should use the client + // identifier value sent by the client or ignore it. The default value + // is true, which indicates that the server should use the client identifier + // and that it takes precedence over the client's MAC address. In deployments + // where MAC address should take precedence, this value can be set to + // false, in which case the clients will be identified by MAC address. + // This is specifically useful when clients don't generate unique + // identifiers or these identifiers are not stable, etc. + "match-client-id": false, + + // Global value of the next server address set in 'siaddr' field. + // The global value may be overridden in lower-level configuration + // scopes. + "next-server": "192.0.2.123", + + // Global value which limits the number of client packets (e.g. + // DHCPREQUESTs) that may be parked while waiting for hook library + // work to complete, prior to a response (e.g. DHCPACK) being sent + // back to the client. A typical example is when kea-dhcp4 parks a + // DHCPREQUEST while it sends the lease update(s) to its HA peer(s). + // The packet is unparked once the update(s) have been acknowledged. + // This value limits the number of packets that can be held pending + // the updates. In times of heavy client traffic, this value can keep + // kea-dhcp4 from building an insurmountable backlog of updates. + "parked-packet-limit": 128, + + // List of global DHCP options that the Kea DHCPv4 server assigns to + // clients. + "option-data": [ + { + // Boolean flag indicating whether the given option is always + // sent in response or only when requested. The default + // value of false indicates that it is only sent when + // requested. + "always-send": false, + + // Option code. It is not required if the option name is + // provided. + "code": 6, + + // Boolean value indicating whether the option data specified + // in the "data" field is specified as a string of hexadecimal + // digits or in human-readable CSV format. + "csv-format": true, + + // Option data to be stored in the option payload. + "data": "192.0.3.1, 192.0.3.2", + + // Option name. It is not required if the option code is + // provided. + "name": "domain-name-servers", + + // Boolean flag indicating whether the given option is never + // sent in response. The default value of false indicates + // that it is sent when it should be. When true, the option + // is not sent despite any other setting, i.e. it is + // a final flag. + "never-send": false, + + // Option space. The default is the "dhcp4" option space which + // groups top-level DHCPv4 options. + "space": "dhcp4" + } + ], + + // List of global option definitions, i.e. option formats, that the + // Kea DHCPv4 server is using. + "option-def": [ + { + // Boolean flag indicating whether the option definition comprises + // an array of values of some type, e.g. an array of IPv4 addresses. + // The default value of false means that the option does not + // comprise an array of values. + "array": false, + + // Option code. + "code": 6, + + // Holds a name of the option space encapsulated by this option. + // All options that belong to this option space will be sent + // as sub-options of this option. An empty string means that this + // option doesn't encapsulate any option. + "encapsulate": "", + + // Option name. + "name": "my-option", + + // Specifies the types of fields within the option if the option + // is said to be a "record" (see "type"). In this particular example + // this option comprises two fields, 1 byte and 2 bytes long. + "record-types": "uint8, uint16", + + // Name of the option space to which this option belongs. + "space": "my-space", + + // Option type. All possible types are listed in the Kea + // Administrator Reference Manual. + "type": "record" + } + ], + + // Global value for the rebind timer, i.e. the time after which the + // DHCP client enters the rebind state if it fails to renew the lease. + "rebind-timer": 40, + + // Global value for the renew timer, i.e. the time after which the + // DHCP client renews the lease. + "renew-timer": 30, + + // Global value to store extended information (e.g. relay agent + // information) with each lease. + "store-extended-info": true, + + // Statistics keep some samples per observation point. + // There are two default values: maximum count and maximum age. + // Setting the maximum count to zero disables it. + "statistic-default-sample-count": 0, + + // When the maximum count is 0 the maximum age (in seconds) applies. + "statistic-default-sample-age": 60, + + // Multi-threading parameters. + "multi-threading": { + // By default, Kea processes packets on multiple threads if the hardware permits. + "enable-multi-threading": true, + + // When multi-threading is enabled, Kea will process packets on a + // number of multiple threads configurable through this option. The + // value must be a positive integer (0 means auto-detect). + "thread-pool-size": 0, + + // When multi-threading is enabled, Kea will read packets from the + // interface and append a working item to the thread pool. This + // option configures the maximum number of items that can be queued. + // The value must be a positive integer (0 means unlimited). + "packet-queue-size": 0 + }, + + // Governs how the Kea DHCPv4 server should deal with invalid + // data received from the client. + "sanity-checks": { + // Specifies how the Kea DHCPv4 server should behave when invalid + // data is read for a lease from the lease file. The following + // values are supported: "none" (don't attempt to correct the + // lease information), "warn" (print a warning for subnet-id + // related inconsistencies), "fix" (correct the subnet id by + // trying to find the suitable subnet), "fix-del" (similar + // to "fix" but delete the lease if no suitable subnet found), + // "del" (delete the lease if the lease has invalid subnet + // identifier value). + "lease-checks": "warn", + + // Specifies how Kea DHCPv4 server should behave when invalid + // extended info is read for a lease from the lease file, or + // whether to upgrade from the old format. The following values + // are supported: "none" (don't attempt to correct or upgrade + // the extended info), "fix" (fix common inconsistencies and + // upgrade from the old format; this is the default), "strict" + // (fix inconsistencies with an impact on Leasequery), + // "pedantic" (enforce full Kea code format). + "extended-info-checks": "fix" + }, + + // List of shared networks used by the Kea DHCPv4 server. The shared + // networks group subnets together. + "shared-networks": [ + { + // A flag selecting an IP address allocation strategy for all + // subnets in this shared network. + "allocator": "random", + + // Shared-network level authoritative flag. + "authoritative": false, + + // Shared-network level bootfile name. + "boot-file-name": "/dev/null", + + // Restricts this shared network to allow only clients + // that belong to a particular client class. If an + // empty string is provided, no restriction is applied. + "client-class": "", + + // Shared-network level value. See description at the global level. + "ddns-generated-prefix": "myhost", + + // Shared-network level value. See description at the global level. + "ddns-override-client-update": false, + + // Shared-network level value. See description at the global level. + "ddns-override-no-update": false, + + // Shared-network level value. See description at the global level. + "ddns-qualifying-suffix": "", + + // Shared-network level value. See description at the global level. + "ddns-replace-client-name": "never", + + // Shared-network level value. See description at the global level. + "ddns-send-updates": true, + + // Shared-network level value. See description at the global level. + "ddns-update-on-renew": true, + + // Shared-network level value. See description at the global level. + // This field has been replaced by ddns-conflict-resolution-mode. + // Parsing is maintained only for backwards compatibility. + // "ddns-use-conflict-resolution": true, + + // Shared-network level value. See description at the global level. + "ddns-conflict-resolution-mode": "check-with-dhcid", + + // Shared-network level value. See description at the global level. + "ddns-ttl-percent": 0.65, + + // Shared-network level value. See description at the global level. + "hostname-char-replacement": "x", + + // Shared-network level value. See description at the global level. + "hostname-char-set": "[^A-Za-z0-9.-]", + + // Specifies that this shared network is selected for + // requests received on a particular interface. + "interface": "eth0", + + // Shared-network level flag specifying whether the client + // identifier should be used for identifying clients. + "match-client-id": true, + + // Shared network name. + "name": "my-secret-network", + + // Shared-network level specification of the next server + // to be sent in 'siaddr'. + "next-server": "192.0.2.123", + + // If greater than zero, it is the lifetime of leases temporarily allocated + // on DISCOVER. When zero (the default), leases are not allocated on DISCOVER. + "offer-lifetime" : 60, + + // List of shared network-specific DHCP options. + "option-data": [], + + // List of IPv4 relay addresses for which this shared + // network is selected. + "relay": { + "ip-addresses": [] + }, + + // Shared-network level rebind timer. + "rebind-timer": 41, + + // Shared-network level renew timer. + "renew-timer": 31, + + // Shared-network level compute T1 and T2 timers. + "calculate-tee-times": true, + + // T1 = valid lifetime * .5. + "t1-percent": .5, + + // T2 = valid lifetime * .75. + "t2-percent": .75, + + // Cache threshold = valid lifetime * .25. + "cache-threshold": .25, + + // Cache maximum: when the client last-transmission time + // is close enough, the lease is not renewed and the current + // lease is returned as it was "cached". + "cache-max-age": 1000, + + // Enumeration specifying the server's mode of operation when it + // fetches host reservations. + // "reservation-mode": "all", + // It is replaced by the "reservations-global", + // "reservations-in-subnet", and "reservations-out-of-pool" + // parameters. + + // Specify whether the server should look up global reservations. + "reservations-global": false, + + // Specify whether the server should look up in-subnet reservations. + "reservations-in-subnet": true, + + // Specify whether the server can assume that all reserved addresses + // are out-of-pool. + // Ignored when reservations-in-subnet is false. + // If specified, it is inherited by "subnet4" levels. + "reservations-out-of-pool": false, + + // List of client classes which must be evaluated when this shared + // network is selected for client assignments. + "require-client-classes": [ "late" ], + + // Turn off storage of extended information (e.g. relay agent + // information) with each lease for this shared network. + "store-extended-info": false, + + // Shared-network level server hostname set in 'sname' field. + "server-hostname": "", + + // List of IPv4 subnets belonging to this shared network. + "subnet4": [ + { + // Interface name matched against inbound interface name. + // Used in DHCPv4o6. See RFC 7341. + "4o6-interface": "", + + // Interface ID option value. See RFC 7341. + "4o6-interface-id": "", + + // Prefix matched against source address. See RFC7341. + "4o6-subnet": "2001:db8:1:1::/64", + + // A flag selecting an IP address allocation strategy for + // the subnet. + "allocator": "iterative", + + // Subnet-level authoritative flag. + "authoritative": false, + + // Subnet-level bootfile name, set in 'file' field. + "boot-file-name": "", + + // Restricts this subnet to allow only clients that belong + // to a particular client class. If an empty string is + // provided, no restriction is applied. + "client-class": "", + + // Subnet-level value. See description at the global level. + "ddns-generated-prefix": "myhost", + + // Subnet-level value. See description at the global level. + "ddns-override-client-update": false, + + // Subnet-level value. See description at the global level. + "ddns-override-no-update": false, + + // Subnet-level value. See description at the global level. + "ddns-qualifying-suffix": "", + + // Subnet-level value. See description at the global level. + "ddns-replace-client-name": "never", + + // Subnet-level value. See description at the global level. + "ddns-send-updates": true, + + // Subnet-level value. See description at the global level. + "ddns-update-on-renew": true, + + // Shared-network level value. See description at the global level. + // This field has been replaced by ddns-conflict-resolution-mode. + // Parsing is maintained only for backwards compatibility. + // "ddns-use-conflict-resolution": true, + + // Subnet-level value. See description at the global level. + "ddns-conflict-resolution-mode": "check-with-dhcid", + + // Subnet-level value. See description at the global level. + "ddns-ttl-percent": 0.55, + + // Subnet-level value. See description at the global level. + "hostname-char-replacement": "x", + + // Subnet-level value. See description at the global level. + "hostname-char-set": "[^A-Za-z0-9.-]", + + // Subnet unique identifier. + "id": 1, + + // Specifies that this subnet is selected for requests + // received on a particular interface. + "interface": "eth0", + + // Subnet-level flag specifying whether the client identifier + // should be used for identifying clients. + "match-client-id": true, + + // Subnet-level specification of the next server to be sent + // in 'siaddr'. + "next-server": "0.0.0.0", + + // If greater than zero, it is the lifetime of leases temporarily allocated + // on DISCOVER. When zero (the default), leases are not allocated on DISCOVER. + "offer-lifetime" : 60, + + // Turn on storage of extended information (e.g. relay agent + // information) with each lease for this subnet. + "store-extended-info": true, + + // Subnet-level list of DHCP options. + "option-data": [ + { + // Boolean flag indicating whether the particular option + // should be always sent or sent only when requested. + "always-send": false, + + // Option code. + "code": 3, + + // Boolean flag indicating whether the option value specified + // in "data" is a string of hexadecimal values or human-readable + // CSV value. + "csv-format": true, + + // Option data to be included in the option payload. + "data": "192.0.3.1", + + // Option name. + "name": "routers", + + // Boolean flag indicating whether the given option is never + // sent in response. + "never-send": false, + + // Option space. The default value "dhcp4" designates the + // top-level option space. + "space": "dhcp4" + } + ], + + // List of IP address pools belonging to the subnet. + "pools": [ + { + // Restricts this pool to only be used for client + // requests belonging to a particular client class. + "client-class": "phones_server1", + + // Pool-level list of DHCP options. + "option-data": [], + + // Address range used for client assignments. + "pool": "192.1.0.1 - 192.1.0.200", + + // List of client classes which must be evaluated when this pool + // is selected for client assignments. + "require-client-classes": [ "late" ] + }, + { + // Restricts this pool to only be used for client + // requests belonging to a particular client class. + "client-class": "phones_server2", + + // Pool-level list of DHCP options. + "option-data": [], + + // Address range used for client assignments. + "pool": "192.3.0.1 - 192.3.0.200", + + // List of client classes which must be evaluated when this pool + // is selected for client assignments. + "require-client-classes": [], + + // Pool identifier used to enable statistics for this pool. + // The pool ID does not need to be unique within the subnet + // or across subnets. + // If not unconfigured, it defaults to 0. The statistics + // regarding this pool will be combined with the other statistics + // of all other pools with the same pool ID in this subnet. + "pool-id": 1 + } + ], + + // Subnet-level value of the rebind timer. + "rebind-timer": 40, + + // List of IPv4 relay addresses for which this subnet is selected. + "relay": { + "ip-addresses": [ + "192.168.56.1" + ] + }, + + // Subnet-level value of the renew timer. + "renew-timer": 30, + + // Enumeration specifying the server's mode of operation when it + // fetches host reservations. + // "reservation-mode": "all", + // It is replaced by the "reservations-global", + // "reservations-in-subnet", and + // "reservations-out-of-pool" parameters. + + // Specify whether the server should look up global reservations. + "reservations-global": false, + + // Specify whether the server should look up in-subnet reservations. + "reservations-in-subnet": true, + + // Specify whether the server can assume that all reserved + // addresses are out-of-pool. + // Ignored when reservations-in-subnet is false. + "reservations-out-of-pool": false, + + // Subnet-level compute T1 and T2 timers. + "calculate-tee-times": true, + + // T1 = valid lifetime * .5. + "t1-percent": .5, + + // T2 = valid lifetime * .75. + "t2-percent": .75, + + // Cache threshold = valid lifetime * .25. + "cache-threshold": .25, + + // Subnet-level cache maximum. + "cache-max-age": 1000, + + // List of static IPv4 reservations assigned to clients belonging + // to this subnet. For a detailed example, see reservations.json. + "reservations": [ + { + // Identifier used for client matching. Supported values are + // "hw-address", "client-id", "duid", "circuit-id", "flex-id". + "circuit-id": "01:11:22:33:44:55:66", + + // Reserved IP address. + "ip-address": "192.0.2.204", + + // Hostname. + "hostname": "foo.example.org", + + // Reservation-specific option data. + "option-data": [ + { + // Option name. + "name": "vivso-suboptions", + + // Option data. + "data": "4491" + } + ] + } + ], + + // List of client classes which must be evaluated when this subnet + // is selected for client assignments. + "require-client-classes": [ "late" ], + + // Subnet-level server hostname set in 'sname' field. + "server-hostname": "", + + // Subnet prefix. + "subnet": "192.0.0.0/8", + + // Subnet-level (default) valid lifetime. + "valid-lifetime": 6000, + + // Subnet-level min valid lifetime. + "min-valid-lifetime": 4000, + + // Subnet-level max valid lifetime. + "max-valid-lifetime": 8000 + } + ], + + // Shared-network level (default) valid lifetime. + "valid-lifetime": 6001, + + // Shared-network level min valid lifetime. + "min-valid-lifetime": 4001, + + // Shared-network level max valid lifetime. + "max-valid-lifetime": 8001 + } + ], + + // Global server hostname set in the 'sname' field. + "server-hostname": "", + + // List of IPv4 subnets which don't belong to any shared network. + "subnet4": [], + + // Global valid lifetime value. + "valid-lifetime": 6000, + + // Global min valid lifetime value. + "min-valid-lifetime": 4000, + + // Global max valid lifetime value. + "max-valid-lifetime": 8000, + + // Reservations (examples are in other files). + "reservations": [], + + // Configuration control (currently not used, i.e. this syntax + // is already defined but the corresponding feature is not implemented). + "config-control": { + // Only the configuration databases entry is defined. + "config-databases": [ + { + // Name of the database to connect to. + "name": "config", + + // Type of database, e.g. "mysql", "postgresql". + "type": "mysql" + } + ], + // Interval between attempts to fetch configuration updates + // via the configuration backends used. + "config-fetch-wait-time": 30 + }, + + // Server tag. + "server-tag": "my DHCPv4 server", + + // DHCP queue-control parameters. + "dhcp-queue-control": { + // Enable queue is mandatory. + "enable-queue": true, + + // Queue type is mandatory. + "queue-type": "kea-ring4", + + // Capacity is optional. + "capacity": 64 + }, + + // Fetches host reservations. + // "reservation-mode": "all", + // It is replaced by the "reservations-global", + // "reservations-in-subnet", and "reservations-out-of-pool" parameters. + + // Specify whether the server should look up global reservations. + "reservations-global": false, + + // Specify whether the server should look up in-subnet reservations. + "reservations-in-subnet": true, + + // Specify whether the server can assume that all reserved addresses + // are out-of-pool. + // Ignored when reservations-in-subnet is false. + // If specified, it is inherited by "shared-networks" and + // "subnet4" levels. + "reservations-out-of-pool": false, + + // Global compute T1 and T2 timers. + "calculate-tee-times": true, + + // T1 = valid lifetime * .5. + "t1-percent": .5, + + // T2 = valid lifetime * .75. + "t2-percent": .75, + + // Cache threshold = valid lifetime * .25. + "cache-threshold": .25, + + // Global cache maximum. + "cache-max-age": 1000, + + // String of zero or more characters with which to replace each + // invalid character in the hostname or Client FQDN. The default + // value is an empty string, which will cause invalid characters + // to be omitted rather than replaced. + "hostname-char-replacement": "x", + + // Regular expression describing the invalid character set in + // the hostname or Client FQDN. + "hostname-char-set": "[^A-Za-z0-9.-]", + + // List of loggers used by the servers using this configuration file. + "loggers": [ + { + // Debug level, a value between 0..99. The greater the value + // the more detailed the debug log. + "debuglevel": 99, + + // Name of the logger. + "name": "kea-dhcp4", + + // Configures how the log should be output. + "output-options": [ + { + // Determines whether the log should be flushed to a file. + "flush": true, + + // Specifies maximum filesize before the file is rotated. + "maxsize": 10240000, + + // Specifies the maximum number of rotated files to be kept. + "maxver": 1, + + // Specifies the logging destination. + "output": "stdout", + + // Specifies log entry content + "pattern": "%D{%Y-%m-%d %H:%M:%S.%q} %-5p [%c/%i] %m\n" + } + ], + + // Specifies logging severity, i.e. "ERROR", "WARN", "INFO", "DEBUG". + "severity": "INFO" + } + ], + + // If greater than zero, it is the lifetime of leases temporarily allocated + // on DISCOVER. When zero (the default), leases are not allocated on DISCOVER. + "offer-lifetime" : 60, + + // Look at advanced examples for the use of user-contexts. + "user-context": { } + } +} diff --git a/doc/examples/kea4/all-options.json b/doc/examples/kea4/all-options.json new file mode 100644 index 0000000..f74dfcf --- /dev/null +++ b/doc/examples/kea4/all-options.json @@ -0,0 +1,1889 @@ +// This example configuration file for DHCPv4 server in Kea contains: +// +// - data for all the standard options +// - custom option definitions at global level along with some associated +// option data +// - custom option data with standardized option spaces other than "dhcp4" +// - custom option spaces +// - option embedding examples +// +// The reader is strongly encouraged to take a look at the option formats +// documented in the Kea ARM: +// https://kea.readthedocs.io/en/latest/arm/dhcp4-srv.html?highlight=list%20of%20standard%20dhcpv4#id2 + +{ + "Dhcp4": { + /* + Data for all standard option definitions + */ + // Option data defined globally + "option-data": [ + /* + Code Len Time Offset + +-----+-----+-----+-----+-----+-----+ + | 2 | 4 | n1 | n2 | n3 | n4 | + +-----+-----+-----+-----+-----+-----+ + */ + // Type: int32 + { + "code": 2, + "data": "-25200", + "name": "time-offset" + }, + + /* + Code Len Address 1 Address 2 + +-----+-----+-----+-----+-----+-----+-----+-----+-- + | 3 | n | a1 | a2 | a3 | a4 | a1 | a2 | ... + +-----+-----+-----+-----+-----+-----+-----+-----+-- + */ + // Type: array of {IPv4 address} + { + "code": 3, + "data": "192.0.2.2, 192.0.2.3", + "name": "routers" + }, + + /* + Code Len Address 1 Address 2 + +-----+-----+-----+-----+-----+-----+-----+-----+-- + | 4 | n | a1 | a2 | a3 | a4 | a1 | a2 | ... + +-----+-----+-----+-----+-----+-----+-----+-----+-- + */ + // Type: array of {IPv4 address} + { + "code": 4, + "data": "192.0.2.4, 192.0.2.5", + "name": "time-servers" + }, + + /* + Code Len Address 1 Address 2 + +-----+-----+-----+-----+-----+-----+-----+-----+-- + | 5 | n | a1 | a2 | a3 | a4 | a1 | a2 | ... + +-----+-----+-----+-----+-----+-----+-----+-----+-- + */ + // Type: array of {IPv4 address} + { + "code": 5, + "data": "192.0.2.6, 192.0.2.7", + "name": "name-servers" + }, + + /* + Code Len Address 1 Address 2 + +-----+-----+-----+-----+-----+-----+-----+-----+-- + | 6 | n | a1 | a2 | a3 | a4 | a1 | a2 | ... + +-----+-----+-----+-----+-----+-----+-----+-----+-- + */ + // Type: array of {IPv4 address} + { + "code": 6, + "data": "192.0.2.8, 192.0.2.9", + "name": "domain-name-servers" + }, + + /* + Code Len Address 1 Address 2 + +-----+-----+-----+-----+-----+-----+-----+-----+-- + | 7 | n | a1 | a2 | a3 | a4 | a1 | a2 | ... + +-----+-----+-----+-----+-----+-----+-----+-----+-- + */ + // Type: array of {IPv4 address} + { + "code": 7, + "data": "192.0.2.10, 192.0.2.11", + "name": "log-servers" + }, + + /* + Code Len Address 1 Address 2 + +-----+-----+-----+-----+-----+-----+-----+-----+-- + | 8 | n | a1 | a2 | a3 | a4 | a1 | a2 | ... + +-----+-----+-----+-----+-----+-----+-----+-----+-- + */ + // Type: array of {IPv4 address} + { + "code": 8, + "data": "192.0.2.12, 192.0.2.13", + "name": "cookie-servers" + }, + + /* + Code Len Address 1 Address 2 + +-----+-----+-----+-----+-----+-----+-----+-----+-- + | 9 | n | a1 | a2 | a3 | a4 | a1 | a2 | ... + +-----+-----+-----+-----+-----+-----+-----+-----+-- + */ + // Type: array of {IPv4 address} + { + "code": 9, + "data": "192.0.2.14, 192.0.2.15", + "name": "lpr-servers" + }, + + /* + Code Len Address 1 Address 2 + +-----+-----+-----+-----+-----+-----+-----+-----+-- + | 10 | n | a1 | a2 | a3 | a4 | a1 | a2 | ... + +-----+-----+-----+-----+-----+-----+-----+-----+-- + */ + // Type: array of {IPv4 address} + { + "code": 10, + "data": "192.0.2.16, 192.0.2.17", + "name": "impress-servers" + }, + + /* + Code Len Address 1 Address 2 + +-----+-----+-----+-----+-----+-----+-----+-----+-- + | 11 | n | a1 | a2 | a3 | a4 | a1 | a2 | ... + +-----+-----+-----+-----+-----+-----+-----+-----+-- + */ + // Type: array of {IPv4 address} + { + "code": 11, + "data": "192.0.2.18, 192.0.2.19", + "name": "resource-location-servers" + }, + + /* + Code Len File Size + +-----+-----+-----+-----+ + | 13 | 2 | l1 | l2 | + +-----+-----+-----+-----+ + */ + // Type: uint16 + { + "code": 13, + "data": "1024", + "name": "boot-size" + }, + + /* + Code Len Dump File Pathname + +-----+-----+-----+-----+-----+-----+--- + | 14 | n | n1 | n2 | n3 | n4 | ... + +-----+-----+-----+-----+-----+-----+--- + */ + // Type: string + { + "code": 14, + "data": "/etc/crash-dump.img", + "name": "merit-dump" + }, + + /* + Code Len Domain Name + +-----+-----+-----+-----+-----+-----+-- + | 15 | n | d1 | d2 | d3 | d4 | ... + +-----+-----+-----+-----+-----+-----+-- + */ + // Type: FQDN + { + "code": 15, + "data": "my.example.org", + "name": "domain-name" + }, + + /* + Code Len Swap Server Address + +-----+-----+-----+-----+-----+-----+ + | 16 | n | a1 | a2 | a3 | a4 | + +-----+-----+-----+-----+-----+-----+ + */ + // Type: IPv4 address + { + "code": 16, + "data": "192.0.2.20", + "name": "swap-server" + }, + + /* + Code Len Root Disk Pathname + +-----+-----+-----+-----+-----+-----+--- + | 17 | n | n1 | n2 | n3 | n4 | ... + +-----+-----+-----+-----+-----+-----+--- + */ + // Type: string + { + "code": 17, + "data": "/path/to/root", + "name": "root-path" + }, + + /* + Code Len Extensions Pathname + +-----+-----+-----+-----+-----+-----+--- + | 18 | n | n1 | n2 | n3 | n4 | ... + +-----+-----+-----+-----+-----+-----+--- + */ + // Type: string + { + "code": 18, + "data": "/path/to/extensions", + "name": "extensions-path" + }, + + /* + Code Len Value + +-----+-----+-----+ + | 19 | 1 | 0/1 | + +-----+-----+-----+ + */ + // Type: boolean + { + "code": 19, + "data": "true", + "name": "ip-forwarding" + }, + + /* + Code Len Value + +-----+-----+-----+ + | 20 | 1 | 0/1 | + +-----+-----+-----+ + */ + // Type: boolean + { + "code": 20, + "data": "true", + "name": "non-local-source-routing" + }, + + /* + Code Len Address 1 Mask 1 + +-----+-----+-----+-----+-----+-----+-----+-----+-----+-----+ + | 21 | n | a1 | a2 | a3 | a4 | m1 | m2 | m3 | m4 | + +-----+-----+-----+-----+-----+-----+-----+-----+-----+-----+ + Address 2 Mask 2 + +-----+-----+-----+-----+-----+-----+-----+-----+--- + | a1 | a2 | a3 | a4 | m1 | m2 | m3 | m4 | ... + +-----+-----+-----+-----+-----+-----+-----+-----+--- + */ + // Type: array of {IPv4 address} + { + "code": 21, + "data": "10.229.0.128, 255.255.255.128, 10.27.129.0, 255.255.255.0", + "name": "policy-filter" + }, + + /* + Code Len Size + +-----+-----+-----+-----+ + | 22 | 2 | s1 | s2 | + +-----+-----+-----+-----+ + */ + // Type: uint16 + { + "code": 22, + "data": "2048", + "name": "max-dgram-reassembly" + }, + + /* + Code Len TTL + +-----+-----+-----+ + | 23 | 1 | ttl | + +-----+-----+-----+ + */ + // Type: uint8 + { + "code": 23, + "data": "248", + "name": "default-ip-ttl" + }, + + /* + Code Len Timeout + +-----+-----+-----+-----+-----+-----+ + | 24 | 4 | t1 | t2 | t3 | t4 | + +-----+-----+-----+-----+-----+-----+ + */ + // Type: uint32 + { + "code": 24, + "data": "131072", + "name": "path-mtu-aging-timeout" + }, + + /* + Code Len Size 1 Size 2 + +-----+-----+-----+-----+-----+-----+--- + | 25 | n | s1 | s2 | s1 | s2 | ... + +-----+-----+-----+-----+-----+-----+--- + */ + // Type: array of {uint16} + { + "code": 25, + "data": "3072, 4096", + "name": "path-mtu-plateau-table" + }, + + /* + Code Len MTU + +-----+-----+-----+-----+ + | 26 | 2 | m1 | m2 | + +-----+-----+-----+-----+ + */ + // Type: uint16 + { + "code": 26, + "data": "5120", + "name": "interface-mtu" + }, + + /* + Code Len Value + +-----+-----+-----+ + | 27 | 1 | 0/1 | + +-----+-----+-----+ + */ + // Type: boolean + { + "code": 27, + "data": "true", + "name": "all-subnets-local" + }, + + /* + Code Len Broadcast Address + +-----+-----+-----+-----+-----+-----+ + | 28 | 4 | b1 | b2 | b3 | b4 | + +-----+-----+-----+-----+-----+-----+ + */ + // Type: IPv4 address + { + "code": 28, + "data": "192.0.2.255", + "name": "broadcast-address" + }, + + /* + Code Len Value + +-----+-----+-----+ + | 29 | 1 | 0/1 | + +-----+-----+-----+ + */ + // Type: boolean + { + "code": 29, + "data": "true", + "name": "perform-mask-discovery" + }, + + /* + Code Len Value + +-----+-----+-----+ + | 30 | 1 | 0/1 | + +-----+-----+-----+ + */ + // Type: boolean + { + "code": 30, + "data": "true", + "name": "mask-supplier" + }, + + /* + Code Len Value + +-----+-----+-----+ + | 31 | 1 | 0/1 | + +-----+-----+-----+ + */ + // Type: boolean + { + "code": 31, + "data": "true", + "name": "router-discovery" + }, + + /* + Code Len Address + +-----+-----+-----+-----+-----+-----+ + | 32 | 4 | a1 | a2 | a3 | a4 | + +-----+-----+-----+-----+-----+-----+ + */ + // Type: IPv4 address + { + "code": 32, + "data": "192.0.2.23", + "name": "router-solicitation-address" + }, + + /* + Code Len Destination 1 Router 1 + +-----+-----+-----+-----+-----+-----+-----+-----+-----+-----+ + | 33 | n | d1 | d2 | d3 | d4 | r1 | r2 | r3 | r4 | + +-----+-----+-----+-----+-----+-----+-----+-----+-----+-----+ + Destination 2 Router 2 + +-----+-----+-----+-----+-----+-----+-----+-----+--- + | d1 | d2 | d3 | d4 | r1 | r2 | r3 | r4 | ... + +-----+-----+-----+-----+-----+-----+-----+-----+--- + */ + // Type: array of {IPv4 address} + { + "code": 33, + "data": "192.0.2.24, 192.0.2.25", + "name": "static-routes" + }, + + /* + Code Len Value + +-----+-----+-----+ + | 34 | 1 | 0/1 | + +-----+-----+-----+ + */ + // Type: boolean + { + "code": 34, + "data": "true", + "name": "trailer-encapsulation" + }, + + /* + Code Len Time + +-----+-----+-----+-----+-----+-----+ + | 35 | 4 | t1 | t2 | t3 | t4 | + +-----+-----+-----+-----+-----+-----+ + */ + // Type: uint32 + { + "code": 35, + "data": "196608", + "name": "arp-cache-timeout" + }, + + /* + Code Len Value + +-----+-----+-----+ + | 36 | 1 | 0/1 | + +-----+-----+-----+ + */ + // Type: boolean + { + "code": 36, + "data": "true", + "name": "ieee802-3-encapsulation" + }, + + /* + Code Len TTL + +-----+-----+-----+ + | 37 | 1 | n | + +-----+-----+-----+ + */ + // Type: uint8 + { + "code": 37, + "data": "124", + "name": "default-tcp-ttl" + }, + + /* + Code Len Time + +-----+-----+-----+-----+-----+-----+ + | 38 | 4 | t1 | t2 | t3 | t4 | + +-----+-----+-----+-----+-----+-----+ + */ + // Type: uint32 + { + "code": 38, + "data": "262144", + "name": "tcp-keepalive-interval" + }, + + /* + Code Len Value + +-----+-----+-----+ + | 39 | 1 | 0/1 | + +-----+-----+-----+ + */ + // Type: boolean + { + "code": 39, + "data": "true", + "name": "tcp-keepalive-garbage" + }, + + /* + Code Len NIS Domain Name + +-----+-----+-----+-----+-----+-----+--- + | 40 | n | n1 | n2 | n3 | n4 | ... + +-----+-----+-----+-----+-----+-----+--- + */ + // Type: string + { + "code": 40, + "data": "nis.example.org", + "name": "nis-domain" + }, + + /* + Code Len Address 1 Address 2 + +-----+-----+-----+-----+-----+-----+-----+-----+-- + | 41 | n | a1 | a2 | a3 | a4 | a1 | a2 | ... + +-----+-----+-----+-----+-----+-----+-----+-----+-- + */ + // Type: array of {IPv4 address} + { + "code": 41, + "data": "192.0.2.26, 192.0.2.27", + "name": "nis-servers" + }, + + /* + Code Len Address 1 Address 2 + +-----+-----+-----+-----+-----+-----+-----+-----+-- + | 42 | n | a1 | a2 | a3 | a4 | a1 | a2 | ... + +-----+-----+-----+-----+-----+-----+-----+-----+-- + */ + // Type: array of {IPv4 address} + { + "code": 42, + "data": "192.0.2.28, 192.0.2.29", + "name": "ntp-servers" + }, + + /* + Code Len Vendor-specific information + +-----+-----+-----+-----+--- + | 43 | n | i1 | i2 | ... + +-----+-----+-----+-----+--- + + Code Len Data item Code Len Data item Code + +-----+-----+-----+-----+-----+-----+-----+-----+-----+-----+-----+ + | T1 | n | d1 | d2 | ... | T2 | n | D1 | D2 | ... | ... | + +-----+-----+-----+-----+-----+-----+-----+-----+-----+-----+-----+ + */ + // Type: empty + { + "code": 43, + "name": "vendor-encapsulated-options" + }, + + /* + Code Len Address 1 Address 2 + +-----+-----+-----+-----+-----+-----+-----+-----+-----+-----+---- + | 44 | n | a1 | a2 | a3 | a4 | b1 | b2 | b3 | b4 | ... + +-----+-----+-----+-----+-----+-----+-----+-----+-----+-----+---- + */ + // Type: array of {IPv4 address} + { + "code": 44, + "data": "192.0.2.30, 192.0.2.31", + "name": "netbios-name-servers" + }, + + /* + Code Len Address 1 Address 2 + +-----+-----+-----+-----+-----+-----+-----+-----+-----+-----+---- + | 45 | n | a1 | a2 | a3 | a4 | b1 | b2 | b3 | b4 | ... + +-----+-----+-----+-----+-----+-----+-----+-----+-----+-----+---- + */ + // Type: array of {IPv4 address} + { + "code": 45, + "data": "192.0.2.32, 192.0.2.33", + "name": "netbios-dd-server" + }, + + /* + Value Node Type + ----- --------- + 0x1 B-node + 0x2 P-node + 0x4 M-node + 0x8 H-node + + Code Len Node Type + +-----+-----+-----------+ + | 46 | 1 | see above | + +-----+-----+-----------+ + */ + // Type: uint8 + { + "code": 46, + "data": "0x1", + "name": "netbios-node-type" + }, + + /* + Code Len NetBIOS Scope + +-----+-----+-----+-----+-----+-----+---- + | 47 | n | s1 | s2 | s3 | s4 | ... + +-----+-----+-----+-----+-----+-----+---- + */ + // Type: string + { + "code": 47, + "data": "scope42", + "name": "netbios-scope" + }, + + /* + Code Len Address 1 Address 2 + +-----+-----+-----+-----+-----+-----+-----+-----+--- + | 48 | n | a1 | a2 | a3 | a4 | a1 | a2 | ... + +-----+-----+-----+-----+-----+-----+-----+-----+--- + */ + // Type: array of {IPv4 address} + { + "code": 48, + "data": "192.0.2.34, 192.0.2.35", + "name": "font-servers" + }, + + /* + Code Len Address 1 Address 2 + +-----+-----+-----+-----+-----+-----+-----+-----+--- + | 49 | n | a1 | a2 | a3 | a4 | a1 | a2 | ... + +-----+-----+-----+-----+-----+-----+-----+-----+--- + */ + // Type: array of {IPv4 address} + { + "code": 49, + "data": "192.0.2.36, 192.0.2.37", + "name": "x-display-manager" + }, + + /* + Value Meaning + ----- -------- + 1 the 'file' field is used to hold options + 2 the 'sname' field is used to hold options + 3 both fields are used to hold options + + Code Len Value + +-----+-----+-----+ + | 52 | 1 |1/2/3| + +-----+-----+-----+ + */ + // Type: uint8 + { + "code": 52, + "data": "3", + "name": "dhcp-option-overload" + }, + + /* + Code Len Address + +-----+-----+-----+-----+-----+-----+ + | 54 | 4 | a1 | a2 | a3 | a4 | + +-----+-----+-----+-----+-----+-----+ + */ + // Type: IPv4 address + { + "code": 54, + "data": "192.0.2.39", + "name": "dhcp-server-identifier" + }, + + /* + Code Len Text + +-----+-----+-----+-----+--- + | 56 | n | c1 | c2 | ... + +-----+-----+-----+-----+--- + */ + // Type: string + { + "code": 56, + "data": "Error: here is a DHCPNAK!", + "name": "dhcp-message" + }, + + /* + Code Len Length + +-----+-----+-----+-----+ + | 57 | 2 | l1 | l2 | + +-----+-----+-----+-----+ + */ + // Type: uint16 + { + "code": 57, + "data": "1536", + "name": "dhcp-max-message-size" + }, + + /* + Code Len Vendor class Identifier + +-----+-----+-----+-----+--- + | 60 | n | i1 | i2 | ... + +-----+-----+-----+-----+--- + */ + // Type: string + { + "code": 60, + "data": "ISC", + "name": "vendor-class-identifier" + }, + + /* + Code Len NetWare/IP Domain Name + +-----+-----+------+------+------+----- + | 62 | n | c1 | c2 | c3 | ... + +-----+-----+------+------+------+----- + */ + // Type: string + { + "code": 62, + "data": "nwip.example.org", + "name": "nwip-domain-name" + }, + + /* + Code Len NetWare/IP General Info + +-----+-----+----+----+ + | 63 | 11 | 2 | 0 | + +-----+-----+----+----+ + NWIP_EXIST_IN_OPTIONS_AREA (length 0) + + +----+----+----+ + | 5 | 1 | 1 | + +----+----+----+ + NSQ_BROADCAST_SERVER (length 1) + value is YES + + +----+----+------------+ + | 7 | 4 | IP address | + +----+----+------------+ + NEAREST_NWIP_SERVER (length 4) + value is IP address of server + */ + // Type: binary + { + "code": 63, + "data": "1A BB AD AB BA D0 00 00 00 00 00 00 00 00 CA FE", + "name": "nwip-suboptions" + }, + + /* + Code Len NIS Client Domain Name + +-----+-----+-----+-----+-----+-----+--- + | 64 | n | n1 | n2 | n3 | n4 | ... + +-----+-----+-----+-----+-----+-----+--- + */ + // Type: string + { + "code": 64, + "data": "nisplus.example.org", + "name": "nisplus-domain-name" + }, + + /* + Code Len Address 1 Address 2 + +-----+-----+-----+-----+-----+-----+-----+-----+-- + | 65 | n | a1 | a2 | a3 | a4 | a1 | a2 | ... + +-----+-----+-----+-----+-----+-----+-----+-----+-- + */ + // Type: IPv4 address + { + "code": 65, + "data": "192.0.2.40", + "name": "nisplus-servers" + }, + + /* + Code Len TFTP server + +-----+-----+-----+-----+-----+--- + | 66 | n | c1 | c2 | c3 | ... + +-----+-----+-----+-----+-----+--- + */ + // Type: string + { + "code": 66, + "data": "tftp.example.org", + "name": "tftp-server-name" + }, + + /* + Code Len Bootfile name + +-----+-----+-----+-----+-----+--- + | 67 | n | c1 | c2 | c3 | ... + +-----+-----+-----+-----+-----+--- + */ + // Type: string + { + "code": 67, + "data": "boot-file.img", + "name": "boot-file-name" + }, + + /* + Code Len Home Agent Addresses (zero or more) + +-----+-----+-----+-----+-----+-----+-- + | 68 | n | a1 | a2 | a3 | a4 | ... + +-----+-----+-----+-----+-----+-----+-- + */ + // Type: array of {IPv4 address} + { + "code": 68, + "data": "192.0.2.41, 192.0.2.42", + "name": "mobile-ip-home-agent" + }, + + /* + Code Len Address 1 Address 2 + +-----+-----+-----+-----+-----+-----+-----+-----+-- + | 69 | n | a1 | a2 | a3 | a4 | a1 | a2 | ... + +-----+-----+-----+-----+-----+-----+-----+-----+-- + */ + // Type: array of {IPv4 address} + { + "code": 69, + "data": "192.0.2.43, 192.0.2.44", + "name": "smtp-server" + }, + + /* + Code Len Address 1 Address 2 + +-----+-----+-----+-----+-----+-----+-----+-----+-- + | 70 | n | a1 | a2 | a3 | a4 | a1 | a2 | ... + +-----+-----+-----+-----+-----+-----+-----+-----+-- + */ + // Type: array of {IPv4 address} + { + "code": 70, + "data": "192.0.2.45, 192.0.2.46", + "name": "pop-server" + }, + + /* + Code Len Address 1 Address 2 + +-----+-----+-----+-----+-----+-----+-----+-----+-- + | 71 | n | a1 | a2 | a3 | a4 | a1 | a2 | ... + +-----+-----+-----+-----+-----+-----+-----+-----+-- + */ + // Type: array of {IPv4 address} + { + "code": 71, + "data": "192.0.2.47, 192.0.2.48", + "name": "nntp-server" + }, + + /* + Code Len Address 1 Address 2 + +-----+-----+-----+-----+-----+-----+-----+-----+-- + | 72 | n | a1 | a2 | a3 | a4 | a1 | a2 | ... + +-----+-----+-----+-----+-----+-----+-----+-----+-- + */ + // Type: array of {IPv4 address} + { + "code": 72, + "data": "192.0.2.49, 192.0.2.50", + "name": "www-server" + }, + + /* + Code Len Address 1 Address 2 + +-----+-----+-----+-----+-----+-----+-----+-----+-- + | 73 | n | a1 | a2 | a3 | a4 | a1 | a2 | ... + +-----+-----+-----+-----+-----+-----+-----+-----+-- + */ + // Type: array of {IPv4 address} + { + "code": 73, + "data": "192.0.2.51, 192.0.2.52", + "name": "finger-server" + }, + + /* + Code Len Address 1 Address 2 + +-----+-----+-----+-----+-----+-----+-----+-----+-- + | 74 | n | a1 | a2 | a3 | a4 | a1 | a2 | ... + +-----+-----+-----+-----+-----+-----+-----+-----+-- + */ + // Type: array of {IPv4 address} + { + "code": 74, + "data": "192.0.2.53, 192.0.2.54", + "name": "irc-server" + }, + + /* + Code Len Address 1 Address 2 + +-----+-----+-----+-----+-----+-----+-----+-----+-- + | 75 | n | a1 | a2 | a3 | a4 | a1 | a2 | ... + +-----+-----+-----+-----+-----+-----+-----+-----+-- + */ + // Type: array of {IPv4 address} + { + "code": 75, + "data": "192.0.2.55, 192.0.2.56", + "name": "streettalk-server" + }, + + /* + Code Len Address 1 Address 2 + +-----+-----+-----+-----+-----+-----+-----+-----+-- + | 76 | n | a1 | a2 | a3 | a4 | a1 | a2 | ... + +-----+-----+-----+-----+-----+-----+-----+-----+-- + */ + // Type: array of {IPv4 address} + { + "code": 76, + "data": "192.0.2.57, 192.0.2.58", + "name": "streettalk-directory-assistance-server" + }, + + /* + Code Len Value + +-----+-----+--------------------- . . . --+ + | 77 | N | User Class Data ('Len' octets) | + +-----+-----+--------------------- . . . --+ + */ + // Type: binary + { + "code": 77, + "data": "1A BB AD AB BA D0 00 00 00 00 00 00 00 00 CA FE", + "name": "user-class" + }, + + /* + 0 1 2 3 + 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 + +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ + | Code = 78 | Length | Mandatory | a1 | + +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ + | a2 | a3 | a4 | ... + +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ + */ + // Type: boolean, array of {IPv4 address} + { + "code": 78, + "data": "true, 192.0.2.59, 192.0.2.60", + "name": "slp-directory-agent" + }, + + /* + 0 1 2 3 + 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 + +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ + | Code = 79 | Length | Mandatory | <Scope List>... + +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ + */ + // Type: boolean, string + { + "code": 79, + "data": "true, slp-scope", + "name": "slp-service-scope" + }, + + // Option code 80 is not defined in Kea. + // Option code 83 is not defined in Kea. + // Option code 84 is unassigned. + + /* + Code Len Address 1 Address 2 + +-----+-----+-----+-----+-----+-----+-----+-----+-----+-----+-- + | 85 | n | a1 | a2 | a3 | a4 | a1 | a2 | a3 | a4 | ... + +-----+-----+-----+-----+-----+-----+-----+-----+-----+-----+-- + */ + // Type: array of IPv4 address + { + "code": 85, + "data": "192.0.2.61, 192.0.2.62", + "name": "nds-servers" + }, + + /* + Code Len NDS Tree Name + +----+----+----+----+----+----+-- + | 86 | n | c1 | c2 | c3 | c4 | ... + +----+----+----+----+----+----+-- + */ + // Type: string + { + "code": 86, + "data": "my-tree", + "name": "nds-tree-name" + }, + + /* + Code Len Initial NDS Context + +----+----+----+----+----+----+-- + | 87 | n | c1 | c2 | c3 | c4 | ... + +----+----+----+----+----+----+-- + */ + // Type: string + { + "code": 87, + "data": "context", + "name": "nds-context" + }, + + /* + Code Len FQDN(s) of BCMCS Controller + +-----+-----+-----+-----+-----+-----+-----+-- + | 88 | n | s1 | s2 | s3 | s4 | s5 | ... + +-----+-----+-----+-----+-----+-----+-----+-- + */ + // Type: FQDN + { + "code": 88, + "data": "bcms-controller.example.org", + "name": "bcms-controller-names" + }, + + /* + Code Len Address 1 Address 2 + +-----+-----+-----+-----+-----+-----+-----+-- + | 89 | n | a1 | a2 | a3 | a4 | a1 | ... + +-----+-----+-----+-----+-----+-----+-----+-- + */ + // Type: array of {IPv4 address} + { + "code": 89, + "data": "192.0.2.63", + "name": "bcms-controller-address" + }, + + /* + Code Len 16-bit Type + +----+-----+-----+-----+ + | 93 | n | n1 | n2 | + +----+-----+-----+-----+ + */ + // Type: array of uint16 + { + "code": 93, + "data": "6144, 7168", + "name": "client-system" + }, + + /* + Code Len Type Major Minor + +----+-----+----+-----+-----+ + | 94 | 3 | t | M | m | + +----+-----+----+-----+-----+ + */ + // Type: uint8, uint8, uint8 + { + "code": 94, + "data": "0, 1, 0", + "name": "client-ndi" + }, + + // Option code 95 is unsupported. + // Option code 96 is unassigned. + + /* + Code Len Type Machine Identifier + +----+-----+----+-----+ . . . +-----+ + | 97 | n | t | | . . . | | + +----+-----+----+-----+ . . . +-----+ + */ + // Type: uint8, binary + { + "code": 97, + "data": "0, 1A BB AD AB BA D0 00 00 00 00 00 00 00 00 CA FE", + "name": "uuid-guid" + }, + + /* + 0 1 2 3 + 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 + +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ + | Code | Length | URL list + +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ + + Code 98 + + Length The length of the data field (i.e., URL list) in + bytes. + + URL list A list of one or more URLs separated by the ASCII + space character (0x20). + */ + // Type: string + { + "code": 98, + "data": "uap1.example.org uap2.example.org", + "name": "uap-servers" + }, + + /* + 0 1 2 3 + 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 + +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ + | GEOCONF_CIVIC | N | what | country | + +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ + | code | civic address elements ... + +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ + + Code GEOCONF_CIVIC: The code for this DHCP option is 99. + + N: The length of this option is variable. The minimum length is 3 + octets. + + what: The 'what' element describes to which location the DHCP entry + refers. Currently, three options are defined: the location of the + DHCP server (a value of 0), the location of the network element + believed to be closest to the client (a value of 1), or the + location of the client (a value of 2). Option (2) SHOULD be used, + but may not be known. Options (0) and (1) SHOULD NOT be used + unless it is known that the DHCP client is in close physical + proximity to the server or network element. + + country code: The two-letter ISO 3166 country code in capital ASCII + letters, e.g., DE or US. (Civic addresses always contain country + designations, suggesting the use of a fixed-format field to save + space.) + + civic address elements: Zero or more elements comprising the civic + and/or postal address, with the format described below + (Section 3.3). + */ + // Type: binary + { + "code": 99, + "data": "1A BB AD AB BA D0 00 00 00 00 00 00 00 00 CA FE", + "name": "geoconf-civic" + }, + + /* + PCode Len TZ-POSIX String + +-----+-----+------------------------------+ + | 100 | N | IEEE 1003.1 String | + +-----+-----+------------------------------+ + */ + // Type: string + { + "code": 100, + // String options that have a comma in their values need to have + // it escaped (i.e. each comma is preceded by two backslashes). + // That's because commas are reserved for separating fields in + // compound options. At the same time, we need to be conformant + // with JSON spec, that does not allow "\,". Therefore the + // slightly uncommon double backslashes notation is needed. + // The value sent over the wire is: + // EST5EDT4,M3.2.0/02:00,M11.1.0/02:00 + "data": "EST5EDT4\\,M3.2.0/02:00\\,M11.1.0/02:00", + "name": "pcode" + }, + + /* + TCode Len TZ-Database String + +-----+-----+------------------------------+ + | 101 | N | Reference to the TZ Database | + +-----+-----+------------------------------+ + */ + // Type: string + { + "code": 101, + "data": "Europe/Zurich", + "name": "tcode" + }, + + // Option codes 102-107 are unassigned. + + /* + 0 1 2 3 + 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 + +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ + | Code | Length | Value | + +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ + | Value (cont.) | + +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ + + Code: 8-bit identifier of the IPv6-Only Preferred option code as + assigned by IANA: 108. The client includes the Code in the + Parameter Request List in DHCPDISCOVER and DHCPREQUEST messages as + described in Section 3.2. + + Length: 8-bit unsigned integer. The length of the option, excluding + the Code and Length Fields. The server MUST set the length field + to 4. The client MUST ignore the IPv6-Only Preferred option if + the length field value is not 4. + + Value: 32-bit unsigned integer. The number of seconds for which the + client should disable DHCPv4 (V6ONLY_WAIT configuration variable). + If the server pool is explicitly configured with a V6ONLY_WAIT + timer, the server MUST set the field to that configured value. + Otherwise, the server MUST set it to zero. The client MUST + process that field as described in Section 3.2. + */ + // Type: uint32 + { + "code": 108, + "data": "3600", + "name": "v6-only-preferred" + }, + + // Option codes 109-111 are unassigned. + + // Type: array of {IPv4 address} + { + "code": 112, + "data": "192.0.2.63, 192.0.2.64", + "name": "netinfo-server-address" + }, + + // Type: string + { + "code": 113, + "data": "server1", + "name": "netinfo-server-tag" + }, + + // Type: string + { + "code": 114, + "data": "https://default.example.org", + "name": "v4-captive-portal" + }, + + // Option code 115 is unassigned. + + /* + Code Len Value + +-----+-----+-----+ + | 116 | 1 | a | + +-----+-----+-----+ + */ + // Type: uint8 + { + "code": 116, + "data": "1", + "name": "auto-config" + }, + + /* + Code Length Name Service Search Order in Sequence + 0 1 2 3 + 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 + +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ + | 117 | Len | ns1 | + +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ + | ns2 | ... | + +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ + */ + // Type: array of {uint16} + { + "code": 117, + "data": "6, 41, 44, 65", + "name": "name-service-search" + }, + + /* + Code Len IPv4 Address + +-----+-----+-----+-----+-----+-----+ + | 118 | 4 | A1 | A2 | A3 | A4 | + +-----+-----+-----+-----+-----+-----+ + */ + // Type: IPv4 address + { + "code": 118, + "data": "192.0.2.65", + "name": "subnet-selection" + }, + + /* + 0 1 2 3 + 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 + +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ + | 119 | Len | Searchstring... + +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ + | Searchstring... + +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ + */ + // Type: array of {FQDN} + { + "code": 119, + "data": "example.com, example.org", + "name": "domain-search" + }, + + // Option code 120 is not defined in Kea. + + /* + Code Len Destination 1 Router 1 + +-----+---+----+-----+----+----+----+----+----+ + | 121 | n | d1 | ... | dN | r1 | r2 | r3 | r4 | + +-----+---+----+-----+----+----+----+----+----+ + + Destination 2 Router 2 + +----+-----+----+----+----+----+----+ + | d1 | ... | dN | r1 | r2 | r3 | r4 | + +----+-----+----+----+----+----+----+ + + Destination 1...N Destination descriptors - describe the IP + subnet number and subnet mask of a particular + destination using a compact encoding. This + encoding consists of one octet describing + the width of the subnet mask, followed by all + the significant octets of the subnet number. + + Router 1...N The IP address of the router that should + be used to reach that destination. + */ + // Type: internal + { + "code": 121, + // please mind the convenience notation used: + // subnet1 - router1 IP addr, subnet2 - router2 IP addr, ..., subnetN - routerN IP addr + "data": "10.229.0.128/25 - 10.229.0.1, 10.198.122.47/32 - 10.198.122.1", + "name": "classless-static-route" + }, + + // Option codes 122-123 are not defined in Kea. + + /* + 1 1 1 1 1 1 + 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 + +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ + | option-code | option-len | + +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ + | enterprise-number1 | + | | + +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ + | data-len1 | | + +-+-+-+-+-+-+-+-+ | + / vendor-class-data1 / + +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ ---- + | enterprise-number2 | ^ + | | | + +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ | + | data-len2 | | optional + +-+-+-+-+-+-+-+-+ | | + / vendor-class-data2 / | + +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ | + ~ ... ~ V + +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ ---- + + option-code OPTION_V-I_VENDOR_CLASS (124) + + option-len total length of all following option data in + octets + + enterprise-numberN The vendor's 32-bit Enterprise Number as + registered with IANA [3] + + data-lenN Length of vendor-class-data field + + vendor-class-dataN Details of the hardware configuration of the + host on which the client is running, or of + industry consortium compliance + */ + // Type: uint32, binary + { + "code": 124, + "data": "4491, 0f BA AD AB BA D0 00 00 00 00 00 00 00 00 CA FE", + "name": "vivco-suboptions" + }, + + /* + 1 1 1 1 1 1 + 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 + +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ + | option-code | option-len | + +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ + | enterprise-number1 | + | | + +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ + | data-len1 | | + +-+-+-+-+-+-+-+-+ option-data1 | + / / + +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ ---- + | enterprise-number2 | ^ + | | | + +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ | + | data-len2 | | optional + +-+-+-+-+-+-+-+-+ option-data2 | | + / / | + +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ | + ~ ... ~ V + +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ ---- + + option-code OPTION_V-I_VENDOR_OPTS (125) + + option-len total length of all following option data in + octets + + enterprise-numberN The vendor's registered 32-bit Enterprise Number + as registered with IANA [3] + + data-lenN Length of option-data field + + option-dataN Vendor-specific options, described below + */ + // Type: uint32 + { + "code": 125, + "data": "4491", + "name": "vivso-suboptions" + }, + + // Option codes 126-127 are unassigned. + // Option codes 128-135 are not defined in Kea. + + /* + 0 1 + 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 + +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ + | option-code | option-length | + +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ + | | + + PAA IPv4 Address + + | | + +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ + | ... | + +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ + Figure 1: PAA DHCPv4 option + + option-code: OPTION_PANA_AGENT (136). + + option-length: Length of the 'options' field in octets; + MUST be a multiple of four (4). + + PAA IPv4 Address: IPv4 address of a PAA for the client to use. + The PAAs are listed in the order of preference + for use by the client. + */ + // Type: array of {IPv4 address} + { + "code": 136, + "data": "192.0.2.66, 192.0.2.67", + "name": "pana-agent" + }, + + /* + Code Len LoST Server Domain Name + +-----+-----+-----+-----+-----+-----+-----+---- + | 137 | n | s1 | s2 | s3 | s4 | s5 | ... + +-----+-----+-----+-----+-----+-----+-----+---- + */ + // Type: FQDN + { + "code": 137, + "data": "lost.example.org", + "name": "v4-lost" + }, + + /* + 0 1 + 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 + +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ + | option-code | option-length | + +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ + | | + + AC IPv4 Address + + | | + +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ + | ... | + +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ + + option-code: OPTION_CAPWAP_AC_V4 (138) + + option-length: Length of the 'options' field in octets; MUST be a + multiple of four (4). + + AC IPv4 Address: IPv4 address of a CAPWAP AC that the WTP may use. + The ACs are listed in the order of preference for use by the WTP + */ + // Type: array of {IPv4 address} + { + "code": 138, + "data": "192.0.2.68, 192.0.2.69", + "name": "capwap-ac-v4" + }, + + // Option codes 139-140 are not defined in Kea. + + /* + 0 1 2 3 + 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 + +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ + | 141 | Len | Searchstring... | + +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ + | Searchstring... | + +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ + */ + // Type: array of {FQDN} + { + "code": 141, + "data": "example.com, example.org", + "name": "sip-ua-cs-domains" + }, + + // Option code 142 is not defined in Kea. + + /* + 0 1 + 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 + +--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+ + | option-code (143) | option-length | + +--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+ + . . + . bootstrap-server-list (variable length) . + . . + +--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+ + + option-code: OPTION_V4_SZTP_REDIRECT (143) + + option-length: The option length in octets. + + bootstrap-server-list: A list of servers for the + client to attempt contacting, in order to obtain + further bootstrapping data. Each URI entry in the + bootstrap-server-list is structured as follows: + + +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-...-+-+-+-+-+-+-+ + | uri-length | URI | + +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-...-+-+-+-+-+-+-+ + + uri-length: 2 octets long; specifies the length of the URI data. + URI: URI of the SZTP bootstrap server. + */ + // Type: array of {tuple} + { + "code": 143, + "data": "https://sztp1.example.com:8443, https://sztp2.example.com:8444", + "name": "v4-sztp-redirect" + }, + + // Option codes 144-145 are not defined in Kea. + + // Type: uint8, IPv4 address, IPv4 address, array of {FQDN} + { + "code": 146, + "data": "1, 192.0.2.70, 192.0.2.71, example.com, example.org", + "name": "rdnss-selection" + }, + + // Option codes 147-158 are not defined in Kea. + + // Type: uint8, PSID + { + "code": 159, + "data": "2, 3/4", + "name": "v4-portparams" + }, + + // Option codes 160-161 are unassigned. + + /* + 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 + +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ + | OPTION_V4_DNR | Length | + +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ + ~ DNR Instance Data #1 ~ + +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ --- + . ... . | + +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ optional + ~ DNR Instance Data #n ~ | + +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ --- + + DNR Instance Data Format: + 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 + +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ + | DNR Instance Data Length | + +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ + | Service Priority | + +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ + | ADN Length | | + +-+-+-+-+-+-+-+-+ | + ~ authentication-domain-name ~ + +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ + | Addr Length | | + +-+-+-+-+-+-+-+-+ | + ~ IPv4 Address(es) ~ + | +-+-+-+-+-+-+-+-+ + | | | + +-+-+-+-+-+-+-+-+ | + ~Service Parameters (SvcParams) ~ + | | + +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ + + Code: OPTION_V4_DNR (162). + + Length: Indicates the length of the enclosed data in octets. + + DNR Instance Data: Includes the configuration data of an encrypted + DNS resolver. When several encrypted DNS resolvers are to be included, the "DNR + Instance Data" field is repeated. + + DNR Instance Data Length: Length of all following data in octets. + This field is set to ('ADN Length' + 3) when only an ADN is + provided for a DNR instance. + + Service Priority: The priority of this instance compared to other + DNR instances. This 16-bit unsigned integer is interpreted + following the rules specified in Section 2.4.1 of + [RFC9460]. + + ADN Length: Length of the authentication-domain-name in octets. + + authentication-domain-name (variable length): The authentication + domain name of the encrypted DNS resolver. This field is + formatted as specified in Section 10 of [RFC8415]. + + Addr Length: Length of included IPv4 addresses in octets. When + present, it MUST be a multiple of 4. + + IPv4 Address(es) (variable length): Indicates one or more IPv4 + addresses to reach the encrypted DNS resolver. Both private and + public IPv4 addresses can be included in this field. + + Service Parameters (SvcParams) (variable length): Specifies a set of + service parameters that are encoded following the rules in + Section 2.2 of [RFC9460]. + The length of this field is ('DNR Instance Data Length' - 4 - 'ADN + Length' - 'Addr Length'). + + Note that "Addr Length", "IPv4 Address(es)", and "Service Parameters + (SvcParams)" fields are not present if the ADN-only mode is used. + */ + // Type: internal + { + // DNR option may be configured using convenient notation. DNR Instances must be delimited with pipe "|" char. + // For each DNR Instance comma delimited fields must be provided: + // - service priority (mandatory), + // - ADN (mandatory), + // - IP address(es) (optional - if more than one - they must be space-separated) + // - SvcParams (optional - if more than one - they must be space-separated; + // to provide more than one alpn-id separate them with double-backslash escaped comma like in the + // example below). + // Note: whenever pipe "|" char needs to be used not as the delimiter, it must be escaped with + // double backslash, like in case of escaped commas in alpn-ids list. + // Basing on the config, Kea will encode the option according to RFC9463. + "code": 162, + "name": "v4-dnr", + "data": "1, resolver.example., 10.2.3.4 10.0.4.5, alpn=dot\\,doq\\,h2\\,h3 dohpath=/q{?dns} | 2, resolver.example., 10.0.5.6, alpn=dot port=8530 | 3, fooexp.resolver.example." + }, + + // Option codes 163-209 are unassigned. + + /* + 0 1 2 3 + 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 + +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ + | OPTION_6RD | option-length | IPv4MaskLen | 6rdPrefixLen | + +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ + | | + | 6rdPrefix | + | (16 octets) | + | | + | | + | | + +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ + | 6rdBRIPv4Address(es) | + . . + . . + . . + +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ + + option-code OPTION_6RD (212) + + option-length The length of the DHCP option in octets (22 + octets with one BR IPv4 address). + + IPv4MaskLen The number of high-order bits that are identical + across all CE IPv4 addresses within a given 6rd + domain. This may be any value between 0 and 32. + Any value greater than 32 is invalid. + + 6rdPrefixLen The IPv6 prefix length of the SP's 6rd IPv6 + prefix in number of bits. For the purpose of + bounds checking by DHCP option processing, the + sum of (32 - IPv4MaskLen) + 6rdPrefixLen MUST be + less than or equal to 128. + + 6rdBRIPv4Address One or more IPv4 addresses of the 6rd Border + Relay(s) for a given 6rd domain. + + 6rdPrefix The service provider's 6rd IPv6 prefix + represented as a 16-octet IPv6 address. The bits + in the prefix after the 6rdPrefixlen number of + bits are reserved and MUST be initialized to zero + by the sender and ignored by the receiver. + */ + // Type: uint8, uint8, IPv6 address, array of {IPv4 address} + { + "code": 212, + "data": "24, 96, 2001:db8::f001, 192.0.2.72, 192.0.2.73", + "name": "option-6rd" + }, + + /* + 0 1 2 3 + 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 + +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ + | Code | Length | Access Network Domain Name . + +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ + . Access Network Domain Name (cont.) . + . ... . + +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ + + option-code: OPTION_V4_ACCESS_DOMAIN (213). + + option-length: The length of the entire access network domain name + option in octets. + + option-value: The domain name associated with the access network, + encoded as described in Section 3.1. + */ + // Type: FQDN + { + "code": 213, + "data": "example.org", + "name": "v4-access-domain" + }, + + // Option codes 214-219 are unassigned. + // Option codes 220-221 are not defined in Kea. + // Option codes 222-254 are unassigned + + /* + Custom option data + */ + // See "option-def" below for the definitions. + { + "code": 1, + "name": "my-empty-option", + "space": "my-fancy-space" + }, + { + "code": 224, + "data": "192.0.2.74, 3/4, 1, example.org, string", + "name": "my-lengthy-option", + "space": "my-fancy-space" + }, + { + "code": 254, + "data": "127, 32767, 2147483647, 255, 65535, 4294967295, 192.0.2.75, 3/4, 1, example.org, string", + "name": "my-fancy-option", + "space": "my-fancy-space" + }, + { + "code": 232, + "name": "my-encapsulating-option", + "space": "my-encapsulating-space" + } + ], + + /* + Custom option definitions + */ + // For kea-dhcp4, custom option definitions can be global or in a client + // class. + "option-def": [ + // New option space allows for a new set of option codes. + // An empty option requires no "data" in "option-data". It's + // presence should be sufficient to trigger custom behavior. + { + "array": false, + "code": 1, + "encapsulate": "", + "name": "my-empty-option", + "record-types": "", + "space": "my-fancy-space", + "type": "empty" + }, + + // A custom type has "type" set to "record" and all data types (which need + // to be more than 1, otherwise you're better off using the type directly) + // are specified in "record-types". If "string" is part of them, it needs + // to be last. + { + "array": false, + "code": 224, + "encapsulate": "", + "name": "my-lengthy-option", + "record-types": "ipv4-address, psid, tuple, fqdn, string", + "space": "my-fancy-space", + "type": "record" + }, + + // Contains arrays of all types except strings since an array of strings + // is not a valid option definition. + { + "array": true, + "code": 254, + "encapsulate": "", + "name": "my-fancy-option", + "record-types": "int8, int16, int32, uint8, uint16, uint32, ipv4-address, psid, tuple, fqdn", + "space": "my-fancy-space", + "type": "record" + }, + + // A single encapsulating space can be used. An option containing any + // option from said space will now be unpacked successfully by Kea. + { + "array": false, + "code": 232, + "encapsulate": "my-fancy-space", + "name": "my-encapsulating-option", + "record-types": "", + "space": "my-encapsulating-space", + "type": "empty" + } + ], + + "subnet4": [ + /* + DOCSIS3 option data + */ + // Headers are as defined in CL-SP-CANN-DHCP-Reg-I16-200715. + // "space" is required to be explicitly defined as "docsis3-v4" + { + "option-data": [ + /* + 0 1 2 3 + 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 + +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ + | CL_V4OPTION_ORO| option-len | req-opt-code-1| req-opt-code-2| + +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ + | ... | + +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ + + option-code CL_V4OPTION_ORO (1). + + option-len number of requested options. + + req-opt-code-n The option code for an option requested by the client. + + */ + // Type: array of {uint8} + { + "code": 1, + "data": "32, 42", + "name": "oro", + "space": "docsis3-v4" + }, + + /* + 0 1 2 3 + 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 + +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ + | option code | option-len | IPv4 address of TFTP server 1 | + +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ + | address of server 1 (cont.) | IPv4 address of TFTP server 2 | + +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ + | address of server 2 (cont.) | ... + +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ + . ... | IPv4 address of TFTP server n | + +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ + | address of server n (cont.) | + +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ + + option code CL_VV4OPTION_TFTP_SERVERS (2) + + option len number of bytes for TFTP server IPv4 addresses (4*n for + n servers) + */ + // Type: array of {IPv4 address} + { + "code": 2, + "data": "192.0.2.76, 192.0.2.77", + "name": "tftp-servers", + "space": "docsis3-v4" + } + ], + "id": 1, + "subnet": "192.0.2.0/24" + } + ] + } +} diff --git a/doc/examples/kea4/backends.json b/doc/examples/kea4/backends.json new file mode 100644 index 0000000..62817c0 --- /dev/null +++ b/doc/examples/kea4/backends.json @@ -0,0 +1,107 @@ +// This is an example configuration file for the DHCPv4 server in Kea. +// It is a basic scenario with one IPv4 subnet configured. It demonstrates +// how to configure Kea to use various backends to store leases: +// - memfile +// - MySQL +// - PostgreSQL + +{ "Dhcp4": + +{ +// Kea is told to listen on eth0 interface only. + "interfaces-config": { + "interfaces": [ "eth0" ] + }, + +// We need to specify lease type. Exactly one lease-database section +// should be present. Make sure you uncomment only one. + +// 1. memfile backend. Leases information will be stored in flat CSV file. +// This is the easiest backend to use as it does not require any extra +// dependencies or services running. +// "lease-database": { +// "type": "memfile", +// "persist": true, +// "lfc-interval": 3600 +// }, + +// 2. MySQL backend. Leases will be stored in MySQL database. Make sure it +// is up, running and properly initialized. See kea-admin documentation +// for details on how to initialize the database. The only strictly required +// parameters are type and name. If other parameters are not specified, +// Kea will assume the database is available on localhost, that user and +// password is not necessary to connect and that timeout is 5 seconds. +// Kea must be compiled with --with-mysql option to use this backend. +// "lease-database": { +// "type": "mysql", +// "name": "keatest", +// "host": "localhost", +// "port": 3306, +// "user": "keatest", +// "password": "secret1", +// "reconnect-wait-time": 3000, // expressed in ms +// "max-reconnect-tries": 3, +// "on-fail": "stop-retry-exit", +// "retry-on-startup": false, +// "connect-timeout": 3 +// }, + +// 3. PostgreSQL backend. Leases will be stored in PostgreSQL database. Make +// sure it is up, running and properly initialized. See kea-admin documentation +// for details on how to initialize the database. The only strictly required +// parameters are type and name. If other parameters are not specified, +// Kea will assume the database is available on localhost, that user and +// password is not necessary to connect and that timeout is 5 seconds. +// Kea must be compiled with --with-pgsql option to use this backend. +// "lease-database": { +// "type": "postgresql", +// "name": "keatest", +// "host": "localhost", +// "port": 5432, +// "user": "keatest", +// "password": "secret1", +// "reconnect-wait-time": 3000, // expressed in ms +// "max-reconnect-tries": 3, +// "on-fail": "stop-retry-exit", +// "retry-on-startup": false, +// "connect-timeout": 3 +// }, + +// 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, + +// The following list defines subnets. We have only one subnet +// here. We tell Kea that it is directly available over local interface. + "subnet4": [ + { + "pools": [ { "pool": "192.0.2.1 - 192.0.2.200" } ], + "id":1 , + "subnet": "192.0.2.0/24", + "interface": "eth0" + } + ], + +// The following configures logging. It assumes that messages with at +// least informational level (info, warn, error and fatal) should be +// logged to stdout. + "loggers": [ + { + "name": "kea-dhcp4", + "output-options": [ + { + "output": "stdout" + } + ], + "severity": "INFO" + } + ] +} + +} diff --git a/doc/examples/kea4/classify.json b/doc/examples/kea4/classify.json new file mode 100644 index 0000000..9af06d8 --- /dev/null +++ b/doc/examples/kea4/classify.json @@ -0,0 +1,147 @@ +// This is an example configuration file for the DHCPv4 server in Kea. +// The purpose of this example is to showcase how clients can be classified. + +{ "Dhcp4": + +{ + +// Kea is told to listen on eth0 interface only. + "interfaces-config": { + "interfaces": [ "eth0" ] + }, + +// Let's use the simplest backend: memfile and use some reasonable values +// for timers. They are of no concern for the classification demonstration. + "lease-database": { "type": "memfile" }, + "renew-timer": 1000, + "rebind-timer": 2000, + "valid-lifetime": 4000, + +// This list defines several classes that incoming packets can be assigned to. +// One packet can belong to zero or more classes. + "client-classes": [ + +// The first class attempts to match the whole hardware address to a specific +// value. All incoming packets with that MAC address will get a special +// value of the option. If there are many hosts that require special +// treatment, it is much better to use host reservations. However, doing +// tricks with MAC addresses may prove useful in some cases, e.g. +// by matching OUI to known values we can detect certain vendors. + { + "name": "special_snowflake", + "test": "pkt4.mac == 0x010203040506", + "option-data": [{ + "name": "domain-name-servers", + "data": "127.0.0.1" + }] + }, + +// Let's classify all incoming DISCOVER (message type 1) to a separate +// class. + { + "name": "discovers", + "test": "pkt4.msgtype == 1" + }, + +// Clients are supposed to set the transaction-id field to a random value. +// Clients that send it with 0 are most likely broken. Let's mark them +// as such. + { + "name": "broken", + "test": "pkt4.transid == 0" + }, + +// Let's pick VoIP phones. Those that send their class identifiers +// as Aastra, should belong to VoIP class. For a list of all options, +// see www.iana.org/assignments/bootp-dhcp-parameters/. +// In this particular class, we want to set specific values +// of certain DHCPv4 fields. If the incoming packet matches the +// test, those fields will be set in outgoing responses. +// The option 43 is defined to encapsulate suboption in the aastra space. + { + "name": "VoIP", + "test": "substring(option[60].hex,0,6) == 'Aastra'", + "next-server": "192.0.2.254", + "server-hostname": "hal9000", + "boot-file-name": "/dev/null", + "option-def": [ { + "name": "vendor-encapsulated-options", + "code": 43, + "type": "empty", + "encapsulate": "aastra" } ] + } + + ], + +// The following list defines subnets. For some subnets we defined +// a class that is allowed in that subnet. If not specified, +// everyone is allowed. When a class is specified, only packets belonging +// to that class are allowed for that subnet. + "subnet4": [ + // This one is for VoIP devices only. + { + "pools": [ { "pool": "192.0.2.1 - 192.0.2.200" } ], + "id": 1, + "subnet": "192.0.2.0/24", + "client-class": "VoIP", + "interface": "eth0" + }, + + // This one doesn't have any client-class specified, so everyone + // is allowed in. The normal subnet selection rules still apply, + // though. There is also a static class reservation for a client + // using MAC address 1a:1b:1c:1d:1e:1f. This client will always + // be assigned to this class. + { + "pools": [ { "pool": "192.0.3.1 - 192.0.3.200" } ], + "id": 2, + "subnet": "192.0.3.0/24", + "reservations": [ + { + "hw-address": "1a:1b:1c:1d:1e:1f", + "client-classes": [ "VoIP" ] + } ], + "interface": "eth0" + }, + + // The following list defines a subnet with pools. For some pools + // we defined a class that is allowed in that pool. If not specified + // everyone is allowed. When a class is specified, only packets belonging + // to that class are allowed for that pool. + { + "pools": [ + // This one is for VoIP devices only. + { + "pool": "192.0.4.1 - 192.0.4.200", + "client-class": "VoIP" + }, + + // This one doesn't have any client-class specified, + // so everyone is allowed in. + { + "pool": "192.0.5.1 - 192.0.5.200" + } ], + + "subnet": "192.0.4.0/23", + "id": 3, + "interface": "eth1" + } + ], + +// The following configures logging. It assumes that messages with at +// least informational level (info, warn, error and fatal) should be +// logged to stdout. + "loggers": [ + { + "name": "kea-dhcp4", + "output-options": [ + { + "output": "stdout" + } + ], + "severity": "INFO" + } + ] +} + +} diff --git a/doc/examples/kea4/classify2.json b/doc/examples/kea4/classify2.json new file mode 100644 index 0000000..3bb48d2 --- /dev/null +++ b/doc/examples/kea4/classify2.json @@ -0,0 +1,180 @@ +// This is an example configuration file for the DHCPv4 server in Kea. +// The purpose of this example is to showcase how clients can be classified +// with advanced features. + +{ "Dhcp4": + +{ + +// Kea is told to listen on eth0 interface only. + "interfaces-config": { + "interfaces": [ "eth0" ] + }, + +// Let's use the simplest backend: memfile and use some reasonable values +// for timers. They are of no concern for the classification demonstration. + "lease-database": { "type": "memfile" }, + "renew-timer": 1000, + "rebind-timer": 2000, + "valid-lifetime": 4000, + +// This list defines several classes that incoming packets can be assigned to. +// One packet can belong to zero or more classes. + "client-classes": [ + +// This class is required by the second subnet and is evaluated only +// if it is required. The test expression returns true. +// Note it is not possible to depend on VoIP class because it is not yet +// defined. + { + "name": "second_subnet", + "only-if-required": true, + "test": "member('ALL')", + "option-data": [{ + "name": "domain-name-servers", + "data": "127.0.0.1" + }] + }, + +// Let's classify all incoming DISCOVER (message type 1) to a separate +// class. + { + "name": "discovers", + "test": "pkt4.msgtype == 1" + }, + +// Clients are supposed to set the transaction-id field to a random value. +// Clients that send it with 0 are most likely broken. Let's mark them +// as such. + { + "name": "broken", + "test": "pkt4.transid == 0" + }, + +// Let's pick VoIP phones. Those that send their class identifiers +// as Aastra, should belong to VoIP class. For a list of all options, +// see www.iana.org/assignments/bootp-dhcp-parameters/. +// In this particular class, we want to set specific values +// of certain DHCPv4 fields. If the incoming packet matches the +// test, those fields will be set in outgoing responses. +// The option 43 is defined to encapsulate suboption in the aastra space. + { + "name": "VoIP", + "test": "substring(option[60].hex,0,6) == 'Aastra'", + "next-server": "192.0.2.254", + "server-hostname": "hal9000", + "boot-file-name": "/dev/null", + "option-def": [ { + "name": "vendor-encapsulated-options", + "code": 43, + "type": "empty", + "encapsulate": "aastra" } ] + }, + +// Both a VoIP phone (by evaluation or host reservation) and has a host +// reservation. + { + "name": "VoIP_host", + "test": "member('VoIP') and member('KNOWN')", + "server-hostname": "hal9001" + } + + ], + +// The following list defines subnets. For some subnets we defined +// a class that is allowed in that subnet. If not specified, +// everyone is allowed. When a class is specified, only packets belonging +// to that class are allowed for that subnet. + "subnet4": [ + { +// This one is for VoIP devices only. + "pools": [ { "pool": "192.0.2.1 - 192.0.2.200" } ], + "id": 1, + "subnet": "192.0.2.0/24", + "client-class": "VoIP", + "interface": "eth0" + }, +// This one doesn't have any client-class specified, so everyone +// is allowed in. The normal subnet selection rules still apply, +// though. There is also a static class reservation for a client +// using MAC address 1a:1b:1c:1d:1e:1f. This client will always +// be assigned to this class. + { + "pools": [ { "pool": "192.0.3.1 - 192.0.3.200" } ], + "id": 2, + "subnet": "192.0.3.0/24", + "reservations": [ + { + "hw-address": "1a:1b:1c:1d:1e:1f", + "client-classes": [ "VoIP" ] + } ], + "interface": "eth0", + "require-client-classes": [ "second_subnet" ] + }, + +// The following list defines a subnet with pools. For some pools +// we defined a class that is allowed in that pool. If not specified +// everyone is allowed. When a class is specified, only packets belonging +// to that class are allowed for that pool. + { + "pools": [ + { +// This one is for VoIP devices only. + "pool": "192.0.4.1 - 192.0.4.200", + "client-class": "VoIP" + }, +// This one doesn't have any client-class specified, so everyone +// is allowed in. + { + "pool": "192.0.5.1 - 192.0.5.200" + } ], + "id": 3, + "subnet": "192.0.4.0/23", + "interface": "eth1" + }, +// This subnet is divided in two pools for unknown and known +// (i.e. which have a reservation) clients. The built-in KNOWN and +// UNKNOWN classes are set or not at host reservation lookup (KNOWN if +// this returns something, UNKNOWN if this finds nothing) and client +// classes depending on it are evaluated. +// This happens after subnet selection and before address allocation +// from pools. + { + "pools": [ + { + "pool": "192.0.8.100 - 192.0.8.200", + "client-class": "UNKNOWN" + }, + { + "pool": "192.0.9.100 - 192.0.9.200", + "client-class": "KNOWN" + } + ], + "id": 4, + "subnet": "192.0.8.0/23", + "reservations": [ + { "hw-address": "00:00:00:11:22:33", "hostname": "h1" }, + { "hw-address": "00:00:00:44:55:66", "hostname": "h4" }, + { "hw-address": "00:00:00:77:88:99", "hostname": "h7" }, + { "hw-address": "00:00:00:aa:bb:cc", "hostname": "ha" } + ] + } + ], + +// The following configures logging. It assumes that messages with at +// least informational level (info, warn, error and fatal) should be +// logged to stdout. + "loggers": [ + { + "name": "kea-dhcp4", + "output-options": [ + { + "output": "stdout" + } + ], + "severity": "INFO" + } + ] +} + +} diff --git a/doc/examples/kea4/comments.json b/doc/examples/kea4/comments.json new file mode 100644 index 0000000..a5cfbdc --- /dev/null +++ b/doc/examples/kea4/comments.json @@ -0,0 +1,113 @@ +// This is an example configuration file for the DHCPv4 server in Kea. +// It uses embedded (i.e., which will be included in configuration objects +// and not stripped by at lexical analysis) comments. + +{ "Dhcp4": + +{ + // Global scope + "comment": "A DHCPv4 server", + + // In interface config + "interfaces-config": { + "comment": "Use wildcard", + "interfaces": [ "*" ] }, + + // In option definitions + "option-def": [ { + "comment": "An option definition", + "name": "foo", + "code": 100, + "type": "ipv4-address", + "space": "isc" + } ], + + // In option data + "option-data": [ { + "comment": "Set option value", + "name": "dhcp-message", + "data": "ABCDEF0105", + "csv-format": false + } ], + + // In client classes + "client-classes": [ + { + "comment": "match all", + "name": "all", + "test": "'' == ''" + }, + // Of course comments are optional + { + "name": "none" + }, + // A comment and a user-context can be specified + { + "comment": "a comment", + "name": "both", + "user-context": { + "version": 1 + } + } + ], + + // In control socket (more for the agent) + "control-socket": { + "socket-type": "unix", + "socket-name": "/tmp/kea4-ctrl-socket", + "user-context": { "comment": "Indirect comment" } + }, + + // In shared networks + "shared-networks": [ { + "comment": "A shared network", + "name": "foo", + + // In subnets + "subnet4": [ + { + "comment": "A subnet", + "subnet": "192.0.1.0/24", + "id": 100, + + // In pools + "pools": [ + { + "comment": "A pool", + "pool": "192.0.1.1-192.0.1.10" + } + ], + + // In host reservations + "reservations": [ + { + "comment": "A host reservation", + "hw-address": "AA:BB:CC:DD:EE:FF", + "hostname": "foo.example.com", + + // Again in an option data + "option-data": [ { + "comment": "An option in a reservation", + "name": "domain-name", + "data": "example.com" + } ] + } + ] + } + ] + } ], + + // In dhcp ddns + "dhcp-ddns": { + "comment": "No dynamic DNS", + "enable-updates": false + }, + + // In loggers + "loggers": [ { + "comment": "A logger", + "name": "kea-dhcp4" + } ] +} + +} diff --git a/doc/examples/kea4/config-backend.json b/doc/examples/kea4/config-backend.json new file mode 100644 index 0000000..82d36fb --- /dev/null +++ b/doc/examples/kea4/config-backend.json @@ -0,0 +1,91 @@ +// This is an example configuration file for the DHCPv4 server in Kea. +// It demonstrates how to enable Kea Configuration Backend using MySQL. +// It requires that libdhcp_mysql_cb.so library is available and +// optionally libdhcp_cb_cmds.so hook library. + +{ "Dhcp4": + +{ + // Set the server tag for the configuration backend. This instance will + // be named server1. Every configuration element that is applicable to + // either "all" or "server1" will be used by this instance. + "server-tag": "server1", + + // Kea is told to listen on eth0 interface only. + "interfaces-config": { + "interfaces": [ "eth0" ] + }, + + // Use memfile lease database backend. + "lease-database": { + "type": "memfile", + "lfc-interval": 3600 + }, + + // This parameter controls how the server accesses the configuration + // database. Currently only one database type is available - "mysql". + // It requires that the libdhcp_mysql_cb.so hook library is loaded. + "config-control": { + // A list of database backends to connect to. Currently, it is limited + // to a single backend. + "config-databases": [ + { + "type": "mysql", + "reconnect-wait-time": 3000, // expressed in ms + "max-reconnect-tries": 3, + "name": "kea", + "user": "kea", + "password": "kea", + "host": "localhost", + "port": 3306 + } + ], + // Controls how often the server polls the database for the + // configuration updates. The setting below implies that it + // will take up to approx. 20 seconds for the server to + // discover and fetch configuration changes. + "config-fetch-wait-time": 20 + }, + + // This defines a control socket. If defined, Kea will open a UNIX socket + // and will listen for incoming commands. See section 17 of the Kea ARM for + // details. + "control-socket": { + "socket-type": "unix", + "socket-name": "/tmp/kea4-ctrl-socket" + }, + + // Hooks libraries that enable configuration backend are loaded. + "hooks-libraries": [ + // The libdhcp_mysql_cb.so is required to use MySQL Configuration + // Backend. + { + "library": "/usr/local/lib/kea/hooks/libdhcp_mysql_cb.so" + } + // The libdhcp_cb_cmds.so is optional. It allows for managing the + // configuration in the database. If this library is not loaded, + // the configuration can be managed directly using available + // tools that work directly with the MySQL database. + // ,{ + // "library": "/usr/local/lib/kea/hooks/libdhcp_cb_cmds.so" + // } + ], + + // The following configures logging. It assumes that messages with at + // least informational level (info, warn, error and fatal) should be + // logged to stdout. Alternatively, you can specify stderr here, a filename + // or 'syslog', which will store output messages via syslog. + "loggers": [ + { + "name": "kea-dhcp4", + "output-options": [ + { + "output": "stdout" + } + ], + "severity": "INFO" + } + ] +} + +} diff --git a/doc/examples/kea4/dhcpv4-over-dhcpv6.json b/doc/examples/kea4/dhcpv4-over-dhcpv6.json new file mode 100644 index 0000000..c622c42 --- /dev/null +++ b/doc/examples/kea4/dhcpv4-over-dhcpv6.json @@ -0,0 +1,48 @@ +// This is an example configuration file for the DHCPv4 server of +// DHCPv4-over-DHCPv6 tests in Kea. + +{ + +// DHCPv4 conf +"Dhcp4": +{ + "interfaces-config": { + "interfaces": [ "eth0" ] + }, + + "lease-database": { + "type": "memfile", + "name": "/tmp/kea-dhcp4.csv", + "lfc-interval": 3600 + }, + + "valid-lifetime": 4000, + + "subnet4": [ + { + "id": 100, + "subnet": "10.10.10.0/24", +// Don't forget the "4o6-" before "interface" here! + "4o6-interface": "eth0", + "4o6-subnet": "2001:db8:1:1::/64", + "pools": [ { "pool": "10.10.10.100 - 10.10.10.199" } ] } + ], + +// This enables DHCPv4-over-DHCPv6 support + "dhcp4o6-port": 6767, + + "loggers": [ + { + "name": "kea-dhcp4", + "output-options": [ + { + "output": "/tmp/kea-dhcp4.log" + } + ], + "severity": "DEBUG", + "debuglevel": 0 + } + ] +} + +} diff --git a/doc/examples/kea4/global-reservations.json b/doc/examples/kea4/global-reservations.json new file mode 100644 index 0000000..37cba50 --- /dev/null +++ b/doc/examples/kea4/global-reservations.json @@ -0,0 +1,178 @@ +// This is an example configuration file for the DHCPv4 server in Kea. +// It demonstrates how global host reservations can be configured. +// The global reservations are not associated with any subnet. They +// are assigned regardless of the subnet to which the DHCP client belongs. +// Global reservations are assigned to the DHCP clients using the +// same host identifier types as subnet specific reservations. This file +// contains multiple examples of host reservations using different +// identifier types, e.g. MAC address, client identifier etc. +{ "Dhcp4": + +{ +// Kea is told to listen on eth0 interface only. + "interfaces-config": { + "interfaces": [ "eth0" ] + }, + +// We need to specify the database used to store leases. As of June +// 2022, three database backends are supported: MySQL, PostgreSQL and +// the in-memory database, Memfile. We'll use memfile because it doesn't +// require any prior set up. + "lease-database": { + "type": "memfile", + "lfc-interval": 3600 + }, + +// 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, + +// Kea supports reservations by several different types of identifiers: +// hw-address (hardware/MAC address of the client), duid (DUID inserted by the +// client), client-id (client identifier inserted by the client), circuit-id +// (circuit identifier inserted by the relay agent) and flex-id (flexible +// identifier available when flex_id hook library is loaded). When told to do +// so, Kea can check for all of those identifier types, but it takes a costly +// database lookup to do so. It is therefore useful from a performance +// perspective to use only the reservation types that are actually used in a +// given network. + +// The example below is not optimal from a performance perspective, but it +// nicely showcases the host reservation capabilities. Please use the minimum +// set of identifier types used in your network. + "host-reservation-identifiers": [ "circuit-id", "hw-address", "duid", + "client-id", "flex-id" ], + +// This directive tells Kea that reservations are global. Note that this +// can also be specified at shared network and/or subnet level. +// "reservation-mode": "global", +// It is replaced by the "reservations-global", "reservations-in-subnet", and +// "reservations-out-of-pool" parameters. + +// Specify whether the server should look up global reservations. + "reservations-global": true, + +// Specify whether the server should look up in-subnet reservations. + "reservations-in-subnet": false, + +// Specify whether the server can assume that all reserved addresses +// are out-of-pool. +// Ignored when reservations-in-subnet is false. +// If specified, it is inherited by "shared-networks" and "subnet4" levels. + "reservations-out-of-pool": false, + +// Define several global host reservations. + "reservations": [ + +// This is a reservation for a specific hardware/MAC address. It's a very +// simple reservation: just an address and nothing else. +// Note it is not recommended but still allowed to reverse addresses at +// the global scope: as it breaks the link between the reservation and +// the subnet it can lead to a client localized in another subnet than +// its address belongs to. + { + "hw-address": "1a:1b:1c:1d:1e:1f", + "ip-address": "192.0.2.201" + }, + +// This is a reservation for a specific client-id. It also shows +// the this client will get a reserved hostname. A hostname can be defined +// for any identifier type, not just client-id. Either a hostname or +// an address is required. + { + "client-id": "01:11:22:33:44:55:66", + "hostname": "special-snowflake" + }, + +// The third reservation is based on DUID. This reservation also +// defines special option values for this particular client. If +// the domain-name-servers option would have been defined on a global, +// subnet or class level, the host specific values take precedence for +// this particular DHCP client. + { + "duid": "01:02:03:04:05", + "ip-address": "192.0.2.203", + "option-data": [ { + "name": "domain-name-servers", + "data": "10.1.1.202,10.1.1.203" + } ] + }, + +// The fourth reservation is based on circuit-id. This is an option inserted +// by the relay agent that forwards the packet from client to the server. +// In this example the host is also assigned vendor specific options. + { + "circuit-id": "01:11:22:33:44:55:66", + "ip-address": "192.0.2.204", + "option-data": [ + { + "name": "vivso-suboptions", + "data": "4491" + }, + { + "name": "tftp-servers", + "space": "vendor-4491", + "data": "10.1.1.202,10.1.1.203" + } + ] + }, + +// This reservation is for a client that needs specific DHCPv4 fields to be +// set. Three supported fields are next-server, server-hostname and +// boot-file-name + { + "client-id": "01:0a:0b:0c:0d:0e:0f", + "ip-address": "192.0.2.205", + "next-server": "192.0.2.1", + "server-hostname": "hal9000", + "boot-file-name": "/dev/null" + }, + +// This reservation is using flexible identifier. Instead of relying +// on specific field, sysadmin can define an expression similar to what +// is used for client classification, +// e.g. substring(relay[0].option[17],0,6). Then, based on the value of +// that expression for incoming packet, the reservation is matched. +// Expression can be specified either as hex or plain text using single +// quotes. +// Note: flexible identifier requires flex_id hook library to be +// loaded to work. + { + "flex-id": "'s0mEVaLue'", + "ip-address": "192.0.2.206" + } + ], + + // Define a subnet. + "subnet4": [ + { + "pools": [ { "pool": "192.0.2.1 - 192.0.2.200" } ], + "id": 1, + "subnet": "192.0.2.0/24", + "interface": "eth0" + } + ], + +// The following configures logging. It assumes that messages with at +// least informational level (info, warn, error and fatal) should be +// logged to stdout. + "loggers": [ + { + "name": "kea-dhcp4", + "output-options": [ + { + "output": "stdout" + } + ], + "severity": "INFO" + } + ] +} + +} diff --git a/doc/examples/kea4/ha-load-balancing-server1-mt-with-tls.json b/doc/examples/kea4/ha-load-balancing-server1-mt-with-tls.json new file mode 100644 index 0000000..9191216 --- /dev/null +++ b/doc/examples/kea4/ha-load-balancing-server1-mt-with-tls.json @@ -0,0 +1,284 @@ +// This is an example configuration of the Kea DHCPv4 server. It uses High +// Availability hook library and Lease Commands hook library to enable +// High Availability function for the DHCP server. Note that almost exactly +// the same configuration must be used on the second server (partner). +// The only difference is that "this-server-name" must be set to "server2" +// on this other server. Also, the interface configuration and location of TLS +// specific files depend on the network settings and configuration of the +// particular machine. +// +// The servers using this configuration work in load balancing mode. +{ + +// DHCPv4 configuration starts here. +"Dhcp4": { + // Add names of your network interfaces to listen on. + "interfaces-config": { + // The DHCPv4 server listens on this interface. + "interfaces": [ "eth0" ] + }, + + // Control socket is required for communication between the Control + // Agent and the DHCP server. High Availability with MT does not require + // Control Agent to be running because lease updates are sent over the + // RESTful API between the HA peers using the server dedicated listener. + // The Control Agent is used only to handle user commands. + "control-socket": { + "socket-type": "unix", + "socket-name": "/tmp/kea4-ctrl-socket" + }, + + // Multi-threading parameters. + "multi-threading": { + // By default, Kea processes packets on multiple threads if the hardware permits. + "enable-multi-threading": true, + + // When multi-threading is enabled, Kea will process packets on a + // number of multiple threads configurable through this option. + "thread-pool-size": 4, + + // When multi-threading is enabled, Kea will read packets from the + // interface and append a working item to the thread pool. This + // option configures the maximum number of items that can be queued. + "packet-queue-size": 64 + }, + + // Use Memfile lease database backend to store leases in a CSV file. + // Depending on how Kea was compiled, it may also support SQL databases + // (MySQL and/or PostgreSQL). Those database backends require more + // parameters, like name, host and possibly user and password. + // There are dedicated examples for each backend. See Section 7.2.2 "Lease + // Storage" for details. + "lease-database": { + // Memfile is the simplest and easiest backend to use. It's an in-memory + "type": "memfile" + }, + + // Client classes will associate address pools with certain servers taking + // part in providing High Availability. + "client-classes": [ + // phones class + { + "name": "phones", + "test": "substring(option[60].hex,0,6) == 'Aastra'" + }, + // laptops are everything but phones. + { + "name": "laptops", + "test": "not member('phones')" + }, + // Some phones will be handled by server1. Whether the HA_server1 + // or HA_server2 is assigned for the client is a matter of load + // balancing performed by the HA hook library. + { + "name": "phones_server1", + "test": "member('phones') and member('HA_server1')" + }, + // Some phones will be handled by server2. + { + "name": "phones_server2", + "test": "member('phones') and member('HA_server2')" + }, + // Some laptops will be handled by server1. + { + "name": "laptops_server1", + "test": "member('laptops') and member('HA_server1')" + }, + // Some laptops will be handled by server2. + { + "name": "laptops_server2", + "test": "member('laptops') and member('HA_server2')" + } + ], + + // HA requires two hook libraries to be loaded: libdhcp_lease_cmds.so and + // libdhcp_ha.so. The former handles incoming lease updates from the HA peers. + // The latter implements high availability feature for Kea. + "hooks-libraries": [ + // The lease_cmds library must be loaded because HA makes use of it to + // deliver lease updates to the server as well as synchronize the + // lease database after failure. + { + "library": "/opt/lib/kea/hooks/libdhcp_lease_cmds.so", + "parameters": { } + }, + { + // The HA hook library should be loaded. + "library": "/opt/lib/kea/hooks/libdhcp_ha.so", + "parameters": { + // High Availability configuration is specified for the HA hook library. + // Each server should have the same HA configuration, except for the + // "this-server-name" parameter. + "high-availability": [ { + // This parameter points to this server instance. The respective + // HA peers must have this parameter set to their own names. + "this-server-name": "server1", + // The HA mode is set to load-balancing. In this mode, the active + // servers share the traffic (50/50). + "mode": "load-balancing", + // Heartbeat is to be sent every 10 seconds if no other control + // commands are transmitted. + "heartbeat-delay": 10000, + // Maximum time for partner's response to a heartbeat, after which + // failure detection is started. This is specified in milliseconds. + "max-response-delay": 60000, + // The following parameters control how the server detects the + // partner's failure. The ACK delay sets the threshold for the + // 'secs' field of the received discovers. This is specified in + // milliseconds. + "max-ack-delay": 5000, + // This specifies the number of clients which send messages to + // the partner but appear to not receive any response. + "max-unacked-clients": 5, + // This specifies the maximum timeout (in milliseconds) for the server + // to complete sync. If you have a large deployment (high tens or + // hundreds of thausands of clients), you may need to increase it + // further. The default value is 60000ms (60 seconds). + "sync-timeout": 60000, + // To not experience performance degradation when the Kea server is + // processing packets on multiple threads, the High Availability module + // must have multi-threading enabled. + "multi-threading": { + // Enable High Availability to benefit from multi-threading. Default: true. + "enable-multi-threading": true, + // When running in MT mode, the dedicated listener is used to handle + // lease updates. + "http-dedicated-listener": true, + // The number of threads used to handle incoming requests. + // A value of 0 instructs the server to use the same number of + // threads that the Kea core is using for DHCP multi-threading. + "http-listener-threads": 0, + // The number of threads used to handle outgoing requests. + // A value of 0 instructs the server to use the same number of + // threads that the Kea core is using for DHCP multi-threading. + "http-client-threads": 0 + }, + "peers": [ + // This is the configuration of this server instance. + { + "name": "server1", + // This specifies the URL of this server instance. The + // Control Agent is not required to run along with this DHCPv4 server + // instance if multi-threading is enabled. + // The "http-host" and "http-port" values must be set to different + // values then the ones used by the Control Agent. + "url": "http://192.168.56.33:8000/", + // Trust anchor aka certificate authority file or directory. + "trust-anchor": "/usr/lib/kea/CA.pem", + // Client certificate file name. + "cert-file": "/usr/lib/kea/server1_cert.pem", + // Private key file name. + "key-file": "/usr/lib/kea/server1_key.pem", + // Client certificates are required and verified. + "require-client-certs": true, + // This server is primary. The other one must be + // secondary. + "role": "primary" + }, + // This is the configuration of the HA peer. + { + "name": "server2", + // Specifies the URL on which the partner's control + // channel can be reached. The Control Agent is not required + // to run on the partner's machine if multi-threading is enabled. + // The "http-host" and "http-port" values must be set to different + // values then the ones used by the Control Agent. + "url": "http://192.168.56.66:8000/", + // Trust anchor aka certificate authority file or directory. + "trust-anchor": "/usr/lib/kea/CA.pem", + // Client certificate file name. + "cert-file": "/usr/lib/kea/server2_cert.pem", + // Private key file name. + "key-file": "/usr/lib/kea/server2_key.pem", + // Client certificates are required and verified. + "require-client-certs": true, + // The partner is secondary. This server is primary. + "role": "secondary" + } + ] + } ] + } + } + ], + + // This example contains a single subnet declaration. + "subnet4": [ + { + // Subnet id. + "id": 1, + + // Subnet prefix. + "subnet": "192.0.3.0/24", + + // Specify four address pools. + "pools": [ + { + "pool": "192.0.3.100 - 192.0.3.125", + "client-class": "phones_server1" + }, + { + "pool": "192.0.3.126 - 192.0.3.150", + "client-class": "laptops_server1" + }, + { + "pool": "192.0.3.200 - 192.0.3.225", + "client-class": "phones_server2" + }, + { + "pool": "192.0.3.226 - 192.0.3.250", + "client-class": "laptops_server2" + } + ], + + // These are options that are subnet specific. In most cases, + // you need to define at least routers option, as without this + // option your clients will not be able to reach their default + // gateway and will not have Internet connectivity. + "option-data": [ + { + // For each IPv4 subnet you most likely need to specify at + // least one router. + "name": "routers", + "data": "192.0.3.1" + } + ], + + // This subnet will be selected for queries coming from the following + // IP address. + "relay": { "ip-address": "192.168.56.1" } + } + ], + +// The following configures logging. It assumes that messages with at +// least informational level (info, warn, error and fatal) should be +// logged to stdout. Alternatively, you can specify stderr here, a filename +// or 'syslog', which will store output messages via syslog. + "loggers": [ + { + // This section affects kea-dhcp4, which is the base logger for DHCPv4 + // component. It tells DHCPv4 server to write all log messages (on + // severity INFO or more) to a file. + "name": "kea-dhcp4", + "output-options": [ + { + "output": "stdout" + } + ], + "severity": "INFO", + "debuglevel": 0 + }, + { + // This section specifies configuration of the HA hook library-specific + // logger. + "name": "kea-dhcp4.ha-hooks", + "output-options": [ + { + "output": "stdout" + } + ], + "severity": "INFO", + "debuglevel": 99 + } + ] +} +} diff --git a/doc/examples/kea4/ha-load-balancing-server2-mt.json b/doc/examples/kea4/ha-load-balancing-server2-mt.json new file mode 100644 index 0000000..ab31cfa --- /dev/null +++ b/doc/examples/kea4/ha-load-balancing-server2-mt.json @@ -0,0 +1,267 @@ +// This is an example configuration of the Kea DHCPv4 server. It uses High +// Availability hook library and Lease Commands hook library to enable +// High Availability function for the DHCP server. Note that almost exactly +// the same configuration must be used on the second server (partner). +// The only difference is that "this-server-name" must be set to "server1" +// on this other server. Also, the interface configuration depends on the +// network settings of the particular machine. +// +// The servers using this configuration work in load balancing mode. +{ + +// DHCPv4 configuration starts here. +"Dhcp4": { + // Add names of your network interfaces to listen on. + "interfaces-config": { + // The DHCPv4 server listens on this interface. + "interfaces": [ "eth0" ] + }, + + // Control socket is required for communication between the Control + // Agent and the DHCP server. High Availability with MT does not require + // Control Agent to be running because lease updates are sent over the + // RESTful API between the HA peers using the server dedicated listener. + // The Control Agent is used only to handle user commands. + "control-socket": { + "socket-type": "unix", + "socket-name": "/tmp/kea4-ctrl-socket" + }, + + // Multi-threading parameters. + "multi-threading": { + // By default, Kea processes packets on multiple threads if the hardware permits. + "enable-multi-threading": true, + + // When multi-threading is enabled, Kea will process packets on a + // number of multiple threads configurable through this option. + "thread-pool-size": 4, + + // When multi-threading is enabled, Kea will read packets from the + // interface and append a working item to the thread pool. This + // option configures the maximum number of items that can be queued. + "packet-queue-size": 64 + }, + + // Use Memfile lease database backend to store leases in a CSV file. + // Depending on how Kea was compiled, it may also support SQL databases + // (MySQL and/or PostgreSQL). Those database backends require more + // parameters, like name, host and possibly user and password. + // There are dedicated examples for each backend. See Section 7.2.2 "Lease + // Storage" for details. + "lease-database": { + // Memfile is the simplest and easiest backend to use. It's an in-memory + "type": "memfile" + }, + + // Client classes will associate address pools with certain servers taking + // part in providing High Availability. + "client-classes": [ + // phones class + { + "name": "phones", + "test": "substring(option[60].hex,0,6) == 'Aastra'" + }, + // laptops are everything but phones. + { + "name": "laptops", + "test": "not member('phones')" + }, + // Some phones will be handled by server1. Whether the HA_server1 + // or HA_server2 is assigned for the client is a matter of load + // balancing performed by the HA hook library. + { + "name": "phones_server1", + "test": "member('phones') and member('HA_server1')" + }, + // Some phones will be handled by server2. + { + "name": "phones_server2", + "test": "member('phones') and member('HA_server2')" + }, + // Some laptops will be handled by server1. + { + "name": "laptops_server1", + "test": "member('laptops') and member('HA_server1')" + }, + // Some laptops will be handled by server2. + { + "name": "laptops_server2", + "test": "member('laptops') and member('HA_server2')" + } + ], + + // HA requires two hook libraries to be loaded: libdhcp_lease_cmds.so and + // libdhcp_ha.so. The former handles incoming lease updates from the HA peers. + // The latter implements high availability feature for Kea. + "hooks-libraries": [ + // The lease_cmds library must be loaded because HA makes use of it to + // deliver lease updates to the server as well as synchronize the + // lease database after failure. + { + "library": "/opt/lib/kea/hooks/libdhcp_lease_cmds.so", + "parameters": { } + }, + { + // The HA hook library should be loaded. + "library": "/opt/lib/kea/hooks/libdhcp_ha.so", + "parameters": { + // High Availability configuration is specified for the HA hook library. + // Each server should have the same HA configuration, except for the + // "this-server-name" parameter. + "high-availability": [ { + // This parameter points to this server instance. The respective + // HA peers must have this parameter set to their own names. + "this-server-name": "server2", + // The HA mode is set to load-balancing. In this mode, the active + // servers share the traffic (50/50). + "mode": "load-balancing", + // Heartbeat is to be sent every 10 seconds if no other control + // commands are transmitted. + "heartbeat-delay": 10000, + // Maximum time for partner's response to a heartbeat, after which + // failure detection is started. This is specified in milliseconds. + "max-response-delay": 60000, + // The following parameters control how the server detects the + // partner's failure. The ACK delay sets the threshold for the + // 'secs' field of the received discovers. This is specified in + // milliseconds. + "max-ack-delay": 5000, + // This specifies the number of clients which send messages to + // the partner but appear to not receive any response. + "max-unacked-clients": 5, + // This specifies the maximum timeout (in milliseconds) for the server + // to complete sync. If you have a large deployment (high tens or + // hundreds of thausands of clients), you may need to increase it + // further. The default value is 60000ms (60 seconds). + "sync-timeout": 60000, + // To not experience performance degradation when the Kea server is + // processing packets on multiple threads, the High Availability module + // must have multi-threading enabled. + "multi-threading": { + // Enable High Availability to benefit from multi-threading. Default: true. + "enable-multi-threading": true, + // When running in MT mode, the dedicated listener is used to handle + // lease updates. + "http-dedicated-listener": true, + // The number of threads used to handle incoming requests. + // A value of 0 instructs the server to use the same number of + // threads that the Kea core is using for DHCP multi-threading. + "http-listener-threads": 0, + // The number of threads used to handle outgoing requests. + // A value of 0 instructs the server to use the same number of + // threads that the Kea core is using for DHCP multi-threading. + "http-client-threads": 0 + }, + "peers": [ + // This is the configuration of the HA peer. + { + "name": "server1", + // Specifies the URL on which the partner's control + // channel can be reached. The Control Agent is not required + // to run on the partner's machine if multi-threading is enabled. + // The "http-host" and "http-port" values must be set to different + // values then the ones used by the Control Agent. + "url": "http://192.168.56.33:8000/", + // The partner is primary. This server is secondary. + "role": "primary" + }, + // This is the configuration of this server instance. + { + "name": "server2", + // This specifies the URL of this server instance. The + // Control Agent is not required to run along with this DHCPv4 server + // instance if multi-threading is enabled. + // The "http-host" and "http-port" values must be set to different + // values then the ones used by the Control Agent. + "url": "http://192.168.56.66:8000/", + // This server is secondary. The other one must be + // primary. + "role": "secondary" + } + ] + } ] + } + } + ], + + // This example contains a single subnet declaration. + "subnet4": [ + { + // Subnet id. + "id": 1, + + // Subnet prefix. + "subnet": "192.0.3.0/24", + + // Specify four address pools. + "pools": [ + { + "pool": "192.0.3.100 - 192.0.3.125", + "client-class": "phones_server1" + }, + { + "pool": "192.0.3.126 - 192.0.3.150", + "client-class": "laptops_server1" + }, + { + "pool": "192.0.3.200 - 192.0.3.225", + "client-class": "phones_server2" + }, + { + "pool": "192.0.3.226 - 192.0.3.250", + "client-class": "laptops_server2" + } + ], + + // These are options that are subnet specific. In most cases, + // you need to define at least routers option, as without this + // option your clients will not be able to reach their default + // gateway and will not have Internet connectivity. + "option-data": [ + { + // For each IPv4 subnet you most likely need to specify at + // least one router. + "name": "routers", + "data": "192.0.3.1" + } + ], + + // This subnet will be selected for queries coming from the following + // IP address. + "relay": { "ip-address": "192.168.56.1" } + } + ], + +// The following configures logging. It assumes that messages with at +// least informational level (info, warn, error and fatal) should be +// logged to stdout. Alternatively, you can specify stderr here, a filename +// or 'syslog', which will store output messages via syslog. + "loggers": [ + { + // This section affects kea-dhcp4, which is the base logger for DHCPv4 + // component. It tells DHCPv4 server to write all log messages (on + // severity INFO or more) to a file. + "name": "kea-dhcp4", + "output-options": [ + { + "output": "stdout" + } + ], + "severity": "INFO", + "debuglevel": 0 + }, + { + // This section specifies configuration of the HA hook library-specific + // logger. + "name": "kea-dhcp4.ha-hooks", + "output-options": [ + { + "output": "stdout" + } + ], + "severity": "INFO", + "debuglevel": 99 + } + ] +} +} diff --git a/doc/examples/kea4/hooks-radius.json b/doc/examples/kea4/hooks-radius.json new file mode 100644 index 0000000..164e6f8 --- /dev/null +++ b/doc/examples/kea4/hooks-radius.json @@ -0,0 +1,224 @@ +// This is an example configuration file for the DHCPv4 server in Kea +// illustrating the configuration of the RADIUS and Host Cache hook libraries. +// +// It is not intended to be used as is. It tries to showcase some of the +// parameters available. +// +// To use this configuration file, you need to have both RADIUS and +// Host Cache hooks. These are currently available to support customers only. +// +// clients get a wine name (option AOP code 250) divided into red and white. +// Expensive brands have a host entry, i.e. a reserved address. +// +// Names +// +// brouilly (red) +// chablis (white) +// chambertin (red, expensive) +// chinon (red) +// chiroubles (red) +// condrieu (white) +// cornas (red) +// corton (red) +// fleurie (red) +// givry (red) +// margaux (red, expensive) +// meursault (white) +// montrachet (white, expensive) +// morgon (red) +// muscadet (white) +// petrus (red, expensive) +// riesling (white) +// romanee (red, expensive) +// sylvaner (white) +// yquem (white, expensive) +// +// Address space is 192.0.2.0/24 with 10-99 for reds and 110-199 for whites. +// +// Reservations are given here in Kea/JSON style but they must be +// in the RADIUS server configuration: +// +// { +// "flex-id": "'chambertin'", +// "ip-address": "192.0.2.10" +// }, +// { +// "flex-id": "'margaux'", +// "ip-address": "192.0.2.11" +// }, +// { +// "flex-id": "'petrus'", +// "ip-address": "192.0.2.12" +// }, +// { +// "flex-id": "'romanee'", +// "ip-address": "192.0.2.13" +// }, +// { +// "flex-id": "'montrachet'", +// "ip-address": "192.0.2.110" +// }, +// { +// "flex-id": "'yquem'", +// "ip-address": "192.0.2.111" +// } +// + +{"Dhcp4": + +{ + // Kea is told to listen on specific interfaces only. + "interfaces-config": { + // You should probably list your network interfaces here (e.g. "eth1961") + "interfaces": [ "eth1961" ] + }, + + // Set up the storage for leases. + "lease-database": { + "type": "memfile" + }, + + // Note there is hosts-database defined. RADIUS and Host Cache libraries + // will create them dynamically. + + // RADIUS uses flex-id reservations, so restrict Kea to use flex-id only. + "host-reservation-identifiers": [ "flex-id" ], + + // Define the AOP option. + "option-def": [ { + "name": "AOP", + "code": 250, + "type": "string" } ], + + // Define red and white client classes. + // If they are not defined we can get spurious warnings. + "client-classes": [ + { "name": "red" }, + { "name": "white" } ], + + // Define a subnet. + "subnet4": [ { + // Set the subnet ID (aka RADIUS NAS port). + "id": 14, + "subnet": "192.0.2.0/24", + "interface": "eth1961", + "pools": [ + { + // Red pool (10-19 are for reservations) + "pool": "192.0.2.20-192.0.2.99", + "client-class": "red" + }, + { + // White pool (110-119 are for reservations) + "pool": "192.0.2.120-192.0.2.199", + "client-class": "white" + } + + // Note there are not pools available to anyone. This is + // important to note. This means that to get an address, the + // client needs to belong to red class, to white class or + // have an address reserved. + ] + } ], + + // Set up the hook libraries. + "hooks-libraries": [ + { + // Load the flex-id hook library. + "library": "/usr/local/lib/kea/hooks/libdhcp_flex_id.so", + + "parameters": { + // Take the ID from the AOP option. + "identifier-expression": "option[250].text", + + // Replace the client ID in queries by the flex-id. + // Currently required by access code. + // Required for accounting as it will become the lease ID too. + "replace-client-id": true + } + }, + { + // Load the host cache hook library. It is needed by the RADIUS + // library to keep the attributes from authorization to later user + // for accounting. + "library": "/usr/local/lib/kea/hooks/libdhcp_host_cache.so" + }, + { + // Load the RADIUS hook library. + "library": "/usr/local/lib/kea/hooks/libdhcp_radius.so", + + "parameters": { + // If do not use RFC 4361 + // "extract-duid": false, + + // If have conflicting subnets + // "reselect-subnet-pool": true, + + // Strip the 0 type added by flex-id + "client-id-pop0": true, + + // flex Id is printable (far easier for the RADIUS server config) + // Without this it will be in hexadecimal... + "client-id-printable": true, + + // Use the flex-id. + "identifier-type4": "flex-id", + + // Configure an access (aka authentication/authorization) server. + "access": { + + // This starts the list of access servers + "servers": [ + { + // These are parameters for the first (and only) access server + "name": "127.0.0.1", + "port": 1812, + "secret": "secret" + } + // Additional access servers could be specified here + ], + + // This define a list of additional attributes Kea will send to each + // access server in Access-Request. + "attributes": [ + { + // This attribute is identified by name (must be present in the + // dictionary) and has static value (i.e. the same value will be + // sent to every server for every packet) + "name": "Password", + "data": "mysecretpassword" + }, + { + // It's also possible to specify an attribute using its type, + // rather than a name. 77 is Connect-Info. The value is specified + // using hex. Again, this is a static value. It will be sent the + // same for every packet and to every server. + "type": 77, + "raw": "65666a6a71" + }, + { + // This example shows how an expression can be used to send dynamic + // value. The expression (see Section 13) may take any value from + // the incoming packet or even its metadata (e.g. the interface + // it was received over from) + "name": "Configuration-Token", + "expr": "pkt.iface" + } + ] // End of attributes + }, + + // Configure an accounting server. + "accounting": { + "servers": [ { + "name": "127.0.0.1", + "port": 1813, + "secret": "secret" + } + ] + } + } + } + ] +} + +} diff --git a/doc/examples/kea4/hooks.json b/doc/examples/kea4/hooks.json new file mode 100644 index 0000000..d82db2b --- /dev/null +++ b/doc/examples/kea4/hooks.json @@ -0,0 +1,50 @@ +// This is an example configuration file for the DHCPv4 server in Kea +// illustrating the configuration of hook libraries. It uses a basic scenario +// of one IPv4 subnet configured with the default values for all parameters. + +{"Dhcp4": + +{ +// Kea is told to listen on the eth0 interface only. + "interfaces-config": { + "interfaces": [ "eth0" ] + }, + +// Set up the storage for leases. + "lease-database": { + "type": "memfile" + }, + + "valid-lifetime": 1800, + +// Define a single subnet. + "subnet4": [ + { + "pools": [ { "pool": "192.0.2.1 - 192.0.2.200" } ], + "id": 1, + "subnet": "192.0.2.0/24", + "interface": "eth0" + } + ], + +// Set up the hook libraries. For this example, we assume that two libraries +// are loaded, called "security" and "charging". Note that order is important: +// "security" is specified first so if both libraries supply a hook function +// for a given hook, the function in "security" will be called before that in +// "charging". + + "hooks-libraries": [ + { + "library": "/opt/lib/security.so" + }, + { + "library": "/opt/lib/charging.so", + "parameters": { + "path": "/var/lib/kea", + "base-name": "kea-forensic6" + } + } + ] +} + +} diff --git a/doc/examples/kea4/leases-expiration.json b/doc/examples/kea4/leases-expiration.json new file mode 100644 index 0000000..427eb40 --- /dev/null +++ b/doc/examples/kea4/leases-expiration.json @@ -0,0 +1,76 @@ +// This is an example configuration file for the DHCPv4 server in Kea. +// It provides parameters controlling processing of expired leases, +// a.k.a. leases reclamation. + +{ "Dhcp4": + +{ +// Kea is told to listen on eth0 interface only. + "interfaces-config": { + "interfaces": [ "eth0" ] + }, + +// We need to specify the database used to store leases. As of +// June 2022, three database backends are supported: MySQL, +// PostgreSQL and the in-memory database, Memfile. +// We'll use memfile because it doesn't require any prior set up. +// Note, we're setting the maximum number of row read errors to 100, +// (defaults to 0, meaning unlimited). + "lease-database": { + "type": "memfile", + "lfc-interval": 3600, + "max-row-errors": 100 + }, + +// The following parameters control processing expired leases. Expired +// leases will be reclaimed periodically according to the +// "reclaim-timer-wait-time" parameter. Reclaimed leases will be held in +// the database for 1800s to facilitate lease affinity. After this +// period the leases will be removed. The frequency of removal is +// controlled by the "flush-reclaimed-timer-wait-time" parameter. The +// lease reclamation routine will process at most 500 leases or will +// last for at most 100ms, during a single run. If there are still some +// unreclaimed leases after 10 attempts, a warning message is issued. +// If both "flush-reclaimed-timer-wait-time" and "hold-reclaimed-time" are not +// 0, when the client sends a release message the lease is expired instead of +// being deleted from lease storage. + "expired-leases-processing": { + "reclaim-timer-wait-time": 5, + "hold-reclaimed-time": 1800, + "flush-reclaimed-timer-wait-time": 10, + "max-reclaim-leases": 500, + "max-reclaim-time": 100, + "unwarned-reclaim-cycles": 10 + }, + +// Addresses will be assigned with a lifetime of 4000 seconds. + "valid-lifetime": 4000, + +// The following list defines subnets. We have only one subnet +// here. We tell Kea that it is directly available over local interface. + "subnet4": [ + { + "pools": [ { "pool": "192.0.2.1 - 192.0.2.200" } ], + "id": 1, + "subnet": "192.0.2.0/24", + "interface": "eth0" + } + ], + +// The following configures logging. It assumes that messages with at +// least informational level (info, warn, error and fatal) should be +// logged to stdout. + "loggers": [ + { + "name": "kea-dhcp4", + "output-options": [ + { + "output": "stdout" + } + ], + "severity": "INFO" + } + ] +} + +} diff --git a/doc/examples/kea4/multiple-options.json b/doc/examples/kea4/multiple-options.json new file mode 100644 index 0000000..d8495b0 --- /dev/null +++ b/doc/examples/kea4/multiple-options.json @@ -0,0 +1,187 @@ +// 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 eth0 interface only. + "interfaces-config": { + "interfaces": [ "eth0" ] + }, + +// We need to specify the database used to store leases. As of +// June 2022, three database backends are supported: MySQL, +// PostgreSQL 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. + "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, + +// Defining a subnet. There are some DHCP options returned to the +// clients connected to this subnet. The first and third options are +// clients connected to this subnet. The first two options are +// identified by the name. The third option is identified by the +// option code. +// There is an address pool defined within this subnet. Pool +// specific value for option domain-name-servers is defined +// for the pool. + "subnet4": [ + { + "id": 1, + "subnet": "192.0.2.0/24", + "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" + }, + // Domain search is also a popular option. It tells the client to + // attempt to resolve names within those specified domains. For + // example, name "foo" would be attempted to be resolved as + // foo.mydomain.example.com and if it fails, then as + // foo.example.com + + { + "name": "domain-search", + "data": "mydomain.example.com, example.com" + }, + + // Options can also be specified using hexadecimal format. + // This should be avoided if possible, because Kea ability to + // validate correctness is limited when using hex values. + { + "name": "broadcast-address", + "csv-format": false, + "data": "ffff8000" + }, + + // String options that have a comma in their values need to have + // it escaped (i.e. each comma is preceded by two backslashes). + // That's because commas are reserved for separating fields in + // compound options. At the same time, we need to be conformant + // with JSON spec, that does not allow "\,". Therefore the + // slightly uncommon double backslashes notation is needed. + + // Legal JSON escapes are \ followed by "\/bfnrt character + // or \u followed by 4 hexa-decimal numbers (currently Kea + // supports only \u0000 to \u00ff code points). + // CSV processing translates '\\' into '\' and '\,' into ',' + // only so for instance '\x' is translated into '\x'. But + // as it works on a JSON string value each of these '\' + // characters must be doubled on JSON input. + { + "name": "boot-file-name", + "data": "EST5EDT4\\,M3.2.0/02:00\\,M11.1.0/02:00" + + }, + // 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" + }, + // At a few exceptions options are added to response only when + // the client requests them. The always-send flag should be used + // to enforce a particular option. + { + "name": "vendor-class-identifier", + "data": "isc", + "always-send": true + } + ], + + // Now we define pools. There are two pools here. + "pools": [ { + // This is the first pool. Nothing spectacular here, just a range + // of addresses. + "pool": "192.0.2.10 - 192.0.2.100" + + }, { + // This second pool is more interesting. Anyone who gets an + // address from this pool will also get this specific option + // value if asks for DNS servers configuration. This value, + // being more specific, overrides any values that were specified + // on either global or subnet scope. + "pool": "192.0.2.101 - 192.0.2.200", + "option-data": [ + { + "name": "domain-name-servers", + "data": "192.0.2.3, 192.0.2.4" + } + ] + } ] + } ], + +// The following configures logging. It assumes that messages with at +// least informational level (info, warn, error and fatal) should be +// logged to stdout. + "loggers": [ + { + "name": "kea-dhcp4", + "output-options": [ + { + "output": "stdout" + } + ], + "severity": "INFO" + } + ] +} + +} diff --git a/doc/examples/kea4/mysql-reservations.json b/doc/examples/kea4/mysql-reservations.json new file mode 100644 index 0000000..e8c0c22 --- /dev/null +++ b/doc/examples/kea4/mysql-reservations.json @@ -0,0 +1,103 @@ +// This is an example configuration file for the DHCPv4 server in Kea. +// It contains configuration of the MySQL host database backend, used +// to retrieve reserved addresses, host names, DHCPv4 message fields +// and DHCP options from MySQL database. +{ "Dhcp4": + +{ +// Kea is told to listen on eth0 interface only. + "interfaces-config": { + "interfaces": [ "eth0" ] + + }, + +// We need to specify the database used to store leases. As of +// June 2022, three database backends are supported: MySQL, +// PostgreSQL and the in-memory database, Memfile. +// We'll use memfile because it doesn't require any prior set up. + "lease-database": { + "type": "memfile", + "lfc-interval": 3600 + }, + +// 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, + + +// Kea supports reservations by several different types of +// identifiers: hw-address (hardware/MAC address of the client), duid +// (DUID inserted by the client), client-id (client identifier inserted +// by the client) and circuit-id (circuit identifier inserted by the +// relay agent). When told to do so, Kea can check for all of those +// identifier types, but it takes a costly database lookup to do so. It +// is therefore useful from a performance perspective to use only the +// reservation types that are actually used in a given network. + +// The example below is not optimal from a performance perspective, but it +// nicely showcases the host reservation capabilities. Please use the minimum +// set of identifier types used in your network. + "host-reservation-identifiers": + [ "circuit-id", "hw-address", "duid", "client-id" ], + +// Specify connection to the database holding host reservations. The type +// specifies that the MySQL database is used. user and password are the +// credentials used to connect to the database. host and name specify +// location of the host where the database instance is running, and the +// name of the database to use. The server processing a packet will first +// check if there are any reservations specified for this client in the +// reservations list, within the subnet (configuration file). If there are +// no reservations there, the server will try to retrieve reservations +// from this database. + "hosts-database": { + "type": "mysql", + "reconnect-wait-time": 3000, // expressed in ms + "max-reconnect-tries": 3, + "name": "keatest", + "user": "keatest", + "password": "keatest", + "host": "localhost", + "port": 3306, + "trust-anchor": "my-ca", + "cert-file": "my-cert", + "key-file": "my-key", + "cipher-list": "AES" + }, + +// Define a subnet with a single pool of dynamic addresses. Addresses from +// this pool will be assigned to clients which don't have reservations in the +// database. Subnet identifier is equal to 1. If this subnet is selected for +// the client, this subnet id will be used to search for the reservations +// within the database. + "subnet4": [ + { + "pools": [ { "pool": "192.0.2.10 - 192.0.2.200" } ], + "subnet": "192.0.2.0/24", + "interface": "eth0", + "id": 1 + } + ], + +// The following configures logging. It assumes that messages with at +// least informational level (info, warn, error and fatal) should be +// logged to stdout. + "loggers": [ + { + "name": "kea-dhcp4", + "output-options": [ + { + "output": "stdout" + } + ], + "severity": "INFO" + } + ] +} + +} diff --git a/doc/examples/kea4/pgsql-reservations.json b/doc/examples/kea4/pgsql-reservations.json new file mode 100644 index 0000000..6941fd0 --- /dev/null +++ b/doc/examples/kea4/pgsql-reservations.json @@ -0,0 +1,101 @@ +// This is an example configuration file for the DHCPv4 server in Kea. +// It contains configuration of the PostgreSQL host database backend, used +// to retrieve reserved addresses, host names, DHCPv4 message fields +// and DHCP options from PostgreSQL database. +{ "Dhcp4": + +{ +// Kea is told to listen on eth0 interface only. + "interfaces-config": { + "interfaces": [ "eth0" ] + }, + + +// We need to specify the database used to store leases. As of +// June 2022, three database backends are supported: MySQL, +// PostgreSQL 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. + "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, + + +// Kea supports reservations by several different types of +// identifiers: hw-address (hardware/MAC address of the client), duid +// (DUID inserted by the client), client-id (client identifier inserted +// by the client) and circuit-id (circuit identifier inserted by the +// relay agent). When told to do so, Kea can check for all of those +// identifier types, but it takes a costly database lookup to do so. It +// is therefore useful from a performance perspective to use only the +// reservation types that are actually used in a given network. + +// The example below is not optimal from a performance perspective, but it +// nicely showcases the host reservation capabilities. Please use the minimum +// set of identifier types used in your network. + "host-reservation-identifiers": + [ "circuit-id", "hw-address", "duid", "client-id" ], + +// Specify connection to the database holding host reservations. The type +// specifies that the PostgreSQL database is used. user and password are the +// credentials used to connect to the database. host and name specify +// location of the host where the database instance is running, and the +// name of the database to use. The server processing a packet will first +// check if there are any reservations specified for this client in the +// reservations list, within the subnet (configuration file). If there are +// no reservations there, the server will try to retrieve reservations +// from this database. +// The database specification can go into one hosts-database entry for +// backward compatibility or be listed in hosts-databases list. + "hosts-databases": [ + { + "type": "postgresql", + "reconnect-wait-time": 3000, // expressed in ms + "max-reconnect-tries": 3, + "name": "keatest", + "user": "keatest", + "password": "keatest", + "host": "localhost" + } + ], + +// Define a subnet with a single pool of dynamic addresses. Addresses from +// this pool will be assigned to clients which don't have reservations in the +// database. Subnet identifier is equal to 1. If this subnet is selected for +// the client, this subnet id will be used to search for the reservations +// within the database. + "subnet4": [ + { + "pools": [ { "pool": "192.0.2.10 - 192.0.2.200" } ], + "subnet": "192.0.2.0/24", + "interface": "eth0", + "id": 1 + } + ], + +// The following configures logging. It assumes that messages with at +// least informational level (info, warn, error and fatal) should be +// logged to stdout. + "loggers": [ + { + "name": "kea-dhcp4", + "output-options": [ + { + "output": "stdout" + } + ], + "severity": "INFO" + } + ] +} + +} diff --git a/doc/examples/kea4/reservations.json b/doc/examples/kea4/reservations.json new file mode 100644 index 0000000..da44c1b --- /dev/null +++ b/doc/examples/kea4/reservations.json @@ -0,0 +1,183 @@ +// This is an example configuration file for the DHCPv4 server in Kea. +// It contains one subnet in which there are two static address reservations +// for the clients identified by the MAC addresses. +{ "Dhcp4": + +{ +// Kea is told to listen on eth0 interface only. + "interfaces-config": { + "interfaces": [ "eth0" ] + }, + +// We need to specify the database used to store leases. As of April +// 2022, three database backends are supported: MySQL, PostgreSQL, and the +// in-memory database, Memfile. We'll use memfile because it doesn't +// require any prior set up. + "lease-database": { + "type": "memfile", + "lfc-interval": 3600 + }, + +// 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, + +// Kea supports reservations by several different types of identifiers: +// hw-address (hardware/MAC address of the client), duid (DUID inserted by the +// client), client-id (client identifier inserted by the client), circuit-id +// (circuit identifier inserted by the relay agent) and flex-id (flexible +// identifier available when flex_id hook library is loaded). When told to do +// so, Kea can check for all of those identifier types, but it takes a costly +// database lookup to do so. It is therefore useful from a performance +// perspective to use only the reservation types that are actually used in a +// given network. + +// The example below is not optimal from a performance perspective, but it +// nicely showcases the host reservation capabilities. Please use the minimum +// set of identifier types used in your network. +"host-reservation-identifiers": [ "circuit-id", "hw-address", "duid", + "client-id", "flex-id" ], + +// Define a subnet with four reservations. Some of the reservations belong +// to the dynamic pool. Kea is able to handle this case, but it is not +// recommended from a performance perspective, as Kea would not only need to +// check if a given address is free, but also whether it is reserved. +// To avoid this check, one can change reservation-mode to out-of-pool, rather +// than 'all'. If a subnet does not have reservations at all, the reservation +// lookup can be skipped altogether (reservation-mode is set to 'disabled'). +// The reservation-mode has been replaced by reservations-global, +// reservations-in-subnet and reservations-out-of-pool. + +// Note that the second reservation is for an address which is within the +// range of the pool of the dynamically allocated address. The server will +// exclude this address from this pool and only assign it to the client which +// has a reservation for it. + "subnet4": [ + { + "pools": [ { "pool": "192.0.2.1 - 192.0.2.200" } ], + "id": 1, + "subnet": "192.0.2.0/24", + "interface": "eth0", + // This directive tells Kea that reservations may be made both in-pool + // and out-of-pool. For improved performance, you may move all reservations + // out of the dynamic pool and change reservation-mode to "out-of-pool". + // Kea will then be able to skip querying for host reservations when + // assigning leases from dynamic pool. + // "reservation-mode": "all", + // It is replaced by the "reservations-global", "reservations-in-subnet" + // and "reservations-out-of-pool" parameters. + + // Specify whether the server should look up global reservations. + "reservations-global": false, + + // Specify whether the server should look up in-subnet reservations. + "reservations-in-subnet": true, + + // Specify whether the server can assume that all reserved addresses + // are out-of-pool. + // Ignored when reservations-in-subnet is false. + // If specified, it is inherited by "shared-networks" and + // "subnet4" levels. + "reservations-out-of-pool": false, + + "reservations": [ + +// This is a reservation for a specific hardware/MAC address. It's a very +// simple reservation: just an address and nothing else. + { + "hw-address": "1a:1b:1c:1d:1e:1f", + "ip-address": "192.0.2.201" + }, + +// This is a reservation for a specific client-id. It also shows +// the this client will get a reserved hostname. A hostname can be defined +// for any identifier type, not just client-id. + { + "client-id": "01:11:22:33:44:55:66", + "ip-address": "192.0.2.202", + "hostname": "special-snowflake" + }, + +// The third reservation is based on DUID. This reservation also +// defines special option values for this particular client. If +// the domain-name-servers option would have been defined on a global, +// subnet or class level, the host specific values take preference. + { + "duid": "01:02:03:04:05", + "ip-address": "192.0.2.203", + "option-data": [ { + "name": "domain-name-servers", + "data": "10.1.1.202,10.1.1.203" + } ] + }, + +// The fourth reservation is based on circuit-id. This is an option inserted +// by the relay agent that forwards the packet from client to the server. +// In this example the host is also assigned vendor specific options. + { + "circuit-id": "01:11:22:33:44:55:66", + "ip-address": "192.0.2.204", + "option-data": [ + { + "name": "vivso-suboptions", + "data": "4491" + }, + { + "name": "tftp-servers", + "space": "vendor-4491", + "data": "10.1.1.202,10.1.1.203" + } + ] + }, +// This reservation is for a client that needs specific DHCPv4 fields to be +// set. Three supported fields are next-server, server-hostname and +// boot-file-name + { + "client-id": "01:0a:0b:0c:0d:0e:0f", + "ip-address": "192.0.2.205", + "next-server": "192.0.2.1", + "server-hostname": "hal9000", + "boot-file-name": "/dev/null" + }, + +// This reservation is using flexible identifier. Instead of relying +// on specific field, sysadmin can define an expression similar to what +// is used for client classification, +// e.g. substring(relay[0].option[17],0,6). Then, based on the value of +// that expression for incoming packet, the reservation is matched. +// Expression can be specified either as hex or plain text using single +// quotes. +// Note: flexible identifier requires flex_id hook library to be +// loaded to work. + { + "flex-id": "'s0mEVaLue'", + "ip-address": "192.0.2.206" + } + + ] + } + ], + +// The following configures logging. It assumes that messages with at +// least informational level (info, warn, error and fatal) should be +// logged to stdout. + "loggers": [ + { + "name": "kea-dhcp4", + "output-options": [ + { + "output": "stdout" + } + ], + "severity": "INFO" + } + ] +} + +} diff --git a/doc/examples/kea4/several-subnets.json b/doc/examples/kea4/several-subnets.json new file mode 100644 index 0000000..6a9e1f5 --- /dev/null +++ b/doc/examples/kea4/several-subnets.json @@ -0,0 +1,86 @@ +// This is an example configuration file for DHCPv4 server in Kea. +// It's a basic scenario with three IPv4 subnets configured. In each +// subnet, there's a smaller pool of dynamic addresses. + +{ "Dhcp4": + +{ +// Kea is told to listen on eth0 interface only. + "interfaces-config": { + "interfaces": [ "eth0" ] + }, + +// We need to specify the database used to store leases. As of +// June 2022, three database backends are supported: MySQL, +// PostgreSQL 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. +// The client is told to start renewing after 1000 seconds. If the server +// does not respond within 2000 seconds of the lease being granted, client +// is supposed to start REBIND procedure (emergency renewal that allows +// switching to a different server). + "valid-lifetime": 4000, + "renew-timer": 1000, + "rebind-timer": 2000, + +// RFC6842 says that the server is supposed to echo back client-id option. +// However, some older clients do not support this and are getting confused +// when they get their own client-id. Kea can disable RFC6842 support. + "echo-client-id": false, + +// Some clients don't use stable client identifier, but rather generate them +// during each boot. This may cause a client that reboots frequently to get +// multiple leases, which may not be desirable. As such, sometimes admins +// prefer to tell their DHCPv4 server to ignore client-id value altogether +// and rely exclusively on MAC address. This is a parameter that is defined +// globally, but can be overridden on a subnet level. + "match-client-id": true, + + // By default, Kea ignores requests by clients for unknown IP addresses, + // because other non-cooperating DHCP servers could reside on the same + // network (RFC 2131). This parameter is defined globally, but can be + // overridden on a subnet level + "authoritative": false, + +// The following list defines subnets. Each subnet consists of at +// least subnet and pool entries. + "subnet4": [ + { + "pools": [ { "pool": "192.0.2.1 - 192.0.2.200" } ], + "id": 1, + "subnet": "192.0.2.0/24" + }, + { +// This particular subnet has match-client-id value changed. + "pools": [ { "pool": "192.0.3.100 - 192.0.3.200" } ], + "id": 2, + "subnet": "192.0.3.0/24", + "match-client-id": false + }, + { + "pools": [ { "pool": "192.0.4.1 - 192.0.4.254" } ], + "id": 3, + "subnet": "192.0.4.0/24" + } ], + +// The following configures logging. It assumes that messages with at +// least informational level (info, warn, error and fatal) should be +// logged to stdout. + "loggers": [ + { + "name": "kea-dhcp4", + "output-options": [ + { + "output": "stdout" + } + ], + "severity": "INFO" + } + ] +} + +} diff --git a/doc/examples/kea4/shared-network.json b/doc/examples/kea4/shared-network.json new file mode 100644 index 0000000..4b5a474 --- /dev/null +++ b/doc/examples/kea4/shared-network.json @@ -0,0 +1,164 @@ +// This is an example configuration file for DHCPv4 server in Kea. +// It demonstrates an advanced feature called shared network. Typically, for +// each physical link there is one IPv4 subnet that the server is expected +// to manage. However, in some cases there is a need to configure more subnets +// in the same physical location. The most common use case is an existing +// subnet that grew past its original assumptions and ran out of addresses, +// so the sysadmin needs to add another subnet on top of existing one. +{ + "Dhcp4": { + + // As with any other configuration, you need to tell Kea the interface + // names, so it would listen to incoming traffic. + "interfaces-config": { + "interfaces": [ "eth0" ] + }, + + // You also need to tell where to store lease information. + // memfile is the backend that is easiest to set up. + "lease-database": { + "type": "memfile", + "lfc-interval": 3600 + }, + + // The shared networks definition starts here. shared-networks can + // contain a list of shared networks. There are many parameters + // that can be specified here, so this example may be overwhelming + // at first, but the only mandatory parameter for each shared + // network is name. It must be unique. Typically, each shared + // network also needs to have at least two subnets to be functional, + // but if you really want to, you can define a degraded shared + // network that has 1 or even 0 subnets. This may come in handy + // when migrating between regular subnets and shared networks + // or when debugging a problem. It is not recommended to use + // 1 subnet per shared network, as there is extra processing + // overhead for shared networks. + "shared-networks": [ + { + // Name of the shared network. It may be an arbitrary string + // and it must be unique among all shared networks. + "name": "frog", + + // You may specify interface name if the shared network is + // reachable directly from the server. + "interface": "eth1", + + // You can specify many parameters that are allowed in subnet scope + // here. It's useful to put them here if they apply to all subnets + // in this shared network. It's likely that the most common + // parameter here will be option values defined with option-data. + "match-client-id": false, + "option-data": [ ], + "rebind-timer": 150, + "authoritative": true, + + // If all the traffic coming from that shared network is reachable + // via relay and that relay always use the same IP address, you + // can specify that relay address here. Since this example shows + // a shared network reachable directly, we put 0.0.0.0 here. + // It would be better to skip the relay scope altogether, but + // it was left here for demonstration purposes. + "relay": { + "ip-address": "0.0.0.0" + }, + + // Timer values can be overridden here. + "renew-timer": 100, + + // "reservation-mode": "all", + // It is replaced by the "reservations-global", + // "reservations-in-subnet", and "reservations-out-of-pool" + // parameters. + + // Specify whether the server should look up global reservations. + "reservations-global": false, + + // Specify whether the server should look up in-subnet reservations. + "reservations-in-subnet": true, + + // Specify whether the server can assume that all reserved addresses + // are out-of-pool. + // Ignored when reservations-in-subnet is false. + // If specified, it is inherited by "subnet4" levels. + "reservations-out-of-pool": false, + + // This starts a list of subnets allowed in this shared network. + // In our example, there are two subnets. + "subnet4": [ + { + "id": 1, + "match-client-id": true, + "next-server": "0.0.0.0", + "server-hostname": "", + "boot-file-name": "", + "option-data": [ ], + "pools": [ ], + "rebind-timer": 20, + + // You can override the value inherited from shared-network + // here if your relay uses different IP addresses for + // each subnet. + "relay": { + "ip-address": "0.0.0.0" + }, + "renew-timer": 10, + // "reservation-mode": "all", + // It is replaced by the "reservations-global", + // "reservations-in-subnet", and "reservations-out-of-pool" + // parameters. + // Specify whether the server should look up global reservations. + "reservations-global": false, + // Specify whether the server should look up in-subnet reservations. + "reservations-in-subnet": true, + // Specify whether the server can assume that all reserved addresses + // are out-of-pool. + // Ignored when reservations-in-subnet is false. + "reservations-out-of-pool": false, + "subnet": "10.0.0.0/8", + "valid-lifetime": 30 + }, + { + "id": 2, + "match-client-id": true, + "next-server": "0.0.0.0", + "server-hostname": "", + "boot-file-name": "", + "option-data": [ ], + "pools": [ ], + "rebind-timer": 20, + "renew-timer": 10, + // "reservation-mode": "all", + // It is replaced by the "reservations-global", + // "reservations-in-subnet", and "reservations-out-of-pool" + // parameters. + // Specify whether the server should look up global reservations. + "reservations-global": false, + // Specify whether the server should look up in-subnet reservations. + "reservations-in-subnet": true, + // Specify whether the server can assume that all reserved addresses + // are out-of-pool. + // Ignored when reservations-in-subnet is false. + "reservations-out-of-pool": false, + "subnet": "192.0.2.0/24", + "valid-lifetime": 30 + } + ], + "valid-lifetime": 200 + } ], // end of shared-networks + + // It is likely that in your network you'll have a mix of regular, + // "plain" subnets and shared networks. It is perfectly valid to mix + // them in the same config file. + + // This is regular subnet. It's not part of any shared-network. + "subnet4": [ + { + "pools": [ { "pool": "192.0.3.1 - 192.0.3.200" } ], + "subnet": "192.0.3.0/24", + "interface": "eth0", + "id": 3 + } + ] + + } // end of Dhcp4 +} diff --git a/doc/examples/kea4/single-subnet.json b/doc/examples/kea4/single-subnet.json new file mode 100644 index 0000000..4a2880b --- /dev/null +++ b/doc/examples/kea4/single-subnet.json @@ -0,0 +1,60 @@ +// This is an example configuration file for the DHCPv4 server in Kea. +// It is a basic scenario with one IPv4 subnet configured. The subnet +// contains a single pool of dynamically allocated addresses. + +{ "Dhcp4": + +{ +// Kea is told to listen on eth0 interface only. + "interfaces-config": { + "interfaces": [ "eth0" ] + }, + +// We need to specify the database used to store leases. As of +// June 2022, three database backends are supported: MySQL, +// PostgreSQL and the in-memory database, Memfile. +// We'll use memfile because it doesn't require any prior set up. + "lease-database": { + "type": "memfile", + "lfc-interval": 3600 + }, + +// 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, + +// The following list defines subnets. We have only one subnet +// here. We tell Kea that it is directly available over local interface. + "subnet4": [ + { + "pools": [ { "pool": "192.0.2.1 - 192.0.2.200" } ], + "id": 1, + "subnet": "192.0.2.0/24", + "interface": "eth0" + } + ], + +// The following configures logging. It assumes that messages with at +// least informational level (info, warn, error and fatal) should be +// logged to stdout. Alternatively, you can specify stderr here, a filename +// or 'syslog', which will store output messages via syslog. + "loggers": [ + { + "name": "kea-dhcp4", + "output-options": [ + { + "output": "stdout" + } + ], + "severity": "INFO" + } + ] +} + +} diff --git a/doc/examples/kea4/vendor-specific.json b/doc/examples/kea4/vendor-specific.json new file mode 100644 index 0000000..83b40fd --- /dev/null +++ b/doc/examples/kea4/vendor-specific.json @@ -0,0 +1,96 @@ +// This is an example configuration file for the DHCPv4 server in Kea. +// The purpose of this example is to showcase how configure +// Vendor Specific Information (code 43) RFC 2132 section 8.4 +{ + "Dhcp4": { + "option-def": [ + { +// Two options that we are planning to include in option 43 as suboptions +// should be defined on global level + "array": false, + "code": 2, + "name": "vlanid", +// suboptions should have space configured and it can't start with 'vendor-' +// otherwise those will be included in 125 option not 43 + "space": "339", + "type": "uint32" + }, + { + "array": false, + "code": 3, + "name": "dls", + "space": "339", + "type": "string" + } + ], + "client-classes": [ + { + +// Kea needs classification based on option 60, you can either use name: +// VENDOR_CLASS_ + option 60 content (test parameter is not required than) +// or use any name and add "test" parameter accordingly e.g. +// "test": "substring(option[60].hex,0,9) == 'partial-content-of-option-60'" + "name": "VENDOR_CLASS_339", + "option-def": [ + { +// Vendor-specific option has to be defined on the class level, if we're planning +// to send a single value, then define its type accordingly. If this option +// should encapsulate other suboptions, the "space" parameter should be the same +// as included suboptions and "type" set to empty + "code": 43, +// Using the "encapsulate" direction, Kea is told to include options from +// the "339" namespace. We have defined several such options earlier. +// This way, the sub-options are "glued" to this option 43. + "encapsulate": "339", + "name": "vendor-encapsulated-options", + "type": "empty" + } + ], + "option-data": [ + { +// vendor-encapsulated-options and defined option on global level should +// be also configured with proper "data" parameters in "option-data" list. +// Because Kea will send only option that client ask for, and there is no way +// to ask for suboptions, parameter "always-send" with value set +// to true has also be included in all custom suboptions + "name": "vendor-encapsulated-options" + }, + { + "always-send": true, + "data": "123", + "name": "vlanid", + "space": "339" + }, + { + "always-send": true, + "data": "sdlp://192.0.2.11:18443", + "name": "dls", + "space": "339" + } + ] + } + ], +// Kea is told to listen on eth0 interface only. + "interfaces-config": { + "interfaces": ["eth0"] + }, +// We need to specify the database used to store leases. + "lease-database": { + "type": "memfile" + }, +// The following list defines subnets. We have only one subnet +// here. We tell Kea that it is directly available over local interface. + "subnet4": [ + { + "interface": "eth0", + "pools": [ + { + "pool": "192.0.2.50-192.0.2.50" + } + ], + "subnet": "192.0.2.0/24", + "id": 1 + } + ] + } +} diff --git a/doc/examples/kea4/vivso.json b/doc/examples/kea4/vivso.json new file mode 100644 index 0000000..f69f189 --- /dev/null +++ b/doc/examples/kea4/vivso.json @@ -0,0 +1,90 @@ +// This is an example configuration file for the DHCPv4 server in Kea. +// The purpose of this example is to showcase how configure +// Vendor-Identifying Vendor-specific Information option +// (code 125) RFC 3925 + + +{ + "Dhcp4": { +// If we want to send suboptions in option 125 first those have to be defined +// on global level + "option-def": [ + { + "array": false, + "code": 2, + "name": "vlanid", +// In case of suboption of option 125 space has to start with prefix "vendor-" +// in this case it's "vendor-" + vendor id from option 60 sent by client +// 339 is Siemens Industry Inc. + "space": "vendor-339", + "type": "uint32" + }, + { + "array": false, + "code": 3, + "name": "dls", + "space": "vendor-339", + "type": "string" + } + ], + "client-classes": [ + { +// Kea needs classification based on option 60, you can either use name: +// VENDOR_CLASS_ + option 60 content (test parameter is not required than) +// or use any name and add "test" parameter accordingly e.g. +// "test": "substring(option[60].hex,0,9) == 'partial-content-of-option-60'" + "name": "VENDOR_CLASS_339", + "option-data": [ + { +// In "option-data" list we have to configure option 125 with data parameter equal +// to vendor-id we are expecting, also it will tell Kea which vendor space +// encapsulate in suboptions. + "data": "339", + "name": "vivso-suboptions" + }, + { +// And additionally we have to configure all previously defined suboptions +// with "space" parameter same as in option-def. +// Because Kea will send only option that client ask for, and there is no way +// to ask for suboptions parameter "always-send" with value set +// to true has also be included in all custom suboptions. + "always-send": true, + "data": "123", + "name": "vlanid", + "space": "vendor-339" + }, + { + "always-send": true, + "data": "sdlp://192.0.2.11:18443", + "name": "dls", + "space": "vendor-339" + } + ] + } + ], +// Kea is told to listen on eth0 interface only. + "interfaces-config": { + "interfaces": [ + "eth0" + ] + }, +// We need to specify the database used to store leases. + "lease-database": { + "type": "memfile" + }, +// The following list defines subnets. We have only one subnet +// here. We tell Kea that it is directly available over local interface. + "subnet4": [ + { + "id": 1, + "interface": "eth0", + "pools": [ + { + "pool": "192.0.2.50-192.0.2.50" + } + ], + "subnet": "192.0.2.0/24" + } + ] + } +} diff --git a/doc/examples/kea4/with-ddns.json b/doc/examples/kea4/with-ddns.json new file mode 100644 index 0000000..f479c57 --- /dev/null +++ b/doc/examples/kea4/with-ddns.json @@ -0,0 +1,85 @@ +// This is an example configuration file for the DHCPv4 server in Kea. +// It is a basic scenario with one IPv4 subnet configured and with DDNS +// enabled. + +{ "Dhcp4": + +{ +// Kea is told to listen on eth0 interface only. + "interfaces-config": { + "interfaces": [ "eth0" ] + }, + +// We need to specify the database used to store leases. As of +// June 2022, three database backends are supported: MySQL, +// PostgreSQL and the in-memory database, Memfile. +// We'll use memfile because it doesn't require any prior set up. + "lease-database": { + "type": "memfile", + "lfc-interval": 3600 + }, + +// 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, + +// The following list defines subnets. We have only one subnet +// here. We tell Kea that it is directly available over local interface. + "subnet4": [ + { + "pools": [ { "pool": "192.0.2.1 - 192.0.2.200" } ], + "subnet": "192.0.2.0/24", + "interface": "eth0", + "id": 1 + } + ], + +// Enable connectivity with kea-dhcp-ddns +// (Required for dynamic DNS updates) + "dhcp-ddns" : { + "enable-updates" : true, + "server-ip" : "192.0.2.0", + "server-port" : 3432, + "sender-ip" : "192.0.2.1", + "sender-port" : 3433, + "max-queue-size" : 2048, + "ncr-protocol" : "UDP", + "ncr-format" : "JSON" + }, + +// Enable DDNS updates and configure DDNS update behavior + "ddns-send-updates" : true, + "ddns-override-no-update" : true, + "ddns-override-client-update" : true, + "ddns-replace-client-name" : "when-present", + "ddns-generated-prefix" : "test.prefix", + "ddns-qualifying-suffix" : "test.suffix.", + "ddns-update-on-renew" : false, + "ddns-conflict-resolution-mode": "check-with-dhcid", + "ddns-ttl-percent" : 0.75, + "hostname-char-set": "[^A-Za-z0-9.-]", + "hostname-char-replacement": "x", + +// The following configures logging. It assumes that messages with at +// least informational level (info, warn, error and fatal) should be +// logged to stdout. + "loggers": [ + { + "name": "kea-dhcp4", + "output-options": [ + { + "output": "stdout" + } + ], + "severity": "INFO" + } + ] +} + +} |