Default variables: configuration

some of debops.dhcpd default variables have more extensive configuration than simple strings or lists, here you can find documentation and examples for them.

dhcpd_keys

This list lets you define symmetric keys used to update dynamic DNS with information configured using DHCP.

key
Name of the key used to select it in specific scope
algorithm
Name of the algorithm to use for key encryption
secret
Encrypted symmetric key shared between DHCP and DNS servers
comment
An optional comment added in the configuration file

Examples:

# Read the secret key from an external file
dhcpd_secret_secure_key: '{{ lookup("password",
                             secret + "/" + ansible_domain +
                             "/shared/ddns/keys/secure-key") }}'

dhcpd_keys:
  - key: "secure-key"
    algorithm: "hmac-md5"
    secret: "{{ dhcpd_secret_secure_key }}"

dhcpd_zones

This list lets you define DNS zones used to update dynamic DNS with information configured using DHCP.

zone
DNS domain name of a zone, needs to end with a dot (.)
primary
Address of the primary DNS server serving the specified zone
key
Name of the symmetric key used to authorize Dynamic DNS updates of the specified zone
comment
An optional comment added in the configuration file

Examples:

dhcpd_zones:
  - zone: "example.org."
    primary: "127.0.0.1"
    key: "secure-key"

dhcpd_classes

Here you can define host classes and custom options for each class.

class
Name of the host class
comment
Optional comment added in the configuration file
options
Text block with options for a particular class scope
include
Include an external file
subclass

Dict. You can specify matches for a class in two ways:

  • a dict key without a value will create a simple match for that host. You need to specify dict key with colon (:) at the end to indicate that this is a dict key, see examples below
  • a dict with a text block as a value will create an extended match scope with options specified in the text block inside that scope

Examples:

dhcpd_classes:

  - class: 'empty-class'

  - class: 'allocation-class-1'

    options: |
      match pick-first-value (option dhcp-client-identifier, hardware);

    subclass:
      # Simple match
      '00:11:22:33:44:55':

      # Extended match
      '00:11:22:33:22:11': |
        option root-path "samsara:/var/diskless/alphapc";
        filename "/tftpboot/netbsd.alphapc-diskless";

dhcpd_groups

Group related configuration together.

comment
Optional comment added in the configuration file
options
Text block with options for a particular group
include
Include an external file
groups
Include another group definition of the group in this group. Child group should be defined in a separate YAML dict. Recursion is not allowed.
hosts
List of hosts included in this group. Use the same format as the dhcpd_hosts list.
subnets
List of subnets included in this group. Use the same format as the dhcpd_subnets list.

Examples:

dhcpd_groups:
  - comment: 'First group'
    hosts: '/etc/dhcp/dhcpd-group1-hosts.conf'
    groups: '{{ dhcpd_group_second }}'

# An example of group nesting
dhcpd_group_second:
  - comment: 'Second group'
    hosts: '/etc/dhcp/dhcpd-group2-hosts.conf'

dhcpd_shared_networks

List of shared networks which combine specified subnets together.

name
Name of a shared network
comment
A comment added to this shared network in the configuration
options
Custom options in the text block format for this shared network
include
Include an external file in this shared network scope
subnets
List of subnets included in this shared network. Use the same format as the dhcpd_subnets list.

Examples:

dhcpd_shared_networks:
  - name: 'shared-net'
    comment: "Local shared network"
    subnets: '{{ dhcpd_subnets_local }}'
    options: |
      default-lease-time 600;
      max-lease-time 900;

dhcpd_subnets_local:
  - subnet: '10.0.30.0'
    netmask: '255.255.255.0'
    routers: [ '10.0.30.1', '10.0.30.2' ]

  - subnet: '10.0.40.0'
    netmask: '255.255.255.0'
    routers: '19.0.40.1'
    options: |
      default-lease-time 300;
      max-lease-time 7200;
    pools:
      - comment: "A pool in a subnet"
        range: '10.0.30.10 10.0.30.20'

dhcpd_subnets

List of subnets included in a specified group.

subnet
IP address of the subnet. If it's IPv4, it should be the first IP address in the subnet, if it's IPv6, it should be specified with the prefix.
netmask
If the subnet is IPv4, specify it's netmask in "normal" IP address form, not the CIDR form.
ipv6
Set to True if managed subnet is IPv6.
routers
String (if just one), or list (if many) of IP addresses of the routers for this subnet
comment
A comment added to this subnet in the configuration
options
Custom options in the text block format for this subnet
include
Include an external file in this subnet scope
pools

List of different address pools within specified subnet. Each pool should be specified as a dict, following keys are recognized:

  • range: a string which defines the range of the specific pool, with IP addresses of the start and end delimited by space
  • comment: a comment added to this host in the configuration
  • options: custom options in the text block format for this host
  • include: include an external file in this pool

Examples:

# List of subnets
dhcpd_subnets: [ '{{ dhcpd_subnet_default }}' ]

dhcpd_subnet_default:
  subnet: '{{ ansible_default_ipv4.network }}'
  netmask: '{{ ansible_default_ipv4.netmask }}'
  comment: 'Generated automatically by Ansible'

# An IPv6 subnet
example_ipv6_subnet:
  subnet: 'dead:be:ef::/64'
  ipv6: True
  routers: 'dead:be:ef::1'
  comment: "Example IPv6 subnet"
  options: |
    default-lease-time 300;
    max-lease-time 7200;

