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, 0 insertions, 730 deletions

diff --git a/docs/contributing/md-build-vyos.md b/docs/contributing/md-build-vyos.md
deleted file mode 100644
index bfda5298..00000000
--- a/docs/contributing/md-build-vyos.md
+++ /dev/null
@@ -1,730 +0,0 @@
----
-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