Default variable details¶
Some of debops.dnsmasq
default variables have more extensive
configuration than simple strings or lists, here you can find documentation and
examples for them.
dnsmasq__interfaces¶
The dnsmasq__*_interfaces
variables define per-interface configuration of
dnsmasq. Each defined network interface has its own subdomain, IP
address ranges taken from the interface configuration, and some other options.
The result is merged with the main dnsmasq configuration defined in
the dnsmasq__*_configuration
variables, which can be used to refine the
generated parameters if necessary.
The dnsmasq__*_interfaces
entries are merged together, and Ansible
inventory can be used to override the defaults provided in the role.
Examples¶
Disable the interface configuration generated by default by the role:
dnsmasq__interfaces:
- name: 'br2'
state: 'absent'
Generate interface configuration with a custom DNS subdomain, IP address ranges for DHCP and disabled boot services:
dnsmasq__interfaces:
- name: 'br2'
addresses: [ '192.0.2.1/24', '2001:db8:feed:beef::1/64' ]
domain: 'custom.{{ ansible_domain }}'
boot_enabled: False
Syntax¶
Each entry in the dnsmasq__*_interfaces
lists is a YAML dictionary with
specific parameters:
name
- Required. Network interface name for which to generate the configuration.
This parameter is used as an anchor to merge multiple entries with the same
name
together. filename
- Optional. Override the name of the generated configuration file stored in the
/etc/dnsmasq.d/
directory. If not specified, the filename will be generated automatically based on the interface name. state
Optional. If not specified or
present
the interface configuration will be generated. Ifabsent
, the interface configuration will be not generated, and existing configuration file will be removed. Ifignore
, a given configuration entry will not be evaluated by the role.This parameter can be used to conditionally enable or disable interface configuration, for example when a given interface is present on a host.
tag
- Optional. A string that defines a "tag" for a given network which can be used to define DHCP options for that specific network. If not specified, the interface name will be used by default.
address
/addressess
Optional. List of IPv4 or IPv6 addresses in the "host/prefix" format which should be used in the interface configuration.
You need to specify the IP address of the network interface and the subnet mask (prefix) in the CIDR format for it to be accepted by the role. The IP addresses will not be configured automatically, you can use the debops.ifupdown role to configure the network interfaces.
The role automatically gathers the existing network interface configuration and uses existing IP addresses defined on the network interface, therefore you don't need to use this parameter unless required for a specific application.
hostname
- Optional. Specify the hostname which will be used in the interface DNS
record. If not specified, the value in the
dnsmasq__hostname
variable is used by default. domain
- Optional. Define a custom DNS domain for a given interface. If not specified,
a DNS domain will be generated automatically using the interface name and the
value of the
dnsmasq__base_domain
variable. This domain will be advertised over DHCP with the search option, new DHCP clients will be added to the DNS on this domain as well. search
- Optional. List of additional DNS domains to add to the DHCP search option.
dhcp_enabled
- Optional, boolean. If not specified or
True
, the DHCP service will be configured on a specific network interface. To disable, set this parameter toFalse
. dhcp_range_state
- Optional. If not specified or
present
, the role will configure a range of dynamic IP addresses in the DHCP server for a given network. Ifabsent
, the DHCP range configuration will not be included in the generated configuration file. dhcp_range_start
- Optional. Specify a positive number of IP addresses to reserve at the start of the subnet for static DHCP entries. If not specified, 10 IP addresses will be reserved by default.
dhcp_range_end
- Optional. Specify a negative number of IP addresses to reserve at the end of
the subnet for static DHCP entries. If not specified, 10 IP addresses
(specified as
-10
) will be reserved by default. dhcp_lease
- Optional. Specify the lease time for IP addresses on a given network
interface. If not specified,
24h
will be used by default. dhcp_ipv6_mode
- Optional. A string that defines DHCP IPv6 mode, see dnsmasq(8) for
more details. If not specified, the value is defined as:
ra-names,ra-stateless,slaac
. router_state
- Optional. If not specified or
present
orenabled
, the router will be advertised for the DHCP clients on a given network interface. Ifdisabled
, the router advertisements will be disabled on a given network interface. Ifabsent
, the router configuration option will not be included in the generated configuration file. router_gateway
- Optional. Specify the IP address of the default router advertised by dnsmasq on a given interface. If not specified, dnsmasq will advertise its own host as the default router.
boot_enabled
- Optional, boolean. If not specified or
True
, enable support for booting clients over the network using TFTP and PXE services. To disable, set the value toFalse
. boot_tftp_root
- Optional. Absolute path of the TFTP root directory used for boot services on
this interface. If not specified, the value of the
dnsmasq__boot_tftp_root
variable will be used by default. boot_filename
- Optional. The name of the file which the network boot clients should load and
run at boot time. If not specified, the value of the
dnsmasq__boot_filename
variable will be used by default. boot_server
- Optional. The IP address of the "next server" the network boot clients should contact for the TFTP service. If not specified, the dnsmasq will direct them to its own host automatically.
raw
- Optional. String or YAML text block with raw dnsmasq(8) configuration options, added at the end of a given interface configuration file. This can be used to add configuration not covered by the above parameters.
dnsmasq__dhcp_hosts, dnsmasq__dns_records¶
The dnsmasq__dhcp_hosts
and dnsmasq__dns_records
variables
can be used to define configuration for specific DHCP clients and custom DNS
resource records. The syntax for both variables is the same.
Configuration defined in these variables is not converted to the
dnsmasq__*_configuration
variable format, and entries defined in these
lists are not merged together. The dnsmasq configuration defined
here will be stored in a separate config file, with its filename defined in the
dnsmasq__dhcp_dns_filename
variable.
Examples of DHCP client configuration¶
Reserve a static IP address for a DHCP client with a particular MAC address:
dnsmasq__dhcp_hosts:
- mac: '00:00:5e:00:53:01'
ip: '192.0.2.1'
Override a hostname sent by a particular client, with reserved IP address:
dnsmasq__dhcp_hosts:
- name: 'custom-hostname'
comment: "This is a custom static host entry"
mac: '00:00:5e:00:53:02'
ip: '192.0.2.2'
Add a dbserver.example.org
DNS resource record for a DHCP client on
a specified domain:
dnsmasq__dhcp_hosts:
- name: 'dbserver'
domain: 'example.org'
mac: '00:00:5e:00:53:03'
ip: '192.0.2.3'
Define a webserver host with multiple CNAME records on a given domain, for different web services:
dnsmasq__dhcp_hosts:
- name: 'webserver'
comment: 'Internal web services'
domain: 'example.org'
mac: '00:00:5e:00:53:04'
ip: '192.0.2.4'
cname: [ 'code', 'dcim', 'ipam', 'cloud' ]
Ignore requests from a particular MAC address:
dnsmasq__dhcp_hosts:
- mac: '00:00:5e:00:53:05'
ignore: True
Examples of DNS resource records¶
Define an MX resource record for a specific domain that points to the dnsmasq host for mail delivery:
dnsmasq__dns_records:
- mx: 'example.org'
Define custom mail servers for a particular domain, with specific priority:
dnsmasq__dns_records:
- mx: 'example.com'
target: 'mx1.example.com'
priority: 10
- mx: 'example.com'
target: 'mx2.example.com'
priority: 20
Create an A resource record with a particular IP address:
dnsmasq__dns_records:
- host: 'other.example.org'
address: '192.0.2.30'
Define a TXT resource record with a DomainKeys Identified Mail (DKIM) entry:
dnsmasq__dns_records:
- txt: 'mail._domainkeys.example.org'
value: 'v=DKIM1; k=rsa; p=<base64-encoded public key>'
Define a multi-line TXT resource record with custom characters inside:
dnsmasq__dns_records:
- txt: 'info.example.org'
value:
- "Custom string with it's value quoted"
- "\"Additional string, with a comma\""
Create a SRV resource record that points to a service, with default values for weight and priority:
dnsmasq__dns_records:
- srv: '_http._tcp.example.org'
target: 'webserver.example.org'
port: '80'
Define a CNAME resource record that points to a different host:
dnsmasq__dns_records:
- cname: 'alias.example.org'
target: 'service.example.org'
Define PTR resource records for hosts:
dnsmasq__dns_records:
- ptr: '40.2.0.192.in-addr.arpa'
target: 'host1.example.org'
- ptr: '{{ "192.0.2.50" | ansible.utils.ipaddr("revdns") }}'
target: 'host2.example.org'
Syntax¶
Each entry in the list is a YAML dictionary with specific parameters:
state
- Optional. If not specified or
present
, the entry will be added in the configuration file. Ifabsent
, the entry will be removed from the configuration file. Ifcomment
, the entry will be included in the configuration file, but commented out. comment
- Optional. String or a YAML text block with a comment added to a given configuration entry.
address
/ip
/ipaddr
Optional. Specify an IPv4 or IPv6 address, or a YAML list of addresses for a given entry.
In DHCP host configuration this parameter specifies the IP addresses which will be reserved for a particular host.
In DNS record configuration this parameter along with the
host
/a
/aaaa
parameter defines a DNS A record; in case of multiple IP addresses, the first IP address will be used to create the host's DNS PTR record.cname
Optional. If defined in a DHCP client configuration, it's a list of DNS subdomains to add in the DNS database (the
domain
parameter is also required in this case). All of the subdomains will point at a given host.If defined in a DNS record, it's a Fully Qualified Domain Name that can be used to reference a specific target name. The
target
parameter is required in this case.raw
- Optional. A string or YAML text block with raw dnsmasq configuration, which will be included in the generated file as-is.
The parameters below are related to DHCP host configuration:
name
/hostname
- Optional. Specify the hostname for a given DHCP client which will be registered in the DNS. This overrides any hostname sent by the client.
hwaddr
/mac
- Optional. Specify the media access control address of a host to create a DHCP client entry for it. You can specify multiple MAC addresses as a YAML list to set DHCP options shared between multiple hosts with different MAC addresses.
id
- Optional. Specify the DHCP Unique Identifier used in DHCPv6 configuration to identify a given DHCP client. Only one DUID can be used at a time.
tag
- Optional. Set a tag for a given DHCP client. This tag can be referenced by other dnsmasq configuration options to target specific DHCP clients or sets of clients.
lease
- Optional. Specify lease time for an IP address of a given DHCP client. If not
specified, leases will be given for 24 hours (
24h
). ignore
- Optional, boolean. If specified and
True
, dnsmasq will ignore DHCP client requests from a specific MAC address. domain
- Optional. Specify a DNS domain on which a given DHCP client should be
published. Only one domain at a time is allowed. The domain will be added to
the DNS service managed by dnsmasq, the FQDN of the host will be
pointed to its IPv4 and IPv6 addresses. Any subdomains specified with the
cname
parameter will be added to the DNS and pointed at the DHCP client.
The parameters below are related to DNS record configuration:
host
/a
/aaaa
- Optional. Define a DNS A and/or AAAA record for a FQDN hostname. This
parameter is used to define the hostname, and the
address
,ip
,ipaddr
ortarget
parameter, which specifies the IP address, is required to complete the DNS record. txt
- Optional. Define a DNS TXT record. This parameter specifies the resource
name, the
value
ortarget
parameters are required to complete the record. value
- Optional. Specify the content of the DNS TXT record, either as a string or as a YAML list.
ptr
- Optional. Define the DNS PTR record. This parameter specifies the IP address
in the Reverse DNS lookup format. The
target
parameter is required and specifies the corresponding DNS A or AAAA record. mx
Optional. Define a DNS MX record for a particular domain. Specify only the domain part (
example.org
), not a FQDN address (other.example.org
).If only the
mx
parameter is specified, the dnsmasq DNS server will point to its own host as the MX host. If you want to specify a different host instead, you can do so by adding thetarget
parameter. Optionalpreference
orprioritty
parameters can be used to specify the MX record priority.srv
- Optional. Define DNS SRV Records. The parameter value is the
name of the SRV record; the
target
andport
parameters are required while thepreference
,priority
andweight
parameters are optional, see DNS SRV Records for further details. target
- Optional. This parameter is used in various DNS record entries to specify the "value" of a given DNS resource, usually a hostname, an IP address or other data.
preference
/priority
- Optional. These parameters are used with SRV or MX records to define priority for a given record, and tell the clients the desired order in which they should connect when there are multiple targets. The lower priority wins.
weight
- Optional. This parameter is used in the SRV record to further order different targets with the same priority.
port
- Optional. This parameter is used in the SRV record to specify the TCP/UDP port to which a given client should connect to. You can specify different ports for different targets if needed.
The DNS record names (A
, AAAA
, CNAME
, PTR
, SRV
, TXT
,
MX
) can be specified as uppercase or lowercase.
dnsmasq__configuration¶
The dnsmasq__*_configuration
variables define the contents of the
/etc/dnsmasq.d/*
configuration files. Each variable is a list of YAML
dictionaries. The list entries with the same name
parameter are merged
together; this allows to change specific parameters in the Ansible inventory
without the need to copy over the entire variable contents.
The interface configuration defined using the dnsmasq__*_interfaces
variables is converted to this format via a lookup template, therefore it's
possible to augment it using the dnsmasq__*_configuration
variables.
Examples¶
To see the examples of the configuration, you can look at the
dnsmasq__default_configuration
variable which defines the
dnsmasq default configuration set by the role.
Syntax¶
Each entry in the list is a YAML dictionary that describes one file in the
/etc/dnsmasq.d/
directory, using specific parameters:
name
- Required. The filename of the generated configuration file, it should include
a
.conf
extension. This parameter is used to merge multiple entries with the samename
together. filename
- Optional. This parameter can be used to override the filename used by the
role, for example if you want to modify a different file than the
name
parameter would suggest. state
Optional. If not specified or
present
, the given configuration file will be generated. Ifabsent
, the configuration file will not be generated and existing configuration file will be removed. Ifignore
, a given configuration entry will not be evaluated by the role; this can be used to enable or disable configuration entries conditionally.If
init
, a given configuration entry will be prepared by the role, but it will not be activated by default - these entries can be activated via Ansible inventory by setting the parameter topresent
.comment
- Optional. A string or YAML text block with a comment added at the top of the generated configuration file.
raw
- Optional. YAML text block with raw dnsmasq configuration file options. See dnsmasq(8) for syntax and possible options.
options
Optional. A YAML list of dnsmasq configuration options defined in the configuration file. The
options
parameters from different configuration entries are merged together, therefore it's easy to modify specific parameters without the need to copy the entire value to the inventory.Each element of the options list is a YAML dictionary with specific parameters:
name
- Required. This parameter defines the option name, and it needs to be unique
in a given configuration file. Parameters from different options lists with
the same
name
are merged together when the configuration entries are merged. option
- Optional. Because dnsmasq configuration files can specify the
same options multiple times, and the
name
parameter has to be unique to correctly merge the options lists, theoption
parameter can be used to specify the "actual" option name to be used in the configuration file. value
- Optional. Specify the option value for a given option.
raw
- Optional. Specify the raw dnsmasq(8) configuration options as
a string or a YAML text block. You can use this parameter to define
dnsmasq options that don't have specific values, for example
bogus-priv
orrebind-localhost-ok
. state
Optional. If not specified or
present
, a given option will be included in the configuration file. Ifabsent
, an option will be removed from the configuration file. Ifcomment
, an option will be included in the configuration file but commented out.If
init
, the option will be prepared by the role but it will not be included in the configuration file. This can be used to activate certain options via Ansible inventory. Ifignore
, a given configuration entry will not be evaluated by the role. This can be used to conditionally enable or disable options in the configuration files.comment
- Optional. A string or YAML text block with a comment added to a given option.