kea-dhcp4.conf.pre 21.5 KB
Newer Older
1 2 3
// 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.
4 5 6 7
// 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:
8 9 10 11 12 13 14 15 16 17
// - 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
Suzanne Goldlust's avatar
Suzanne Goldlust committed
18 19
// in ISC's Knowledgebase (https://kb.isc.org/docs/kea-administrator-reference-manual; the direct link for
// the stable version is https://jenkins.isc.org/job/Kea_doc/guide/kea-guide.html).
20 21 22 23
//
// 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.
24 25
{

26 27 28 29 30 31 32 33 34 35 36 37 38 39 40
// 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": [ ]

        // 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:
41
        // "dhcp-socket-type": "udp"
42 43
    },

44 45 46 47 48 49
    // 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.
50 51
    "control-socket": {
        "socket-type": "unix",
52
        "socket-name": "/tmp/kea-dhcp4-ctrl.sock"
53 54 55 56 57 58 59 60 61 62 63
    },

    // 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.
64 65
        "type": "memfile",
        "lfc-interval": 3600
66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103
    },

    // 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.
    "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,

104 105 106 107
    // 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)
108 109
    // - client classes
    // - hooks
110
    // - ddns information (how the DHCPv4 component can reach a DDNS daemon)
111
    //
112 113 114 115 116 117 118 119 120 121
    // 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)
122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 137 138 139 140 141 142 143 144 145 146 147 148 149 150 151 152 153 154 155 156 157 158 159 160 161 162
    //
    // 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
163
        // attempt to resolve names within those specified domains. For
164 165 166 167 168 169 170 171
        // 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
172
        // it escaped (i.e. each comma is preceded by two backslashes).
173 174 175 176 177 178
        // 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
179
        // or \u followed by 4 hexadecimal numbers (currently Kea
180 181 182 183 184 185 186 187 188 189 190 191 192 193 194 195 196 197 198 199 200 201 202 203 204
        // 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).
    ],

205 206 207 208
    // 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).
209 210 211 212 213 214 215 216 217 218 219 220 221 222 223 224 225

    // 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
226 227 228
            // 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.
229 230 231 232 233 234 235 236 237 238 239 240 241 242 243 244 245 246 247
            "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
Suzanne Goldlust's avatar
Suzanne Goldlust committed
248
    // hook libraries, see https://gitlab.isc.org/isc-projects/kea/wikis/Hooks-available.
249 250 251 252 253 254 255 256 257 258 259 260 261 262 263 264 265 266 267 268 269 270 271 272 273 274 275 276 277 278 279 280 281 282 283 284 285 286 287 288 289 290 291 292 293 294 295 296 297 298 299 300 301 302 303 304 305 306 307 308 309 310 311 312 313 314 315 316 317 318 319 320
    //"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": "@localstatedir@/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": "@localstatedir@/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.
    "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.
            "subnet": "192.0.2.0/24",

            // 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.0.2.1 - 192.0.2.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": "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.
321 322 323 324
            //
            // Note that reservations are subnet-specific in Kea. This is
            // different than ISC DHCP. Keep that in mind when migrating
            // your configurations.
325 326
            "reservations": [

327 328 329
                // This is a reservation for a specific hardware/MAC address.
                // It's a rather simple reservation: just an address and nothing
                // else.
330 331 332 333 334 335
                {
                    "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
336 337
                // the this client will get a reserved hostname. A hostname can
                // be defined for any identifier type, not just client-id.
338 339 340 341 342 343 344 345 346 347 348 349 350 351 352
                {
                    "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",
353
                        "data": "10.1.1.202, 10.1.1.203"
354 355 356 357 358 359 360 361 362 363 364 365 366 367 368 369 370 371 372 373 374 375
                    } ]
                },

                // 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",
376
                            "data": "10.1.1.202, 10.1.1.203"
377 378 379 380 381 382 383 384 385 386 387 388 389 390 391 392 393 394 395 396 397 398 399 400 401 402 403 404 405 406 407 408 409 410
                        }
                    ]
                },
                // 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.
411 412
    // They were not added here to not overwhelm people with too much
    // information at once.
413 414
},

415 416
// Logging configuration starts here. Kea uses different loggers to log various
// activities. For details (e.g. names of loggers), see Chapter 18.
417 418 419 420
"Logging":
{
  "loggers": [
    {
421 422 423 424 425 426
        // 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": [
            {
427 428 429 430 431 432 433
                // 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
434 435 436 437 438 439 440 441 442 443 444 445 446 447 448 449 450 451 452 453 454 455
                "output": "@localstatedir@/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.
        "debuglevel": 0
456
    }
457
  ]
458 459
}
}