feat: flip swap mechanism — MD as primary, RST as override (Phase 1)

This is the first of three phases inverting the per-page swap mechanism
so MD becomes the canonical primary and RST becomes the rare override.

Phase 1 — file renames + conf.py exclude_patterns flip only:
- Rename docs/**/md-<stem>.md to docs/**/<stem>.md (drop md- prefix)
  for all 254 stems previously listed in docs/_swap.txt
- Rename docs/**/<stem>.rst to docs/**/rst-<stem>.rst (add rst- prefix)
  for the same 254 stems
- Repurpose docs/_swap.txt as docs/_rst_overrides.txt; initially empty
  comment-only since no pages need the RST fallback right now
- conf.py exclude_patterns flipped: rst-*.rst is now excluded by default
  instead of md-*.md
- conf.py runtime-artifact references updated to _rst_override_state.json
  and _md_exclude.txt (Phase 2 will rewrite swap_sources.py to produce
  these names; for now no swap script runs because overrides list is empty)

Phase 2 (next commit on this branch) will rewrite scripts/swap_sources.py
with inverted rename direction, delete scripts/import_myst.py + tests, and
update tests/test_swap_sources.py for the new semantics.

Phase 3 will be the cleanup pass and ready-for-review flip.

Generated by robots https://vyos.io

1 files changed, 730 insertions, 0 deletions

