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{deb1} using the following commands on the host:
\begin{lstlisting}[language=bash]
incus create images:debian/12 deb1
incus config set deb1 security.syscalls.intercept.mount true
incus config set deb1 security.nesting true
incus config set deb1 security.privileged true
incus start deb1
\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.


% New subsection for firewall settings
\subsection{Firewall Configuration}
To allow traffic forwarding between the \texttt{incusbr0} bridge and the \texttt{wlo1} wireless interface, the following iptables rules are applied:

\begin{lstlisting}
sudo iptables -A FORWARD -i incusbr0 -o wlo1 -j ACCEPT
sudo iptables -A FORWARD -i wlo1 -o incusbr0 -m state --state RELATED,ESTABLISHED -j ACCEPT
\end{lstlisting}

\subsection{Installing Additional Packages}
Install the necessary packages inside the container:
\begin{lstlisting}[language=bash]
incus exec deb1 -- apt update
incus exec deb1 -- 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 deb1 -- 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]
sudo useradd -m -s /bin/bash -G sudo user && echo 'user:pass' | sudo chpasswd
\end{lstlisting}

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

% New section for veth pair setup
\section{Setting Up a Veth Pair Between Container and Network Namespace}
To enable direct communication between a container and a network namespace, a virtual Ethernet (\texttt{veth}) pair is created. The following Python script (\texttt{link.py}) is used to create a \texttt{veth} pair between the \texttt{deb1} (an Incus container) and the \texttt{ns1} network namespace, with interfaces named \texttt{vA} and \texttt{vB}.

\begin{lstlisting}
sudo python3 link.py -n1 vA -t2 incus -ns2 deb1 -n2 vB
\end{lstlisting}

This command:
\begin{itemize}
  \item Creates a \texttt{veth} pair with one end (\texttt{vA}) in the default namespace and the other end (\texttt{vB}) in the \texttt{deb1}'s network namespace.
  \item Ensures the interfaces are set up and operational, allowing network traffic to flow between the container and the \texttt{ns1} namespace (or default namespace if \texttt{ns1} is not explicitly created).
\end{itemize}

The script uses the \texttt{pyroute2} library to manage network interfaces and namespaces, and supports container types such as Incus, LXC, LXD, and Docker. Ensure the \texttt{deb1} is running in Incus before executing the command.

\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 deb1 -- nano /etc/netplan/01-netcfg.yaml
\end{lstlisting}
Add the following configuration:
\begin{lstlisting}[language=yaml]
network:
  version: 2
  ethernets:
    vB:
      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 deb1 -- netplan apply
\end{lstlisting}


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


\subsection{Configuring dnsmasq}
Edit the \texttt{dnsmasq} configuration file at \texttt{/etc/dnsmasq.conf}:
\begin{lstlisting}[language=bash]
incus exec deb1 -- 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 deb1 -- systemctl restart dnsmasq
incus exec deb1 -- systemctl enable dnsmasq
\end{lstlisting}
Verify that \texttt{dnsmasq} is running:
\begin{lstlisting}[language=bash]
incus exec deb1 -- systemctl status dnsmasq
\end{lstlisting}

\subsection{Testing the Configuration}
Test DNS resolution from within the container:
\begin{lstlisting}[language=bash]
incus exec deb1 -- 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 deb1 -- 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 deb1 -- ip a} and \texttt{incus exec deb1 -- 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}