vyos/vyos-documentation
1
0
Fork 0
mirror of https://github.com/vyos/vyos-documentation.git synced 2025-10-26 08:41:46 +01:00
Code Issues Packages Projects Releases Wiki Activity

Merge pull request #1591 from dmbaturin/sagitta-updates

Browse Source 
Updates for project changes since Sagitta release
This commit is contained in:
Robert Göhler 2025-01-23 12:19:11 +01:00 committed by GitHub
commit a75b18016b
No known key found for this signature in database
GPG Key ID: B5690EEEBB952194
3 changed files with 24 additions and 329 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

189
docs/contributing/build-vyos.rst
View File

@ -14,72 +14,41 @@ 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`.
.. note:: Starting with VyOS 1.2 the release model of VyOS has changed. VyOS
is now **free as in speech, but not as in beer**. This means that while
VyOS is still an open source project, the release ISOs are no longer free
and can only be obtained via subscription, or by contributing to the
community.
.. 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 remains public and an ISO can be built using the process
outlined in this chapter.
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 1.2 to the latest version.
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 Jessie, Stretch, and
Buster.
This process has been tested on clean installs of Debian Bookworm.
.. _build_native:
Native Build
============
To build VyOS natively you require a properly configured build host with the
To build VyOS natively you need 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
- Debian Bookworm
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)
$ sudo make clean
$ sudo ./build-vyos-image iso --architecture amd64 --build-by "j.randomhacker@vyos.io"
# For VyOS 1.5 (circinus,current)
$ sudo make clean
$ sudo ./build-vyos-image generic --architecture amd64 --build-by "j.randomhacker@vyos.io"
$ 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
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).
This process has been tested on clean installs of Bookworm (12).
.. _build_docker:
@ -142,10 +111,7 @@ To manually download the container from DockerHub, run:
.. code-block:: none
$ 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 VyOS 1.5 rolling release
$ docker pull vyos/vyos-build:current # For VyOS rolling release
Build from source
^^^^^^^^^^^^^^^^^
@ -154,20 +120,10 @@ The container can also be built directly from source:
.. 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
$ 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
$ 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
@ -177,7 +133,7 @@ Tips and Tricks
---------------
You can create yourself some handy Bash aliases to always launch the latest -
per release train (`current` or `crux`) - container. Add the following to your
per release train (`current`) - container. Add the following to your
``.bash_aliases`` file:
.. code-block:: none
@ -191,16 +147,7 @@ per release train (`current` or `crux`) - container. Add the following to your
-e GOSU_UID=$(id -u) -e GOSU_GID=$(id -g) \
vyos/vyos-build:current bash'
alias vybld_crux='docker pull vyos/vyos-build:crux && 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:crux bash'
Now you are prepared with two new aliases ``vybld`` and ``vybld_crux`` to spawn
Now you are prepared with a new aliase ``vybld`` to spawn
your development containers in your current working directory.
.. note:: Some VyOS packages (namely vyos-1x) come with build-time tests which
@ -220,20 +167,9 @@ 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.
Please note as this will differ for both `current` and `crux`.
.. 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
@ -243,57 +179,20 @@ Now a fresh build of the VyOS ISO can begin. Change directory to the
.. code-block:: none
$ cd vyos-build
# For VyOS 1.2 (crux)
$ docker run --rm -it --privileged -v $(pwd):/vyos -w /vyos vyos/vyos-build:crux bash
# For VyOS 1.3 (equuleus)
$ docker run --rm -it --privileged -v $(pwd):/vyos -w /vyos vyos/vyos-build:equuleus bash
# 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)
$ git clone https://github.com/vyos/vyos-utils-misc
$ cd build-tools/macos-build
# For VyOS 1.2 (crux)
$ os=jessie64 branch=crux make build
# For VyOS 1.3 (equuleus)
$ os=buster64 branch=equuleus make build
# For VyOS 1.4 (sagitta)
$ os=buster64 branch=sagitta make build
Start the build:
.. code-block:: none
# For VyOS 1.2 (crux) and VyOS 1.3 (equuleus)
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)
vyos_bld@8153428c7e1f:/vyos$ sudo make clean
vyos_bld@8153428c7e1f:/vyos$ sudo ./build-vyos-image iso --architecture amd64 --build-by "j.randomhacker@vyos.io"
# For VyOS 1.5 (circinus,current)
vyos_bld@8153428c7e1f:/vyos$ sudo make clean
vyos_bld@8153428c7e1f:/vyos$ sudo ./build-vyos-image generic --architecture amd64 --build-by "j.randomhacker@vyos.io"
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``.
Good luck!
.. hint:: Building VyOS on Windows WSL2 with Docker integrated into WSL2 will
work like a charm. No problems are known so far!
.. _build source:
@ -736,39 +635,6 @@ Simply use our wrapper script to build all of the driver modules.
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.
Mellanox OFED
^^^^^^^^^^^^^
The Mellanox OFED drivers do not come from a Git repository, instead we fetch the
tarball from Nvidia and compile the sources its contains against our kernel tree.
Simply use our wrapper script to build all of the driver modules.
.. code-block:: none
./build-mellanox-ofed.sh
...
Below is the list of OFED packages that you have chosen
(some may have been added by the installer due to package dependencies):
ofed-scripts
mlnx-tools
mlnx-ofed-kernel-utils
mlnx-ofed-kernel-modules
...
Building packages
Building DEB for ofed-scripts-24.04.OFED.24.04.0.6.6 (ofed-scripts)...
Running /usr/bin/dpkg-buildpackage -us -uc
Installing ofed-scripts-24.04.OFED.24.04.0.6.6...
Running /usr/bin/dpkg -i --force-confmiss '/vyos/packages/linux-kernel/MLNX_OFED_SRC-debian-24.04-0.6.6.0/DEBS/debian12.1/x86_64/ofed-scripts_24.04.OFED.24.04.0.6.6-1_amd64.deb'
Building DEB for mlnx-tools-24.04.0 (mlnx-tools)...
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.
@ -816,29 +682,6 @@ during ISO build.
.. start_vyoslinter
Virtualization Platforms
========================
QEMU
----
Run the following command after building the ISO image.
.. code-block:: none
$ make qemu
VMware
------
Run the following command after building the QEMU image.
.. code-block:: none
$ make vmware
.. _build_packages:
********

151
docs/contributing/development.rst
View File

@ -119,20 +119,11 @@ repositories found in the VyOS GitHub organisation at https://github.com/vyos
Determinine source package
--------------------------
Suppose you want to make a change in the webproxy script but yet you do not know
which of the many VyOS packages ship this file. You can determine the VyOS
Suppose you want to make a change in a file but yet you do not know
which of the VyOS packages ship this file. You can determine the VyOS
package name in question by using Debian's ``dpkg -S`` command of your running
VyOS installation.
.. code-block:: none
vyos@vyos:~ dpkg -S /opt/vyatta/sbin/vyatta-update-webproxy.pl
vyatta-webproxy: /opt/vyatta/sbin/vyatta-update-webproxy.pl
This means the file in question (``/opt/vyatta/sbin/vyatta-update-webproxy.pl``)
is located in the ``vyatta-webproxy`` package which can be found here:
https://github.com/vyos/vyatta-webproxy
Fork Repository and submit Patch
--------------------------------
@ -171,7 +162,7 @@ record them in your created Git commit:
* Submit the patch ``git push`` and create the GitHub pull-request.
Attach patch to Phabricator task
Attach patch to Phorge task
--------------------------------
Follow the above steps on how to "Fork repository to submit a Patch". Instead
@ -192,9 +183,6 @@ us all. By having a consistent coding style it becomes very easy for new
and also longtime contributors to navigate through the sources and all the
implied logic of any one source file..
Python 3 **shall** be used. How long can we keep Python 2 alive anyway? No
considerations for Python 2 compatibility **should** be taken at any time.
Formatting
----------
@ -219,43 +207,6 @@ used for structured, multi-line formats such as those used by ISC DHCPd.
The default template processor for VyOS code is Jinja2_.
Summary
-------
When modifying the source code, remember these rules of the legacy elimination
campaign:
* No new features in Perl
* No old style command definitions
* No code incompatible with Python3
Python
======
The switch to the Python programming language for new code is not merely a
change of the language, but a chance to rethink and improve the programming
approach.
Let's face it: VyOS is full of spaghetti code where logic for reading the VyOS
config, generating daemon configs, and restarting processes is all mixed up.
Python (or any other language, for that matter) does not provide automatic
protection from bad design, so we need to also devise design guidelines and
follow them to keep the system extensible and maintainable.
But we are here to assist you and want to guide you through how you can become
a good VyOS contributor. The rules we have are not there to punish you - the
rules are in place to help us all. What does it mean? By having a consistent
coding style it becomes very easy for new contributors and also longtime
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/Python
interface.
Configuration Script Structure and Behaviour
--------------------------------------------
@ -635,69 +586,6 @@ Examples:
* Good: "Disable IPv6 forwarding"
* Bad: "Disables IPv6 forwarding"
Migrating old CLI
-----------------
.. list-table::
:widths: 25 25 50
:header-rows: 1
* - Old concept/syntax
- New syntax
- Notes
* - mynode/node.def
- <node name="mynode"> </node>
- Leaf nodes (nodes with values) use <leafNode> tag instead
* - mynode/node.tag , tag:
- <tagNode name="mynode> </node>
-
* - help: My node
- <properties> <help>My node</help>
-
* - val_help: <format>; some string
- <properties> <valueHelp> <format> format </format> <description> some
string </description>
- Do not add angle brackets around the format, they will be inserted
automatically
* - syntax:expression: pattern
- <properties> <constraint> <regex> ...
- <constraintErrorMessage> will be displayed on failure
* - syntax:expression: $VAR(@) in "foo", "bar", "baz"
- None
- Use regex
* - syntax:expression: exec ...
- <properties> <constraint> <validator> <name ="foo" argument="bar">
- "${vyos_libexecdir}/validators/foo bar $VAR(@)" will be executed,
<constraintErrorMessage> will be displayed on failure
* - syntax:expression: (arithmetic expression)
- None
- External arithmetic validator may be added if there's demand, complex
validation is better left to commit-time scripts
* - priority: 999
- <properties> <priority>999</priority>
- Please leave a comment explaining why the priority was chosen
(e.g. "after interfaces are configured")
* - multi:
- <properties> <multi/>
- Only applicable to leaf nodes
* - allowed: echo foo bar
- <properties> <completionHelp> <list> foo bar </list>
-
* - allowed: cli-shell-api listNodes vpn ipsec esp-group
- <properties> <completionHelp> <path> vpn ipsec esp-group </path> ...
-
* - allowed: /path/to/script
- <properties> <completionHelp> <script> /path/to/script </script> ...
-
* - default:
- None
- Move default values to scripts
* - commit:expression:
- None
- All commit time checks should be in the verify() function of the script
* - begin:/create:/delete:
- None
- All logic should be in the scripts
C++ Backend Code
================
@ -717,39 +605,6 @@ in the C/C++ code.
- https://github.com/vyos/vyatta-cfg/blob/0f42786a0b3/src/commit/commit-algorithm.cpp#L1252
Continuous Integration
======================
VyOS makes use of Jenkins_ as our Continuous Integration (CI) service. Our
`VyOS CI`_ server is publicly accessible here: https://ci.vyos.net. You can get
a brief overview of all required components shipped in a VyOS ISO.
To build our modules we utilize a CI/CD Pipeline script. Each and every VyOS
component comes with it's own ``Jenkinsfile`` which is (more or less) a copy.
The Pipeline utilizes the Docker container from the :ref:`build_iso` section -
but instead of building it from source on every run, we rather always fetch a
fresh copy (if needed) from Dockerhub_.
Each module is build on demand if a new commit on the branch in question is
found. After a successful run the resulting Debian Package(s) will be deployed
to our Debian repository which is used during build time. It is located here:
http://dev.packages.vyos.net/repositories/.
.. stop_vyoslinter
.. _Jenkins: https://jenkins.io/
.. _Dockerhub: https://hub.docker.com/u/vyos/
.. _process: https://blog.vyos.io/vyos-development-digest-10
.. _VyConf: https://github.com/vyos/vyconf/tree/master/data/schemata
.. _vyos-1x: https://github.com/vyos/vyos-1x/tree/current/schema
.. _Jinja2: https://jinja.palletsprojects.com/
.. _`IPv4, IPv6 and DHCP(v6)`: https://github.com/vyos/vyos-1x/blob/current/interface-definitions/include/interface/address-ipv4-ipv6-dhcp.xml.i
.. _`IPv4, IPv6`: https://github.com/vyos/vyos-1x/blob/current/interface-definitions/include/interface/address-ipv4-ipv6.xml.i
.. _`VLAN (VIF)`: https://github.com/vyos/vyos-1x/blob/current/interface-definitions/include/interface/vif.xml.i
.. _`MAC address`: https://github.com/vyos/vyos-1x/blob/current/interface-definitions/include/interface/mac.xml.i
.. include:: /_include/common-references.txt
.. start_vyoslinter

13
docs/introducing/history.rst
View File

@ -12,7 +12,7 @@ called Vyatta. [*]_ 2006 onwards, it was a great free software
alternative to Cisco IOS and Jupiter JUNOS. It came in two editions:
Vyatta Core (previously Vyatta Community Edition) that was completely
free software, and Vyatta Subscription Edition that had proprietary
features and was only available to paying customers. [*]_
features and was only available to paying customers.
Vyatta was acquired by Brocade Communication Systems in 2012. Shortly
after, Brocade renamed Vyatta Subscription Edition to Brocade vRouter,
@ -30,7 +30,7 @@ the last Vyatta Core version (6.6R1) and VyOS Project came into being.
`Sentrium SL <https://blog.vyos.io/sentrium-what-sentrium>`_ was
established by VyOS maintainers in 2014 to fund VyOS development by
selling support, consulting services and prebuilt long-term support
images.
images. The company was later reorganized under the VyOS brand.
Brocade was acquired by Broadcom in 2016 and sold what remains of
erstwhile Vyatta to AT&T in 2017, who in turn sold it to Ciena in 2021.
@ -85,7 +85,7 @@ configuration migration. Introduction of new Perl and shell code was
proscribed and the rewriting of legacy Perl code in pure Python began
with Crux.
As of 2022, Crux is still supported and maintained.
Crux reached end of support in 2023..
Equuleus (1.3)
--------------
@ -101,13 +101,12 @@ interfaces, support for GENEVE and MACSec interfaces, VRF, IS-IS
routing, preliminary support for MPLS and LDP, and many other
initialisms.
As of 2022, Equuleus is in the stable.
Equuleus reached end of support in 2025.
Sagitta (1.4)
-------------
Sagitta (the Arrow) is the codename of the current development
branch, so there's no VyOS 1.4 yet.
Sagitta (the Arrow) was released in 2024 and is currently a supported LTS release.
Circinus (1.5)
--------------
@ -131,6 +130,4 @@ any pre-built image for more precise information.
.. [*] From the Sanskrit adjective "Vyātta" (व्यात्त), meaning opened.
.. [*] A business model comparable to that of Redis, rather than that
of VyOS today.
.. [*] This is not unlike how Linus Torvalds owns the trademark "Linux".