dnsmasq/doc/main.tex

\documentclass[a4paper,12pt]{article}
\usepackage[utf8]{inputenc}
\usepackage[T1]{fontenc}
\usepackage{lmodern}
\usepackage{geometry}
\geometry{margin=1in}
\usepackage{listings}
\usepackage{xcolor}
\usepackage{parskip}

\lstset{
  basicstyle=\ttfamily\small,
  breaklines=true,
  frame=single,
  numbers=left,
  numberstyle=\tiny,
  keywordstyle=\color{blue},
  commentstyle=\color{gray},
  stringstyle=\color{red}
}

% Define YAML language for listings
\lstdefinelanguage{yaml}{
  keywords={true,false,null,yaml,network,version,ethernets,dhcp4,addresses,routes,to,via,nameservers},
  keywordstyle=\color{blue}\bfseries,
  basicstyle=\ttfamily\small,
  sensitive=false,
  comment=[l]{\#},
  commentstyle=\color{gray}\itshape,
  stringstyle=\color{red},
  morestring=[b]{"},
  morestring=[b]{'}
}

\begin{document}

\title{Basic Configuration of dnsmasq in an Incus Container on Debian with Netplan}
\author{}
\date{}
\maketitle

\section{Introduction}
This guide provides step-by-step instructions for setting up \texttt{dnsmasq} as a DNS and DHCP server in an Incus container running Debian. The network configuration is managed using Netplan to ensure proper network integration.

\section{Prerequisites}
Before proceeding, ensure the following:
\begin{itemize}
  \item Incus is installed on the host system (\texttt{sudo apt install incus}).
  \item A Debian-based container is created in Incus.
  \item Basic knowledge of Linux networking and container management.
  \item Root or sudo access to the host and container.
\end{itemize}

\section{Step-by-Step Configuration}

\subsection{Creating and Setting Up the Incus Container}
Create a Debian container named \texttt{dnsmasq-container} using the following commands on the host:
\begin{lstlisting}[language=bash]
incus create images:debian/12 dnsmasq-container
incus config set dnsmasq-container security.syscalls.intercept.mount true
incus config set dnsmasq-container security.nesting true
incus config set dnsmasq-container security.privileged true
incus start dnsmasq-container
\end{lstlisting}
The \texttt{security.syscalls.intercept.mount}, \texttt{security.nesting}, and \texttt{security.privileged} settings are required for \texttt{dnsmasq} and Docker to function correctly in the container.

\subsection{Installing Additional Packages}
Install the necessary packages inside the container:
\begin{lstlisting}[language=bash]
incus exec dnsmasq-container -- apt update
incus exec dnsmasq-container -- apt install -y \
    netplan.io \
    sudo vim nano git tmux mc zip unzip curl wget htop lynx \
    iproute2 termshark bridge-utils \
    python3 python3-ipython python3-pyroute2 python3-scapy \
    docker.io docker-compose
\end{lstlisting}

\subsection{Configuring Users and Permissions}
Configure user access and permissions within the container.

\subsubsection{Changing the Root Password}
Set the root password to "passroot":
\begin{lstlisting}[language=bash]
incus exec dnsmasq-container -- bash -c 'echo "root:passroot" | chpasswd'
\end{lstlisting}

\subsubsection{Adding a New User}
Add a new user named "user" with the password "pass" and add them to the "sudo" and "docker" groups:
\begin{lstlisting}[language=bash]
incus exec dnsmasq-container -- useradd -m -s /bin/bash user
incus exec dnsmasq-container -- bash -c 'echo "user:pass" | chpasswd'
incus exec dnsmasq-container -- usermod -aG sudo user
incus exec dnsmasq-container -- usermod -aG docker user
\end{lstlisting}

After creating the user, you can also transfer configuration files such as \texttt{.tmux.conf} and \texttt{.vimrc} from your local machine to the home directory of the newly created user inside the container:

\begin{lstlisting}[language=bash]
incus file push .tmux.conf dnsmasq-container/home/user/
incus file push .vimrc dnsmasq-container/home/user/
\end{lstlisting}

To enhance the functionality of Vim, it's recommended to install a plugin manager such as \texttt{vim-plug}. This can be done by downloading the plugin manager directly into the user's Vim configuration directory using the following command:

\begin{lstlisting}[language=bash]
curl -fLo ~/.vim/autoload/plug.vim --create-dirs \\
    https://raw.githubusercontent.com/junegunn/vim-plug/master/plug.vim
\end{lstlisting}

\subsection{Accessing the Container}
Access the container's shell:
\begin{lstlisting}[language=bash]
incus exec dnsmasq-container -- bash
\end{lstlisting}

\subsection{Installing dnsmasq}
Update the package list and install \texttt{dnsmasq}:
\begin{lstlisting}[language=bash]
incus exec dnsmasq-container -- apt update
incus exec dnsmasq-container -- apt install dnsmasq -y
\end{lstlisting}

\subsection{Configuring the Network with Netplan}
Configure the container's network using Netplan to assign a static IP address. Create or edit the Netplan configuration file at \texttt{/etc/netplan/01-netcfg.yaml}:
\begin{lstlisting}[language=bash]
incus exec dnsmasq-container -- nano /etc/netplan/01-netcfg.yaml
\end{lstlisting}
Add the following configuration:
\begin{lstlisting}[language=yaml]
network:
  version: 2
  ethernets:
    eth0:
      dhcp4: no
      addresses:
        - 192.168.1.10/24
      routes:
        - to: default
          via: 192.168.1.1
      nameservers:
        addresses: [8.8.8.8, 8.8.4.4]
\end{lstlisting}
Apply the configuration:
\begin{lstlisting}[language=bash]
incus exec dnsmasq-container -- netplan apply
\end{lstlisting}

\subsection{Configuring dnsmasq}
Edit the \texttt{dnsmasq} configuration file at \texttt{/etc/dnsmasq.conf}:
\begin{lstlisting}[language=bash]
incus exec dnsmasq-container -- nano /etc/dnsmasq.conf
\end{lstlisting}
Add or modify the following settings to enable DNS and DHCP:
\begin{lstlisting}
# DNS settings
domain-needed
bogus-priv
no-resolv
server=8.8.8.8
server=8.8.4.4
local=/example.local/
domain=example.local

# DHCP settings
dhcp-range=192.168.1.100,192.168.1.200,12h
dhcp-option=3,192.168.1.1
dhcp-option=6,8.8.8.8,8.8.4.4
\end{lstlisting}

\textbf{Explanation:}
\begin{itemize}
  \item \texttt{domain-needed}: Prevents incomplete domain names from being sent to upstream DNS.
  \item \texttt{bogus-priv}: Blocks reverse DNS lookups for private IP ranges.
  \item \texttt{no-resolv}: Disables reading \texttt{/etc/resolv.conf}.
  \item \texttt{server}: Specifies upstream DNS servers (Google DNS in this case).
  \item \texttt{local} and \texttt{domain}: Configures a local domain.
  \item \texttt{dhcp-range}: Defines the IP range for DHCP clients (from 192.168.1.100 to 192.168.1.200, lease time 12 hours).
  \item \texttt{dhcp-option}: Sets the default gateway (option 3) and DNS servers (option 6).
\end{itemize}

\subsection{Starting and Enabling dnsmasq}
Restart and enable the \texttt{dnsmasq} service:
\begin{lstlisting}[language=bash]
incus exec dnsmasq-container -- systemctl restart dnsmasq
incus exec dnsmasq-container -- systemctl enable dnsmasq
\end{lstlisting}
Verify that \texttt{dnsmasq} is running:
\begin{lstlisting}[language=bash]
incus exec dnsmasq-container -- systemctl status dnsmasq
\end{lstlisting}

\subsection{Testing the Configuration}
Test DNS resolution from within the container:
\begin{lstlisting}[language=bash]
incus exec dnsmasq-container -- nslookup example.local 192.168.1.10
\end{lstlisting}
To test DHCP, connect a client device to the same network and verify that it receives an IP address in the range \texttt{192.168.1.100--192.168.1.200}.

\section{Troubleshooting}
If \texttt{dnsmasq} fails to start:
\begin{itemize}
  \item Check the logs: \texttt{incus exec dnsmasq-container -- journalctl -u dnsmasq}.
  \item Ensure no other service is using port 53 (DNS) or 67 (DHCP).
  \item Verify the network configuration with \texttt{incus exec dnsmasq-container -- ip a} and \texttt{incus exec dnsmasq-container -- ping 8.8.8.8}.
\end{itemize}

\section{Conclusion}
This guide configures \texttt{dnsmasq} as a DNS and DHCP server in an Incus container on Debian. The Netplan configuration ensures proper network setup. For advanced configurations, refer to the \texttt{dnsmasq} documentation (\texttt{man dnsmasq}).

\end{document}