Reorganize role documentation

CHANGES.rst

@@ -0,0 +1,8 @@
+Changelog
+=========
+
+v0.1.0
+------
+
+- First release [drybjed]
+

defaults/main.yml

@@ -1,49 +1,95 @@
 ---
+# Default variables
+# =================
 
+# .. contents:: Sections
+#    :local:
+#
+# -------------------
+#   General options
+# -------------------
+
+# .. envvar:: dhcpd_mode
+#
 # What service type to configure on this host:
-#   'server' - host is an ISC DHCP server, see dhcpd(8)
+#
-#   'relay'  - host is an ISC DHCP relay, see dhcrelay(8)
+# - ``server``: host is an ISC DHCP server, see ``dhcpd(8)``
-dhcpd_mode: 'relay'
+#
+# - ``relay``: host is an ISC DHCP relay, see dhcrelay(8)
+#
+dhcpd_mode: 'server'
 
+
+# .. envvar:: dhcpd_base_packages_map
+#
 # What packages should be installed, depending on mode of operation
 dhcpd_base_packages_map:
   'server': [ 'isc-dhcp-server' ]
   'relay':  [ 'isc-dhcp-relay' ]
 
 
-# ---- ISC DHCP Relay configuration ----
+# --------------------------------
+#   ISC DHCP Relay configuration
+# --------------------------------
 
+# .. envvar:: dhcpd_relay_servers
+#
 # List of DHCP servers which should receive the relayed packets
 dhcpd_relay_servers: [ '{{ ansible_default_ipv4.gateway }}' ]
 
+
+# .. envvar:: dhcpd_relay_interfaces
+#
 # List of network interfaces that dhcrelay should listen on
 dhcpd_relay_interfaces: []
 
+
+# .. envvar:: dhcpd_relay_options
+#
 # Additional dhcrelay options
 dhcpd_relay_options: '-4'
 
 
-# ---- Global ISC DHCP Server configuration ----
+# ----------------------------------------
+#   Global ISC DHCP Server configuration
+# ----------------------------------------
 
+# .. envvar:: dhcpd_authoritative
+#
 # Is this DHCP server authoritative?
 dhcpd_authoritative: False
 
+
+# .. envvar:: dhcpd_interfaces
+#
 # List of network interfaces to listen on for DHCP requests
 # If this list is empty, Ansible will try to guess correct interfaces
 # automatically
 dhcpd_interfaces: []
 
+
+# .. envvar:: dhcpd_domain
+#
 # Default domain to use
 dhcpd_domain: '{{ ansible_domain }}'
 
+
+# .. envvar:: dhcpd_dns_servers
+#
 # List of default DNS servers. By default, point users to the same host that
 # serves them DHCP requests, on default interface. If this host is a router,
 # you might need to set DNS server to internal interface IP address.
 dhcpd_dns_servers: [ '{{ ansible_default_ipv4.address }}' ]
 
+
+# .. envvar:: dhcpd_lease_time
+#
 # Max lease time in hours (default lease time is calculated below)
 dhcpd_lease_time: 24
 
+
+# .. envvar:: dhcpd_global_options
+#
 # Default global options formatted as a text block
 dhcpd_global_options: |
   option domain-name "{{ ansible_domain }}";
@@ -52,257 +98,76 @@ dhcpd_global_options: |
   max-lease-time {{ (dhcpd_lease_time * 60 * 60)|round|int }};
   log-facility local7;
 
+
+# .. envvar:: dhcpd_options
+#
 # Custom options formatted as a text block
 dhcpd_options: False
 
 
-# ---- ISC DHCP Server configuration scopes ----
+# ----------------------------------------
+#   ISC DHCP Server configuration scopes
+# ----------------------------------------
 
 # These lists allow you to generate nested configuration scopes in
 # dhcpd.conf. Most of the information about them can be found in dhcpd.conf(5)
 # manual page. You can create nested configuration using Ansible variable
