Created
September 17, 2023 14:19
-
-
Save JourneymanGeek/1c84e5d9a710b9e0c325e4639cef5e06 to your computer and use it in GitHub Desktop.
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
/ This is a basic configuration for the Kea DHCPv4 server. Subnet declarations | |
// are mostly commented out and no interfaces are listed. Therefore, the servers | |
// will not listen or respond to any queries. | |
// The basic configuration must be extended to specify interfaces on which | |
// the servers should listen. There are a number of example options defined. | |
// These probably don't make any sense in your network. Make sure you at least | |
// update the following, before running this example in your network: | |
// - change the network interface names | |
// - change the subnets to match your actual network | |
// - change the option values to match your network | |
// | |
// This is just a very basic configuration. Kea comes with large suite (over 30) | |
// of configuration examples and extensive Kea User's Guide. Please refer to | |
// those materials to get better understanding of what this software is able to | |
// do. Comments in this configuration file sometimes refer to sections for more | |
// details. These are section numbers in Kea User's Guide. The version matching | |
// your software should come with your Kea package, but it is also available | |
// in ISC's Knowledgebase (https://kea.readthedocs.io; the direct link for | |
// the stable version is https://kea.readthedocs.io/). | |
// | |
// This configuration file contains only DHCPv4 server's configuration. | |
// If configurations for other Kea services are also included in this file they | |
// are ignored by the DHCPv4 server. | |
{ | |
// DHCPv4 configuration starts here. This section will be read by DHCPv4 server | |
// and will be ignored by other components. | |
"Dhcp4": { | |
// Add names of your network interfaces to listen on. | |
"interfaces-config": { | |
// See section 8.2.4 for more details. You probably want to add just | |
// interface name (e.g. "eth0" or specific IPv4 address on that | |
// interface name (e.g. "eth0/192.0.2.1"). | |
//"interfaces": [ "lan", "eth0" ] | |
"interfaces": [ "eth0" ] | |
// Kea DHCPv4 server by default listens using raw sockets. This ensures | |
// all packets, including those sent by directly connected clients | |
// that don't have IPv4 address yet, are received. However, if your | |
// traffic is always relayed, it is often better to use regular | |
// UDP sockets. If you want to do that, uncomment this line: | |
// "dhcp-socket-type": "udp" | |
}, | |
// Kea supports control channel, which is a way to receive management | |
// commands while the server is running. This is a Unix domain socket that | |
// receives commands formatted in JSON, e.g. config-set (which sets new | |
// configuration), config-reload (which tells Kea to reload its | |
// configuration from file), statistic-get (to retrieve statistics) and many | |
// more. For detailed description, see Sections 8.8, 16 and 15. | |
"control-socket": { | |
"socket-type": "unix", | |
"socket-name": "/tmp/kea4-ctrl-socket" | |
}, | |
// 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": { | |
"type": "memfile", | |
"persist": true, | |
"name": "/var/lib/kea/dhcp4.leases" | |
}, | |
// Kea allows storing host reservations in a database. If your network is | |
// small or you have few reservations, it's probably easier to keep them | |
// in the configuration file. If your network is large, it's usually better | |
// to use database for it. To enable it, uncomment the following: | |
// "hosts-database": { | |
// "type": "mysql", | |
// "name": "kea", | |
// "user": "kea", | |
// "password": "kea", | |
// "host": "localhost", | |
// "port": 3306 | |
// }, | |
// See Section 7.2.3 "Hosts storage" for details. | |
// Setup reclamation of the expired leases and leases affinity. | |
// Expired leases will be reclaimed every 10 seconds. Every 25 | |
// seconds reclaimed leases, which have expired more than 3600 | |
// seconds ago, will be removed. The limits for leases reclamation | |
// are 100 leases or 250 ms for a single cycle. A warning message | |
// will be logged if there are still expired leases in the | |
// database after 5 consecutive reclamation cycles. | |
// 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 the lease storage. | |
"expired-leases-processing": { | |
"reclaim-timer-wait-time": 10, | |
"flush-reclaimed-timer-wait-time": 25, | |
"hold-reclaimed-time": 3600, | |
"max-reclaim-leases": 100, | |
"max-reclaim-time": 250, | |
"unwarned-reclaim-cycles": 5 | |
}, | |
// Global timers specified here apply to all subnets, unless there are | |
// subnet specific values defined in particular subnets. | |
"renew-timer": 900, | |
"rebind-timer": 1800, | |
"valid-lifetime": 3600, | |
// Many additional parameters can be specified here: | |
// - option definitions (if you want to define vendor options, your own | |
// custom options or perhaps handle standard options | |
// that Kea does not support out of the box yet) | |
// - client classes | |
// - hooks | |
// - ddns information (how the DHCPv4 component can reach a DDNS daemon) | |
// | |
// Some of them have examples below, but there are other parameters. | |
// Consult Kea User's Guide to find out about them. | |
// These are global options. They are going to be sent when a client | |
// requests them, unless overwritten with values in more specific scopes. | |
// The scope hierarchy is: | |
// - global (most generic, can be overwritten by class, subnet or host) | |
// - class (can be overwritten by subnet or host) | |
// - subnet (can be overwritten by host) | |
// - host (most specific, overwrites any other scopes) | |
// | |
// Not all of those options make sense. Please configure only those that | |
// are actually useful in your network. | |
// | |
// For a complete list of options currently supported by Kea, see | |
// Section 7.2.8 "Standard DHCPv4 Options". Kea also supports | |
// vendor options (see Section 7.2.10) and allows users to define their | |
// own custom options (see Section 7.2.9). | |
"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": "8.8.8.8, 9.9.9.9" | |
}, | |
// 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.com" | |
}, | |
// 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": "example.com, home" | |
}, | |
// 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 hexadecimal 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" | |
} | |
// Note that Kea provides some of the options on its own. In particular, | |
// it sends IP Address lease type (code 51, based on valid-lifetime | |
// parameter, Subnet mask (code 1, based on subnet definition), Renewal | |
// time (code 58, based on renew-timer parameter), Rebind time (code 59, | |
// based on rebind-timer parameter). | |
], | |
// Other global parameters that can be defined here are option definitions | |
// (this is useful if you want to use vendor options, your own custom | |
// options or perhaps handle options that Kea does not handle out of the box | |
// yet). | |
// You can also define classes. If classes are defined, incoming packets | |
// may be assigned to specific classes. A client class can represent any | |
// group of devices that share some common characteristic, e.g. Windows | |
// devices, iphones, broken printers that require special options, etc. | |
// Based on the class information, you can then allow or reject clients | |
// to use certain subnets, add special options for them or change values | |
// of some fixed fields. | |
//"client-classes": [ | |
// { | |
// This specifies a name of this class. It's useful if you need to | |
// reference this class. | |
//"name": "voip", | |
// This is a test. It is an expression that is being evaluated on | |
// each incoming packet. It is supposed to evaluate to either | |
// true or false. If it's true, the packet is added to specified | |
// class. See Section 12 for a list of available expressions. There | |
// are several dozens. Section 8.2.14 for more details for DHCPv4 | |
// classification and Section 9.2.19 for DHCPv6. | |
//"test": "substring(option[60].hex,0,6) == 'Aastra'", | |
// If a client belongs to this class, you can define extra behavior. | |
// For example, certain fields in DHCPv4 packet will be set to | |
// certain values. | |
//"next-server": "192.0.2.254", | |
//"server-hostname": "hal9000", | |
//"boot-file-name": "/dev/null" | |
// You can also define option values here if you want devices from | |
// this class to receive special options. | |
//} | |
//], | |
// Another thing possible here are hooks. Kea supports a powerful mechanism | |
// that allows loading external libraries that can extract information and | |
// even influence how the server processes packets. Those libraries include | |
// additional forensic logging capabilities, ability to reserve hosts in | |
// more flexible ways, and even add extra commands. For a list of available | |
// hook libraries, see https://gitlab.isc.org/isc-projects/kea/wikis/Hooks-available. | |
// "hooks-libraries": [ | |
// { | |
// // Forensic Logging library generates forensic type of audit trail | |
// // of all devices serviced by Kea, including their identifiers | |
// // (like MAC address), their location in the network, times | |
// // when they were active etc. | |
// "library": "/usr/lib/x86_64-linux-gnu/kea/hooks/libdhcp_legal_log.so", | |
// "parameters": { | |
// "path": "/var/lib/kea", | |
// "base-name": "kea-forensic4" | |
// } | |
// }, | |
// { | |
// // Flexible identifier (flex-id). Kea software provides a way to | |
// // handle host reservations that include addresses, prefixes, | |
// // options, client classes and other features. The reservation can | |
// // be based on hardware address, DUID, circuit-id or client-id in | |
// // DHCPv4 and using hardware address or DUID in DHCPv6. However, | |
// // there are sometimes scenario where the reservation is more | |
// // complex, e.g. uses other options that mentioned above, uses part | |
// // of specific options or perhaps even a combination of several | |
// // options and fields to uniquely identify a client. Those scenarios | |
// // are addressed by the Flexible Identifiers hook application. | |
// "library": "/usr/lib/x86_64-linux-gnu/kea/hooks/libdhcp_flex_id.so", | |
// "parameters": { | |
// "identifier-expression": "relay4[2].hex" | |
// } | |
// } | |
// ], | |
// Below an example of a simple IPv4 subnet declaration. Uncomment to enable | |
// it. This is a list, denoted with [ ], of structures, each denoted with | |
// { }. Each structure describes a single subnet and may have several | |
// parameters. One of those parameters is "pools" that is also a list of | |
// structures. | |
"subnet4": [ | |
{ | |
// This defines the whole subnet. Kea will use this information to | |
// determine where the clients are connected. This is the whole | |
// subnet in your network. | |
// Subnet identifier should be unique for each subnet. | |
"id": 1, | |
// This is mandatory parameter for each subnet. | |
"subnet": "10.0.0.0/24", | |
"interface": "eth0", | |
// Pools define the actual part of your subnet that is governed | |
// by Kea. Technically this is optional parameter, but it's | |
// almost always needed for DHCP to do its job. If you omit it, | |
// clients won't be able to get addresses, unless there are | |
// host reservations defined for them. | |
"pools": [ { "pool": "10.0.0.51 - 10.0.0.200" } ], | |
// 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": "10.0.0.2" | |
} | |
], | |
// Kea offers host reservations mechanism. 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). | |
// | |
// Kea also support flexible identifier (flex-id), which lets you | |
// specify an expression that is evaluated for each incoming packet. | |
// Resulting value is then used for as an identifier. | |
// | |
// Note that reservations are subnet-specific in Kea. This is | |
// different than ISC DHCP. Keep that in mind when migrating | |
// your configurations. | |
"reservations": [ | |
// This is a reservation for a specific hardware/MAC address. | |
// It's a rather simple reservation: just an address and nothing | |
// else. | |
{ | |
"hw-address": "a0:36:9f:40:31:ae", | |
"ip-address": "10.0.0.50" | |
} | |
// 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": "A0:36:9F:40:31:AE", | |
// "ip-address": "192.0.2.202", | |
// "hostname": "special-snowflake" | |
//}, | |
// The third reservation is based on DUID. This reservation defines | |
// a 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. | |
// | |
// When using reservations, it is useful to configure | |
// reservations-global, reservations-in-subnet, | |
// reservations-out-of-pool (subnet specific parameters) | |
// and host-reservation-identifiers (global parameter). | |
//{ | |
// "client-id": "01:12:23:34:45:56:67", | |
// "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" | |
//} | |
// You can add more reservations here. | |
] | |
// You can add more subnets there. | |
} | |
], | |
// There are many, many more parameters that DHCPv4 server is able to use. | |
// They were not added here to not overwhelm people with too much | |
// information at once. | |
// Logging configuration starts here. Kea uses different loggers to log various | |
// activities. For details (e.g. names of loggers), see Chapter 18. | |
"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": [ | |
{ | |
// Specifies the output file. There are several special values | |
// supported: | |
// - stdout (prints on standard output) | |
// - stderr (prints on standard error) | |
// - syslog (logs to syslog) | |
// - syslog:name (logs to syslog using specified name) | |
// Any other value is considered a name of the file | |
"output": "stdout", | |
// Shorter log pattern suitable for use with systemd, | |
// avoids redundant information | |
"pattern": "%-5p %m\n" | |
// This governs whether the log output is flushed to disk after | |
// every write. | |
// "flush": false, | |
// This specifies the maximum size of the file before it is | |
// rotated. | |
// "maxsize": 1048576, | |
// This specifies the maximum number of rotated files to keep. | |
// "maxver": 8 | |
} | |
], | |
// This specifies the severity of log messages to keep. Supported values | |
// are: FATAL, ERROR, WARN, INFO, DEBUG | |
"severity": "INFO", | |
// If DEBUG level is specified, this value is used. 0 is least verbose, | |
// 99 is most verbose. Be cautious, Kea can generate lots and lots | |
// of logs if told to do so. | |
"debuglevel": 0 | |
} | |
] | |
} | |
} |
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment