## 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 ## on Kea web page (http://kea.isc.org, click User's Guide, direct link for ## stable version is http://kea.isc.org/docs/kea-guide.html). ## ## 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": [ "ens192/192.168.42.5" ] # 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 support 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/kea-dhcp4-ctrl.sock" }, # 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) and even Cassandra. 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 a in-memory # C++ database that stores its state in CSV file. # "type": "memfile", # "lfc-interval": 3600 #}, "lease-database": { "type": "mysql", "name": "kea", "user": "kea", "password": "Kea#38037", "host": "localhost", "port": 3306 }, # 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 # }, "hosts-database": { "type": "mysql", "name": "kea", "user": "kea", "password": "Kea#38037", "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. "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": "192.0.2.1, 192.0.2.2" # }, # 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" # }, # 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 http://kea.isc.org/wiki/Hooks. #"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/local/var/kea/libdhcp_legal_log.so" # "parameters": { # "path": "/var/kea/var", # "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/local/var/kea/libdhcp_flex_id.so", # "parameters": { # "identifier-expression": "substring(relay6[0].option[18],0,8)" # } # } #], # 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. "client-classes": [ { "name": "DELL", "test": "(substring(pkt4.mac,0,3) == 0x002564)" } ], "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. This is mandatory parameter for each # subnet. "id": 1, "subnet": "192.168.42.0/24", "option-data": [ { "space": "dhcp4", "name": "domain-name-servers", "code": 6, "data": "8.8.8.8, 8.8.4.4" }, { "space": "dhcp4", "name": "routers", "code": 3, data": "192.168.42.1" }, { "space": "dhcp4", "name": "broadcast-address", "code": 28, "data": "192.168.42.255" } ], "valid-lifetime": 259200, # 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": "192.168.42.200 - 192.168.42.220", "client-class": "DELL" } ] }, # 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.2.1" # } #], # 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": "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 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 # reservation-mode (subnet specific parameter) 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. "Logging": { "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 a time "output": "/usr/local/var/log/kea-dhcp4.log" # 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. "debug": 0 ] } ] } }