-# expansion (examples below).
+# expansion.
-
-# List of general configuration parameters (work in any configuration scope):
-#  - comment: ''            add a comment to a scope
-#  - options: |             custom options for that scope defined as a text block
-#  - include: ''            path to external file to include in this scope
-
-# List of hosts (works in groups, subnets):
-#  - hosts: '' or []        list of hosts to configure in that scope; if this is
-#                           a path to a file, dhcpd will include an external file
-#                           in this scope
-
-# List of parameters specific to dhcpd_classes:
-#  - class: ''              class name
-#  - subclass:              this is a hash with expression as key and additional
-#                           options as value in a text block (see example below);
-#                           each match expression must end with a colon to indicate
-#                           hash key; optional
-
-# List of parameters specific to dhcpd_groups:
-#  - subnets: []            list of subnet scopes to group together
-#  - groups: []             list of other group scopes to include. No recursion!
-
-# List of parameters specific to dhcpd_shared_networks:
-#  - name: ''               name of shared network
-#  - subnets: []            list of subnets in a shared network (do not use
-#                           dhcpd_subnets here, because they will be duplicated
-#                           and DHCP server will not start)
-
-# List of parameters specific to dhcpd_subnets:
-#  - subnet: ''             start of a subnet range (ie.: 192.168.1.0)
-#  - netmask: ''            netmask for this subnet (ie.: 255.255.255.0)
-#  - routers: '' or []      address or list of addresses of gateway for that
-#                           subnet (ie.: 192.168.1.1)
-
-# List of parameters specific to dhcpd_hosts:
-#  - hostname: ''           hostname, without domain part
-#  - address: ''            IP address reserved for that host, optional
-#  - ethernet: ''           Ethernet MAC address of this host, optional
 
+# .. envvar:: dhcpd_keys
+#
+# List of secret keys used for Dynamic DNS configuration. See
+# :ref:`dhcpd_keys` for more details.
 dhcpd_keys: []
-  #- key: "secure-key"
-  #  algorithm: "hmac-md5"
-  #  secret: "JFw7jM2/KVU2hIB4xkDSQmHB6JJOLUu4xkzwLNNpR88="
 
-# List of classes
+
+# .. envvar:: dhcpd_classes
+#
+# List of client classes (see dhcpd.conf(5)). More informaction can be found in
+# :ref:`dhcpd_classes`.
 dhcpd_classes: []
-  #- class 'example-class'
-  #  subclass:
-  #    'match1':
-  #    'match2': |
-  #      # match2 options in a text block;
-
-  #- class 'example-empty-class'
 
 
-# List of groups
+# .. envvar:: dhcpd_groups
+#
+# List of configuration scopes groped together. See :ref:`dhcpd_groups` for
+# more details.
 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'
 
 
-# List of shared networks
+# .. envvar:: dhcpd_shared_networks
+#
+# List of shared networks grouping specified subnets together. See
+# :ref:`dhcpd_shared_networks` for more details.
 dhcpd_shared_networks: []
-  #- name: 'shared-net'
-  #  comment: "Local shared network"
-  #  subnets: '{{ dhcpd_subnets_local }}'
-  #  options: |
-  #    default-lease-time 600;
-  #    max-lease-time 900;
 
 
-# List of subnets not in a shared network
+# .. envvar:: dhcpd_subnets
-dhcpd_subnets:
+#
-  - subnet: '{{ ansible_default_ipv4.network }}'
+# List of subnets not in a shared network. See :ref:`dhcpd_subnets` for more
+# details.
+dhcpd_subnets: [ '{{ dhcpd_subnet_default }}' ]
+
+# Default subnet managed automatically
+dhcpd_subnet_default:
+  subnet: '{{ ansible_default_ipv4.network }}'
   netmask: '{{ ansible_default_ipv4.netmask }}'
   comment: 'Generated automatically by Ansible'
 
-  #- subnet: 'dead:be:ef::/64'
-  #  ipv6: True
-  #  routers: '10.0.10.1'
-  #  comment: "Example IPv6 subnet"
-  #  options: |
-  #    default-lease-time 300;
-  #    max-lease-time 7200;
-  #
-  #- subnet: '10.0.20.0'
-  #  netmask: '255.255.255.0'
-  #  comment: 'Ignored subnet'
 
-# An example subnets included in a shared network
+# .. envvar:: dhcpd_hosts
-#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'
+# Global list of hosts in DHCP. See ref:`dhcpd_hosts` for more details.
-#    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'
-
-
-# Global list of hosts in DHCP
 dhcpd_hosts: []
-#  - hostname: 'examplehost'
-#    address: '10.0.10.1'
-#    ethernet: '00:00:00:00:00:00'
-
-# Example global list of hosts read from an external file
-#dhcpd_hosts: '/etc/dhcp/dhcpd.hosts.conf'
 
 
-# List of external files to include
+# List of external files to include. See :ref:`dhcpd_includes` for more
+# details.
 dhcpd_includes: []
-  #- '/etc/dhcp/example.conf'
 
