diff --git a/docs/contributing/build-vyos.rst b/docs/contributing/build-vyos.rst index 1b321332fc..65298a7a78 100644 --- a/docs/contributing/build-vyos.rst +++ b/docs/contributing/build-vyos.rst @@ -1,3 +1,5 @@ +:lastproofread: 2025-12-05 + .. _build: ########## @@ -8,18 +10,19 @@ Build VyOS Prerequisites ************* -There are different ways you can build VyOS. - -Building using a :ref:`build_docker` container, although not the only way, -is the easiest way as all dependencies are managed for you. However, you can -also set up your own build machine and run a :ref:`build_native`. +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. +.. 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). + are only available to subscription holders (customers and active community + members with contributors subscriptions). The following includes the build process for VyOS rolling release. @@ -31,25 +34,20 @@ This process has been tested on clean installs of Debian Bookworm. Native Build ============ -To build VyOS natively you need a properly configured build host with the -following Debian versions installed: - -- Debian Bookworm +To build VyOS natively, you need a properly configured build host with +Debian Bookworm installed. -To start, clone the repository to your local machine: +To get started, clone the repository to your local machine: .. code-block:: none $ sudo make clean $ sudo ./build-vyos-image --architecture amd64 --build-by "j.randomhacker@vyos.io" generic -For the packages required, you can refer to the ``docker/Dockerfile`` file -in the repository_. The ``./build-vyos-image`` script will also warn you if any +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. -This will guide you through the process of building a VyOS ISO using Docker. -This process has been tested on clean installs of Bookworm (12). - .. _build_docker: Docker @@ -57,8 +55,8 @@ Docker Installing Docker_ and prerequisites: -.. hint:: Due to the updated version of Docker, the following examples may - become invalid. +.. hint:: Docker versions are updated frequently. The following examples may + become outdated. .. code-block:: none @@ -78,29 +76,27 @@ Installing Docker_ and prerequisites: sudo apt-get update sudo apt-get install docker-ce docker-ce-cli containerd.io docker-buildx-plugin docker-compose-plugin -To be able to use Docker_ without ``sudo``, the current non-root user must be -added to the ``docker`` group by calling: ``sudo usermod -aG docker -yourusername``. +To use Docker without ``sudo``, add your current non-root user to the ``docker`` +group: ``sudo usermod -aG docker yourusername``. -.. hint:: Doing so grants privileges equivalent to the ``root`` user! It is - recommended to remove the non-root user from the ``docker`` group after - building the VyOS ISO. See also `Docker as non-root`_. +.. 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 needs to be built on a local file system, building - on SMB or NFS shares will result in the container failing to build properly! - VirtualBox Drive Share is also not an option as block device operations - are not implemented and the drive is always mounted as "nodev" +.. 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. Using the pre-built containers from the `VyOS DockerHub -organisation`_ will ensure that the container is always up-to-date. A rebuild -is triggered once the container changes (please note this will take 2-3 hours -after pushing to the vyos-build repository). +DockerHub. It is recommended to use the pre-built containers from the +`VyOS DockerHub`organization_ +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 are using the pre-built container, it will be automatically +.. 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. @@ -125,16 +121,15 @@ The container can also be built directly from source: $ cd vyos-build $ docker build -t vyos/vyos-build:current docker -.. note:: VyOS has switched to Debian (12) Bookworm in its ``current`` branch, - Due to software version updates, it is recommended to use the official +.. 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 yourself some handy Bash aliases to always launch the latest - -per release train (`current`) - container. Add the following to your -``.bash_aliases`` file: +You can create Bash aliases to easily launch the latest container per release +train (``current``). Add the following to your ``.bash_aliases`` file: .. code-block:: none @@ -147,8 +142,8 @@ per release train (`current`) - container. Add the following to your -e GOSU_UID=$(id -u) -e GOSU_GID=$(id -g) \ vyos/vyos-build:current bash' -Now you are prepared with a new aliase ``vybld`` to spawn -your development containers in your current working directory. +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 @@ -165,16 +160,16 @@ your development containers in your current working directory. Build ISO ********* -Now as you are aware of the prerequisites we can continue and build our own -ISO from source. For this we have to fetch the latest source code from GitHub. +Now that you understand the prerequisites, you can build a VyOS ISO from source. +First, fetch the latest source code from GitHub: .. code-block:: none $ git clone -b current --single-branch https://github.com/vyos/vyos-build -Now a fresh build of the VyOS ISO can begin. Change directory to the -``vyos-build`` directory and run: +Now you can begin a fresh VyOS ISO build. Change to the ``vyos-build`` +directory and run: .. code-block:: none @@ -188,8 +183,8 @@ Start the build: 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, the resulting iso can be found inside the -``build`` directory as ``live-image-[architecture].hybrid.iso``. +When the build is successful, find the resulting ISO in the ``build`` directory +as ``live-image-[architecture].hybrid.iso``. .. _build source: @@ -199,8 +194,8 @@ When the build is successful, the resulting iso can be found inside the Customize ========= -This ISO can be customized with the following list of configure options. -The full and current list can be generated with ``./build-vyos-image --help``: +You can customize the ISO with the following configure options. Generate the +full and current list with ``./build-vyos-image --help``: .. code-block:: none @@ -411,11 +406,11 @@ file (example uses kernel 4.19.146): HEAD is now at 015e94d0e37b Linux 4.19.146 -Now we can use the helper script ``build-kernel.sh`` which does all the -necessary voodoo by applying required patches from the -`vyos-build/packages/linux-kernel/patches` folder, copying our kernel -configuration ``x86_64_vyos_defconfig`` to the right location, and finally -building the Debian packages. +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 @@ -496,16 +491,16 @@ building the Debian packages. dpkg-buildpackage: info: binary-only upload (no source included) -In the end you will be presented with the kernel binary packages which you can -then use in your custom ISO build process, by placing all the `*.deb` files in -the vyos-build/packages folder where they will be used automatically when -building VyOS as documented above. +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. -Build a new ``vyos-linux-firmware`` package with the included helper scripts. +This builds a new ``vyos-linux-firmware`` package using the included helper +scripts. .. code-block:: none @@ -514,8 +509,8 @@ Build a new ``vyos-linux-firmware`` package with the included helper scripts. $ ./build-linux-firmware.sh $ cp vyos-linux-firmware_*.deb ../ -This tries to automatically detect which blobs are needed based on which drivers -were built. If it fails to find the correct files you can add them manually to +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``: .. code-block:: bash @@ -526,24 +521,24 @@ were built. If it fails to find the correct files you can add them manually to Building Out-Of-Tree Modules ---------------------------- -Building the kernel is one part, but now you also need to build the required -out-of-tree modules so everything is lined up and the ABIs match. To do so, -you can again take a look at ``vyos-build/packages/linux-kernel/Jenkinsfile`` -to see all of the required modules and their selected versions. We will show -you how to build all the current required 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 by running: +First, clone the source code and check out the appropriate version: .. code-block:: none $ cd vyos-build/packages/linux-kernel $ git clone https://github.com/accel-ppp/accel-ppp.git -We again make use of a helper script and some patches to make the build work. -Just run the following command: +Use the helper script and patches to build the package. Run the following +command: .. code-block:: none @@ -576,10 +571,9 @@ 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, instead we just fetch -the tarballs from our mirror and compile them. - -Simply use our wrapper script to build all of the driver modules. +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: .. code-block:: none @@ -598,17 +592,17 @@ Simply use our wrapper script to build all of the driver modules. Created package {:path=>"vyos-intel-iavf_4.0.1-0_amd64.deb"} I: Cleanup iavf 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. +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, instead we just fetch the tarballs from 01.org, Intel's -open-source website. -Simply use our wrapper script to build all of the driver modules. +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: .. code-block:: none @@ -640,24 +634,23 @@ to the ``vyos-build/packages`` folder for inclusion during the ISO build. Packages ======== -If you are brave enough to build yourself an ISO image containing any modified -package from our GitHub organisation - this is the place to be. +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 refer to an altered version of e.g. vyos-1x package -that you would like to test before filing a pull request on GitHub. +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 any customized package is in no way different than -building a regular (customized or not) ISO image. Simply place your modified -`*.deb` package inside the `packages` folder within `vyos-build`. The build -process will then pickup your custom package and integrate it into your ISO. +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 is not very verbose when it comes to errors. If your ISO build breaks -for whatever reason and you suspect it's a problem with APT dependencies or -installation you can add this small patch which increases the APT verbosity -during ISO build. +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. .. stop_vyoslinter @@ -686,17 +679,17 @@ during ISO build. Packages ******** -VyOS itself comes with a bunch of packages that are specific to our system and -thus cannot be found in any Debian mirror. Those packages can be found at the -`VyOS GitHub project`_ in their source format can easily be compiled into -a custom Debian (`*.deb`) package. +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 above mentioned -:ref:`build_docker` container, it includes all required dependencies for -all VyOS related 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. -Assume we want to build the vyos-1x package on our own and modify it to our -needs. We first need to clone the repository from GitHub. +Assuming you want to build the ``vyos-1x`` package and modify it for your needs, +first clone the repository from GitHub: .. code-block:: none @@ -705,7 +698,7 @@ needs. We first need to clone the repository from GitHub. Build ===== -Launch Docker container and build package +Launch the Docker container and build the package: .. code-block:: none @@ -718,8 +711,8 @@ Launch Docker container and build package # Build DEB $ dpkg-buildpackage -uc -us -tc -b -After a minute or two you will find the generated DEB packages next to the -vyos-1x source directory: +After a minute or two, the generated DEB packages are located next to the +``vyos-1x`` source directory: .. code-block:: none @@ -730,11 +723,10 @@ vyos-1x source directory: Install ======= -To take your newly created package on a test drive you can simply SCP it to a -running VyOS instance and install the new `*.deb` package over the current -running one. +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. -Just install using the following commands: +Install the package using the following commands: .. code-block:: none @@ -745,14 +737,14 @@ Just install using the following commands: Setting up vyos-1x (1.3dev0-1847-gb6dcb0a8) ... Processing triggers for rsyslog (8.1901.0-1) ... -You can also place the generated `*.deb` into your ISO build environment to -include it in a custom iso, see :ref:`build_custom_packages` for more +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 build, replacing the upstream ones. Make sure you delete them (both - the source directories and built deb packages) if you want to build an iso - from purely upstream packages. +.. 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. .. stop_vyoslinter diff --git a/docs/contributing/cla.rst b/docs/contributing/cla.rst index 778beb9d1a..c19e266a26 100644 --- a/docs/contributing/cla.rst +++ b/docs/contributing/cla.rst @@ -1,3 +1,5 @@ +:lastproofread: 2025-12-05 + .. _cla: ############################# @@ -7,38 +9,37 @@ Contributor License Agreement Before we can accept your contributions to VyOS, you must sign a **Contributor License Agreement (CLA)**. -This is a standard open-source practice designed to protect both you and the -project. +This is a standard open-source practice that protects both you and the project. -The process is simple and fully automated: +The process is straightforward and fully automated: 1. **Review the CLA document** - You can find the CLA text at our + Find the CLA text in our `GitHub repository `__. 2. **Submit a pull request** - When you open a pull request, a CLA bot will automatically check whether all + When you open a pull request, a CLA bot automatically checks whether all commit authors have signed the CLA. 3. **Follow the bot's instructions** - If the CLA has not been signed, the bot will leave a comment with a prompt. - Simply reply to that comment with the suggested text to sign the CLA. + If the CLA has not been signed, the bot leaves a comment with instructions. + Reply to that comment with the suggested text to sign the CLA. 4. **Wait for confirmation** - The CLA bot will verify your response and update the pull request status. - Once all commit authors have signed, the bot will confirm that the CLA - requirement has been met, and unlock the pull request for merging. + The CLA bot verifies your response and updates the pull request status. + Once all commit authors have signed, the bot confirms that the CLA + requirement is met and unlocks the pull request for merging. .. note:: - The CLA must be signed by **each commit author**. + Each commit author must sign the CLA. - If your pull request includes commits from multiple contributors, each of - them must sign the CLA before the pull request can be accepted. + If your pull request includes commits from multiple contributors, each one + must sign the CLA before the pull request can be accepted. -Once signed, the CLA remains valid for all past and future contributions to VyOS -made under the same GitHub identity. +Once you sign the CLA, it remains valid for all your past and future +contributions to VyOS under the same GitHub identity. diff --git a/docs/contributing/debugging.rst b/docs/contributing/debugging.rst index e443feee73..41aa3c32fd 100644 --- a/docs/contributing/debugging.rst +++ b/docs/contributing/debugging.rst @@ -1,116 +1,113 @@ +:lastproofread: 2025-12-05 + .. _debugging: ######### Debugging ######### -There are two flags available to aid in debugging configuration scripts. -Since configuration loading issues will manifest during boot, the flags are -passed as kernel boot parameters. +Two flags are available to help debug configuration scripts. Configuration +loading issues manifest during boot, so these flags are passed as kernel boot +parameters. ISO image build =============== -When having trouble compiling your own ISO image or debugging Jenkins issues -you can follow the steps at :ref:`iso_build_issues`. +If you have trouble compiling your own ISO image or debugging Jenkins issues, +follow the steps at :ref:`iso_build_issues`. System Startup ============== -The system startup can be debugged (like loading in the configuration -file from ``/config/config.boot``. This can be achieve by extending the -Kernel command-line in the bootloader. +Debug system startup by examining the configuration file loading from +``/config/config.boot``. Extend the kernel command-line in the bootloader to +enable this. Kernel ------ -* ``vyos-debug`` - Adding the parameter to the linux boot line will produce - timing results for the execution of scripts during commit. If one is seeing - an unexpected delay during manual or boot commit, this may be useful in - identifying bottlenecks. The internal flag is ``VYOS_DEBUG``, and is found - in vyatta-cfg_. Output is directed to ``/var/log/vyatta/cfg-stdout.log``. +* ``vyos-debug`` - Add this parameter to the Linux boot line to produce + timing results for script execution during commit. If you see an unexpected + delay during manual or boot commit, this parameter helps identify bottlenecks. + The internal flag is ``VYOS_DEBUG``, found in vyatta-cfg_. Output is directed + to ``/var/log/vyatta/cfg-stdout.log``. -* ``vyos-config-debug`` - During development, coding errors can lead to a - commit failure on boot, possibly resulting in a failed initialization of the - CLI. In this circumstance, the kernel boot parameter ``vyos-config-debug`` - will ensure access to the system as user ``vyos``, and will log a Python - stack trace to the file ``/tmp/boot-config-trace``. - File ``boot-config-trace`` will generate only if config loaded with a failure - status. +* ``vyos-config-debug`` - During development, coding errors can cause commit + failures on boot, potentially preventing CLI initialization. This kernel boot + parameter ensures access to the system as user ``vyos`` and logs a Python + stack trace to ``/tmp/boot-config-trace``. The file is created only if the + configuration load fails. Live System =========== -A number of flags can be set up to change the behaviour of VyOS at runtime. -These flags can be toggled using either environment variables or creating -files. +Several flags can be set to change VyOS behavior at runtime. Toggle these flags +using environment variables or by creating files. -For each feature, a file called ``vyos.feature.debug`` can be created to -toggle the feature on. If a parameter is required it can be placed inside -the file as its first line. +For each feature, create a file called ``vyos.feature.debug`` to enable it. +If a parameter is required, place it as the first line inside the file. -The file can be placed in ``/tmp`` for one time debugging (as the file -will be removed on reboot) or placed in '/config' to stay permanently. +Place the file in ``/tmp`` for one-time debugging (the file is removed on +reboot) or in ``/config`` to persist permanently. For example, ``/tmp/vyos.ifconfig.debug`` can be created to enable interface debugging. -It is also possible to set up the debugging using environment variables. -In that case, the name will be (in uppercase) VYOS_FEATURE_DEBUG. +You can also enable debugging using environment variables. +The environment variable name follows the convention ``VYOS_FEATURE_DEBUG``. -For example running, ``export VYOS_IFCONFIG_DEBUG=""`` on your vbash, -will have the same effect as ``touch /tmp/vyos.ifconfig.debug``. +For example, ``export VYOS_IFCONFIG_DEBUG=""`` in your vbash has the same effect +as ``touch /tmp/vyos.ifconfig.debug``. -* ``ifconfig`` - Once set, all commands used, and their responses received - from the OS, will be presented on the screen for inspection. +* ``ifconfig`` - Display all commands and their responses from the OS on + screen for inspection. -* ``command`` - Once set, all commands used, and their responses received - from the OS, will be presented on the screen for inspection. +* ``command`` - Display all commands and their responses from the OS on screen + for inspection. -* ``developer`` - Should a command fail, instead of printing a message to the - user explaining how to report issues, the python interpreter will start a - PBD post-mortem session to allow the developer to debug the issue. As the - debugger will wait from input from the developer, it has the capacity to - prevent a router to boot and therefore should only be permanently set up - on production if you are ready to see the OS fail to boot. +* ``developer`` - When a command fails, start a PDB post-mortem session instead + of showing a standard error message. This allows developers to debug issues + interactively. Because the debugger waits for input, it can prevent the router + from booting, so only enable this permanently on production systems if you are + ready for potential boot failures. -* ``log`` - In some rare cases, it may be useful to see what the OS is doing, - including during boot. This option sends all commands used by VyOS to a - file. The default file is ``/tmp/full-log`` but it can be changed. +* ``log`` - Send all commands used by VyOS to a log file for inspection. This + is useful in rare cases when you need to see what the OS is doing, including + during boot. The default file is ``/tmp/full-log``, but you can change it. -.. note:: In order to retrieve the debug output on the command-line you need to - disable ``vyos-configd`` in addition. This can be run either one-time by - calling ``sudo systemctl stop vyos-configd`` or make this reboot-safe by - calling ``sudo systemctl disable vyos-configd``. +.. note:: To retrieve debug output on the command line, disable ``vyos-configd`` + in addition. You can do this one-time with ``sudo systemctl stop vyos-configd`` + or permanently with ``sudo systemctl disable vyos-configd``. FRR --- -Recent versions use the ``vyos.frr`` framework. The Python class is located -inside our ``vyos-1x:python/vyos/frr.py``. It comes with an embedded debugging/ -(print style) debugger as vyos.ifconfig does. +Recent versions use the ``vyos.frr`` framework. The Python class is located in +``vyos-1x:python/vyos/frr.py``. It includes an embedded debugger similar to the +one in ``vyos.ifconfig``. -To enable debugging just run: ``$ touch /tmp/vyos.frr.debug`` +Enable debugging by running: ``touch /tmp/vyos.frr.debug`` -Debugging Python Code with PDB +Debug Python code with PDB ------------------------------ -Sometimes it might be useful to debug Python code interactively on the live -system rather than a IDE. This can be achieved using pdb. +Sometimes it is useful to debug Python code interactively on the live system +rather than in an IDE. You can do this using pdb. -Let us assume you want to debug a Python script that is called by an op-mode -command. After you found the script by looking up the op-mode-defitions you -can edit the script in the live system using e.g. vi: +Assuming you want to debug a Python script called by an op-mode command, find +the script by looking up the op-mode definitions, then edit it on the live +system using vi: ``vi /usr/libexec/vyos/op_mode/show_xyz.py`` Insert the following statement right before the section where you want to -investigate a problem (e.g. a statement you see in a backtrace): +investigate a problem (for example, a statement you see in a backtrace): ``import pdb; pdb.set_trace()`` -Optionally you can surrounded this statement by an ``if`` which only triggers -under the condition you are interested in. -Once you run ``show xyz`` and your condition is triggered you should be dropped -into the python debugger: +Optionally, surround this statement with an ``if`` condition that triggers only +for the conditions you are interested in. + +When you run ``show xyz`` and your condition triggers, you enter the Python +debugger: .. code-block:: none @@ -122,7 +119,7 @@ into the python debugger: You can type ``help`` to get an overview of the available commands, and ``help command`` to get more information on each command. -Useful commands are: +Common useful commands include: * examine variables using ``pp(var)`` * continue execution using ``cont`` @@ -131,9 +128,9 @@ Useful commands are: Config Migration Scripts ------------------------ -Starting with VyOS 1.5 a new mechanism is used for config migration whichwill improve -migration performance. New migrators only exist in the new format with a migration() -function. +Starting with VyOS 1.5, a new mechanism is used for config migration that +improves migration performance. New migrators use only the new format with a +``migration()`` function. .. code-block:: python @@ -145,9 +142,8 @@ function. return # do your stuff here -New style migrations scripts can no longer be executed on their own. The new -handler of the entire migration subsystem on the other hand comes with a handy -test kit: +New-style migration scripts can no longer run on their own. However, the new +migration subsystem handler includes a test kit: .. code-block:: none @@ -166,57 +162,56 @@ test kit: --force force run of all migration scripts -So in order to test your migrator you can run this as simple as: +To test your migration, run: .. code-block:: none vyos@vyos:~$ /usr/libexec/vyos/run-config-migration.py --test-script /opt/vyatta/etc/config-migrate/migrate/quagga/11-to-12 --output-file /tmp/foo /tmp/static-route-basic vyos@vyos:~$ cat /tmp/foo -Where `/tmp/foo` will contain the migrated configuration. +The file ``/tmp/foo`` contains the migrated configuration. Configuration Error on System Boot ---------------------------------- -Being brave and running the latest rolling releases will sometimes trigger -bugs due to corner cases we missed in our design. Those bugs should be filed -via Phabricator_ but you can help us to narrow down the issue. Login to your -VyOS system and change into configuration mode by typing ``configure``. Now -re-load your boot configuration by simply typing ``load`` followed by return. +Running the latest rolling releases sometimes exposes bugs due to edge cases +missed in design. File these bugs via Phabricator_, but you can help narrow +down the issue by following these steps: + +1. Log in to your VyOS system. +2. Enter configuration mode: ``configure`` +3. Reload your boot configuration: ``load`` -You should now see a Python backtrace which will help us to handle the issue, -please attach it to the Phabricator_ task. +You should see a Python backtrace that helps identify the issue. Attach it to +the Phabricator_ task. Boot Timing ----------- -During the migration and extensive rewrite of functionality from Perl into -Python a significant increase in the overall system boottime was noticed. The -system boot time can be analysed and a graph can be generated in the end which -shows in detail who called whom during the system startup phase. +During the migration and rewrite of functionality from Perl to Python, system +boot time increased significantly. You can analyze and graph boot time to see +detailed call sequences during startup. -This is done by utilizing the ``systemd-bootchart`` package which is now -installed by default on the VyOS 1.3 (equuleus) branch. The configuration is -also versioned so we get comparable results. ``systemd-bootchart`` is configured -using this file: bootchart.conf_ +This uses the ``systemd-bootchart`` package, which is installed by default on +VyOS 1.3 (equuleus) and later. Configuration is versioned for comparable results. +Refer to bootchart.conf_ for the configuration file. -To enable boot time graphing change the Kernel commandline and add the following -string: ``init=/usr/lib/systemd/systemd-bootchart`` +To enable boot time graphing, add the following to the kernel command line: +``init=/usr/lib/systemd/systemd-bootchart`` -This can also be done permanently by changing ``/boot/grub/grub.cfg``. +You can also make this permanent by editing ``/boot/grub/grub.cfg``. Priorities ========== -VyOS CLI is all about priorities. Every CLI node has a corresponding -``node.def`` file and possibly an attached script that is executed when the -node is present. Nodes can have a priority, and on system bootup - or any -other ``commit`` to the config all scripts are executed from lowest to highest -priority. This is good as this gives a deterministic behavior. +VyOS CLI depends heavily on priorities. Every CLI node has a corresponding +``node.def`` file and possibly an attached script. Nodes can have priorities, +and on system bootup or any ``commit`` to the configuration, scripts execute +from lowest to highest priority. This provides deterministic behavior. -To debug issues in priorities or to see what's going on in the background -you can use the ``/opt/vyatta/sbin/priority.pl`` script which lists to you -the execution order of the scripts. +To debug priority issues or see script execution order, use the +``/opt/vyatta/sbin/priority.pl`` script, which lists the execution order of +scripts. .. stop_vyoslinter diff --git a/docs/contributing/issues-features.rst b/docs/contributing/issues-features.rst index e57766fc83..bc62388144 100644 --- a/docs/contributing/issues-features.rst +++ b/docs/contributing/issues-features.rst @@ -1,3 +1,5 @@ +:lastproofread: 2025-12-08 + .. _issues_features: ####################### @@ -9,17 +11,15 @@ Issues/Feature requests Bug Report/Issue ================ -Issues or bugs are found in any software project. VyOS is not an exception. +Issues and bugs occur in every software project, and VyOS is no exception. -All issues should be reported to the developers. This lets the developers know -what is not working properly. Without this sort of feedback every developer -will believe that everything is working correctly. +Report all issues to the developers so they know what is not working correctly. +Without this feedback, developers assume everything works properly. I have found a bug, what should I do? ------------------------------------- -When you believe you have found a bug, it is always a good idea to verify the -issue prior to opening a bug request. +When you believe you have found a bug, verify it first to ensure it is genuine. * Consult the documentation_ to ensure that you have configured your system correctly @@ -28,90 +28,80 @@ issue prior to opening a bug request. Ensure the problem is reproducible ---------------------------------- -You should include the following information: - -* A sequence of configuration commands or a complete configuration file - required to recreate a setup where the bug occurs. - Please avoid partial configs: a sequence of commands is easy to paste into the console, - a complete config is easy to load in a VM, but a partial config is neither! - At least not until we implement a "merge from the CLI" - feature that allows pasting config file chunks into a session. -* The behavior you expect and how it's different from the behavior you observe. - Don't just include command outputs or traffic dumps — - try to explain at least briefly why they are wrong and what they should be. -* A sequence of actions that triggers the bug. - We understand that it's not always possible, but it makes developer's job a lot easier - and also allows any community member to independently confirm - that the bug still exists or if it's already fixed. -* If it's a regression, tell us a VyOS version where the feature still worked correctly. - It's perfect if you can tell exactly which version broke it, - but we understand that it's not always easy or feasible — any working version is acceptable. - -If you aren't certain what the correct behavior is and if what you see is really a bug, -or if you don't have a reproducing procedure that reliably triggers it, -please create a post on the forum or ask in the chat first — -or, if you have a subscription, create a support ticket. -Our team and community members can help you identify the bug and work around it, -then create an actionable and testable bug report. +Include the following information when reporting a bug: + +* A sequence of configuration commands or a complete configuration file needed + to recreate the bug. Avoid partial configs: a sequence of commands is easy to + paste, a complete config is easy to load, but a partial config is neither. + This limitation should improve once we implement a "merge from the CLI" feature. +* Describe the expected behavior and how it differs from what you observe. Include + command outputs or traffic dumps, but explain briefly why they are wrong and + what the correct behavior should be. +* A sequence of actions that trigger the bug. While not always possible, this + helps developers and community members confirm the issue and verify fixes. +* If it is a regression, specify a VyOS version where the feature worked correctly. + If you can identify the exact version that broke it, that is helpful. Any + working version is acceptable. + +If you are uncertain whether the behavior is a bug or what the correct behavior +is, or if you lack a reliable reproducing procedure, post on the forum or ask in +chat first. If you have a subscription, create a support ticket. The team and +community can help identify the issue, work around it, and create an actionable +bug report. Report a Bug ------------ -In order to open up a bug-report/feature request you need to create yourself -an account on VyOS Phabricator_. On the left side of the specific project (VyOS -1.2 or VyOS 1.3) you will find quick-links for opening a bug-report/feature -request. +To open a bug report or feature request, create an account on VyOS Phabricator_. +On the left side of the specific project (VyOS 1.2 or VyOS 1.3), you will find +quick links for opening bug reports or feature requests. -* Provide as much information as you can -* Which version of VyOS are you using? ``run show version`` -* How can we reproduce this Bug? +* Provide as much information as you can. +* Specify which VyOS version you are using: ``run show version`` +* Explain how to reproduce the bug. .. _feature_request: Feature Requests ================ -You have an idea of how to make VyOS better or you are in need of a specific -feature which all users of VyOS would benefit from? To send a feature request -please search Phabricator_ to check if there is already a request pending. You can -enhance it or if you don't find one, create a new one by use the quick link in -the left side under the specific project. +Have an idea to improve VyOS or need a feature that would benefit all users? +Before submitting a feature request, search Phabricator_ to check if a request +already exists. You can enhance an existing request or create a new one using +the quick link on the left side of the specific project. -You must create a task before you start working on a feature. -Yes, even if it's a tiny feature — we use the task tracker to generate release notes, -so it's essential that everything is reflected there. +Create a task before starting work on a feature, even if it is a tiny feature. +We use the task tracker to generate release notes, so all work must be reflected +there. -You must include at least the following: +Include at least the following information: -* A reasonably detailed description of the feature: what it is, how it's supposed to work, - and how you'd use it. - The maintainers aren't familiar with every feature of every protocol and tool, - and community contributors who are looking for tasks to work on will also - appreciate more information that helps them implement and test a feature. -* Proposed CLI syntax, if the feature requires new commands. - Please include both configuration and operational mode commands, if both are required. +* Provide a detailed description of the feature: what it is, how it works, and how + you would use it. Maintainers may not be familiar with every feature of every + protocol and tool. Community contributors looking for work also appreciate + detailed information that helps them implement and test the feature. +* Include proposed CLI syntax if the feature requires new commands. Provide both + configuration and operational mode commands if both are needed. -You should include the following information: +Consider including the following information: -* Is the feature supported by the underlying component - (FreeRangeRouting, nftables, Kea...) already? -* How you'd configure it by hand there? -* Are there any limitations (hardware support, resource usage)? -* Are there any adverse or non-obvious interactions with other features? - Should it be mutually exclusive with anything? +* Is the feature already supported by the underlying component (FreeRangeRouting, + nftables, Kea, etc.)? +* How would you configure it manually with that component? +* Are there limitations (hardware support, resource usage)? +* Are there any adverse or non-obvious interactions with other features? Should + it be mutually exclusive with anything? -It's fine if you cannot provide some of that information, but if you can, -it makes the work of developers considerably simpler, -so try to do the research to answer those questions. +You do not need to provide all this information, but if you can, it simplifies +developers' work considerably. Research these questions when possible. Task auto-closing ================= -There is a special status for tasks -where all work on the side of maintainers and contributors is complete: -"Needs reporter action". +A special task status exists for when all work by maintainers and contributors +is complete: "Needs reporter action". -We assign that status to: +We assign this status to: * Feature requests that do not include required information and need clarification. * Bug reports that lack reproducing procedures. @@ -119,14 +109,14 @@ We assign that status to: but require testing in the real-world environment that only the reporter can replicate (e.g., hardware we do not have, specific network conditions...). -This is what will happen when a task is set to "Needs reporter action": +When a task is set to "Needs reporter action", the following happens: -* If there is no response from the reporter within two weeks, - the task bot will add a comment ("Any news?") to remind the reporter to reply. -* If there is no response after further two weeks, the task will be automatically closed. +* If no response arrives within two weeks, the task bot adds a comment + ("Any news?") to remind the reporter. +* If there is still no response after two more weeks, the task closes automatically. -We will not auto-close tasks with any other status -and will not close tasks for the lack of maintainer activity! +We do not auto-close tasks with any other status and do not close tasks due to +lack of maintainer activity. .. _documentation: https://docs.vyos.io .. _Slack: https://slack.vyos.io diff --git a/docs/contributing/testing.rst b/docs/contributing/testing.rst index f5d3db5260..d6a68ee33a 100644 --- a/docs/contributing/testing.rst +++ b/docs/contributing/testing.rst @@ -1,39 +1,37 @@ +:lastproofread: 2025-12-02 + .. _testing: ####### Testing ####### -One of the major advantages introduced in VyOS 1.3 is an automated test -framework. When assembling an ISO image multiple things can go wrong badly and -publishing a faulty ISO makes no sense. The user is disappointed by the quality -of the image and the developers get flodded with bug reports over and over -again. +One of the major features introduced in VyOS 1.3 is an automated test +framework. When you assemble an ISO image, several things can go wrong. +VyOS uses this framework to detect issues before they cause downstream problems. -As the VyOS documentation is not only for users but also for the developers - -and we keep no secret documentation - this section describes how the automated -testing works. +This section describes how the automated testing process at VyOS works. Jenkins CI ========== -Our `VyOS CI`_ system is based on Jenkins and builds all our required packages -for VyOS 1.2 to 1.4. In addition to the package build, there is the vyos-build -Job which builds and tests the VyOS ISO image which is published after a -successful test drive. +The `VyOS CI`_ system is based on Jenkins. It builds all required packages +for VyOS 1.2 to 1.4. In addition to the package build, there is the +``vyos-build`` job, which builds and tests the VyOS ISO image. +The image is published after a successful test run. -We differentiate in two independent tests, which are both run in parallel by -two separate QEmu instances which are launched via ``make test`` and ``make -testc`` from within the vyos-build_ repository. +VyOS runs two independent tests in parallel using separate QEMU instances. +These are launched via ``make test`` and ``make testc`` from within the +vyos-build_ repository. Smoketests ========== -Smoketests executes predefined VyOS CLI commands and checks if the desired -daemon/service configuration is rendert - that is how to put it "short". +Smoketests execute predefined VyOS CLI commands and check if the desired +daemon or service configuration is rendered. -When and ISO image is assembled by the `VyOS CI`_, the ``BUILD_SMOKETEST`` -parameter is enabled by default, which will extend the ISO configuration line +When an ISO image is assembled by the `VyOS CI`_, the ``BUILD_SMOKETEST`` +parameter is enabled by default. This extends the ISO configuration line with the following packages: .. code-block:: python @@ -42,29 +40,29 @@ with the following packages: if (params.BUILD_SMOKETESTS) CUSTOM_PACKAGES = '--custom-package vyos-1x-smoketest' -So if you plan to build your own custom ISO image and want to make use of our +If you plan to build your own custom ISO image and want to use VyOS's smoketests, ensure that you have the `vyos-1x-smoketest` package installed. -The ``make test`` command from the vyos-build_ repository will launch a new -QEmu instance and the ISO image is first installed to the virtual harddisk. +The ``make test`` command from the vyos-build_ repository launches a new +QEMU instance, and the ISO image is first installed to the virtual hard disk. -After its first boot into the newly installed system the main Smoketest script -is executed, it can be found here: `/usr/bin/vyos-smoketest` +After the first boot into the newly installed system, the main Smoketest script +is executed. It can be found at `/usr/bin/vyos-smoketest`. -The script only searches for executable "test-cases" under +The script searches for executable test cases under ``/usr/libexec/vyos/tests/smoke/cli/`` and executes them one by one. -.. note:: As Smoketests will alter the system configuration and you are logged - in remote you may loose your connection to the system. +.. note:: Smoketests will alter the system configuration. If you are logged + in remotely, you may lose your connection to the system. -.. note:: To enable smoketest debugging (print of the CLI set commands used) - you can run: ``touch /tmp/vyos.smoketest.debug``. +.. note:: To enable smoketest debugging (print the CLI set commands used), + run: ``touch /tmp/vyos.smoketest.debug``. Manual Smoketest Run -------------------- -On the other hand - as each test is contain in its own file - one can always -execute a single Smoketest by hand by simply running the Python test scripts. +Each test is contained in its own file, so you can execute a single Smoketest +manually by running the Python test script. Example: @@ -90,15 +88,14 @@ Example: OK -Interface based tests +Interface-based tests --------------------- -Our smoketests not only test daemons and serives, but also check if what we -configure for an interface works. Thus there is a common base classed named: -``base_interfaces_test.py`` which holds all the common code that an interface -supports and is tested. +Our smoketests not only test daemons and services, but also check if interface +configuration works as expected. There is a common base class named +``base_interfaces_test.py`` that holds all the common code for interface tests. -Those common tests consists out of: +These common tests consist of: * Add one or more IP addresses * DHCP client and DHCPv6 prefix delegation @@ -109,12 +106,12 @@ Those common tests consists out of: * VLANs (QinQ and regular 802.1q) * ... -.. note:: When you are working on interface configuration and you also want to - test if the Smoketests pass you would normally loose the remote SSH connection - to your :abbr:`DUT (Device Under Test)`. To handle this issue, some of the - interface based tests can be called with an environment variable beforehand - to limit the number of interfaces used in the test. By default all interface - e.g. all Ethernet interfaces are used. +.. note:: When you are working on interface configuration and want to test + if the Smoketests pass, you would normally lose the remote SSH connection + to your :abbr:`DUT (Device Under Test)`. To handle this, some interface-based + tests can be called with an environment variable beforehand to limit the + number of interfaces used in the test. By default, all interfaces (e.g., all + Ethernet interfaces) are used. .. code-block:: none @@ -148,31 +145,32 @@ Those common tests consists out of: OK -This will limit the `bond` interface test to only make use of `eth1` and `eth2` +This will limit the `bond` interface test to use only `eth1` and `eth2` as member ports. Config Load Tests ================= -The other part of our tests are called "config load tests". The config load tests -will load - one after another - arbitrary configuration files to test if the -configuration migration scripts work as designed and that a given set of -functionality still can be loaded with a fresh VyOS ISO image. +The other part of our tests are called "config load tests." Config load tests +sequentially load arbitrary configuration files to verify that configuration +migration scripts work as designed and that a given set of functionality can +still be loaded with a fresh VyOS ISO image. -The configurations are all derived from production systems and can not only act -as a testcase but also as reference if one wants to enable a certain feature. -The configurations can be found here: +The configurations are all derived from production systems and can act as +test cases or as references for enabling certain features. The configurations +can be found here: https://github.com/vyos/vyos-1x/tree/current/smoketest/configs -The entire test is controlled by the main wrapper script ``/usr/bin/vyos-configtest`` -which behaves in the same way as the main smoketest script. It scans the folder -for potential configuration files and issues a ``load`` command one after another. +The entire test is controlled by the main wrapper script +``/usr/bin/vyos-configtest``. +It behaves in the same way as the main smoketest script. It scans the folder +for potential configuration files and issues a ``load`` command for each file. Manual config load test ----------------------- -One is not bound to load all configurations one after another but can also load -individual test configurations on his own. +You do not have to load all configurations sequentially; you can also load +individual test configurations manually. .. code-block:: none @@ -202,10 +200,10 @@ individual test configurations on his own. vyos@vyos# commit vyos@vyos# -.. note:: Some of the configurations have preconditions which need to be met. - Those most likely include generation of crypographic keys before the config - can be applied - you will get a commit error otherwise. If you are interested - how those preconditions are fulfilled check the vyos-build_ repository and - the ``scripts/check-qemu-install`` file. +.. note:: Some configurations have preconditions that must be met. These most + likely include generation of cryptographic keys before the config can be + applied; otherwise, you will get a commit error. If you are interested in + how those preconditions are fulfilled, check the vyos-build_ repository and + the ``scripts/check-qemu-install`` file. .. include:: /_include/common-references.txt diff --git a/docs/contributing/upstream-packages.rst b/docs/contributing/upstream-packages.rst index 5c48bbb3d6..78fe374512 100644 --- a/docs/contributing/upstream-packages.rst +++ b/docs/contributing/upstream-packages.rst @@ -1,86 +1,90 @@ +:lastproofread: 2025-11-30 + .. _upstream_packages: -Upstream packages ------------------ +################# +Upstream Packages +################# -Many base system packages are pulled straight from Debian's main and contrib -repositories, but there are exceptions. +Many base system packages are pulled straight from Debian's ``main`` and +``contrib`` repositories, but there are exceptions. -This chapter lists those exceptions and gives you a brief overview what we -have done on those packages. If you only want to build yourself a fresh ISO -you can completely skip this chapter. It may become interesting once you have -a VyOS deep dive. +This page lists those exceptions and briefly describes changes made to +these packages. If you only want to build a fresh ISO image, you can skip +this section. This information may be useful for a deeper dive into VyOS. -vyos-netplug -^^^^^^^^^^^^ +``vyos-netplug`` +---------------- -Due to issues in the upstream version that sometimes set interfaces down, a -modified version is used. +VyOS uses a modified version because the upstream release sometimes causes +network interfaces to go down. -The source is located at https://github.com/vyos/vyos-netplug +Source: https://github.com/vyos/vyos-netplug. -In the future, we may switch to using systemd infrastructure instead. Building -it doesn't require a special procedure. +VyOS may switch to ``systemd`` in the future. Building the package does not +require a special procedure. -keepalived -^^^^^^^^^^ +``keepalived`` +-------------- -Keepalived normally isn't updated to newer feature releases between Debian -versions, so we are building it from source. +``keepalived`` is not updated to newer feature releases between Debian releases. +VyoS builds it from source. -Debian does keep their package in git, but it's upstream tarball imported into -git without its original commit history. To be able to merge new tags in, we -keep a fork of the upstream repository with packaging files imported from -Debian at https://github.com/vyos/keepalived-upstream +Debian maintains the package in git, but the upstream tarball was imported +without its original commit history. To allow merging new tags, we maintain +a fork with packaging files imported from +Debian: https://github.com/vyos/keepalived-upstream. -strongswan -^^^^^^^^^^ +``strongswan`` +-------------- -Our StrongSWAN build differs from the upstream: +VyOS's StrongSWAN build differs from upstream: -- strongswan-nm package build is disabled since we don't use NetworkManager -- Patches for DMVPN are merged in +- We disable the ``strongswan-nm`` package build because VyOS does not use + NetworkManager. +- We merged patches for DMVPN. -The source is at https://github.com/vyos/vyos-strongswan +Source: https://github.com/vyos/vyos-strongswan -DMVPN patches are added by this commit: +DMVPN patches were added in this commit: https://github.com/vyos/vyos-strongswan/commit/1cf12b0f2f921bfc51affa3b81226 -Our op mode scripts use the python-vici module, which is not included in -Debian's build, and isn't quite easy to integrate in that build. For this -reason we debianize that module by hand now, using this procedure: +VyOS's op-mode scripts use the ``python-vici`` module, which is not included +in Debian's build and is difficult to integrate. VyOS debianizes the module +manually: -0. Install https://pypi.org/project/stdeb/ -1. `cd vyos-strongswan` -2. `./configure --enable-python-eggs` -3. `cd src/libcharon/plugins/vici/python` -4. `make` -5. `python3 setup.py --command-packages=stdeb.command bdist_deb` +1. Install ``stdeb`` from PyPI (for example: ``pip3 install stdeb``). +2. ``cd vyos-strongswan`` +3. ``./configure --enable-python-eggs`` +4. ``cd src/libcharon/plugins/vici/python`` +5. ``make`` +6. ``python3 setup.py --command-packages=stdeb.command bdist_deb`` -The package ends up in deb_dist dir. +The package is created in the ``deb_dist`` directory. -mdns-repeater -^^^^^^^^^^^^^ +``mdns-repeater`` +----------------- -This package doesn't exist in Debian. A debianized fork is kept at -https://github.com/vyos/mdns-repeater +This package does not exist in Debian. VyOS maintains a debianized fork at +https://github.com/vyos/mdns-repeater. No special build procedure is required. -udp-broadcast-relay -^^^^^^^^^^^^^^^^^^^ +``udp-broadcast-relay`` +----------------------- -This package doesn't exist in Debian. A debianized fork is kept at -https://github.com/vyos/udp-broadcast-relay +This package does not exist in Debian. VyOS maintain a debianized fork at +https://github.com/vyos/udp-broadcast-relay. No special build procedure is required. -hvinfo -^^^^^^ +``hvinfo`` +---------- -A fork with packaging changes for VyOS is kept at https://github.com/vyos/hvinfo +A fork with packaging changes for VyOS is available +at https://github.com/vyos/hvinfo. -The original repo is at https://github.com/dmbaturin/hvinfo +The original repository is at https://github.com/dmbaturin/hvinfo. -It's an Ada program and requires GNAT and gprbuild for building, dependencies -are properly specified so just follow debuild's suggestions. +It is an Ada program and requires GNAT and ``gprbuild``. Dependencies are +properly specified; follow the suggestions from ``debuild``.