Ansible Role dhcp

This is an Ansible role for installing and configuring ISC DHCPD (Dynamic Host Configuration Protocol Daemon). This role will handle package installation and the DHCP configuration file (dhcpd.conf). It does not manage the firewall settings, so you'll need to do that in your own playbook or with another role, like bertvv.rh-base.

Check the change log for updates in each version.

If you like this role, consider giving it a star. If you find it lacking, please submit feedback or improve it with a pull request. Thank you!

Requirements

No special requirements.

Role Variables

This role can set global settings and specify subnet configurations.

You can see a working example of a DHCP server in a test environment here. Below are the supported options.

Global Options

The following variables will be added to the global section of the DHCP configuration file. If they don't have a default value, they won't appear in dhcpd.conf.

For more information on these options, check the dhcp-options(5) manual.

Notes

1. You can define classes with match statements. Here's an example:

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

2. The variable dhcp_global_domain_name_servers can be written as either a list (for multiple items) or a single string. Here’s how both look:

# Single DNS server
dhcp_global_domain_name_servers: 8.8.8.8

# Multiple DNS servers
dhcp_global_domain_name_servers:
  - 8.8.8.8
  - 8.8.4.4

3. This role also supports failover peer definitions. Here's an example:

# Failover peer
dhcp_global_failover_peer: failover-group
dhcp_global_failover:
  role: primary # | secondary
  address: 192.168.222.2
  port: 647
  peer_address: 192.168.222.3
  peer_port: 647
  max_response_delay: 15
  max_unacked_updates: 10
  load_balance_max_seconds: 5
  split: 255
  mclt: 3600

Subnet Declarations

The variable dhcp_subnets holds a list of subnet configurations to be added to the DHCP config file. Each subnet should include ip and netmask; other options are optional. Here's an example:

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

You can create address pools within a subnet by using the pools option.

Host Declarations

You can define hosts that should receive a static IP based on their MAC address by using the dhcp_hosts option, which is a list of dictionaries containing at least name and mac:

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

PXEBoot Server

Set dhcp_pxeboot_server for directing PXE clients to the specified PXEBoot server for network booting.

Custom Includes

Use dhcp_custom_includes to specify custom config files that will be included in the dhcpd.conf. If the file name ends with .j2, the extension will be removed in the destination.

Example:

dhcp_custom_includes:
  - custom-dhcp-config.conf[.j2]

Testing

To test the role, ensure you have Molecule, VirtualBox, and Vagrant installed. Run molecule converge to create a test VM. You can then use tools like nmap for DHCP testing as shown in the example.

License

BSD License

Contributing

Issues, feature requests, and pull requests are welcome. Please create a topic branch and squash your commits into one before submitting.

Contributors

A list of contributors is available in the original document.