doc: publish documentation on GitHub pages

Add a new CI workflow (pages.yaml) to build and publish the project's
documentation using GitHub pages.

Signed-off-by: Quentin Deslandes <[email protected]>

.github/workflows/pages.yaml

@@ -0,0 +1,59 @@
+name: Deploy static content to Pages
+
+on:
+  push:
+    branches:
+      - main
+
+permissions:
+  contents: read
+  pages: write
+  id-token: write
+
+# Allow only one concurrent deployment, skipping runs queued between the run
+# in-progress and latest queued. However, do NOT cancel in-progress runs as
+# we want to allow these production deployments to complete.
+concurrency:
+  group: "pages"
+  cancel-in-progress: false
+
+jobs:
+  deploy:
+    container: "fedora:39"
+    runs-on: ubuntu-latest
+    steps:
+      - name: Setup Pages
+        uses: actions/configure-pages@v4
+      - name: Check out repository code
+        uses: actions/checkout@v4
+      - name: Install dependencies (Fedora)
+        run: |
+          sudo dnf --disablerepo=* --enablerepo=fedora,updates --setopt=install_weak_deps=False -y install \
+            clang-tools-extra \
+            cmake \
+            libcmocka-devel \
+            doxygen \
+            lcov \
+            libasan \
+            libbpf-devel \
+            libubsan \
+            python3-breathe \
+            python3-furo \
+            python3-sphinx \
+            pkgconf
+      - name: Configure build
+        run: cmake -S $GITHUB_WORKSPACE -B $GITHUB_WORKSPACE/build
+      - name: Generate documentation
+        run: make -C $GITHUB_WORKSPACE/build doc
+      - name: Fix permissions
+        run: |
+          chmod -c -R +rX "$GITHUB_WORKSPACE/build/doc/html" | while read line; do
+            echo "::warning title=Invalid file permissions automatically fixed::$line"
+          done
+      - name: Upload artifact
+        uses: actions/upload-pages-artifact@v3
+        with:
+          path: build/doc/html
+      - name: Deploy to GitHub Pages
+        id: deployment
+        uses: actions/deploy-pages@v4

doc/conf.py.in

@@ -20,4 +20,3 @@ breathe_show_include = True
 
 # -- Options for HTML output -------------------------------------------------
 html_theme = 'furo'
-html_static_path = ['_static']

doc/index.rst

@@ -3,10 +3,18 @@
    You can adapt this file completely to your liking, but it should at least
    contain the root `toctree` directive.
 
-bpfilter
-========
+``bpfilter``
+============
 
 .. toctree::
+   :maxdepth: 2
+   :caption: Usage
+
+   usage
+   iptables
+
+.. toctree::
+   :maxdepth: 2
+   :caption: Development
 
-   todo
    reference

doc/iptables.rst

