DHCPY6D.CONF(5) | DHCPY6D.CONF(5) |
dhcpy6d.conf - Configuration file for DHCPv6 server dhcpy6d
This file contains the general settings for DHCPv6 server daemon dhcpy6d. It follows RFC 822 style parsed by Python ConfigParser module. It contains several sections which will be discussed in detail here.
An online documentation is also available at https://dhcpy6d.de/documentation/config.
Boolean settings can be set with 1|0, on|off or yes|no values.
Some options allow multiple values. These have to be separated by spaces.
There are 5 types of sections:
This section contains important general options. Values are sometimes examples and not meant to be used in production environments.
store_db_host = <database-host>
store_db_db = <database-name>
store_db_user = <database-user>
dns_update_nameserver = <nameserver-address> [<nameserver-address> ...]
dns_rndc_key = <rndc-key_like_in_rndc.conf>
The <address_name> part of an [address_<address_name>] section is an arbitrarily chosen identifier like clients_global or invalid_clients_local. There can be many address definitions which will be used by classes. Every address definition may include several properties:
pattern = 2001:db8::$mac$|$id$|$range$|$random$
preferred_lifetime = <seconds>
dns_zone = <dnszone>
The address scheme used for the default class class_default is by default named address_default. It should be enough if address_default is defined, only if unknown clients should get extra nameservers etc. a class_default has to be set.
The <prefix_name> part of an [prefix_<prefix_name>] section is an arbitrarily chosen identifier like customers. A prefix definition may contain several properties:
pattern = 2001:db8:$range$::
preferred_lifetime = <seconds>
The <class_name> part of an [class_<class_name>] section is an arbitrarily chosen identifier like clients or invalid_clients. Clients can be grouped in classes. Different classes can have different properties, different address sets and different numbers of addresses. Classes also might have different name servers, time intervals, filters and interfaces.
A client gets the addresses, nameserver and T1/T2 values of the class which it is configured for in client configuration database or file.
t1 = <seconds>
filter_hostname = <regular_expression>
filter_mac = <regular_expression>
Example:
At the moment every client which does not match any other class by client configuration or filter automatically matches the class "default". This class could get an address scheme too. It should be enough if 'address_default' is defined, only if unknown clients should get extra nameservers etc. a 'class_default' has to be set.
The <bootfile_name> part of an [bootfile_<bootfile_name>] section is an arbitrarily chosen identifier like efi32, bios or efi64. Each bootfile can be restricted to an architecture and/or an user class which is sent by the PXE client.
Either the integer identifier for an architecture is possible (e.g. 0009 for EFI x86-64). The integer must consists of four numeric digits, empty digits must be written as zero (e.g. 9 => 0009). For a full list of possible integer identifier see https://tools.ietf.org/html/rfc4578#section-2.1. Alternatively the well-known names of registered CPU architectures defined in RF4578 can be used:
Example:
This restricts the bootfile to the iPXE boot firmware.
The following paragraphs contain some hopefully helpful examples:
[dhcpy6d] # Set to yes to really answer to clients. really_do_it = yes # Interface to listen to multicast ff02::1:2. interface = eth0 # Some server DUID. serverduid = 0001000134824528134567366121 # Do not identify and configure clients. store_config = none # SQLite DB for leases and LLIP-MAC-mapping. store_volatile = sqlite store_sqlite_volatile = /var/lib/dhcpy6d/volatile.sqlite # Special address type which applies to all not specially. # configured clients. [address_default] # Choosing MAC-based addresses. category = mac # ULA-type address pattern. pattern = fd01:db8:dead:bad:beef:$mac$
[dhcpy6d] # Set to yes to really answer to clients. really_do_it = yes # Interface to listen to multicast ff02::1:2. interface = eth0 # Server DUID - if not set there will be one generated every time dhcpy6d starts. # This might cause trouble for Windows clients because they go crazy about the # changed server DUID. serverduid = 0001000134824528134567366121 # Non-privileged user/group. user = dhcpy6d group = dhcpy6d # Nameservers for option 23 - there can be several specified separated by spaces. nameserver = fd00:db8::53 # Domain to be used for option 39 - host FQDN. domain = example.com # Domain search list for option 24 - domain search list. # If omitted the value of option "domain" above is taken as default. domain_search_list = example.com # Do logging. log = yes # Log to console. log_console = no # Path to logfile. log_file = /var/log/dhcpy6d.log # Use SQLite for client configuration. store_config = sqlite # Use SQLite for volatile data. store_volatile = sqlite # Paths to SQLite database files. store_sqlite_config = /var/lib/dhcpy6d/config.sqlite store_sqlite_volatile = /var/lib/dhcpy6d/volatile.sqlite # Declare which attributes of a requesting client should be checked # to prove its identity. It is possible to mix them, separated by spaces. identification = mac # Declare if all checked attributes have to match or is it enough if # some do. Kind of senseless with just one attribute. identification_mode = match_all # These lifetimes are also used as default for addresses which # have no extra defined lifetimes. preferred_lifetime = 43200 valid_lifetime = 64800 t1 = 21600 t2 = 32400 # ADDRESS DEFINITION # Addresses for proper valid clients. [address_valid_clients] # Better privacy for global addresses with category random. category = random # The following pattern will result in addresses like 2001:0db8::d3f6:834a:03d5:139c. pattern = 2001:db8::$random64$ # Default addresses for unknown invalid clients. [address_default] # Unknown clients will get an internal ULA range-based address. category = range # The keyword "range" sets the range used in pattern. range = 1000-1fff # This pattern results in addresses like fd00::1234. pattern = fd00::$range$ # CLASS DEFINITION # Class for proper valid client. [class_valid_clients] # At least one of the above address schemes has to be set. addresses = valid_clients # Valid clients get a different nameserver. nameserver = 2001:db8::53 # Default class for unknown hosts - only necessary here because of time interval settings. [class_default] addresses = default # Short interval of address refresh attempts so that a client's status # change will be reflected in IPv6 address soon. t1 = 600 t2 = 900
[dhcpy6d] # Set to yes to really answer to clients. really_do_it = yes # Interfaces to listen to multicast ff02::1:2. # eth1 - client network # eth2 - server network interface = eth1 eth2 # Server DUID - if not set there will be one generated every time dhcpy6d starts. # This might cause trouble for Windows clients because they go crazy about the # changed server DUID. serverduid = 0001000134824528134567366121 # Non-privileged user/group. user = dhcpy6d group = dhcpy6d # Domain to be used for option 39 - host FQDN. domain = example.com # Domain search list for option 24 - domain search list. # If omited the value of option "domain" above is taken as default. domain_search_list = example.com # Do logging. log = yes # Log to console. log_console = no # Path to logfile. log_file = /var/log/dhcpy6d.log # Use MySQL for client configuration. store_config = mysql # Use MySQL for volatile data. store_volatile = mysql # Data used for MySQL storage. store_db_host = localhost store_db_db = dhcpy6d store_db_user = dhcpy6d store_db_password = dhcpy6d # Declare which attributes of a requesting client should be checked # to prove its identity. It is possible to mix them, separated by spaces. identification = mac # Declare if all checked attributes have to match or is it enough if # some do. Kind of senseless with just one attribute. identification_mode = match_all # These lifetimes are also used as default for addresses which # have no extra defined lifetimes. preferred_lifetime = 43200 valid_lifetime = 64800 t1 = 21600 t2 = 32400 # ADDRESS DEFINITION # Global addresses for proper valid clients (GUA). [address_valid_clients_global] # Better privacy for global addresses with category random. category = random # The following pattern will result in addresses like 2001:0db8::d3f6:834a:03d5:139c. pattern = 2001:db8::$random64$ # Local addresses for proper valid clients (ULA). [address_valid_clients_local] # Local addresses need no privacy, so they will be based of range. category = range range = 2000-2FFF # Valid clients will get local ULA addresses from fd01::/64. pattern = fd01::$range$ # Servers in servers network will get local addresses based on IDs from client configuration. [address_servers] # IDs are set in client configuration database in range of 0-FFFF. category = id # Servers will get local ULA addresses from fd02::/64. pattern = fd02::$id$ # Default addresses for unknown invalid clients [address_default] # Unknown clients will get an internal ULA range-based address. category = range # The keyword "range" sets the range used in pattern. range = 1000-1FFF # This pattern results in addresses like fd00::1234. pattern = fd00::$range$ # CLASS DEFINITION # Class for proper valid client. [class_valid_clients] # Clients only exist in network linked with eth1. interface = eth1 # Valid clients get 2 addresses, one local ULA and one global GUA # (only works reliably with Windows clients). addresses = valid_clients_global valid_clients_local # Only valid clients get a nameserver from server network. nameserver = fd02::53 # Class for servers in network on eth2 [class_servers] # Servers only exist in network linked with eth2. interface = eth2 # Only local addresses for servers. addresses = servers # Nameserver from server network. nameserver = fd02::53 # Default class for unknown hosts - only necessary here because of time interval settings [class_default] addresses = default # Short interval of address refresh attempts so that a client's status # change will be reflected in IPv6 address soon. t1 = 600 t2 = 900
[dhcpy6d] # Set to yes to really answer to clients. really_do_it = yes # Interface to listen to multicast ff02::1:2. interface = eth0 # Server DUID - if not set there will be one generated every time dhcpy6d starts. # This might cause trouble for Windows clients because they go crazy about the # changed server DUID. serverduid = 0001000134824528134567366121 # Non-privileged user/group. user = dhcpy6d group = dhcpy6d # Nameservers for option 23 - there can be several specified separated by spaces. nameserver = fd00:db8::53 # Domain to be used for option 39 - host FQDN. domain = example.com # Domain search list for option 24 - domain search list. # If omited the value of option "domain" above is taken as default. domain_search_list = example.com # This works at the moment only for ISC Bind nameservers. dns_update = yes # RNDC key name for DNS Update. dns_rndc_key = rndc-key # RNDC secret - mostly some MD5-hash. Take it from # nameservers' /etc/rndc.key. dns_rndc_secret = 0123456789012345679 # Nameserver to talk to. dns_update_nameserver = ::1 # Regarding RFC 4704 5. there are 3 kinds of client behaviour # for N O S bits: # - client wants to update DNS itself -> sends 0 0 0 # - client wants server to update DNS -> sends 0 0 1 # - client wants no server DNS update -> sends 1 0 0 # Ignore client ideas about DNS (if at all, what name to use, self-updating...) # Here client hostname is taken from client configuration dns_ignore_client = yes # Do logging. log = yes # Log to console. log_console = no # Path to logfile. log_file = /var/log/dhcpy6d.log # Use SQLite for client configuration. store_config = sqlite # Use SQLite for volatile data. store_volatile = sqlite # Paths to SQLite database files. store_sqlite_config = config.sqlite store_sqlite_volatile = volatile.sqlite # Declare which attributes of a requesting client should be checked # to prove its identity. It is possible to mix them, separated by spaces. identification = mac # ADDRESS DEFINITION # Addresses for proper valid clients. [address_valid_clients] # Better privacy for global addresses with category random. category = random # The following pattern will result in addresses like 2001:0db8::d3f6:834a:03d5:139c. pattern = 2001:db8::$random64$ # Update these addresses in Bind DNS dns_update = yes # Zone to update. dns_zone = example.com # Reverse zone to update dns_rev_zone = 8.b.d.0.1.0.0.2.ip6.arpa # Default addresses for unknown invalid clients. [address_default] # Unknown clients will get an internal ULA range-based address. category = range # The keyword "range" sets the range used in pattern. range = 1000-1FFF # This pattern results in addresses like fd00::1234. pattern = fd00::$range$ # CLASS DEFINITION # Class for proper valid client. [class_valid_clients] # At least one of the above address schemes has to be set. addresses = valid_clients # Valid clients get a different nameserver. nameserver = 2001:db8::53
[dhcpy6d] # Set to yes to really answer to clients. really_do_it = yes # Interface to listen to multicast ff02::1:2. interface = eth0 # Server DUID - if not set there will be one generated every time dhcpy6d starts. # This might cause trouble for Windows clients because they go crazy about the # changed server DUID. serverduid = 0001000134824528134567366121 # Use no client configuration. store_config = none # Use SQLite for volatile data. store_volatile = sqlite # Paths to SQLite database file. store_sqlite_volatile = volatile.sqlite # ADDRESS DEFINITION [address_local] category = range range = 1000-1FFF pattern = fd00::$range$ [address_global] category = random pattern = 2001:638::$random64$ # CLASS DEFINITION [class_windows] addresses = local # Python regular expressions to be used here filter_hostname = win.* [class_default] addresses = global
Here dhcpy6d also provides prefixes in the default class. To avoid heavy load by bad clients request limits are activated.
[dhcpy6d] interface = eth0 server_preference = 255 store_config = none store_volatile = sqlite store_sqlite_volatile = /var/lib/dhcpy6d/volatile.sqlite log = on log_console = yes log_syslog = yes log_file = /var/log/dhcpy6d.log identification_mode = match_all identification = mac nameserver = 2001:db8::53 ntp_server = 2001:db8::123 # Mitigate ugly and aggressive clients request_limit = yes request_limit_time = 30 request_limit_count = 10 request_limit_identification = llip ignore_iaid = yes ignore_unknown_clients = yes advertise = addresses prefixes manage_routes_at_start = yes [address_default] category = mac pattern = 2001:db8::$mac$ [prefix_default] category = range range = 0000-ffff pattern = 2001:db8:0:$range$:: route_link_local = yes length = 64 [class_default] addresses = default prefixes = default call_up = sudo ip -6 route add $prefix$/$length$ via $router$ dev eth0 call_down = sudo ip -6 route delete $prefix$/$length$ via $router$ dev eth0
If no addresses should be generated, the clients need to have an address defined in their configuration file or database. It looks like this:
[example-client] hostname = example-client mac = 01:02:03:04:05:06 class = fixed_address address = 2001:db8::1234
The according class of the client simply must not have any address definition an might as well stay empty:
[dhcpy6d] # Set to yes to really answer to clients. really_do_it = yes # Interface to listen to multicast ff02::1:2. interface = eth0 # Some server DUID. serverduid = 0001000134824528134567366121 # Do not identify and configure clients. store_config = none # SQLite DB for leases and LLIP-MAC-mapping. store_volatile = sqlite store_sqlite_volatile = /var/lib/dhcpy6d/volatile.sqlite # Special address type which applies to all not specially. # configured clients. [address_default] # Choosing MAC-based addresses. category = mac # ULA-type address pattern. pattern = fd01:db8:dead:bad:beef:$mac$ # To use the EUI-64 instead of the plain MAC address: #category = eui64 #pattern = fd01:db8:dead:bad:$eui64$ [class_fixed_address] # just no address definiton here
This example how to assign PXE bootfiles depending on CPU architecture and user class:
[class_default_eth1] bootfiles = eth1_ipxe eth1_efi64 eth1_efi32 eth1_efibc addresses = eth1 interface = eth1 nameserver = fdff:cc21:56df:8bc8:5054:00ff:fec2:c5dd 2001:0470:76aa:00f5:5054:00ff:fec2:c5dd filter_mac = .* [address_eth1] # Choosing EUI-64-based addresses. category = eui64 # ULA-type address pattern. pattern = fdff:cc21:56df:8bc8::$eui64$ [bootfile_eth1_ipxe] user_class = iPXE bootfile_url = tftp://[fdff:cc21:56df:8bc8:5054:00ff:fec2:c5dd]/default.ipxe [bootfile_eth1_efi32] client_architecture = 0006 bootfile_url = tftp://[fdff:cc21:56df:8bc8:5054:00ff:fec2:c5dd]/efi32/ipxe.efi [bootfile_eth1_efibc] client_architecture = 0007 bootfile_url = tftp://[fdff:cc21:56df:8bc8:5054:00ff:fec2:c5dd]/efi64/ipxe.efi [bootfile_eth1_efi64] client_architecture = 0009 bootfile_url = tftp://[fdff:cc21:56df:8bc8:5054:00ff:fec2:c5dd]/efi32/ipxe.efi [bootfile_eth2_ipxe] user_class = iPXE bootfile_url = tftp://[fdff:cc21:56df:fe1d:5054:00ff:fe3f:5da0]/default.ipxe [bootfile_eth2_efi32] client_architecture = 0006 bootfile_url = tftp://[fdff:cc21:56df:fe1d:5054:00ff:fe3f:5da0]/efi32/ipxe.efi [bootfile_eth2_efibc] client_architecture = 0007 bootfile_url = tftp://[fdff:cc21:56df:fe1d:5054:00ff:fe3f:5da0]/efi64/ipxe.efi [bootfile_eth2_efi64] client_architecture = 0009 bootfile_url = tftp://[fdff:cc21:56df:fe1d:5054:00ff:fe3f:5da0]/efi32/ipxe.efi
At first there is a check for the iPXE boot firmware, which delivers an iPXE script on success. Otherwise the iPXE binary matching to the architecture is served.
This program is free software; you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation; either version 2 of the License, or (at your option) any later version.
This program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details.
You should have received a copy of the GNU General Public License along with this package; if not, write to the Free Software Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA
On Debian systems, the full text of the GNU General Public License version 2 can be found in the file /usr/share/common-licenses/GPL-2.
Copyright (C) 2012-2022 Henri Wahl <henri@dhcpy6d.de>
This manual page is licensed under the GPL-2 license.
2020-12-21 | 1.0.3 |