-# ---- ISC DHCP failover configuration ----
+
-#
+# .. envvar:: 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: 3600              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.
-#
-#   split: [0-255]          Specifies the split between the primary and
-#                           secondary 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.
-#    -- or --
-#   hba: ([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.
-#   max_response_delay: 5   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.
-#   max_unacked_updates: 10 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.
-#
-# You must use either 'split' or 'hba' statement. Split has a preference, so
-# if it's defined, 'hba' will be omitted by configuration template.
-# Optional field are mostly desribed in dhcpd.conf man page:
-#   port: 647               Specifies port on which primary and secondary
-#                           nodes will listen for failover connection.
-#                           Diffirent ports for primary and secondary is
-#                           currently unsupported.
-#
-#   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: 0    Number of second to start serving partners IPs
-#                           after the partner's failure.
-#
-#   load_balance_max_seconds: 5
-#   max_lease_misbalance: 15
-#   max_lease_ownership: 10
-#   min_balance: 60
-#   max_balance: 3600
 #
+# DHCP failover configuration. See :ref:`dhcpd_failovers` for more details.
 dhcpd_failovers: []
-  ## Following is full cluster configuration
-  #- 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
-  #
-  ## Following is minimal cluster configuration
-  #- 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
 

docs/changelog.rst

@@ -0,0 +1 @@
+.. include:: ../CHANGES.rst

docs/copyright.rst

@@ -0,0 +1,21 @@
+Copyright
+=========
+
+::
+
+    Copyright (C) 2014 Maciej Delmanowski <drybjed@gmail.com>
+    Copyright (C) 2014 DebOps Project http://debops.org/
+    [see Credits for more details]
+
+    his program is free software; you can redistribute it and/or modify
+    it under the terms of the GNU General Public License version 3, as
+    published by the Free Software Foundation.
+
+    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 program. If not, see http://www.gnu.org/licenses/
+

docs/credits.rst

@@ -0,0 +1,16 @@
+Credits
+=======
+
+Credits, in chronological order
+-------------------------------
+
+* Maciej Delmanowski <drybjed_at_gmail.com>
+
+  * creator of the DebOps Project
+
+  * current project maintainer
+
+* RedRampage
+
+  * Added support for DHCP failover and Dynamic DNS keys
+

docs/defaults-configuration.rst

@@ -0,0 +1,439 @@
+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_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
+
+``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'
+
+.. _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
+

docs/getting-started.rst

@@ -0,0 +1,18 @@
+Getting started
+===============
+
+By default ``debops.dhcpd`` installs a DHCP server with some default
+configuration. Server will not be authoritative, and will have a default subnet
+configuration taken from ``ansible_default_ipv4`` network configuration.
+
+An example playbook which uses ``debops.dhcpd`` role::
+
+    ---
+
+    - name: Manage DHCP server
+      hosts: debops_dhcpd
+
+      roles:
+        - role: debops.dhcpd
+          tags: dhcpd
+

docs/guides.rst

@@ -0,0 +1,6 @@
+Guides and examples
+===================
+
+This section will contain guides for configuring ``debops.dhcpd`` in various
+scenarios.
+

docs/index.rst

@@ -0,0 +1,22 @@
+debops.dhcpd
+============
+
+.. toctree::
+   :maxdepth: 3
+
+   introduction
+   installation
+   getting-started
+   defaults
+   defaults-configuration
+   guides
+   troubleshooting
+   copyright
+   credits
+   changelog
+
+..
+ Local Variables:
+ mode: rst
+ ispell-local-dictionary: "american"
+ End:

docs/installation.rst

@@ -0,0 +1,7 @@
+Installation
+============
+
+This role requires at least Ansible ``v1.7.0``. To install it, run::
+
+    ansible-galaxy install debops.dhcpd
+

docs/introduction.rst

@@ -0,0 +1,15 @@
+Introduction
+============
+
+``debops.dhcpd`` role can be used to configure an `ISC DHCP Server`_ as
+standalone or in a 2-host failover configuration. Alternatively, you can
+configure an DHCP relay on a host connected to multiple network which will
+relay DHCP/BOOTP messages to your DHCP server.
+
+.. _ISC DHCP Server: https://www.isc.org/downloads/dhcp/
+
+..
+ Local Variables:
+ mode: rst
+ ispell-local-dictionary: "american"
+ End:

docs/troubleshooting.rst

@@ -0,0 +1,6 @@
+Troubleshooting
+===============
+
+This section will contain information about fixing issues with
+``debops.dhcpd`` role.
+