@@ -0,0 +1,83 @@
+``iptables``
+============
+
+
+The purpose of this document is to guide you through the process of using ``iptables`` as a front-end for ``bpfilter``. Although ``iptables`` does not officially support ``bpfilter``, it can still route its requests directly to the ``bpfilter`` daemon instead of the Linux kernel.
+
+To facilitate the linking of ``iptables`` to ``bpfilter``, we recommend defining a directory for installing both. You can do this by using the following command:
+
+.. code-block:: shell
+
+    export INSTALL_DIRECTORY=$HOME/bpfilter_install
+
+
+Build ``bpfilter``
+------------------
+
+There is no special flag to build ``bpfilter`` to be used with ``iptables``, however you need to override ``CMAKE_INSTALL_PREFIX`` with your custom install directory. To do this, navigate to the bpfilter source directory and run the following commands:
+
+.. code-block:: shell
+
+    # Configure CMake
+    cmake -S . -B build -DCMAKE_INSTALL_PREFIX=$INSTALL_DIRECTORY
+
+    # Build and install bpfilter
+    make -C build install
+
+If you wish to build bpfilter in debug mode, simply add ``-DCMAKE_BUILD_TYPE=debug`` to the CMake command.
+
+Upon successful installation, ``bpfilter`` will be available at ``$INSTALL_DIRECTORY/bin/bpfilter``. The ``libbpfilter.so`` file can be found in the ``lib64`` directory, which is adjacent to the ``bin`` directory.
+
+Build ``iptables``
+------------------
+
+To use ``iptables`` with ``bpfilter``, you need to clone `this fork <https://github.com/qdeslandes/iptables.git>`_ and switch to the ``bpfilter`` branch. This version of ``iptables`` is identical to the one on your system, with the exception of the added ``--bpf`` option. This option allows ``iptables`` to communicate with ``bpfilter`` instead of the kernel.
+
+To configure ``iptables``, navigate to its source directory and run the following commands:
+
+.. code-block:: shell
+
+    ./autogen.sh
+
+    # Instruct the configure script where to find bpfilter and enable it.
+    PKG_CONFIG_PATH=$INSTALL_DIRECTORY/share/pkgconfig ./configure \
+        --prefix=$INSTALL_DIRECTORY \
+        --disable-nftables \
+        --enable-libipq \
+        --enable-bpfilter
+
+Upon completion of the configuration step, a summary of ``iptables``'s options will be displayed, including "bpfilter support".
+
+You can then proceed to build and install your custom ``iptables`` with the following commands:
+
+.. code-block:: shell
+
+    make
+    make install
+
+Please note that running ``make install`` alone is not sufficient to properly build and install ``iptables``. You must first build it using ``make``, and then install it with ``make install``.
+
+Usage
+-----
+
+With everything set up, you can now use ``iptables`` with ``bpfilter``. To initiate the daemon, use the following command:
+
+.. code-block:: shell
+
+    sudo $INSTALL_DIRECTORY/bin/bpfilter --transient --verbose
+
+Given that ``bpfilter`` is a project under active development, it's recommended to run it in transient mode (``--transient``). This ensures that no cache or BPF programs remain on your system once the daemon is stopped. The ``--verbose`` option, while not mandatory, can be helpful in understanding the daemon's operations.
+
+To use ``iptables`` and ensure that requests are routed to ``bpfilter``, use the ``--bpf`` switch:
+
+.. code-block:: shell
+
+    # List existing rules and counters
+    sudo $INSTALL_DIRECTORY/sbin/iptables-legacy -L -v --bpf
+
+    # Filter incoming ICMP packets
+    sudo $INSTALL_DIRECTORY/sbin/iptables-legacy -I INPUT -p icmp -j DROP --bpf
+
+The above example only filters incoming packets based on the protocol field. However, you're free to use the ``FORWARD`` or ``OUTPUT`` chains, and filter based on source or destination addresses, or ports.
+
+If you encounter any issues or have any questions, don't hesitate to open an issue!

doc/reference.rst

@@ -1,4 +1,4 @@
-Reference
-=========
+API reference
+=============
 
 .. doxygenindex::

doc/usage.rst

@@ -0,0 +1,22 @@
+Usage
+=====
+
+Command line options
+--------------------
+
+The bpfilter daemon must be run as root in order to write to `/run` and manipulate BPF programs. It supports the following arguments:
+
+- ``-t``, ``--transient``: if used, ``bpfilter`` won't pin any BPF program or map, and no data will be serialised to the filesystem. Hence, as soom as the daemon is stopped, the loaded BPF programs and maps will be removed from the system.
+- ``--no-iptables``: disable ``iptables`` support. If ``iptables`` is enabled, ``bpfilter`` will create passthrough programs to represent the ``INPUT``, ``OUTPUT``, and ``FORWARD`` hook used by ``iptables``, with ``ACCEPT`` as default policy. If ``iptables`` suport is disabled, no BPF program will be generated for ``iptables`` and ``bpfilter`` will answer to every request coming from ``iptables`` with a failure response.
+- ``-b``, ``--buffer-len=BUF_LEN_POW``: size of the ``BPF_PROG_LOAD`` buffer as a power of 2. Only available if ``--verbose`` is used. ``BPF_PROG_LOAD`` system call can be provided a buffer for the BPF verifier to provide details in case the program can't be loaded. The required size for the buffer being hardly predicatible, this option allows for the use to control it. The final buffer will have a size of ``1 << BUF_LEN_POWER``.
+- ``-v``, ``--verbose``: print more detailed log messages.
+- ``--usage``: print a short usage message.
+- ``-?``, ``--help``: print the help message
+
+``bpfilter`` on the system
+--------------------------
+
+Unless ``bpfilter`` is run in transient mode (``--transient``), it will create a new ``/run/bpfilter`` directory if it doesn't exists in order to store its socket file to listen on. This directory alose contains the serialised rulesets, allowing ``bpfilter`` to restore its internal state and keep track of its BPF program if the daemon is restarted.
+
+
+``bpfilter`` will use ``/run/bpfilter`` to store its runtime environment, as well as a serialised version of the current rulesets.