diff --git a/docs/contributing/build-vyos.md b/docs/contributing/build-vyos.md
new file mode 100644
index 00000000..bfda5298
--- /dev/null
+++ b/docs/contributing/build-vyos.md
@@ -0,0 +1,730 @@
+---
+lastproofread: '2025-12-05'
+---
+
+(build)=
+
+# Build VyOS
+
+## Prerequisites
+
+There are different ways you can build VyOS. Building using a
+{ref}`build_docker`
+container is the easiest way because all dependencies are managed for you.
+Alternatively, you can set up your own build machine and run a
+{ref}`build_native` build.
+
+:::{note}
+Starting with VyOS 1.4, only source code and Debian package
+repositories of the rolling release (the **current** branch) are publicly
+available.
+
+The source code and pre-built Debian package repositories of LTS releases
+are only available to subscription holders (customers and active community
+members with contributors subscriptions).
+
+The following includes the build process for VyOS rolling release.
+:::
+
+This will guide you through the process of building a VyOS ISO using [Docker].
+This process has been tested on clean installs of Debian Bookworm.
+
+(build_native)=
+
+### Native Build
+
+To build VyOS natively, you need a properly configured build host with
+Debian Bookworm installed.
+
+To get started, clone the repository to your local machine:
+
+```none
+$ sudo make clean
+$ sudo ./build-vyos-image --architecture amd64 --build-by "j.randomhacker@vyos.io" generic
+```
+
+For required packages, refer to the `docker/Dockerfile` file in the
+[repository]. The `./build-vyos-image` script will also warn you if any
+dependencies are missing.
+
+(build_docker)=
+
+### Docker
+
+Installing [Docker] and prerequisites:
+
+:::{hint}
+Docker versions are updated frequently. The following examples may
+become outdated.
+:::
+
+```none
+# Add Docker's official GPG key:
+sudo apt-get update
+sudo apt-get install ca-certificates curl gnupg
+sudo install -m 0755 -d /etc/apt/keyrings
+curl -fsSL https://download.docker.com/linux/debian/gpg | sudo gpg --dearmor -o /etc/apt/keyrings/docker.gpg
+sudo chmod a+r /etc/apt/keyrings/docker.gpg
+
+# Add the repository to Apt sources:
+echo \
+  "deb [arch=$(dpkg --print-architecture) signed-by=/etc/apt/keyrings/docker.gpg] https://download.docker.com/linux/debian \
+  $(. /etc/os-release && echo "$VERSION_CODENAME") stable" | \
+  sudo tee /etc/apt/sources.list.d/docker.list > /dev/null
+
+sudo apt-get update
+sudo apt-get install docker-ce docker-ce-cli containerd.io docker-buildx-plugin docker-compose-plugin
+```
+
+To use Docker without `sudo`, add your current non-root user to the `docker`
+group: `sudo usermod -aG docker yourusername`.
+
+:::{hint}
+Adding a user to the `docker` group grants privileges equivalent to
+`root`. It is recommended to remove the non-root user from the `docker`
+group after building the VyOS ISO. See also [Docker as non-root].
+:::
+
+:::{note}
+The build process must run on a local file system. Building on SMB or
+NFS shares will cause the container to fail. VirtualBox shared folders are
+also not supported because block device operations are not implemented.
+:::
+
+#### Build Container
+
+The container can be built by hand or by fetching the pre-built one from
+DockerHub. It is recommended to use the pre-built containers from the
+[VyOS DockerHub organisation](https://hub.docker.com/u/vyos). The container
+is built from Docker packages automatically after every commit to the
+``vyos-build`` repository (this process may take 2-3 hours).
+
+:::{note}
+If you use the pre-built container, it will be automatically
+downloaded from DockerHub if it is not found on your local machine when
+you build the ISO.
+:::
+
+##### Dockerhub
+
+To manually download the container from DockerHub, run:
+
+```none
+$ docker pull vyos/vyos-build:current  # For VyOS rolling release
+```
+
+
+##### Build from source
+
+The container can also be built directly from source:
+
+```none
+$ git clone -b current --single-branch https://github.com/vyos/vyos-build
+
+$ cd vyos-build
+$ docker build -t vyos/vyos-build:current docker
+```
+
+:::{note}
+VyOS switched to Debian Bookworm (12) in its `current` branch.
+Due to software version updates, it is recommended to use the official
+Docker Hub image to build VyOS ISO.
+:::
+
+#### Tips and Tricks
+
+You can create Bash aliases to easily launch the latest container per release
+train (`current`). Add the following to your `.bash_aliases` file:
+
+```none
+alias vybld='docker pull vyos/vyos-build:current && docker run --rm -it \
+    -v "$(pwd)":/vyos \
+    -v "$HOME/.gitconfig":/etc/gitconfig \
+    -v "$HOME/.bash_aliases":/home/vyos_bld/.bash_aliases \
+    -v "$HOME/.bashrc":/home/vyos_bld/.bashrc \
+    -w /vyos --privileged --sysctl net.ipv6.conf.lo.disable_ipv6=0 \
+    -e GOSU_UID=$(id -u) -e GOSU_GID=$(id -g) \
+    vyos/vyos-build:current bash'
+```
+
+Now you have a new alias `vybld` that launches development containers in
+your current working directory.
+
+:::{note}
+Some VyOS packages (namely vyos-1x) come with build-time tests which
+verify some of the internal library calls that they work as expected. Those
+tests are carried out through the Python Unittest module. If you want to
+build the `vyos-1x` package (which is our main development package) you
+need to start your Docker container using the following argument:
+`--sysctl net.ipv6.conf.lo.disable_ipv6=0`, otherwise those tests will
+fail.
+:::
+
+(build-iso)=
+
+## Build ISO
+
+Now that you understand the prerequisites, you can build a VyOS ISO from source.
+First, fetch the latest source code from GitHub:
+
+```none
+$ git clone -b current --single-branch https://github.com/vyos/vyos-build
+```
+
+Now you can begin a fresh VyOS ISO build. Change to the `vyos-build`
+directory and run:
+
+```none
+$ cd vyos-build
+$ docker run --rm -it --privileged -v $(pwd):/vyos -w /vyos vyos/vyos-build:current bash
+```
+
+Start the build:
+
+```none
+vyos_bld@8153428c7e1f:/vyos$ sudo make clean
+vyos_bld@8153428c7e1f:/vyos$ sudo ./build-vyos-image --architecture amd64 --build-by "j.randomhacker@vyos.io" generic
+```
+
+When the build is successful, find the resulting ISO in the `build` directory
+as `live-image-[architecture].hybrid.iso`.
+
+(build-source)=
+
+(customize)=
+
+### Customize
+
+You can customize the ISO with the following configure options. Generate the
+full and current list with `./build-vyos-image --help`:
+
+```none
+$ vyos_bld@8153428c7e1f:/vyos$ sudo ./build-vyos-image --help
+  I: Checking if packages required for VyOS image build are installed
+  usage: build-vyos-image [-h] [--architecture ARCHITECTURE]
+  [--build-by BUILD_BY] [--debian-mirror DEBIAN_MIRROR]
+  [--debian-security-mirror DEBIAN_SECURITY_MIRROR]
+  [--pbuilder-debian-mirror PBUILDER_DEBIAN_MIRROR]
+  [--vyos-mirror VYOS_MIRROR] [--build-type BUILD_TYPE]
+  [--version VERSION] [--build-comment BUILD_COMMENT] [--debug] [--dry-run]
+  [--custom-apt-entry CUSTOM_APT_ENTRY] [--custom-apt-key CUSTOM_APT_KEY]
+  [--custom-package CUSTOM_PACKAGE]
+      [build_flavor]
+
+  positional arguments:
+  build_flavor          Build flavor
+
+  optional arguments:
+  -h, --help            show this help message and exit
+  --architecture ARCHITECTURE
+                          Image target architecture (amd64 or arm64)
+  --build-by BUILD_BY   Builder identifier (e.g. jrandomhacker@example.net)
+  --debian-mirror DEBIAN_MIRROR
+                          Debian repository mirror
+  --debian-security-mirror DEBIAN_SECURITY_MIRROR
+                          Debian security updates mirror
+  --pbuilder-debian-mirror PBUILDER_DEBIAN_MIRROR
+                          Debian repository mirror for pbuilder env bootstrap
+  --vyos-mirror VYOS_MIRROR
+                          VyOS package mirror
+  --build-type BUILD_TYPE
+                          Build type, release or development
+  --version VERSION     Version number (release builds only)
+  --build-comment BUILD_COMMENT
+                          Optional build comment
+  --debug               Enable debug output
+  --dry-run             Check build configuration and exit
+  --custom-apt-entry CUSTOM_APT_ENTRY
+                          Custom APT entry
+  --custom-apt-key CUSTOM_APT_KEY
+                          Custom APT key file
+  --custom-package CUSTOM_PACKAGE
+                          Custom package to install from repositories
+```
+
+(iso_build_issues)=
+
+#### ISO Build Issues
+
+There are (rare) situations where building an ISO image is not possible at all
+due to a broken package feed in the background. APT is not very good at
+reporting the root cause of the issue. Your ISO build will likely fail with a
+more or less similar looking error message:
+
+```none
+The following packages have unmet dependencies:
+ vyos-1x : Depends: accel-ppp but it is not installable
+E: Unable to correct problems, you have held broken packages.
+P: Begin unmounting filesystems...
+P: Saving caches...
+Reading package lists...
+Building dependency tree...
+Reading state information...
+Del frr-pythontools 7.5-20210215-00-g8a5d3b7cd-0 [38.9 kB]
+Del accel-ppp 1.12.0-95-g59f8e1b [475 kB]
+Del frr 7.5-20210215-00-g8a5d3b7cd-0 [2671 kB]
+Del frr-snmp 7.5-20210215-00-g8a5d3b7cd-0 [55.1 kB]
+Del frr-rpki-rtrlib 7.5-20210215-00-g8a5d3b7cd-0 [37.3 kB]
+make: *** [Makefile:30: iso] Error 1
+(10:13) vyos_bld ece068908a5b:/vyos [current] #
+```
+
+To debug the build process and gain additional information of what could be the
+root cause, you need to use `chroot` to change into the build directory. This is
+explained in the following step by step procedure:
+
+```none
+vyos_bld ece068908a5b:/vyos [current] # sudo chroot build/chroot /bin/bash
+```
+
+We now need to mount some required, volatile filesystems
+
+```none
+(live)root@ece068908a5b:/# mount -t proc none /proc
+(live)root@ece068908a5b:/# mount -t sysfs none /sys
+(live)root@ece068908a5b:/# mount -t devtmpfs none /dev
+```
+
+We now are free to run any command we would like to use for debugging, e.g.
+re-installing the failed package after updating the repository.
+
+```none
+(live)root@ece068908a5b:/# apt-get update; apt-get install vyos-1x
+Get:1 file:/root/packages ./ InRelease
+Ign:1 file:/root/packages ./ InRelease
+Get:2 file:/root/packages ./ Release [1235 B]
+Get:2 file:/root/packages ./ Release [1235 B]
+Get:3 file:/root/packages ./ Release.gpg
+Ign:3 file:/root/packages ./ Release.gpg
+Hit:4 http://repo.powerdns.com/debian buster-rec-43 InRelease
+Hit:5 http://repo.saltstack.com/py3/debian/10/amd64/archive/3002.2 buster InRelease
+Hit:6 http://deb.debian.org/debian bullseye InRelease
+Hit:7 http://deb.debian.org/debian buster InRelease
+Hit:8 http://deb.debian.org/debian-security buster/updates InRelease
+Hit:9 http://deb.debian.org/debian buster-updates InRelease
+Hit:10 http://deb.debian.org/debian buster-backports InRelease
+Hit:11 http://dev.packages.vyos.net/repositories/current current InRelease
+Reading package lists... Done
+N: Download is performed unsandboxed as root as file '/root/packages/./InRelease' couldn't be accessed by user '_apt'. - pkgAcquire::Run (13: Permission denied)
+Reading package lists... Done
+Building dependency tree
+Reading state information... Done
+Some packages could not be installed. This may mean that you have
+requested an impossible situation or if you are using the unstable
+distribution that some required packages have not yet been created
+or been moved out of Incoming.
+The following information may help to resolve the situation:
+
+The following packages have unmet dependencies:
+ vyos-1x : Depends: accel-ppp but it is not installable
+E: Unable to correct problems, you have held broken packages.
+```
+
+Now it's time to fix the package mirror and rerun the last step until the
+package installation succeeds again!
+
+(build_custom_packages)=
+
+### Linux Kernel
+
+The Linux kernel used by VyOS is heavily tied to the ISO build process. The
+file `data/defaults.json` hosts a JSON definition of the kernel version used
+`kernel_version` and the `kernel_flavor` of the kernel which represents the
+kernel's LOCAL_VERSION. Both together form the kernel version variable in the
+system:
+
+```none
+vyos@vyos:~$ uname -r
+6.1.52-amd64-vyos
+```
+
+- Accel-PPP
+- Intel NIC drivers
+- Intel QAT
+
+Each of those modules holds a dependency on the kernel version and if you are
+lucky enough to receive an ISO build error which sounds like:
+
+```none
+I: Create initramfs if it does not exist.
+Extra argument '6.1.52-amd64-vyos'
+Usage: update-initramfs {-c|-d|-u} [-k version] [-v] [-b directory]
+Options:
+ -k version     Specify kernel version or 'all'
+ -c             Create a new initramfs
+ -u             Update an existing initramfs
+ -d             Remove an existing initramfs
+ -b directory   Set alternate boot directory
+ -v             Be verbose
+See update-initramfs(8) for further details.
+E: config/hooks/live/17-gen_initramfs.chroot failed (exit non-zero). You should check for errors.
+```
+
+The most obvious reasons could be:
+
+- `vyos-build` repo is outdated, please `git pull` to update to the latest
+  release kernel version from us.
+- You have your own custom kernel `*.deb` packages in the `packages` folder but
+  neglected to create all required out-of tree modules like Accel-PPP, Intel
+  QAT or Intel NIC drivers
+
+#### Building The Kernel
+
+The kernel build is quite easy, most of the required steps can be found in the
+`vyos-build/packages/linux-kernel/Jenkinsfile` but we will walk you through
+it.
+
+Clone the kernel source to `vyos-build/packages/linux-kernel/`:
+
+```none
+$ cd vyos-build/packages/linux-kernel/
+$ git clone https://git.kernel.org/pub/scm/linux/kernel/git/stable/linux.git
+```
+
+Check out the required kernel version - see `vyos-build/data/defaults.json`
+file (example uses kernel 4.19.146):
+
+```none
+$ cd vyos-build/packages/linux-kernel/linux
+$ git checkout v4.19.146
+Checking out files: 100% (61536/61536), done.
+Note: checking out 'v4.19.146'.
+
+You are in 'detached HEAD' state. You can look around, make experimental
+changes and commit them, and you can discard any commits you make in this
+state without impacting any branches by performing another checkout.
+
+If you want to create a new branch to retain commits you create, you may
+do so (now or later) by using -b with the checkout command again. Example:
+  git checkout -b <new-branch-name>
+HEAD is now at 015e94d0e37b Linux 4.19.146
+```
+
+Now you can use the helper script `build-kernel.sh`, which completes all
+the necessary steps: applying required patches from the
+`vyos-build/packages/linux-kernel/patches` folder, copying the kernel
+configuration `x86_64_vyos_defconfig` to the correct location, and building
+the Debian packages.
+
+:::{note}
+Building the kernel will take some time depending on the speed and
+quantity of your CPU/cores and disk speed. Expect 20 minutes
+(or even longer) on lower end hardware.
+:::
+
+```none
+(18:59) vyos_bld 412374ca36b8:/vyos/vyos-build/packages/linux-kernel [current] # ./build-kernel.sh
+I: Copy Kernel config (x86_64_vyos_defconfig) to Kernel Source
+I: Apply Kernel patch: /vyos/vyos-build/packages/linux-kernel/patches/kernel/0001-VyOS-Add-linkstate-IP-device-attribute.patch
+patching file Documentation/networking/ip-sysctl.txt
+patching file include/linux/inetdevice.h
+patching file include/linux/ipv6.h
+patching file include/uapi/linux/ip.h
+patching file include/uapi/linux/ipv6.h
+patching file net/ipv4/devinet.c
+Hunk #1 succeeded at 2319 (offset 1 line).
+patching file net/ipv6/addrconf.c
+patching file net/ipv6/route.c
+I: Apply Kernel patch: /vyos/vyos-build/packages/linux-kernel/patches/kernel/0002-VyOS-add-inotify-support-for-stackable-filesystems-o.patch
+patching file fs/notify/inotify/Kconfig
+patching file fs/notify/inotify/inotify_user.c
+patching file fs/overlayfs/super.c
+Hunk #2 succeeded at 1713 (offset 9 lines).
+Hunk #3 succeeded at 1739 (offset 9 lines).
+Hunk #4 succeeded at 1762 (offset 9 lines).
+patching file include/linux/inotify.h
+I: Apply Kernel patch: /vyos/vyos-build/packages/linux-kernel/patches/kernel/0003-RFC-builddeb-add-linux-tools-package-with-perf.patch
+patching file scripts/package/builddeb
+I: make x86_64_vyos_defconfig
+  HOSTCC  scripts/basic/fixdep
+  HOSTCC  scripts/kconfig/conf.o
+  YACC    scripts/kconfig/zconf.tab.c
+  LEX     scripts/kconfig/zconf.lex.c
+  HOSTCC  scripts/kconfig/zconf.tab.o
+  HOSTLD  scripts/kconfig/conf
+#
+
+# configuration written to .config
+#
+I: Generate environment file containing Kernel variable
+I: Build Debian Kernel package
+  UPD     include/config/kernel.release
+/bin/sh ./scripts/package/mkdebian
+dpkg-buildpackage -r"fakeroot -u" -a$(cat debian/arch) -b -nc -uc
+dpkg-buildpackage: info: source package linux-4.19.146-amd64-vyos
+dpkg-buildpackage: info: source version 4.19.146-1
+dpkg-buildpackage: info: source distribution buster
+dpkg-buildpackage: info: source changed by vyos_bld <christian@poessinger.com>
+dpkg-buildpackage: info: host architecture amd64
+dpkg-buildpackage: warning: debian/rules is not executable; fixing that
+ dpkg-source --before-build .
+ debian/rules build
+make KERNELRELEASE=4.19.146-amd64-vyos ARCH=x86         KBUILD_BUILD_VERSION=1 KBUILD_SRC=
+  SYSTBL  arch/x86/include/generated/asm/syscalls_32.h
+...
+dpkg-shlibdeps: warning: binaries to analyze should already be installed in their package's directory
+dpkg-shlibdeps: warning: binaries to analyze should already be installed in their package's directory
+dpkg-shlibdeps: warning: binaries to analyze should already be installed in their package's directory
+dpkg-shlibdeps: warning: binaries to analyze should already be installed in their package's directory
+dpkg-shlibdeps: warning: binaries to analyze should already be installed in their package's directory
+dpkg-shlibdeps: warning: binaries to analyze should already be installed in their package's directory
+dpkg-shlibdeps: warning: binaries to analyze should already be installed in their package's directory
+dpkg-shlibdeps: warning: binaries to analyze should already be installed in their package's directory
+dpkg-shlibdeps: warning: binaries to analyze should already be installed in their package's directory
+dpkg-shlibdeps: warning: binaries to analyze should already be installed in their package's directory
+dpkg-shlibdeps: warning: binaries to analyze should already be installed in their package's directory
+dpkg-shlibdeps: warning: binaries to analyze should already be installed in their package's directory
+dpkg-shlibdeps: warning: package could avoid a useless dependency if /vyos/vyos-build/packages/linux-kernel/linux/debian/toolstmp/usr/bin/trace /vyos/vyos-build/packages/linux-kernel/linux/debian/toolstmp/usr/bin/perf were not linked against libcrypto.so.1.1 (they use none of the library's symbols)
+dpkg-shlibdeps: warning: package could avoid a useless dependency if /vyos/vyos-build/packages/linux-kernel/linux/debian/toolstmp/usr/bin/trace /vyos/vyos-build/packages/linux-kernel/linux/debian/toolstmp/usr/bin/perf were not linked against libcrypt.so.1 (they use none of the library's symbols)
+dpkg-deb: building package 'linux-tools-4.19.146-amd64-vyos' in '../linux-tools-4.19.146-amd64-vyos_4.19.146-1_amd64.deb'.
+ dpkg-genbuildinfo --build=binary
+ dpkg-genchanges --build=binary >../linux-4.19.146-amd64-vyos_4.19.146-1_amd64.changes
+dpkg-genchanges: warning: package linux-image-4.19.146-amd64-vyos-dbg in control file but not in files list
+dpkg-genchanges: info: binary-only upload (no source code included)
+ dpkg-source --after-build .
+dpkg-buildpackage: info: binary-only upload (no source included)
+```
+
+When complete, you will have kernel binary packages to use in your custom ISO
+build. Place all `*.deb` files in the `vyos-build/packages` folder, where
+the build process will use them automatically.
+
+##### Firmware
+
+If you upgrade your kernel or include new drivers you may need new firmware.
+This builds a new `vyos-linux-firmware` package using the included helper
+scripts.
+
+```none
+$ cd vyos-build/packages/linux-kernel
+$ git clone https://git.kernel.org/pub/scm/linux/kernel/git/firmware/linux-firmware.git
+$ ./build-linux-firmware.sh
+$ cp vyos-linux-firmware_*.deb ../
+```
+
+The script automatically detects which firmware blobs are needed based on the
+built drivers. If detection fails, you can manually add files to
+`vyos-build/packages/linux-kernel/build-linux-firmware.sh`:
+
+```bash
+ADD_FW_FILES="iwlwifi* ath11k/QCA6390/*/*.bin"
+```
+
+
+#### Building Out-Of-Tree Modules
+
+Building the kernel is one step. You must also build required out-of-tree
+modules so the ABIs match.
+Refer to `vyos-build/packages/linux-kernel/Jenkinsfile`
+for all required modules and their versions. We show you how to build the
+currently required modules.
+
+##### Accel-PPP
+
+First, clone the source code and check out the appropriate version:
+
+```none
+$ cd vyos-build/packages/linux-kernel
+$ git clone https://github.com/accel-ppp/accel-ppp.git
+```
+
+Use the helper script and patches to build the package. Run the following
+command:
+
+```none
+$ ./build-accel-ppp.sh
+I: Build Accel-PPP Debian package
+CMake Deprecation Warning at CMakeLists.txt:3 (cmake_policy):
+  The OLD behavior for policy CMP0003 will be removed from a future version
+  of CMake.
+  The cmake-policies(7) manual explains that the OLD behaviors of all
+  policies are deprecated and that a policy should be set to OLD only under
+  specific short-term circumstances.  Projects should be ported to the NEW
+  behavior and not rely on setting a policy to OLD.
+-- The C compiler identification is GNU 8.3.0
+...
+
+CPack: Create package using DEB
+CPack: Install projects
+CPack: - Run preinstall target for: accel-ppp
+CPack: - Install project: accel-ppp
+CPack: Create package
+CPack: - package: /vyos/vyos-build/packages/linux-kernel/accel-ppp/build/accel-ppp.deb generated.
+```
+
+After compiling the packages you will find yourself the newly generated `*.deb`
+binaries in `vyos-build/packages/linux-kernel` from which you can copy them
+to the `vyos-build/packages` folder for inclusion during the ISO build.
+
+##### Intel NIC
+
+The Intel NIC drivers do not come from a Git repository. VyOS fetches the
+tarballs from a mirror and compiles them. Use the following wrapper script
+to build all driver modules:
+
+```none
+./build-intel-drivers.sh
+  % Total    % Received % Xferd  Average Speed   Time    Time     Time  Current
+                                 Dload  Upload   Total   Spent    Left  Speed
+100  490k  100  490k    0     0   648k      0 --:--:-- --:--:-- --:--:--  648k
+I: Compile Kernel module for Intel ixgbe driver
+...
+
+I: Building Debian package vyos-intel-iavf
+Doing `require 'backports'` is deprecated and will not load any backport in the next major release.
+Require just the needed backports instead, or 'backports/latest'.
+Debian packaging tools generally labels all files in /etc as config files, as mandated by policy, so fpm defaults to this behavior for deb packages. You can disable this default behavior with --deb-no-default-config-files flag {:level=>:warn}
+Created package {:path=>"vyos-intel-iavf_4.0.1-0_amd64.deb"}
+I: Cleanup iavf source
+```
+
+After compilation, find the generated `*.deb` binaries in
+`vyos-build/packages/linux-kernel`. Copy them to the `vyos-build/packages`
+folder for inclusion in the ISO build.
+
+##### Intel QAT
+
+The Intel QAT (Quick Assist Technology) drivers do not come from a Git
+repository. VyOS fetches the tarballs from `01.org`, Intel's open-source
+website.
+Use the following wrapper script to build all driver modules:
+
+```none
+$ ./build-intel-qat.sh
+  % Total    % Received % Xferd  Average Speed   Time    Time     Time  Current
+                                 Dload  Upload   Total   Spent    Left  Speed
+100 5065k  100 5065k    0     0  1157k      0  0:00:04  0:00:04 --:--:-- 1157k
+I: Compile Kernel module for Intel qat driver
+checking for a BSD-compatible install... /usr/bin/install -c
+checking whether build environment is sane... yes
+checking for a thread-safe mkdir -p... /bin/mkdir -p
+checking for gawk... gawk
+checking whether make sets $(MAKE)... yes
+...
+
+I: Building Debian package vyos-intel-qat
+Doing `require 'backports'` is deprecated and will not load any backport in the next major release.
+Require just the needed backports instead, or 'backports/latest'.
+Debian packaging tools generally labels all files in /etc as config files, as mandated by policy, so fpm defaults to this behavior for deb packages. You can disable this default behavior with --deb-no-default-config-files flag {:level=>:warn}
+Created package {:path=>"vyos-intel-qat_1.7.l.4.9.0-00008-0_amd64.deb"}
+I: Cleanup qat source
+```
+
+After compiling the packages you will find yourself the newly generated `*.deb`
+binaries in `vyos-build/packages/linux-kernel` from which you can copy them
+to the `vyos-build/packages` folder for inclusion during the ISO build.
+
+### Packages
+
+If you are brave enough to build your own ISO image with any modified package
+from VyOS's GitHub organisation, this is the place for you.
+
+Any modified package may be an altered version (e.g., `vyos-1x`) that you
+want to test before filing a pull request on GitHub.
+
+Building an ISO with a customized package is the same as building a regular
+ISO image. Place your modified `*.deb` package inside the `packages` folder
+within `vyos-build`. The build process will automatically use your custom
+package during the ISO build.
+
+### Troubleshooting
+
+Debian APT does not provide verbose error messages. If your ISO build fails and
+you suspect an APT dependencies or installation issue, you can apply this patch
+to increase APT verbosity during the ISO build.
+
+```diff
+diff --git i/scripts/live-build-config w/scripts/live-build-config
+index 1b3b454..3696e4e 100755
+--- i/scripts/live-build-config
++++ w/scripts/live-build-config
+@@ -57,7 +57,8 @@ lb config noauto \
+         --firmware-binary false \
+         --updates true \
+         --security true \
+-        --apt-options "--yes -oAcquire::Check-Valid-Until=false" \
++        --apt-options "--yes -oAcquire::Check-Valid-Until=false -oDebug::BuildDeps=true -oDebug::pkgDepCache::AutoInstall=true \
++                             -oDebug::pkgDepCache::Marker=true -oDebug::pkgProblemResolver=true -oDebug::Acquire::gpgv=true" \
+         --apt-indices false
+         "${@}"
+ """
+```
+
+(build-packages)=
+
+## Packages
+
+VyOS comes with specific packages that cannot be found in any
+Debian mirror. These packages are located in the [VyOS GitHub project] in
+source format and can easily be compiled into custom
+Debian (`*.deb`) packages.
+
+The easiest way to compile your package is with the {ref}`build_docker`
+container mentioned earlier, as it includes all required dependencies for all
+VyOS related packages.
+
+Assuming you want to build the `vyos-1x` package and modify it for your needs,
+first clone the repository from GitHub:
+
+```none
+$ git clone --recurse-submodules https://github.com/vyos/vyos-1x
+```
+
+
+### Build
+
+Launch the Docker container and build the package:
+
+```none
+# For VyOS 1.3 (equuleus, current)
+$ docker run --rm -it --privileged -v $(pwd):/vyos -w /vyos vyos/vyos-build:current bash
+
+# Change to source directory
+$ cd vyos-1x
+
+# Build DEB
+$ dpkg-buildpackage -uc -us -tc -b
+```
+
+After a minute or two, the generated DEB packages are located next to the
+`vyos-1x` source directory:
+
+```none
+# ls -al ../vyos-1x*.deb
+-rw-r--r-- 1 vyos_bld vyos_bld 567420 Aug  3 12:01 ../vyos-1x_1.3dev0-1847-gb6dcb0a8_all.deb
+-rw-r--r-- 1 vyos_bld vyos_bld   3808 Aug  3 12:01 ../vyos-1x-vmware_1.3dev0-1847-gb6dcb0a8_amd64.deb
+```
+
+
+### Install
+
+To test your newly created package, you can SCP it to a running VyOS instance
+and install the new `*.deb` package to replace the current one.
+
+Install the package using the following commands:
+
+```none
+vyos@vyos:~$ dpkg --install /tmp/vyos-1x_1.3dev0-1847-gb6dcb0a8_all.deb
+(Reading database ... 58209 files and directories currently installed.)
+Preparing to unpack .../vyos-1x_1.3dev0-1847-gb6dcb0a8_all.deb ...
+Unpacking vyos-1x (1.3dev0-1847-gb6dcb0a8) over (1.3dev0-1847-gb6dcb0a8) ...
+Setting up vyos-1x (1.3dev0-1847-gb6dcb0a8) ...
+Processing triggers for rsyslog (8.1901.0-1) ...
+```
+
+You can also place the generated `*.deb` in your ISO build environment to
+include it in a custom ISO. See {ref}`build_custom_packages` for more
+information.
+
+:::{warning}
+Any packages in the `packages` directory will be added to the
+ISO during the build, replacing upstream packages. Delete both the source
+directories and built DEB packages if you want to build an ISO from purely
+upstream packages.
+:::
+
+[docker]: https://docs.docker.com/engine/install/debian/
+[docker as non-root]: https://docs.docker.com/engine/install/linux-postinstall
+[repository]: https://github.com/vyos/vyos-build
+[vyos dockerhub organisation]: https://hub.docker.com/u/vyos
+[vyos github project]: https://github.com/vyos