diff options
Diffstat (limited to 'docs/contributing')
| -rw-r--r-- | docs/contributing/build-vyos.rst | 142 | ||||
| -rw-r--r-- | docs/contributing/debugging.rst | 14 | ||||
| -rw-r--r-- | docs/contributing/development.rst | 2 | ||||
| -rw-r--r-- | docs/contributing/testing.rst | 15 |
4 files changed, 107 insertions, 66 deletions
diff --git a/docs/contributing/build-vyos.rst b/docs/contributing/build-vyos.rst index bb212e2f..16eb8ac7 100644 --- a/docs/contributing/build-vyos.rst +++ b/docs/contributing/build-vyos.rst @@ -23,10 +23,60 @@ also set up your own build machine and run a :ref:`build_native`. The source code remains public and an ISO can be built using the process outlined in this chapter. + The following includes the build process for VyOS 1.2 to the latest version. + This will guide you through the process of building a VyOS ISO using Docker_. This process has been tested on clean installs of Debian Jessie, Stretch, and Buster. +.. _build_native: + +Native Build +============ + +To build VyOS natively you require a properly configured build host with the +following Debian versions installed: + +- Debian Jessie for VyOS 1.2 (crux) +- Debian Buster for VyOS 1.3 (equuleus) +- Debian Bookworm for VyOS 1.4 (sagitta) +- Debian Bookworm for the upcoming VyOS 1.5/circinus/current + (subject to change) - aka the rolling release + +To start, clone the repository to your local machine: + +.. code-block:: none + + # For VyOS 1.2 (crux) + $ git clone -b crux --single-branch https://github.com/vyos/vyos-build + + # For VyOS 1.3 (equuleus) + $ git clone -b equuleus --single-branch https://github.com/vyos/vyos-build + + # For VyOS 1.4 (sagitta) + $ git clone -b sagitta --single-branch https://github.com/vyos/vyos-build + + # For VyOS 1.5 (circinus,current) + $ git clone -b current --single-branch https://github.com/vyos/vyos-build + + $ cd vyos-build + + # For VyOS 1.2 (crux) and VyOS 1.3 (equuleus) + $ ./configure --architecture amd64 --build-by "j.randomhacker@vyos.io" + $ sudo make iso + + # For VyOS 1.4 (sagitta) and VyOS 1.5 (circinus,current) + $ sudo make clean + $ sudo ./build-vyos-image iso --architecture amd64 --build-by "j.randomhacker@vyos.io" + +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 +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 Debian Bullseye (11) and +Bookworm (12). + .. _build_docker: Docker @@ -34,14 +84,26 @@ Docker Installing Docker_ and prerequisites: +.. hint:: Due to the updated version of Docker, the following examples may + become invalid. + .. code-block:: none - $ sudo apt-get update - $ sudo apt-get install -y apt-transport-https ca-certificates curl gnupg2 software-properties-common - $ curl -fsSL https://download.docker.com/linux/debian/gpg | sudo apt-key add - - $ sudo add-apt-repository "deb [arch=amd64] https://download.docker.com/linux/debian $(lsb_release -cs) stable" - $ sudo apt-get update - $ sudo apt-get install -y docker-ce + # 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 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 @@ -79,7 +141,7 @@ To manually download the container from DockerHub, run: $ docker pull vyos/vyos-build:crux # For VyOS 1.2 $ docker pull vyos/vyos-build:equuleus # For VyOS 1.3 $ docker pull vyos/vyos-build:sagitta # For VyOS 1.4 - $ docker pull vyos/vyos-build:current # For rolling release + $ docker pull vyos/vyos-build:current # For VyOS 1.5 rolling release Build from source ^^^^^^^^^^^^^^^^^ @@ -94,15 +156,19 @@ The container can also be built directly from source: $ git clone -b equuleus --single-branch https://github.com/vyos/vyos-build # For VyOS 1.4 (sagitta) $ git clone -b sagitta --single-branch https://github.com/vyos/vyos-build + # For VyOS 1.5 (circinus,current) + $ git clone -b current --single-branch https://github.com/vyos/vyos-build $ cd vyos-build - $ docker build -t vyos/vyos-build:crux docker # For VyOS 1.2 - $ docker build -t vyos/vyos-build:current docker # For rolling release - -.. note:: Since VyOS has switched to Debian (11) Bullseye in its ``current`` - branch, you will require individual container for `current`, `equuleus` and - `crux` builds. - + $ docker build -t vyos/vyos-build:crux docker # For VyOS 1.2 + $ docker build -t vyos/vyos-build:equuleus docker # For VyOS 1.3 + $ docker build -t vyos/vyos-build:sagitta docker # For VyOS 1.4 + $ docker build -t vyos/vyos-build:current docker # For VyOS 1.5 rolling release + +.. note:: VyOS has switched to Debian (12) Bookworm 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 --------------- @@ -141,39 +207,6 @@ your development containers in your current working directory. ``--sysctl net.ipv6.conf.lo.disable_ipv6=0``, otherwise those tests will fail. -.. _build_native: - -Native Build -============ - -To build VyOS natively you require a properly configured build host with the -following Debian versions installed: - -- Debian Jessie for VyOS 1.2 (crux) -- Debian Buster for VyOS 1.3 (equuleus) -- Debian Bullseye for VyOS 1.4 (sagitta) - -To start, clone the repository to your local machine: - -.. code-block:: none - - # For VyOS 1.2 (crux) - $ git clone -b crux --single-branch https://github.com/vyos/vyos-build - - # For VyOS 1.3 (equuleus) - $ git clone -b equuleus --single-branch https://github.com/vyos/vyos-build - - # For VyOS 1.4 (sagitta) - $ git clone -b sagitta --single-branch https://github.com/vyos/vyos-build - - -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 -dependencies are missing. - -Once you have the required dependencies installed, you may proceed with the -steps described in :ref:`build_iso`. - .. _build_iso: @@ -196,6 +229,10 @@ Please note as this will differ for both `current` and `crux`. # For VyOS 1.4 (sagitta) $ git clone -b sagitta --single-branch https://github.com/vyos/vyos-build + # For VyOS 1.5 (circinus,current) + $ 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: @@ -210,7 +247,10 @@ Now a fresh build of the VyOS ISO can begin. Change directory to the # For VyOS 1.4 (sagitta) $ docker run --rm -it --privileged -v $(pwd):/vyos -w /vyos vyos/vyos-build:sagitta bash - + + # For VyOS 1.5 (current) + $ docker run --rm -it --privileged -v $(pwd):/vyos -w /vyos vyos/vyos-build:current bash + .. code-block:: none # For MacOS (crux, equuleus, sagitta) @@ -234,7 +274,7 @@ Start the build: vyos_bld@8153428c7e1f:/vyos$ ./configure --architecture amd64 --build-by "j.randomhacker@vyos.io" vyos_bld@8153428c7e1f:/vyos$ sudo make iso - # For VyOS 1.4 (sagitta) + # For VyOS 1.4 (sagitta) For VyOS 1.5 (circinus,current) vyos_bld@8153428c7e1f:/vyos$ sudo make clean vyos_bld@8153428c7e1f:/vyos$ sudo ./build-vyos-image iso --architecture amd64 --build-by "j.randomhacker@vyos.io" @@ -331,7 +371,7 @@ more or less similar looking error message: (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 directry. This is +root cause, you need to use `chroot` to change into the build directory. This is explained in the following step by step procedure: .. code-block:: none @@ -836,7 +876,7 @@ information. .. stop_vyoslinter -.. _Docker: https://www.docker.com +.. _Docker: https://docs.docker.com/engine/install/debian/ .. _`Docker as non-root`: https://docs.docker.com/engine/install/linux-postinstall .. _VyOS DockerHub organisation: https://hub.docker.com/u/vyos .. _repository: https://github.com/vyos/vyos-build diff --git a/docs/contributing/debugging.rst b/docs/contributing/debugging.rst index fec73257..e03f3f81 100644 --- a/docs/contributing/debugging.rst +++ b/docs/contributing/debugging.rst @@ -125,7 +125,7 @@ You can type ``help`` to get an overview of the available commands, and Useful commands are: * examine variables using ``pp(var)`` -* contine execution using ``cont`` +* continue execution using ``cont`` * get a backtrace using ``bt`` Config Migration Scripts @@ -147,7 +147,7 @@ look like: The reason is that the configuration migration backend is rewritten and uses a new form of "magic string" which is applied on demand when real config -migration is run on boot. When runnint individual migrators for testing, +migration is run on boot. When running individual migrators for testing, you need to convert the "magic string" on your own by: .. code-block:: none @@ -157,13 +157,13 @@ you need to convert the "magic string" on your own by: Configuration Error on System Boot ---------------------------------- -Beeing brave and running the latest rolling releases will sometimes trigger +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 doen the issue. Login to your +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. -You shoudl now see a Python backtrace which will help us to handle the issue, +You should now see a Python backtrace which will help us to handle the issue, please attach it to the Phabricator_ task. Boot Timing @@ -179,7 +179,7 @@ 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_ -To enable boot time graphing change the Kernel commandline and add the folowing +To enable boot time graphing change the Kernel commandline and add the following string: ``init=/usr/lib/systemd/systemd-bootchart`` This can also be done permanently by changing ``/boot/grub/grub.cfg``. @@ -190,7 +190,7 @@ 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 higest +other ``commit`` to the config all scripts are executed from lowest to highest priority. This is good as this gives a deterministic behavior. To debug issues in priorities or to see what's going on in the background diff --git a/docs/contributing/development.rst b/docs/contributing/development.rst index 1f296144..e39af3a5 100644 --- a/docs/contributing/development.rst +++ b/docs/contributing/development.rst @@ -252,7 +252,7 @@ contributors to navigate through the sources and all the implied logic of the spaghetti code. Please use the following template as good starting point when developing new -modules or even rewrite a whole bunch of code in the new style XML/Pyhon +modules or even rewrite a whole bunch of code in the new style XML/Python interface. diff --git a/docs/contributing/testing.rst b/docs/contributing/testing.rst index d5df9d59..78860c06 100644 --- a/docs/contributing/testing.rst +++ b/docs/contributing/testing.rst @@ -4,10 +4,11 @@ Testing ####### -One of the major advantages introduced in VyOS 1.3 is an autmated 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 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. 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 @@ -19,7 +20,7 @@ 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 -successfull test drive. +successful test drive. 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 @@ -41,7 +42,7 @@ 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 wan't to make use of our +So if you plan to build your own custom ISO image and want to make use of our smoketests, ensure that you have the `vyos-1x-smoketest` package installed. The ``make test`` command from the vyos-build_ repository will launch a new @@ -105,7 +106,7 @@ Those common tests consists out of: * VLANs (QinQ and regular 802.1q) * ... -.. note:: When you are working on interface configuration and you also wan't to +.. 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 |