ansible-dhcpd/docs/defaults-configuration.rst
2016-04-07 15:28:13 +05:00

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