475 lines
12 KiB
ReStructuredText
475 lines
12 KiB
ReStructuredText
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
|
|
|