Merge pull request #2 from vyos/master

import 2024-03

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