diff options
Diffstat (limited to 'docs/installation')
| -rw-r--r-- | docs/installation/image.rst | 48 | ||||
| -rw-r--r-- | docs/installation/index.rst | 15 | ||||
| -rw-r--r-- | docs/installation/install.rst | 341 | ||||
| -rw-r--r-- | docs/installation/secure-boot.rst | 88 | ||||
| -rw-r--r-- | docs/installation/update.rst | 66 |
5 files changed, 292 insertions, 266 deletions
diff --git a/docs/installation/image.rst b/docs/installation/image.rst index 906db37c..5b473e78 100644 --- a/docs/installation/image.rst +++ b/docs/installation/image.rst @@ -1,13 +1,15 @@ +:lastproofread: 2026-01-26 + .. _image-mgmt: ################ Image Management ################ -The VyOS image-based installation is implemented by creating a directory for -each image on the storage device selected during the install process. +VyOS uses an image-based installation that creates a directory for each image +on the storage device you select during installation. -The directory structure of the boot device: +The boot device has the following directory structure: .. code-block:: none @@ -16,17 +18,15 @@ The directory structure of the boot device: /boot/grub /boot/2025.07.16-0020-rolling.squashfs -The image directory contains the system kernel, a compressed image of the root -filesystem for the OS, and a directory for persistent storage, such as -configuration. On boot, the system will extract the OS image into memory and -mount the appropriate live-rw sub-directories to provide persistent storage -system configuration. +The image directory contains the system kernel, a compressed root filesystem +image, and a directory for persistent storage (such as configuration). During +boot, the system extracts the OS image into memory and mounts the appropriate +live-rw subdirectories to provide persistent storage for system configuration. -This process allows for a system to always boot to a known working state, as -the OS image is fixed and non-persistent. It also allows for multiple releases -of VyOS to be installed on the same storage device. The image can be selected -manually at boot if needed, but the system will otherwise boot the image -configured to be the default. +This process ensures that the system always boots to a known working state, +since the OS image is fixed and non-persistent. You can also install multiple +VyOS releases on the same storage device. You can manually select the image at +boot if needed, but the system boots the default image by default. .. opcmd:: show system image @@ -44,9 +44,9 @@ configured to be the default. .. opcmd:: delete system image [image-name] - Delete no longer needed images from the system. You can specify an optional - image name to delete, the image name can be retrieved via a list of available - images can be shown using the :opcmd:`show system image`. + Delete unused images from the system. You can specify an optional image name + to delete. Use the :opcmd:`show system image` command to list available + images. .. code-block:: none @@ -93,9 +93,9 @@ configured to be the default. System rollback =============== -If you need to rollback to a previous image, you can easily do so. First -check the available images through the :opcmd:`show system image` -command and then select your image with the following command: +To roll back to a previous image, first view the available images by using the +:opcmd:`show system image` command, then select your image with the following +command: .. opcmd:: set system image default-boot [image-name] @@ -104,9 +104,9 @@ command and then select your image with the following command: Then reboot the system. -.. note:: VyOS automatically associates the configuration to the image, - so you don't need to worry about that. Each image has a unique copy - of its configuration. +.. note:: VyOS automatically associates the configuration with each image, + so you don't need to manage this separately. Each image has its own unique + configuration copy. -If you have access to the console, there is a another way to select -your booting image: reboot and use the GRUB menu at startup. +If you have console access, you can also select the boot image by restarting +the system and using the GRUB menu at startup. diff --git a/docs/installation/index.rst b/docs/installation/index.rst index c1e50a1f..5ba89755 100644 --- a/docs/installation/index.rst +++ b/docs/installation/index.rst @@ -1,17 +1,18 @@ +:lastproofread: 2026-01-26 + ################################# Installation and Image Management ################################# -.. note:: This is most likely only relevant for virtual installations: +.. note:: This information applies primarily to virtual installations: - When installing VyOS ensure that the MAC address selected for your NICs is - not a locally administered MAC address. Locally administered addresses are - distinguished from universally administered addresses by setting (assigning - the value of 1 to) the second-least-significant bit of the first octet of - the address: + When installing VyOS, ensure that the MAC address you select for your NICs + is not a locally administered MAC address. Locally administered addresses are + distinguished from universally administered addresses by setting the + second-least-significant bit of the first octet to 1: Example: ``02:00:00:00:00:01``, where the second-least-significant bit - (``02`` in hex) is set to ``1``. + (``02`` in hexadecimal) is set to ``1``. .. toctree:: :maxdepth: 2 diff --git a/docs/installation/install.rst b/docs/installation/install.rst index 3ea243eb..b002d688 100644 --- a/docs/installation/install.rst +++ b/docs/installation/install.rst @@ -1,49 +1,80 @@ +:lastproofread: 2026-01-26 + .. _installation: ############ Installation ############ -VyOS installation requires a downloaded VyOS .iso file. That file is -a live install image that lets you boot a live VyOS. From the live -system, you can proceed to a permanent installation on a hard drive or -any other type of storage. - -.. table:: Comparison of VyOS image releases - - +--------------+---------------------------------------------------+-------------------+---------------------------------------+-----------------------+------------------+ - | Release Type | Description | Release Cycle | Intended Use | Access to Images | Access to Source | - +==============+===================================================+===================+=======================================+=======================+==================+ - | **Nightly | Automatically built from the current branch. | Every night | Developing VyOS, testing new | Everyone | Everyone | - | (Current)** | Always up to date with cutting edge development | | features, experimenting. | | | - | | but guaranteed to contain bugs. | | | | | - +--------------+---------------------------------------------------+-------------------+---------------------------------------+-----------------------+------------------+ - | **Stream** | VyOS Stream serves as a technology preview and | Every quarter | Non-critical production environments, | Everyone | Everyone | - | | a qulity gate for the upcoming LTS release. | | preparing for the LTS release. | | | - | | Allows everyone to try new features and check if | | | | | - | | they work well or need improvements. | | | | | - +--------------+---------------------------------------------------+-------------------+---------------------------------------+-----------------------+------------------+ - | **Release | Rather stable. All development focuses on testing | Irregularly until | Labs, small offices and non-critical | Everyone | Everyone | - | Candidate** | and hunting down remaining bugs following the | EPA comes out | production systems backed by a | | | - | | feature freeze. | | high-availability setup. | | | - +--------------+---------------------------------------------------+-------------------+---------------------------------------+-----------------------+------------------+ - | **Early | Highly stable with no known bugs. Needs to be | Irregularly until | Non-critical production environments, | Everyone | Everyone | - | Production | tested repeatedly under different conditions | LTS comes out | preparing for the LTS release. | | | - | Access** | before it can become the final release. | | | | | - +--------------+---------------------------------------------------+-------------------+---------------------------------------+-----------------------+------------------+ - | **Long-Term | Guaranteed to be stable and carefully maintained | Every major | Large-scale enterprise networks, | Subscribers, | Subscribers, | - | Support** | for several years after the release. No features | version | internet service providers, | contributors, | contributors | - | | are introduced but security updates are released | | critical production environments | non-profits, | | - | | in a timely manner. | | that call for minimum downtime. | emergency services, | | - | | | | | academic institutions | | - +--------------+---------------------------------------------------+-------------------+---------------------------------------+-----------------------+------------------+ +VyOS installation requires a VyOS .iso file. This file is a live installation +image that you can use to boot a live VyOS system. From there, you can proceed +with a permanent installation on a hard drive or other storage device. + +.. list-table:: Comparison of VyOS image releases + :header-rows: 1 + :widths: 15 35 15 25 15 15 + + * - Release Type + - Description + - Release Cycle + - Intended Use + - Access to Images + - Access to Source + + * - Nightly (Current) + - Automatically built from the current branch. Always up to date + with cutting edge development but guaranteed to contain bugs. + - Every night + - Developing VyOS, testing new features, experimenting. + - Everyone + - Everyone + + * - Stream + - VyOS Stream serves as a technology preview and a quality gate + for the upcoming LTS release. Allows everyone to try new features + and check if they work well or need improvements. + - Every quarter + - Non-critical production environments, preparing for the LTS + release. + - Everyone + - Everyone + + * - Release Candidate + - Rather stable. All development focuses on testing and hunting + down remaining bugs following the feature freeze. + - Irregularly until EPA comes out + - Labs, small offices and non-critical production systems backed + by a high-availability setup. + - Everyone + - Everyone + + * - Early Production Access + - Highly stable with no known bugs. Needs to be tested repeatedly + under different conditions before it can become the final + release. + - Irregularly until LTS comes out + - Non-critical production environments, preparing for the LTS + release. + - Everyone + - Everyone + + * - Long-Term Support + - Guaranteed to be stable and carefully maintained for several + years after the release. No features are introduced but security + updates are released in a timely manner. + - Every major version + - Large-scale enterprise networks, internet service providers, + critical production environments that call for minimum downtime. + - Subscribers, contributors, non-profits, emergency services, + academic institutions + - Subscribers, contributors, non-profits, emergency services, + academic institutions Hardware requirements ===================== -The minimum system requirements are 4 GB RAM and 10 GB storage. -Depending on your use, you might need additional RAM and CPU resources e.g. -when having multiple BGP full tables in your system. +The minimum system requirements for VyOS are 4 GB RAM and 10 GB storage. +Depending on your use case, you might need additional RAM and CPU resources. Download ======== @@ -51,21 +82,22 @@ Download Registered Subscribers ---------------------- -Registered subscribers can log into https://support.vyos.io/ to access a -variety of different downloads via the "Downloads" link. These downloads -include LTS (Long-Term Support), the associated hot-fix releases, early public -access releases, pre-built VM images, as well as device specific installation -ISOs. See this article_ for more information on downloads. +Registered subscribers can log into https://support.vyos.io/ to access +a variety of different downloads via the "Downloads" link. These +downloads include LTS (Long-Term Support), the associated hot-fix releases, +early public access releases, pre-built VM images, as well as device +specific installation ISOs. See this article_ for more information on +downloads. .. figure:: /_static/images/vyosnew-downloads.png Building from source -------------------- -Subscribers can download the source code for the LTS release from the -"Downloads" link, while non-subscribers can access the source code for the -Rolling release. Instructions can be found in the :ref:`build` section of this -manual. VyOS source code repository is available at +Subscribers can download the source code for the LTS release from the +"Downloads" link. Non-subscribers can access the source code for the +Rolling release. For instructions, see the :ref:`build` section. The +VyOS source code repository is available at https://github.com/vyos/vyos-build. Rolling Release @@ -74,39 +106,37 @@ Rolling Release Everyone can download bleeding-edge VyOS rolling images from: https://downloads.vyos.io/ -.. note:: Rolling releases contain all the latest enhancements and fixes. This - means that there will be new bugs of course. If you think you hit a bug - please follow the guide at :ref:`bug_report`. We depend on your feedback - to improve VyOS! +.. note:: Rolling releases contain the latest enhancements and fixes. + This means there may be new bugs. If you encounter a bug, follow the + guide at :ref:`bug_report`. We depend on your feedback to improve VyOS. -The following link contains the list of the most recent VyOS builds for AMD64 -systems from the current branch: -https://vyos.net/get/nightly-builds/ +The following link contains the most recent VyOS builds for AMD64 +systems from the ``current`` branch: https://vyos.net/get/nightly-builds/ Download Verification --------------------- -LTS images are signed by the VyOS lead package-maintainer private key. With -the official public key, the authenticity of the package can be -verified. Minisign is used for verification. +LTS images are signed with the VyOS lead package maintainer's private key. +You can verify the authenticity of the package using the official public key +and Minisign. .. _minisign-verification: Minisign verification ^^^^^^^^^^^^^^^^^^^^^ -Currently we are using Minisign for release signing which is a simple tool to -sign files and verify signatures. +VyOS uses `Minisign <https://github.com/jedisct1/minisign>`__ for release +signing. Minisign is a tool for signing files and verifying signatures. -In 2015, OpenBSD introduced signify. An alternative implementation of the same -protocol is minisign, which is also available for Windows and macOS, and in most -GNU/Linux distros it's in the repositories now. It is portable, lightweight, and -uses the highly secure Ed25519 public-key signature system. +OpenBSD introduced signify in 2015. Minisign is an alternative +implementation of the same protocol, available for Windows, macOS, and +most GNU/Linux distributions. Minisign is portable, lightweight, and +uses the Ed25519 public-key signature system. -:vytask:`T2108` switched the validation system to prefer minisign over GPG keys. +:vytask:`T2108` switched the validation system to prefer Minisign over GPG keys. -To verify a VyOS image starting off with VyOS 1.3.0-rc6 you can run: +To verify a VyOS image starting with VyOS ``1.3.0-rc6``, run: .. code-block:: none @@ -115,7 +145,7 @@ To verify a VyOS image starting off with VyOS 1.3.0-rc6 you can run: Signature and comment signature verified Trusted comment: timestamp:1727223408 file:vyos-1.5-rolling-202409250007-generic-amd64.iso hashed -During an image upgrade VyOS performas the following command: +During an image upgrade, VyOS runs the following command: .. code-block:: none @@ -123,47 +153,43 @@ During an image upgrade VyOS performas the following command: Signature and comment signature verified Trusted comment: timestamp:1629997936 file:vyos-1.3.0-rc6-amd64.iso -.. note:: Starting with 1.4.3, VyOS uses Minisign exclusively. This should not - be a problem for anyone because Minisign signature verification has already - been present in all releases for years. But if you see an unexpected verification - error, you can solve that by updating your system to 1.4.2 first. - Removed support for GnuPG signatures(:vytask:`T7301`). +.. note:: Starting with version ``1.4.3``, VyOS uses Minisign exclusively. + If you see an unexpected verification error, update your system to version + ``1.4.2`` first. Support for GnuPG signatures has been + removed (:vytask:`T7301`). .. _live_installation: Live installation ================= -.. note:: A permanent VyOS installation always requires to go first - through a live installation. +.. note:: To permanently install VyOS, you must first complete a live + installation. -VyOS, as other GNU+Linux distributions, can be tested without installing -it in your hard drive. **With your downloaded VyOS .iso file you can -create a bootable USB drive that will let you boot into a fully -functional VyOS system**. Once you have tested it, you can either decide -to begin a :ref:`permanent_installation` in your hard drive or power -your system off, remove the USB drive, and leave everything as it was. +You can test VyOS without installing it on your hard drive. **Using your +downloaded VyOS .iso file, you can create a bootable USB drive to boot +into a fully functional VyOS system**. After testing it, you can start a +:ref:`permanent_installation` on your hard drive or power off your system +and remove the USB drive. -If you have a GNU+Linux system, you can create your VyOS bootable USB -stick with with the ``dd`` command: +If you have a GNU/Linux system, you can create a bootable VyOS USB drive using +the ``dd`` command: 1. Open your terminal emulator. - 2. Find out the device name of your USB drive (you can use the ``lsblk`` - command) + 2. Find the device name of your USB drive (use the ``lsblk`` command). - 3. Unmount the USB drive. Replace X in the example below with the - letter of your device and keep the asterisk (wildcard) to unmount - all partitions. + 3. Unmount the USB drive. Replace ``X`` with your device letter and keep the + asterisk (*) to unmount all partitions. .. code-block:: none $ umount /dev/sdX* - 4. Write the image (your VyOS .iso file) to the USB drive. - Note that here you want to use the device name (e.g. /dev/sdb), not - the partition name (e.g. /dev/sdb1). + 1. Write the image (your VyOS .iso file) to the USB drive. Use the device + name (for example, ``/dev/sdb``), not the partition name + (for example, ``/dev/sdb1``). **Warning**: This will destroy all data on the USB drive! @@ -171,25 +197,24 @@ stick with with the ``dd`` command: # dd if=/path/to/vyos.iso of=/dev/sdX bs=8M; sync - 5. Wait until you get the outcome (bytes copied). Be patient, in some - computers it might take more than one minute. + 1. Wait for the operation to complete (bytes copied). On some systems, this + may take more than one minute. - 6. Once ``dd`` has finished, pull the USB drive out and plug it into + 2. Once ``dd`` has finished, pull the USB drive out and plug it into the powered-off computer where you want to install (or test) VyOS. - 7. Power the computer on, making sure it boots from the USB drive (you - might need to select booting device or change booting settings). + 3. Power on the computer and ensure it boots from the USB drive + (you may need to select the boot device or change boot settings). - 8. Once VyOS is completely loaded, enter the default credentials - (login: vyos, password: vyos). + 4. When VyOS finishes loading, sign in using the default credentials + (login: ``vyos``, password: ``vyos``). -If you find difficulties with this method, prefer to use a GUI program, -or have a different operating system, there are other programs you can -use to create a bootable USB drive, like balenaEtcher_ (for GNU/Linux, -macOS and Windows), Rufus_ (for Windows) and `many others`_. You can -follow their instructions to create a bootable USB drive from an .iso -file. +If you encounter issues with this method, prefer a different operating +system, or want a GUI program, you can use other tools to create a +bootable USB drive, such as balenaEtcher_ (GNU/Linux, macOS, and Windows), +Rufus_ (Windows), and `many others`_. Follow their instructions to create +a bootable USB drive from an ``.iso`` file. .. hint:: The default username and password for the live system is *vyos*. @@ -202,20 +227,20 @@ Permanent installation .. note:: Before a permanent installation, VyOS requires a :ref:`live_installation`. -Unlike general purpose Linux distributions, VyOS uses "image installation" that -mimics the user experience of traditional hardware routers and allows keeping -multiple VyOS versions installed simultaneously. This makes it possible to -switch to a previous version if something breaks or miss-behaves after an image -upgrade. +Unlike general-purpose Linux distributions, VyOS uses "image installation", +which mimics the user experience of traditional hardware routers and allows +you to keep multiple VyOS versions installed simultaneously. This lets you +switch to a previous version if something breaks or misbehaves after an +image upgrade. -Every version is contained in its own squashfs image that is mounted in a union -filesystem together with a directory for mutable data such as configurations, -keys, or custom scripts. +Each version is contained in its own squashfs image mounted in a union +filesystem along with a directory for mutable data such as configurations, +keys, and custom scripts. In order to proceed with a permanent installation: - 1. Log into the VyOS live system (use the default credentials: vyos, - vyos) + 1. Sign in to the VyOS live system using the default credentials + (login: ``vyos``, password: ``vyos``). 2. Run the ``install image`` command and follow the wizard: @@ -255,8 +280,7 @@ In order to proceed with a permanent installation: The image installed successfully; please reboot now. - 3. After the installation is completed, remove the live USB stick or - CD. + 3. After installation completes, remove the live USB drive or CD. 4. Reboot the system. @@ -271,18 +295,18 @@ In order to proceed with a permanent installation: PXE Boot ======== -VyOS can also be installed through PXE. This is a more complex -installation method that allows deploying VyOS through the network. +You can also install VyOS using PXE, a more complex installation method that +allows you to deploy VyOS over the network. **Requirements** -* Clients (where VyOS is to be installed) with a PXE-enabled NIC +* A machine (client) with a PXE-enabled NIC. * :ref:`dhcp-server` * :ref:`tftp-server` -* Webserver (HTTP) - optional, but we will use it to speed up installation -* VyOS ISO image to be installed (do not use images prior to VyOS 1.2.3) -* Files *pxelinux.0* and *ldlinux.c32* `from the Syslinux distribution - <https://kernel.org/pub/linux/utils/boot/syslinux/>`_ +* Webserver (HTTP). Optional, but speeds up installation. +* VyOS ISO image (do not use images prior to VyOS ``1.2.3``). +* Files *pxelinux.0* and *ldlinux.c32* from the + `Syslinux distribution <https://kernel.org/pub/linux/utils/boot/syslinux/>`_. Configuration ------------- @@ -293,8 +317,9 @@ Step 1: DHCP Configure a DHCP server to provide the client with: * An IP address -* The TFTP server address (DHCP option 66). Sometimes referred as *boot server* -* The *bootfile name* (DHCP option 67), which is *pxelinux.0* +* The TFTP server address (DHCP option 66), sometimes referred to as the + *boot server* +* The *bootfile name* (DHCP option 67): *pxelinux.0* In this example we configured an existent VyOS as the DHCP server: @@ -321,22 +346,19 @@ In this example we configured an existent VyOS as the DHCP server: Step 2: TFTP ^^^^^^^^^^^^ -Configure a TFTP server so that it serves the following: +Configure a TFTP server to serve the following: * The *pxelinux.0* file from the Syslinux distribution * The *ldlinux.c32* file from the Syslinux distribution -* The kernel of the VyOS software you want to deploy. That is the - *vmlinuz* file inside the */live* directory of the extracted - contents from the ISO file. -* The initial ramdisk of the VyOS ISO you want to deploy. That is the - *initrd.img* file inside the */live* directory of the extracted - contents from the ISO file. Do not use an empty (0 bytes) initrd.img - file you might find, the correct file may have a longer name. -* A directory named pxelinux.cfg which must contain the configuration - file. We will use the configuration_ file shown below, which we named - default_. - -In the example we configured our existent VyOS as the TFTP server too: +* The VyOS kernel you want to deploy (*vmlinuz* file from the + */live* directory in the extracted ISO file) +* The VyOS initial ramdisk (*initrd.img* file from the */live* directory + in the extracted ISO file). Do not use an empty (0 bytes) initrd.img + file; the correct file may have a longer name. +* A directory named *pxelinux.cfg* containing the configuration file. + By default, the VyOS configuration file is named default_. + +In the example you configured your existent VyOS as the TFTP server too: .. code-block:: none @@ -378,41 +400,34 @@ Example of simple (no menu) configuration file: Step 3: HTTP ^^^^^^^^^^^^ -We also need to provide the *filesystem.squashfs* file. That is a heavy -file and TFTP is slow, so you could send it through HTTP to speed up the -transfer. That is how it is done in our example, you can find that in -the configuration file above. +You also need to provide the *filesystem.squashfs* file. Because this is a +large file and TFTP is slow, you can send it through HTTP to speed up the +transfer. In our example, we do this—see the configuration file above. -**First** run a web server - you can use a simple one like -`Python's SimpleHTTPServer`_ and start serving the `filesystem.squashfs` -file. The file can be found inside the `/live` directory of the -extracted contents of the ISO file. +1. Start a web server. You can use one like + `Python's SimpleHTTPServer`_ to serve the `filesystem.squashfs` file. + The file is in the `/live` directory of the extracted ISO file. -**Second**, edit the configuration file of the :ref:`install_from_tftp` -so that it shows the correct URL at -``fetch=http://<address_of_your_HTTP_server>/filesystem.squashfs``. +2. Edit the :ref:`install_from_tftp` configuration file to show the correct + URL: ``fetch=http://<address_of_your_HTTP_server>/filesystem.squashfs``. -.. note:: Do not change the name of the *filesystem.squashfs* file. If - you are working with different versions, you can create different - directories instead. +.. note:: Do not rename the *filesystem.squashfs* file. If you're working with + different versions, create different directories instead. -And **third**, restart the TFTP service. If you are using VyOS as your -TFTP Server, you can restart the service with -``sudo service tftpd-hpa restart``. +3. restart the TFTP service. If you're using VyOS as your TFTP server, restart + the service with ``sudo service tftpd-hpa restart``. -.. note:: Make sure the available directories and files in both TFTP - and HTTP server have the right permissions to be accessed from the - booting clients. +.. note:: Ensure the directories and files on both the TFTP and HTTP servers + have the correct permissions for the booting clients to access them. Client Boot ----------- -Finally, turn on your PXE-enabled client or clients. They will -automatically get an IP address from the DHCP server and start booting -into VyOS live from the files automatically taken from the TFTP and HTTP -servers. +Finally, power on your PXE-enabled clients. They will automatically receive an +IP address from the DHCP server and boot into VyOS live using files from the +TFTP and HTTP servers. Once finished you will be able to proceed with the ``install image`` command as in a regular VyOS installation. @@ -427,13 +442,13 @@ This is a list of known issues that can arise during installation. Black screen on install ----------------------- -GRUB attempts to redirect all output to a serial port for ease of installation -on headless hosts. This appears to cause an hard lockup on some hardware that -lacks a serial port, with the result being a black screen after selecting the +GRUB redirects all output to a serial port to facilitate installation +on headless hosts. On some hardware that lacks a serial port, this causes +a hard lockup and displays a black screen after you select the `Live system` option from the installation image. -The workaround is to type `e` when the boot menu appears and edit the GRUB boot -options. Specifically, remove the: +The workaround is to press `e` when the boot menu appears and edit the +GRUB boot options. Specifically, remove the: `console=ttyS0,115200` diff --git a/docs/installation/secure-boot.rst b/docs/installation/secure-boot.rst index b6685039..1dd6713b 100644 --- a/docs/installation/secure-boot.rst +++ b/docs/installation/secure-boot.rst @@ -1,12 +1,14 @@ +:lastproofread: 2026-01-26 + .. _secure_boot: ########### Secure Boot ########### -Initial UEFI secure boot support is available (:vytask:`T861`). We utilize -``shim`` from Debian 12 (Bookworm) which is properly signed by the UEFI -SecureBoot key from Microsoft. +Initial UEFI Secure Boot support is available (:vytask:`T861`). VyOS uses +``shim`` from Debian 12 (Bookworm), which is properly signed by the UEFI +Secure Boot key from Microsoft. .. note:: There is yet no signed version of ``shim`` for VyOS, thus we provide no signed image for secure boot yet. If you are interested in @@ -39,13 +41,13 @@ Installation As our version of ``shim`` is not signed by Microsoft we need to enroll the previously generated :abbr:`MOK (Machine Owner Key)` to the system. -First of all you will need to disable UEFI secure boot for the installation. +First, disable UEFI Secure Boot for the installation. .. figure:: /_static/images/uefi_secureboot_01.png :alt: Disable UEFI secure boot -Proceed with the regular VyOS :ref:`installation <permanent_installation>` on -your system, but instead of the final ``reboot`` we will enroll the +Proceed with the standard VyOS :ref:`installation <permanent_installation>` on +your system. Instead of the final ``reboot`` command, enroll the :abbr:`MOK (Machine Owner Key)`. .. code-block:: none @@ -54,8 +56,8 @@ your system, but instead of the final ``reboot`` we will enroll the input password: input password again: -The requested ``input password`` can be user chosen and is only needed after -rebooting the system into MOK Manager to permanently install the keys. +You can set the ``input password`` to any value you choose. You'll need this +password after reboot when MOK Manager launches to permanently install the keys. With the next reboot, MOK Manager will automatically launch @@ -67,7 +69,7 @@ Select ``Enroll MOK`` .. figure:: /_static/images/uefi_secureboot_03.png :alt: Disable UEFI secure boot -You can now view the key to be installed and ``continue`` with the Key installation +You can now view the key to be installed and continue with key installation. .. figure:: /_static/images/uefi_secureboot_04.png :alt: Disable UEFI secure boot @@ -75,18 +77,18 @@ You can now view the key to be installed and ``continue`` with the Key installat .. figure:: /_static/images/uefi_secureboot_05.png :alt: Disable UEFI secure boot -Now you will need the password previously defined +Now you need to enter the password you defined previously. .. figure:: /_static/images/uefi_secureboot_06.png :alt: Disable UEFI secure boot -Now reboot and re-enable UEFI secure boot. +Now reboot and re-enable UEFI Secure Boot. .. figure:: /_static/images/uefi_secureboot_07.png :alt: Disable UEFI secure boot -VyOS will now launch in UEFI secure boot mode. This can be double-checked by running -either one of the commands: +VyOS will now launch in UEFI Secure Boot mode. You can verify this by running +one of the following commands: .. code-block:: none @@ -126,18 +128,17 @@ either one of the commands: Image Update ************ -.. note:: There is yet no signed version of ``shim`` for VyOS, thus we - provide no signed image for secure boot yet. If you are interested in - secure boot you can build an image on your own. +.. note:: Currently, there is no signed version of ``shim`` for VyOS. If you + want Secure Boot support, you can build a custom image with your own keys. -During image installation you will install your :abbr:`MOK (Machine Owner -Key)` into the UEFI variables to add trust to this key. After enabling -secure boot support in UEFI again, you can only boot into your signed image. +During image installation, you install your :abbr:`MOK (Machine Owner Key)` +into the UEFI variables to add trust to this key. After you re-enable Secure +Boot in UEFI, you can only boot into your signed image. -It is no longer possible to boot into a CI generated rolling release as those -are currently not signed by a trusted party (:vytask:`T861` work in progress). -This also means that you need to sign all your successor builds you build on -your own with the exact same key, otherwise you will see: +You can no longer boot into a CI-generated rolling release because those +are not signed by a trusted party (:vytask:`T861` work in progress). This +also means you must sign all successor builds with the same key; otherwise, +you'll see this error: .. code-block:: none @@ -148,37 +149,44 @@ your own with the exact same key, otherwise you will see: Linux Kernel ************ -In order to add an additional layer of security that can already be used in nonesecure -boot images already is ephem,eral key signing of the Linux Kernel modules. +In addition to Secure Boot support, VyOS uses ephemeral key signing of Linux +Kernel modules for an extra security layer in both Secure and non-Secure boot +images. + +.. stop_vyoslinter https://patchwork.kernel.org/project/linux-integrity/patch/20210218220011.67625-5-nayna@linux.ibm.com/ -Whenever our CI system builds a Kernel package and the required 3rd party modules, -we will generate a temporary (ephemeral) public/private key-pair that's used for signing the -modules. The public key portion is embedded into the Kernel binary to verify the loaded -modules. +.. start_vyoslinter + +When the CI system builds a Kernel package and required third-party modules, +it generates a temporary (ephemeral) key pair for signing the modules. The +public key is embedded in the Kernel binary to verify loaded modules. -After the Kernel CI build completes, the generated key is discarded - meaning we can no londer -sign additional modules with out key. Our Kernel configuration also contains the option -``CONFIG_MODULE_SIG_FORCE=y`` which means that we enforce all modules to be signed. If you -try to load an unsigned module, it will be rejected with the following error: +After the Kernel CI build completes, the generated key is discarded, meaning +we can no longer sign additional modules with that key. The Kernel configuration +also includes the option ``CONFIG_MODULE_SIG_FORCE=y``, which enforces signature +verification for all modules. If you try to load an unsigned module, you'll +get this error: -``insmod: ERROR: could not insert module malicious.ko: Key was rejected by service`` +``insmod: ERROR: could not insert module malicious.ko: Key was rejected by +service`` -Thos we close the door to load any malicious stuff after the image was assembled into the -Kernel as module. You can of course disable this behavior on custom builds. +This prevents loading any malicious code after the image is assembled into the +Kernel as a module. You can disable this behavior on custom builds if needed. ************ Troubleshoot ************ -In most of the cases if something goes wrong you will see the following error message -during system boot: +In most cases, if something goes wrong during system boot, you'll see this +error message: .. code-block:: none error: bad shim signature error: you need to load the kernel first -This means that the Machine Owner Key used to sign the Kernel is not trusted by your -UEFI. You need to install the MOK via ``install mok`` as stated above. +This error means the Machine Owner Key used to sign the Kernel is not trusted +by your UEFI. Install the MOK using the ``install mok`` command as described +above. diff --git a/docs/installation/update.rst b/docs/installation/update.rst index d4fcf11c..967f494b 100644 --- a/docs/installation/update.rst +++ b/docs/installation/update.rst @@ -1,45 +1,44 @@ +:lastproofread: 2026-01-26 + .. _update_vyos: Update VyOS =========== -New system images can be added using the :opcmd:`add system image` -command. The command will extract the chosen image and will prompt you -to use the current system configuration and SSH security keys, allowing -for the new image to boot using the current configuration. +New system images can be added using the :opcmd:`add system image` command. +This command extracts the image and prompts you to use the current system +configuration and SSH security keys, allowing the new image to boot with your +current configuration. .. note:: Only LTS releases are PGP-signed. .. opcmd:: add system image <url | path> | [latest] [vrf name] [username user [password pass]] - Use this command to install a new system image. You can reach the - image from the web (``http://``, ``https://``) or from your local system, - e.g. /tmp/vyos-1.2.3-amd64.iso. + Use this command to install a new system image. You can retrieve the + image from the web (``http://``, ``https://``) or from your local system. + For example: /tmp/vyos-1.2.3-amd64.iso. - The `add system image` command also supports installing new versions - of VyOS through an optional given VRF. Also if URL in question requires - authentication, you can specify an optional username and password via - the commandline which will be passed as "Basic-Auth" to the server. + The ``add system image`` command also supports installing new VyOS versions + through an optional VRF. If the URL requires authentication, you can specify + an optional username and password on the command line, which will be passed + as "Basic-Auth" to the server. -If there is not enough **free disk space available**, the installation -will be canceled. To delete images use the :opcmd:`delete system image` -command. +If there isn't enough free disk space, the installation will be canceled. +To delete images, use the :opcmd:`delete system image` command. -VyOS configuration is associated to each image, and **each image has a -unique copy of its configuration**. This is different than a traditional -network router where the configuration is shared across all images. +VyOS associates configuration with each image, and each image has its own +unique configuration copy. This differs from traditional network routers where +the configuration is shared across all images. -.. note:: If you have any personal files, like some scripts you created, - and you don't want them to be lost during the upgrade, make sure - those files are stored in ``/config`` as this directory is always copied - to newer installed images. +.. note:: If you have personal files such as scripts that you want to preserve + during the upgrade, store them in ``/config`` since this directory is always + copied to newly installed images. You can access files from a previous installation and copy them to your -current image if they were located in the ``/config`` directory. This -can be done using the :opcmd:`copy` command. So, for instance, in order -to copy ``/config/config.boot`` from VyOS 1.2.1 image, you would use the -following command: +current image if they were stored in the ``/config`` directory. Use the +:opcmd:`copy` command to do this. For example, to copy ``/config/config.boot`` +from the VyOS ``1.2.1`` image, run: .. code:: @@ -78,17 +77,20 @@ You can use ``latest`` option. It loads the latest available Rolling release. vyos@vyos:~$ add system image latest -.. note:: To use the `latest` option the "system update-check url" must be configured - appropriately for the installed release. +.. stop_vyoslinter +.. note:: To use the ``latest`` option, "system update-check url" must be + configured appropriately for your installed release. For updates to the Rolling Release for AMD64, the following URL may be used: https://raw.githubusercontent.com/vyos/vyos-nightly-build/refs/heads/current/version.json -.. hint:: The most up-do-date Rolling Release for AMD64 can be accessed using - the following URL from a web browser: - +.. start_vyoslinter + +.. hint:: You can access the latest Rolling Release for AMD64 from a web + browser at: + https://vyos.net/get/nightly-builds/ -After reboot you might want to verify the version you are running with -the :opcmd:`show version` command. +After rebooting, verify the version you're running using the +:opcmd:`show version` command. |