link/doc/main.tex

\documentclass[a4paper,12pt]{article}
\usepackage{amsmath}
\usepackage{listings}
\usepackage{hyperref}
\usepackage{xcolor}

\title{Quick Guide: Using link.py for Veth Pair Management in Incus Containers}
\author{c2023}
\date{\today}

\lstset{
    basicstyle=\ttfamily\footnotesize,
    frame=single,
    backgroundcolor=\color{gray!10},
    keywordstyle=\color{blue},
    commentstyle=\color{green!70!black},
    breaklines=true,
    captionpos=b
}

\begin{document}

\maketitle

\section*{Introduction}
This document provides a quick guide on using \texttt{link.py} to create and manage virtual Ethernet (veth) pairs in Incus containers. Veth pairs are useful for creating network connections between different network namespaces, such as those used by containers. 

\section*{Requirements}
\begin{itemize}
    \item \textbf{Python} (preferably version 3.x)
    \item \textbf{Root privileges}: Run \texttt{link.py} with \texttt{sudo} to ensure the necessary permissions.
    \item \textbf{Incus installed} and properly configured on your system.
    \item \textbf{Running containers}: Ensure that the Incus containers you want to connect are running.
\end{itemize}

\section*{Basic Usage}

The general syntax to run \texttt{link.py} is as follows:
\begin{lstlisting}[language=bash]
sudo python link.py \
    -ns1 <namespace1> -t1 <type1> \
    -ns2 <namespace2> -t2 <type2> \
    -n1 <veth1> -n2 <veth2> \
    [-b1 <bridge1>] [-b2 <bridge2>]
\end{lstlisting}

\begin{itemize}
    \item \texttt{-ns1}, \texttt{-ns2}: Names of the network namespaces or containers.
    \item \texttt{-t1}, \texttt{-t2}: Container type (use \texttt{incus} for Incus containers).
    \item \texttt{-n1}, \texttt{-n2}: Names of the veth interfaces.
    \item \texttt{-b1}, \texttt{-b2} (optional): Attach veth to a specified bridge on either end.
\end{itemize}

\section*{Example Commands}

\subsection*{Example 1: Connect Host and Incus Container}
Connect the host network namespace to an Incus container's network namespace.
\begin{lstlisting}[language=bash]
sudo python link.py \
    -ns1 my_incus_container -t1 incus \
    -n1 veth_container -n2 veth_host
\end{lstlisting}

\subsection*{Example 2: Connect Two Incus Containers}
Create a veth pair connecting two Incus containers.
\begin{lstlisting}[language=bash]
sudo python link.py \
    -ns1 incus_container1 -t1 incus \
    -ns2 incus_container2 -t2 incus \
    -n1 veth1 -n2 veth2
\end{lstlisting}

\subsection*{Example 3: Attach Host End to a Bridge}
Create a veth pair between the host and an Incus container, attaching the host end to a bridge named \texttt{br0}.
\begin{lstlisting}[language=bash]
sudo python link.py \
    -ns1 my_incus_container -t1 incus \
    -n1 veth_container -n2 veth_host \
    -b2 br0
\end{lstlisting}

\section*{Notes}
\begin{itemize}
    \item If \texttt{'1'} is specified for \texttt{-ns1} or \texttt{-ns2}, it defaults to the host namespace.
    \item Ensure bridges exist before attempting to attach veth pairs to them.
    \item The script automatically brings up interfaces and bridges after creation.
\end{itemize}

\section*{Testing Connectivity}
Assign IP addresses to each end of the veth pair for testing connectivity. Example commands:
\begin{lstlisting}[language=bash]
# On the host
sudo ip addr add 192.168.10.1/24 dev veth_host

# Inside the Incus container
sudo incus exec my_incus_container -- ip addr add 192.168.10.2/24 dev veth_container

# Test with ping
ping 192.168.10.2
\end{lstlisting}

\section*{Troubleshooting}
\begin{itemize}
    \item \textbf{Permission errors}: Ensure you're running the script with \texttt{sudo}.
    \item \textbf{Interface not found}: Verify that the interface names are unique and do not conflict with existing interfaces.
    \item \textbf{Container not found}: Check that the Incus container names are correct and that they are running.
\end{itemize}

\end{document}