README.md

Ansible Role jm1.cloudy.dhcpd

This role helps with configuring DHCP IPv4 and DHCP IPv6 services from Ansible variables. It allows to edit e.g. config files /etc/dhcp/dhcpd.conf and /etc/dhcp/dhcpd6.conf with variables dhcpd_config and dhcpd6_config which both define lists of tasks which will be run by this role. Each task calls an Ansible module similar to tasks in roles or playbooks except that only few keywords such as when are supported. For example, to configure a DHCP IPv4 service define variable dhcpd_config in group_vars or host_vars as such:

dhcpd_config:
- # Configure /etc/dhcp/dhcpd.conf
  ansible.builtin.copy:
    dest: /etc/dhcp/dhcpd.conf
    group: root
    mode: u=rw,g=r,o=
    owner: root
    src: "{{ distribution_id | first | regex_replace('[^A-Za-z0-9_]', '_') + '/etc/dhcp/dhcpd.conf' }}"

First, this role will install a DHCP service which matches the distribution specified in variable distribution_id. Next, it will run all tasks listed in dhcpd_config and dhcpd6_config. Once all tasks have finished and if anything has changed (and if dhcpd_service_state or dhcpd6_service_state are not set to stopped), then the DHCP IPv4 and DHCP IPv6 services are restarted to apply changes.

Tested OS images

• Cloud image (amd64) of Debian 10 (Buster)
• Cloud image (amd64) of Debian 11 (Bullseye)
• Cloud image (amd64) of Debian 12 (Bookworm)
• Cloud image (amd64) of Debian 13 (Trixie)
• Cloud image (amd64) of CentOS 7 (Core)
• Cloud image (amd64) of CentOS 8 (Stream)
• Cloud image (amd64) of CentOS 9 (Stream)
• Cloud image (amd64) of Fedora Cloud Base 40
• Cloud image (amd64) of Ubuntu 18.04 LTS (Bionic Beaver)
• Cloud image (amd64) of Ubuntu 20.04 LTS (Focal Fossa)
• Cloud image (amd64) of Ubuntu 22.04 LTS (Jammy Jellyfish)
• Cloud image (amd64) of Ubuntu 24.04 LTS (Noble Numbat)

Available on Ansible Galaxy in Collection jm1.cloudy.

Requirements

This role uses module(s) from collection jm1.ansible and collection jm1.pkg. To install these collections you may follow the steps described in README.md using the provided requirements.yml.

Variables

Name	Default value	Required	Description
dhcpd_config	refer to roles/dhcpd/defaults/main.yml	false	List of tasks to run 1 2 3, e.g. to configure /etc/dhcp/dhcpd.conf
dhcpd6_config	refer to roles/dhcpd/defaults/main.yml	false	List of tasks to run 1 2 3, e.g. to configure /etc/dhcp/dhcpd6.conf
dhcpd_service_enabled	true	false	Whether the DHCP IPv4 service should start on boot
dhcpd6_service_enabled	true	false	Whether the DHCP IPv6 service should start on boot
dhcpd_service_name	depends on distribution_id	false	Name of the DHCP IPv4 service, e.g. isc-dhcp-server on Debian and dhcpd.service on Red Hat Enterprise Linux
dhcpd6_service_name	depends on distribution_id	false	Name of the DHCP IPv6 service, e.g. isc-dhcp-server6 on Ubuntu and dhcpd6.service on Red Hat Enterprise Linux
dhcpd_service_state	started	false	State of the DHCP IPv4 service
dhcpd6_service_state	started	false	State of the DHCP IPv6 service
distribution_id	depends on operating system	false	List which uniquely identifies a distribution release, e.g. [ 'Debian', '10' ] for Debian 10 (Buster)

Dependencies

Name	Description
jm1.pkg.setup	Installs necessary software for module jm1.pkg.meta_pkg from collection jm1.pkg. This role is called automatically, manual execution is NOT required.

Example Playbook

- hosts: all
  become: true
  roles:
  - name: Manage DHCP IPv4 and DHCP IPv6 services
    role: jm1.cloudy.dhcpd
    tags: ["jm1.cloudy.dhcpd"]

For complete examples on how to use this role, refer to hosts lvrt-lcl-session-srv-100-pxe-server-debian11 or lvrt-lcl-session-srv-300-hwfp-server-debian11 from the provided examples inventory. The top-level README.md describes how these hosts can be provisioned with playbook playbooks/site.yml.

For instructions on how to run Ansible playbooks have look at Ansible's Getting Started Guide.

License

GNU General Public License v3.0 or later

See LICENSE.md to see the full text.

Author

Jakob Meng @jm1 (github, galaxy, web)

Footnotes

1. Useful Ansible modules in this context could be blockinfile, copy, debconf, file, lineinfile and template. ↩ ↩²

2. Tasks will be executed with jm1.ansible.execute_module which supports keyword when only. ↩ ↩²

3. Tasks will be executed with jm1.ansible.execute_module which supports modules and action plugins only. Some Ansible modules such as ansible.builtin.meta and ansible.builtin.{include,import}_{playbook,role,tasks} are core features of Ansible, in fact not implemented as modules and thus cannot be called from jm1.ansible.execute_module. Doing so causes Ansible to raise errors such as MODULE FAILURE\nSee stdout/stderr for the exact error. In addition, Ansible does not support free-form parameters for arbitrary modules, so for example, change from - debug: msg="" to - debug: { msg: "" }. ↩ ↩²