This role helps with managing the dnsmasq, a lightweight DHCP and caching DNS server, from Ansible variables.
For example, it allows to edit config files in /etc/dnsmasq.d/
and define [systemd units][archlinux-wiki-systemd].
Variable dnsmasq_config
defines a list 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 run dnsmasq as a DHCP and DNS server on Debian 11 (Bullseye) define variable dnsmasq_config
in group_vars
or host_vars
as such:
dnsmasq_config:
- ansible.builtin.copy:
content: |
bind-dynamic
dhcp-authoritative
dhcp-no-override
dhcp-range=192.168.158.100,192.168.158.254,255.255.255.0
no-resolv
server=192.168.158.1
strict-order
dest: /etc/dnsmasq.d/demo
mode: u=rw,g=r,o=
group: root
owner: root
First, this role will install packages for dnsmasq which match the distribution specified in variable distribution_id
.
Next, it will run all tasks listed in dnsmasq_config
. Once all tasks have finished and if anything has changed (and if
dnsmasq_service_state
is not set to stopped
), then dnsmasq's service (set in dnsmasq_service_name
) is 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.
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
.
Name | Default value | Required | Description |
---|---|---|---|
distribution_id |
depends on operating system | false | List which uniquely identifies a distribution release, e.g. [ 'Debian', '10' ] for Debian 10 (Buster) |
dnsmasq_config |
[] |
false | List of tasks to run 1 2 3, e.g. to configure files in /etc/dnsmasq.d/ |
dnsmasq_service_enabled |
true |
false | Whether the dnsmasq service should start on boot |
dnsmasq_service_name |
dnsmasq |
false | Name of the dnsmasq service |
dnsmasq_service_state |
started |
false | State of the dnsmasq service |
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. |
- hosts: all
become: true
roles:
- name: Manage dnsmasq service
role: jm1.cloudy.dnsmasq
tags: ["jm1.cloudy.dnsmasq"]
For a complete example on how to use this role, refer to host lvrt-lcl-session-srv-036-ubuntu2204-dnsmasq
from the
provided examples inventory. The top-level README.md
describes how this host
can be provisioned with playbook playbooks/site.yml
.
For instructions on how to run Ansible playbooks have look at Ansible's Getting Started Guide.
GNU General Public License v3.0 or later
See LICENSE.md to see the full text.
Jakob Meng @jm1 (github, galaxy, web)
Footnotes
-
Useful Ansible modules in this context could be
blockinfile
,copy
,file
,lineinfile
andtemplate
. ↩ -
Tasks will be executed with
jm1.ansible.execute_module
which supports keywordwhen
only. ↩ -
Tasks will be executed with
jm1.ansible.execute_module
which supports modules and action plugins only. Some Ansible modules such asansible.builtin.meta
andansible.builtin.{include,import}_{playbook,role,tasks}
are core features of Ansible, in fact not implemented as modules and thus cannot be called fromjm1.ansible.execute_module
. Doing so causes Ansible to raise errors such asMODULE 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: "" }
. ↩