Skip to content

Latest commit

 

History

History
204 lines (154 loc) · 11 KB

README.md

File metadata and controls

204 lines (154 loc) · 11 KB
Raw

Ansible role dhcp

Ansible role for setting up ISC DHCPD. The responsibilities of this role are to:

The following are NOT concerns of this role:

  • Managing firewall configuration: Use e.g. bertvv.el7 for this.

A note on compatibility

Version 2.0.0 of this role uses features that are introduced in Ansible 2.0. Users of older versions of Ansible can use version 1.1.0 which has identical functionality. An overview of role compatibility:

Role version Ansible version Supported platform
1.1.0 1.7.x - 1.9.x CentOS 6-7
2.0.0 >= 2.0 CentOS 6-7, Fedora 23, Ubuntu 14.04, 16.04

Only the platforms on which the role was successfully tested are mentioned, but it should also work on other versions of these distributions. If you get it working on another platform, let me know and I will add it to the list.

Requirements

No specific requirements

Role Variables

This role is able to set (some) global options, and to specify subnet declarations.

See the test playbook (see below) for a working example of a DHCP server with two subnets. This section is mainly a reference of all supported options.

Global options

The following variables, when set, will be added to the global section of the DHCP configuration file. There is no default value, so when they are not set, they will be left out.

See the dhcp-options(5) man page for more information about these options.

Variable Comments
dhcp_global_authoritative Global authoritative statement (authoritative, not authoritative)
dhcp_global_log_facility Global log facility
dhcp_global_booting Global booting (allow, deny, ignore)
dhcp_global_bootp Global bootp (allow, deny, ignore)
dhcp_global_broadcast_address Global broadcast address
dhcp_global_classes Class definitions with a match statement(2)
dhcp_global_default_lease_time Default lease time in seconds
dhcp_global_domain_name_servers A list of IP addresses of DNS servers(1)
dhcp_global_domain_name The domain name the client should use when resolving host names
dhcp_global_domain_search A list of domain names too be used by the client to locate non-FQDNs(1)
dhcp_global_filename Filename to request for boot
dhcp_global_includes List of config files to be included (from dhcp_config_dir)
dhcp_global_max_lease_time Maximum lease time in seconds
dhcp_global_next_server IP for boot server
dhcp_global_ntp_servers List of IP addresses of NTP servers
dhcp_global_routers IP address of the router
dhcp_global_server_name Server name sent to the client
dhcp_global_subnet_mask Global subnet mask
dhcp_global_omapi_port OMAPI port
dhcp_global_omapi_secret OMAPI secret
dhcp_global_other_options Array of arbitrary additional global options

(1) This option may be written either as a list (when you have more than one item), or as a string (when you have only one). The following snippet shows an example of both:

# A single DNS server
dhcp_global_domain_name_servers: 8.8.8.8

# A list of DNS servers
dhcp_global_domain_name_servers:
  - 8.8.8.8
  - 8.8.4.4

(2) This role supports the definition of classes with a match statement, e.g.:

# Class for VirtualBox VMs
dhcp_global_classes:
  - name: vbox
    match: 'match if binary-to-ascii(16,8,":",substring(hardware, 1, 3)) = "8:0:27"'

Class names can be used in the definition of address pools (see below).

Subnet declarations

The role variable dhcp_subnets contains a list of dicts, specifying the subnet declarations to be added to the DHCP configuration file. Every subnet declaration should have an ip and netmask, other options are not mandatory. We start this section with an example, a compelete overview of supported options follows.

dhcp_subnets:
  - ip: 192.168.222.0
    netmask: 255.255.255.128
    domain_name_servers:
      - 10.0.2.3
      - 10.0.2.4
    range_begin: 192.168.222.50
    range_end: 192.168.222.127
  - ip: 192.168.222.128
    default_lease_time: 3600
    max_lease_time: 7200
    netmask: 255.255.255.128
    domain_name_servers: 10.0.2.3
    routers: 192.168.222.129

An alphabetical list of supported options in a subnet declaration:

Option Required Comment
booting no allow,deny,ignore
bootp no allow,deny,ignore
default_lease_time no Default lease time for this subnet (in seconds)
domain_name_servers no List of domain name servers for this subnet(1)
domain_search no List of domain names for resolution of non-FQDNs(1)
filename no filename to retrieve from boot server
ip yes Required. IP address of the subnet
max_lease_time no Maximum lease time for this subnet (in seconds)
netmask yes Required. Network mask of the subnet (in dotted decimal notation)
next_server no IP address of the boot server
range_begin no Lowest address in the range of dynamic IP addresses to be assigned
range_end no Highest address in the range of dynamic IP addresses to be assigned
routers no IP address of the gateway for this subnet
server_name no Server name sent to the client
subnet_mask no Overrides the netmask of the subnet declaration

You can specify address pools within a subnet by setting the pools options. This allows you to specify a pool of addresses that will be treated differently than another pool of addresses, even on the same network segment or subnet. It is a list of dicts with the following keys, all of which are optional:

Option Comment
allow Specifies which hosts are allowed in this pool(1)
default_lease_time The default lease time for this pool
deny Specifies which hosts are not allowed in this pool
domain_name_servers The domain name servers to be used for this pool(1)
max_lease_time The maximum lease time for this pool
min_lease_time The minimum lease time for this pool
range_begin The lowest address in this pool
range_end The highest address in this pool

(1) For the allow and deny fields, the options are enumerated in dhcpd.conf(5), but include:

  • booting
  • bootp
  • client-updates
  • known-clients
  • members of "CLASS"
  • unknown-clients

Host declarations

You can specify hosts that should get a fixed IP address based on their MAC by setting the dhcp_hosts option. This is a list of dicts with the following three keys, all of which are mandatory:

Option Comment
name The name of the host
mac The MAC address of the host
ip The IP address to be assigned to the host 
dhcp_hosts:
  - name: cl1
    mac: '00:11:22:33:44:55'
    ip: 192.168.222.150
  - name: cl2
    mac: '00:de:ad:be:ef:00'
    ip: 192.168.222.151

Dependencies

No dependencies.

Example Playbook

See the test playbook

Testing

Tests for this role are provided in the form of a Vagrant environment that is kept in a separate branch, tests. I use git-worktree(1) to include the test code into the working directory. Instructions for running the tests:

  1. Fetch the tests branch: git fetch origin tests
  2. Create a Git worktree for the test code: git worktree add tests tests (remark: this requires at least Git v2.5.0). This will create a directory tests/.
  3. cd tests/
  4. vagrant up will then create a VM and apply a test playbook (test.yml).

You may want to change the base box into one that you like. The current one, bertvv/centos72 was generated using a Packer template from the Boxcutter project with a few modifications.

Contributing

Issues, feature requests, ideas are appreciated and can be posted in the Issues section. Pull requests are also very welcome. Preferably, create a topic branch and when submitting, squash your commits into one (with a descriptive message).

License

BSD

Contributors