= Dnsmasq =

'''`dnsmasq(8)`''' is a lightweight [[Protocols/DNS|DNS]] server. It also offers [[Protocols/DHCP|DHCP]], proxy DHCP, TFTP, and PXE.

<<TableOfContents>>

----



== Installation ==

Most [[Linux]] and [[BSD]] distributions offer a `dnsmasq` package.

For `systemd`-capable systems, [[Linux/Systemd|start and enable]] `dnsmasq.service`.

For BSD distributions, try:

{{{
service dnsmasq restart
}}}

To launch the server on startup, update /etc/rc.conf:

{{{
dnsmasq_enable="YES"
dnsmasq_conf="/usr/local/etc/dnsmasq.conf"
}}}



=== Containers ===

To containerize  `dnsmasq(8)`, consider the following [[Docker/Dockerfile|Dockerfile]] as a template.

{{{
FROM alpine:latest
RUN apk add --no-cache dnsmasq dumb-init
EXPOSE 53 53/udp
ENTRYPOINT ["/usr/bin/dumb-init", "--"]
CMD ["dnsmasq", "--keep-in-foreground"]
}}}

To publish this service on an interface like `10.0.0.1`, try:

{{{
sudo docker build --tag dnsmasq .
sudo docker run --detach --name my-dnsmasq \
  --restart=always \
  --mount type=bind,src=/path/to/dnsmasq.conf,target=/etc/dnsmasq.conf,readonly \
  --publish 10.0.0.1:53:53/udp \
  dnsmasq
}}}

----



== Configuration ==

`dnsmasq(8)` is configured with a configuration file. This typically is located in either `/etc/dnsmasq.conf` (for Linux distributions) or `/usr/local/etc/dnsmasq.conf` (for BSD distributions).

Test the configuration using `dnsmasq --test`.

A basic configuration file is:

{{{
listen-address=::1,127.0.0.1
cache-size=150

# DNSSEC
conf-file=/usr/share/dnsmasq/trust-anchors.conf
dnssec
}}}



=== Disable DNS ===

To disable the DNS features of `dnsmasq(8)`, edit the configuration file such that...

{{{
port=0
}}}



=== Recursive DNS ===

`dnsmasq(8)` is ''not'' a recursive DNS server, so trusted (i.e. DNSSEC) forwarding must be setup. Pursue one of the following configurations:

 1. Configure [[Linux/ResolvConfConf#Example|openresolv]] and include the below lines in the configuration file:

{{{
# Configurations generated by `resolvconf(1)`
conf-file=/etc/dnsmasq-conf.conf
resolv-file=/etc/dnsmasq-resolv.conf
}}}

 2.#2 Manually configure like...

{{{
127.0.0.1 localhost
::1       localhost
trust-ad
}}}

 ...and manually configure like...

{{{
no-hosts
no-resolv

server=8.8.8.8
server=8.8.4.4
}}}



=== Network DNS ===

To operate `dnsmasq(8)` as a DNS server, ensure that it listens on a private address.

{{{
listen-address=::1,127.0.0.1,192.168.86.1
}}}

Provide an additional [[Linux/Hosts|hosts(5) file]] (i.e. `/etc/dnsmasq.hosts`) by configuring like:

{{{
no-hosts
no-resolv

addn-hosts=/etc/dnsmasq.hosts

server=8.8.8.8
server=8.8.4.4
}}}



=== Overriding Names ===

`dnsmasq(8)` offers a search/replace syntax for forcing names to resolve into hardcoded addresses. Specificity wins, so given...

{{{
address=/example.com/1.2.3.4
address=/www.example.com/2.3.4.5
}}}

...`www.example.com` would resolve to `2.3.4.5`.

Note that this breaks reverse DNS.



=== Blacklisting Names ===

To blacklist a name, use the search/replace syntax and return a blank address.

{{{
address=/example.com/
}}}

Managed blacklists can be inserted, as with `conf-file=/etc/dnsmasq.d/blocklist.conf` or `conf-dir=/etc/dnsmasq.d/,*.conf`.

----



== Troubleshooting ==



=== WireGuard Interfaces ===

The service will fail if one of the listening IPs isn't bindable, as would be the case with a [[Encryption/WireGuard|WireGuard]] interface that has not opened yet.

One solution is to switch to dynamic binding. In `/etc/dnsmasq.conf`...

{{{
bind-dynamic
}}}

Note that some distributions vendor the configurations to set `bind-interface`. For example, [[Linux/Ubuntu|Ubuntu]] ships `/etc/dnsmasq.d/ubuntu-fan`.

Another solution is to ensure that the interface opens first. With `systemctl edit dnsmasq`...

{{{
[Unit]
After=wg-quick@wg0.service
Wants=wg-quick@wg0.service
}}}

----



== See also ==

[[https://man.archlinux.org/man/dnsmasq.8|dnsmasq(8)]]



----
CategoryRicottone