====== What is Dnsmasq ? ======

Dnsmasq provides network infrastructure for small networks: DNS, DHCP, router advertisement and network boot. It is designed to be lightweight and have a small footprint, suitable for resource constrained routers and firewalls. It has also been widely used for tethering on smartphones and portable hotspots, and to support virtual networking in virtualisation frameworks. Supported platforms include Linux (with glibc and uclibc), Android, *BSD, and Mac OS X. Dnsmasq is included in most Linux distributions and the ports systems of FreeBSD, OpenBSD and NetBSD. Dnsmasq provides full IPv6 support. 

More information at the [[https://thekelleys.org.uk/dnsmasq/doc.html|Dnsmasq web site]]

====== Installing Dnsmasq on TrueNAS ======

1. Log in to your TrueNAS server as root using SSH or the Shell option of the TrueNAS Web Portal.

2. Make some decisions and define some variables.
<code>
# Tailor each of these examples for your own situation
JAIL_NAME="net" # name of the jail that will contain the instance of dnsmasq

</code>

3. Install the software.
<code>
jexec "ioc-${JAIL_NAME:?}" pkg update
jexec "ioc-${JAIL_NAME:?} "pkg install dnsmasq

</code>

4. Prepare the dnsmasq configuration file structure.
<code>
jexec "ioc-${JAIL_NAME:?}" mkdir /usr/local/etc/dnsmasq.d
jexec "ioc-${JAIL_NAME:?}" mv /usr/local/etc/dnsmasq.conf /usr/local/etc/dnsmasq.d/1-original.conf
jexec "ioc-${JAIL_NAME:?}" touch /usr/local/etc/dnsmasq.d/2-standard.conf
jexec "ioc-${JAIL_NAME:?}" touch /usr/local/etc/dnsmasq.d/3-generated.conf
jexec "ioc-${JAIL_NAME:?}" touch /usr/local/etc/dnsmasq.d/4-bespoke.conf
jexec "ioc-${JAIL_NAME:?}" rm /usr/local/etc/dnsmasq.conf.sample

</code>

5. Configure dnsmasq to use this file structure.
<code>
jexec "ioc-${JAIL_NAME:?}" /bin/sh -c \
"cat >| /usr/local/etc/dnsmasq.conf" \
<<END
# Configuration file for dnsmasq
# Include all files in a directory which end in .conf
conf-dir=/usr/local/etc/dnsmasq.d/,*.conf
END

</code>

====== Configure Dnsmasq ======

1. Configure the "standard" options common to most installations.
<code>
jexec "ioc-${JAIL_NAME:?}" /bin/sh -c \
"cat >| /usr/local/etc/dnsmasq.d/2-standard.conf" \
<<END
# Standard configuration file for dnsmasq

# Never forward plain names (without a dot or domain part)
domain-needed

# Never forward addresses in the non-routed address spaces.
bogus-priv

# If you don't want dnsmasq to read /etc/resolv.conf or any other
# file, getting its servers from this file instead (see below), then
# uncomment this.
no-resolv

# If you don't want dnsmasq to poll /etc/resolv.conf or other resolv
# files for changes and re-read them then uncomment this.
no-poll

# If you don't want dnsmasq to read /etc/hosts, uncomment the
# following line.
no-hosts

# If a DHCP client claims that its name is "wpad", ignore that.
# This fixes a security hole. see CERT Vulnerability VU#598349
dhcp-name-match=set:wpad-ignore,wpad
dhcp-ignore-names=tag:wpad-ignore

# Add other name servers here, with domain specs if they are for
# non-public domains.
# Google DNS
server=8.8.4.4
server=8.8.8.8
# OpenDNS
#server=208.67.220.220
#server=208.67.222.222

# Set the cachesize here.
cache-size=1000

# Set the limit on DHCP leases, the default is 150
dhcp-lease-max=150

# The DHCP server needs somewhere on disk to keep its lease database.
# This defaults to a sane location, but if you want to change it, use
# the line below.
dhcp-leasefile=/var/lib/dnsmasq.leases

# Set the DHCP server to authoritative mode. In this mode it will barge in
# and take over the lease for any client which broadcasts on the network,
# whether it has a record of the lease or not. This avoids long timeouts
# when a machine wakes up on a new network. DO NOT enable this if there's
# the slightest chance that you might end up accidentally configuring a DHCP
# server for your campus/company accidentally. The ISC server uses
# the same option, and this URL provides more information:
# http://www.isc.org/files/auth.html
dhcp-authoritative

# For debugging purposes, log each DNS query as it passes through
# dnsmasq.
log-queries

# Log lots of extra information about DHCP transactions.
#log-dhcp

END

</code>

2. Configure the "bespoke" options specific to your needs.
<code>
jexec "ioc-${JAIL_NAME:?}" /bin/sh -c \
"cat >| /usr/local/etc/dnsmasq.d/4-bespoke.conf" \
<<END
# Bespoke configuration file for dnsmasq

# Uncomment this to enable the integrated DHCP server, you need
# to supply the range of addresses available for lease and optionally
# a lease time. If you have more than one network, you will need to
# repeat this for each network on which you want to supply DHCP
# service.
dhcp-range=192.168.1.200,192.168.1.249,1h

# Set the domain for dnsmasq. this is optional, but if it is set, it
# does the following things.
# 1) Allows DHCP hosts to have fully qualified domain names, as long
#     as the domain part matches this setting.
# 2) Sets the "domain" DHCP option thereby potentially setting the
#    domain of all systems configured by DHCP
# 3) Provides the domain part for "expand-hosts"
domain=net.joynt.org.uk

END

</code>

3. The "generated" options are created by an tool I am currently developing. More information coming soon.

====== Starting the Dnsmasq service ======

Start the Dnsmasq server now, and also when the jail boots up.
<code>
jexec "ioc-${JAIL_NAME:?}" sysrc dnsmasq_enable="YES"
jexec "ioc-${JAIL_NAME:?}" service dnsmasq start

</code>