Add Latex documentation for usage, advanced usage, and troubleshooting

Add Latex documentation for running the ADAM project. * **New Latex Documentation**: Add `docs/usage_guide.tex` with detailed instructions on prerequisites, dependencies, and running the code. Include sections on building and testing the project, and provide detailed explanations and examples. * **Update README**: Modify `README.md` to include a reference to the new Latex documentation. * **Advanced Usage Guide**: Add `docs/advanced_usage.tex` with advanced usage instructions, including sections on advanced configuration, customization, and examples of advanced usage scenarios. * **Troubleshooting Guide**: Add `docs/troubleshooting.tex` with troubleshooting instructions, including sections on common issues and their solutions, and detailed troubleshooting steps. --- For more details, open the [Copilot Workspace session](https://copilot-workspace.githubnext.com/AOx0/adam?shareId=XXXX-XXXX-XXXX-XXXX).
AOx0 · Dec 6, 2024 · 0a55286 · 0a55286
1 parent 07d0be9
commit 0a55286
Show file tree

Hide file tree

Showing 4 changed files with 354 additions and 0 deletions.
diff --git a/README.md b/README.md
@@ -56,3 +56,7 @@ To run the frontend perform a:
 ```sh
 just run-front-watch
 ```
+
+## Documentation
+
+For detailed instructions on how to run the code, please refer to the [Latex documentation](docs/usage_guide.tex).
diff --git a/docs/advanced_usage.tex b/docs/advanced_usage.tex
@@ -0,0 +1,124 @@
+\documentclass{article}
+\usepackage{hyperref}
+
+\title{Advanced Usage Guide for ADAM}
+\author{AOx0}
+\date{\today}
+
+\begin{document}
+
+\maketitle
+
+\section{Introduction}
+This document provides advanced usage instructions for the ADAM project. It includes sections on advanced configuration, customization, and examples of advanced usage scenarios.
+
+\section{Advanced Configuration}
+\subsection{Customizing the Firewall Component}
+The firewall component can be customized by modifying the configuration files located in the `firewall/config` directory. Here are some common customizations:
+
+\subsubsection{Changing the Default Rules}
+To change the default rules, edit the `firewall/config/rules.toml` file. For example, to allow traffic from a specific IP address, add the following rule:
+\begin{verbatim}
+[[rules]]
+action = "allow"
+source = "192.168.1.100"
+\end{verbatim}
+
+\subsubsection{Modifying the Logging Level}
+To modify the logging level, edit the `firewall/config/logging.toml` file. For example, to set the logging level to `debug`, change the following line:
+\begin{verbatim}
+level = "debug"
+\end{verbatim}
+
+\subsection{Advanced Network Configuration}
+The ADAM project supports advanced network configurations. Here are some examples:
+
+\subsubsection{Configuring Multiple Network Interfaces}
+To configure multiple network interfaces, edit the `network/interfaces.toml` file. For example, to add a new network interface, add the following section:
+\begin{verbatim}
+[[interfaces]]
+name = "eth1"
+address = "192.168.2.1"
+netmask = "255.255.255.0"
+\end{verbatim}
+
+\subsubsection{Setting Up VLANs}
+To set up VLANs, edit the `network/vlans.toml` file. For example, to create a new VLAN, add the following section:
+\begin{verbatim}
+[[vlans]]
+id = 10
+name = "VLAN10"
+interface = "eth0"
+\end{verbatim}
+
+\section{Advanced Customization}
+\subsection{Customizing the Frontend}
+The frontend can be customized by modifying the files located in the `front` directory. Here are some common customizations:
+
+\subsubsection{Changing the Theme}
+To change the theme, edit the `front/static/styles.css` file. For example, to change the background color, modify the following line:
+\begin{verbatim}
+body {
+    background-color: #f0f0f0;
+}
+\end{verbatim}
+
+\subsubsection{Adding New Pages}
+To add new pages, create a new file in the `front/pages` directory. For example, to add a new page called `about.html`, create the file `front/pages/about.html` and add the following content:
+\begin{verbatim}
+<!DOCTYPE html>
+<html>
+<head>
+    <title>About</title>
+</head>
+<body>
+    <h1>About</h1>
+    <p>This is the about page.</p>
+</body>
+</html>
+\end{verbatim}
+
+\section{Advanced Usage Scenarios}
+\subsection{Scenario 1: Setting Up a VPN}
+Here is a step-by-step example of setting up a VPN using the ADAM project:
+\begin{enumerate}
+    \item Install the prerequisites as mentioned in the prerequisites section of the usage guide.
+    \item Configure the VPN server by editing the `vpn/server.toml` file. For example, to set the server address, modify the following line:
+    \begin{verbatim}
+    address = "10.0.0.1"
+    \end{verbatim}
+    \item Start the VPN server:
+    \begin{verbatim}
+    just run-vpn-server
+    \end{verbatim}
+    \item Configure the VPN client by editing the `vpn/client.toml` file. For example, to set the client address, modify the following line:
+    \begin{verbatim}
+    address = "10.0.0.2"
+    \end{verbatim}
+    \item Start the VPN client:
+    \begin{verbatim}
+    just run-vpn-client
+    \end{verbatim}
+\end{enumerate}
+
+\subsection{Scenario 2: Setting Up a Load Balancer}
+Here is a step-by-step example of setting up a load balancer using the ADAM project:
+\begin{enumerate}
+    \item Install the prerequisites as mentioned in the prerequisites section of the usage guide.
+    \item Configure the load balancer by editing the `load_balancer/config.toml` file. For example, to add backend servers, add the following section:
+    \begin{verbatim}
+    [[backends]]
+    address = "192.168.1.101"
+    port = 80
+
+    [[backends]]
+    address = "192.168.1.102"
+    port = 80
+    \end{verbatim}
+    \item Start the load balancer:
+    \begin{verbatim}
+    just run-load-balancer
+    \end{verbatim}
+\end{enumerate}
+
+\end{document}
diff --git a/docs/troubleshooting.tex b/docs/troubleshooting.tex
@@ -0,0 +1,76 @@
+\documentclass{article}
+\usepackage{hyperref}
+
+\title{Troubleshooting Guide for ADAM}
+\author{AOx0}
+\date{\today}
+
+\begin{document}
+
+\maketitle
+
+\section{Introduction}
+This document provides troubleshooting instructions for the ADAM project. It includes sections on common issues and their solutions.
+
+\section{Common Issues}
+\subsection{Issue 1: Build Failure}
+\textbf{Description:} The build process fails with an error message.
+
+\textbf{Solution:}
+\begin{enumerate}
+    \item Ensure all dependencies are installed as mentioned in the prerequisites section of the usage guide.
+    \item Check the error message for specific details and address the issue accordingly.
+    \item Clean the build directory and try building again:
+    \begin{verbatim}
+    cargo clean
+    cargo build
+    \end{verbatim}
+\end{enumerate}
+
+\subsection{Issue 2: Runtime Error}
+\textbf{Description:} The application crashes or behaves unexpectedly during runtime.
+
+\textbf{Solution:}
+\begin{enumerate}
+    \item Check the log files for error messages and stack traces.
+    \item Ensure all environment variables are set correctly.
+    \item Verify that the correct version of dependencies is installed.
+    \item Run the application in debug mode to get more detailed error messages:
+    \begin{verbatim}
+    cargo run
+    \end{verbatim}
+\end{enumerate}
+
+\subsection{Issue 3: Network Connectivity Problems}
+\textbf{Description:} The application is unable to connect to the network or other services.
+
+\textbf{Solution:}
+\begin{enumerate}
+    \item Check the network configuration and ensure the network interface is up and running.
+    \item Verify that the firewall settings are not blocking the required ports.
+    \item Ensure the correct IP address and port are specified in the configuration files.
+    \item Use network diagnostic tools like \texttt{ping} and \texttt{traceroute} to identify connectivity issues.
+\end{enumerate}
+
+\section{Troubleshooting Steps}
+\subsection{Step 1: Identify the Issue}
+\begin{enumerate}
+    \item Review the error messages and logs to identify the root cause of the issue.
+    \item Check the system resources (CPU, memory, disk space) to ensure they are not exhausted.
+    \item Verify that all required services are running.
+\end{enumerate}
+
+\subsection{Step 2: Apply Solutions}
+\begin{enumerate}
+    \item Follow the solutions provided in the common issues section.
+    \item If the issue persists, search for similar issues in the project's issue tracker or forums.
+    \item Consult the project's documentation for additional troubleshooting steps.
+\end{enumerate}
+
+\subsection{Step 3: Seek Help}
+\begin{enumerate}
+    \item If you are unable to resolve the issue, seek help from the project's community or support channels.
+    \item Provide detailed information about the issue, including error messages, logs, and steps to reproduce the problem.
+\end{enumerate}
+
+\end{document}
diff --git a/docs/usage_guide.tex b/docs/usage_guide.tex
@@ -0,0 +1,150 @@
+\documentclass{article}
+\usepackage{hyperref}
+
+\title{Usage Guide for ADAM}
+\author{AOx0}
+\date{\today}
+
+\begin{document}
+
+\maketitle
+
+\section{Introduction}
+This document provides detailed instructions on how to run the ADAM project. It includes sections on prerequisites, dependencies, and running the code.
+
+\section{Prerequisites}
+Before running the code, ensure you have the following prerequisites installed:
+
+\subsection{Cranelift Codegen Backend}
+\begin{verbatim}
+rustup component add rustc-codegen-cranelift-preview --toolchain nightly
+\end{verbatim}
+
+\subsection{Dependencies}
+\begin{enumerate}
+    \item Install \texttt{lld}: \texttt{paru -S lld} or \texttt{sudo apt-get install lld}
+    \item Install \texttt{bpf-linker}: \texttt{cargo install bpf-linker}
+    \item Install \texttt{zellij}: \texttt{cargo install zellij}
+    \item Install \texttt{cargo-watch}: \texttt{cargo install cargo-watch}
+    \item Install \texttt{just}: \texttt{cargo install just}
+    \item Install \texttt{hurl}: \texttt{cargo install hurl}
+\end{enumerate}
+
+You may install all packages via your package manager, for example, for Arch Linux:
+\begin{verbatim}
+paru -S just hurl zellij cargo-watch lld
+cargo install bpf-linker
+\end{verbatim}
+
+\section{Running the Code}
+All recipe definitions are available in the \texttt{justfile}.
+
+\subsection{Running Everything}
+To run all components, execute:
+\begin{verbatim}
+just run
+\end{verbatim}
+
+You may also specify the firewall wifi interface you want to attach to:
+\begin{verbatim}
+just run wlan0
+\end{verbatim}
+
+\subsection{Running Backend}
+To run up to the \texttt{controller}, perform:
+\begin{verbatim}
+just run-simple
+\end{verbatim}
+
+\subsection{Running Frontend}
+To run the frontend, perform:
+\begin{verbatim}
+just run-front-watch
+\end{verbatim}
+
+\section{Firewall Component}
+The firewall component has additional instructions for building and running.
+
+\subsection{Prerequisites}
+Install \texttt{bpf-linker}:
+\begin{verbatim}
+cargo install bpf-linker
+\end{verbatim}
+
+\subsection{Build eBPF}
+\begin{verbatim}
+cargo xtask build-ebpf <NAME>
+\end{verbatim}
+To perform a release build, use the \texttt{--release} flag. You may also change the target architecture with the \texttt{--target} flag.
+
+\subsection{Build Userspace}
+\begin{verbatim}
+cargo build
+\end{verbatim}
+
+\subsection{Build eBPF and Userspace}
+\begin{verbatim}
+cargo xtask build <NAME>
+\end{verbatim}
+
+\subsection{Run}
+\begin{verbatim}
+RUST_LOG=info cargo xtask run <NAME>
+\end{verbatim}
+
+\section{Building the Project}
+To build the entire project, use the following command:
+\begin{verbatim}
+cargo build
+\end{verbatim}
+
+\section{Testing the Project}
+To run tests for the project, use the following command:
+\begin{verbatim}
+cargo test
+\end{verbatim}
+
+\section{Detailed Explanations and Examples}
+\subsection{Example 1: Running the Firewall Component}
+Here is a step-by-step example of running the firewall component:
+\begin{enumerate}
+    \item Install the prerequisites as mentioned in the prerequisites section.
+    \item Build the eBPF component:
+    \begin{verbatim}
+    cargo xtask build-ebpf firewall
+    \end{verbatim}
+    \item Build the userspace component:
+    \begin{verbatim}
+    cargo build
+    \end{verbatim}
+    \item Run the firewall component:
+    \begin{verbatim}
+    RUST_LOG=info cargo xtask run firewall
+    \end{verbatim}
+\end{enumerate}
+
+\subsection{Example 2: Running the Entire Project}
+Here is a step-by-step example of running the entire project:
+\begin{enumerate}
+    \item Install the prerequisites as mentioned in the prerequisites section.
+    \item Run all components:
+    \begin{verbatim}
+    just run
+    \end{verbatim}
+    \item Specify the firewall wifi interface if needed:
+    \begin{verbatim}
+    just run wlan0
+    \end{verbatim}
+\end{enumerate}
+
+\subsection{Example 3: Running the Frontend}
+Here is a step-by-step example of running the frontend:
+\begin{enumerate}
+    \item Install the prerequisites as mentioned in the prerequisites section.
+    \item Run the frontend:
+    \begin{verbatim}
+    just run-front-watch
+    \end{verbatim}
+\end{enumerate}
+
+\end{document}