dhcpd_hosts

String or list. If string, include an external file with host list in this place of the configuration. If list, specify a list of dicts describing the hosts. Each dict can have following keys:

hostname
Name of the host
ethernet
Ethernet address of this host, if host has multiple aggregated(bonded) links you may specify their ethernet addresses as a list.
address
IP address of this host
comment
A comment added to this host in the configuration
options
Custom options in the text block format for this host

Examples:

# External file with list of hosts
dhcpd_hosts: '/etc/dhcp/dhcp-hosts.conf'

# List of hosts
dhcpd_hosts:
  - hostname: 'examplehost'
    address: '10.0.10.1'
    ethernet: '00:00:00:00:00:00'
  - hostname: 'bondedhost'
    address: '10.0.10.2'
    ethernet:
      - '00:00:00:00:00:01'
      - '00:00:00:00:00:02'

dhcpd_includes

List of external files to include in DHCP configuration. Use absolute paths for the files.

Examples:

dhcpd_includes:
  - '/etc/dhcp/other-options.conf'

dhcpd_failovers

Each 'failover pair' declaration consists of primary and secondary host, no more than two nodes failover is currently allowed by isc-dhcpd.

You must specify which failover pair each pool should use by specifying a 'failover peer' statement under an options block in each pool declaration. e.g:

dhcpd_failovers:
  - failover: "my-failover"
    primary: '10.0.30.1'
    secondary: '10.0.30.2'
    ...

dhcpd_subnets:
  - subnet: ...
    ...
    pools:
      - comment: "My pool with failover"
        range: '10.0.30.10 10.0.30.20'
        options: |
          failover peer "my-failover";

Each failover declaration has a set of an mandatory fields, which is:

primary
Ansible inventory name of a primary DHCP host, if you need failover to work on different IP, see primary_fo_addr option below.
secondary
Ansible inventory name of a secondary DHCP host, if you need failover to work on different IP, see secondary_fo_addr option below.

Ansible inventory name is either IP ot hostname specified in inventory file.

mclt

Max Client Lead Time. The maximum amount of time that one server can extend a lease for a DHCP client beyond the time known by the partner server.

Default value: 3600

Split configuration between two failover DHCP servers:

split

Percentage value between 0 and 255.

Specifies the split between the primary and secondary servers for the purposes of load balancing. Whenever a client makes a DHCP request, the DHCP server runs a hash on the client identification, resulting in value from 0 to 255. This is used as an index into a 256 bit field. If the bit at that index is set, the primary is responsible. If the bit at that index is not set, the secondary is responsible. Instead of split, you can use hba.

hba

32 character string in the regexp: ([0-9a-f]{2}:){32}

Specifies the split between the primary and secondary as a bitmap rather than a cutoff, which theoretically allows for finer-grained control. In practice, there is probably no need for such fine-grained control, however.

You must use either 'split' or 'hba' statement. Split has a preference, so if it's defined, 'hba' will be omitted by configuration template.

max_response_delay

Tells the DHCP server how many seconds may pass without receiving a message from its failover peer before it assumes that connection has failed. This is mandatory according to dhcpd.conf man page.

Default value: 5

max_unacked_updates

Tells the remote DHCP server how many BNDUPD messages it can send before it receives a BNDACK from the local system. This is mandatory according to dhcpd.conf man page.

Default value: 10

Optional field are mostly desribed in dhcpd.conf man page:

port

Specifies port on which primary and secondary nodes will listen for failover connection. Diffirent ports for primary and secondary is currently unsupported.

Default value: 647

primary_fo_addr
IP/Hostname of a primary DHCP host. This option is used if you need failover address be different from ansible inventory IP/hostname. If omitted, then primary is used.
secondary_fo_addr
IP/Hostname of a secondary DHCP host. This option is used if you need failover address be different from ansible inventory IP/hostname. If omitted, then secondary is used.
auto_partner_down
Number of seconds to start serving partners IPs after the partner's failure.

Other parameters:

load_balance_max_seconds: 5
max_lease_misbalance: 15
max_lease_ownership: 10
min_balance: 60
max_balance: 3600

Examples:

# Full cluster configuration
dhcpd_failovers:
- failover: 'failover-localsubnet'
  primary: '10.0.10.1'
  primary_fo_addr: '10.5.10.1'
  secondary: '10.0.10.2'
  secondary_fo_addr: '10.5.10.2'
  port: 1337
  split: 128
  hba: aa:aa:aa:aa:aa:aa:aa:aa:aa:aa:aa:aa:aa:aa:aa:aa:aa:aa:aa:aa:aa:aa:aa:aa:aa:aa:aa:aa:aa:aa:aa:aa
  max_response_delay: 5
  max_unacked_updates: 10
  load_balance_max_seconds: 5
  auto_partner_down: 0
  max_lease_misbalance: 15
  max_lease_ownership: 10
  min_balance: 60
  max_balance: 3600

# Minimal cluster configuration
dhcpd_failovers:
- failover: 'failover-san'
  primary: '10.0.10.1'
  secondary: '10.0.10.2'
  mclt: 3600
  split: 128
  max_response_delay: 5
  max_unacked_updates: 10