ansible-dhcpd/docs/defaults-configuration.rst

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.

.. contents::
   :local:
   :depth: 1


.. _dhcpd_keys:

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:

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:

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:

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:

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:

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:

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:

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:

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