From 158506121deeb9b183b9258a34538dc38c4499ee Mon Sep 17 00:00:00 2001 From: currite Date: Wed, 16 Sep 2020 14:25:07 +0200 Subject: image management: backport add rollback subsection and last changes --- docs/image-mgmt.rst | 225 +++++++++++++++++++++++++++++++++------------------- 1 file changed, 145 insertions(+), 80 deletions(-) diff --git a/docs/image-mgmt.rst b/docs/image-mgmt.rst index ecef997d..143d02b2 100644 --- a/docs/image-mgmt.rst +++ b/docs/image-mgmt.rst @@ -1,7 +1,8 @@ .. _image-mgmt: -System Image Management -======================= +################ +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. @@ -17,112 +18,176 @@ The directory structure of the boot device: 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. +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. 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. +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. -The image can be selected manually at boot if needed, but the system will -otherwise boot the image configured to be the default. +.. opcmd:: show system image -The default boot image can be set using the :code:`set system image -default-boot` command in operational mode. + List all available system images which can be bootet on the current system. -A list of available images can be shown using the :code:`show system image` -command in operational mode. + .. code-block:: none -.. code-block:: none + vyos@vyos:~$ show system image + The system currently has the following image(s) installed: - vyos@vyos:~$ show system image - The system currently has the following image(s) installed: + 1: 1.2.0-rolling+201810021347 (default boot) + 2: 1.2.0-rolling+201810021217 + 3: 1.2.0-rolling+201809252218 - 1: 1.2.0-rolling+201810021347 (default boot) - 2: 1.2.0-rolling+201810021217 - 3: 1.2.0-rolling+201809280337 - 4: 1.2.0-rolling+201809252218 - 5: 1.2.0-rolling+201809192034 - 6: 1.2.0-rolling+201809191744 - 7: 1.2.0-rolling+201809150337 - 8: 1.2.0-rolling+201809141130 - 9: 1.2.0-rolling+201809140949 - 10: 1.2.0-rolling+201809131722 - vyos@vyos:~$ +.. 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`. + + .. code-block:: none + + vyos@vyos:~$ delete system image + The following image(s) can be deleted: + + 1: 1.3-rolling-201912181733 (default boot) (running image) + 2: 1.3-rolling-201912180242 + 3: 1.2.2 + 4: 1.2.1 + + Select the image to delete: 2 + + Are you sure you want to delete the + "1.3-rolling-201912180242" image? (Yes/No) [No]: y + Deleting the "1.3-rolling-201912180242" image... + Done + +.. opcmd:: show version + + Show current system image version. + + .. code-block:: none + + vyos@vyos:~$ show version + Version: VyOS 1.3-rolling-201912181733 + Built by: autobuild@vyos.net + Built on: Wed 18 Dec 2019 17:33 UTC + Build UUID: bccde2c3-261c-49cc-b421-9b257204e06c + Build Commit ID: f7ce0d8a692f2d + + Architecture: x86_64 + Boot via: installed image + System type: bare metal + + Hardware vendor: VMware, Inc. + Hardware model: VMware Virtual Platform + Hardware S/N: VMware-42 1d 83 b9 fe c1 bd b2-7d 3d 49 db 94 18 f5 c9 + Hardware UUID: b9831d42-c1fe-b2bd-7d3d-49db9418f5c9 + + Copyright: VyOS maintainers and contributors -Images no longer needed can be removed using the :code:`delete system image` -command. .. _update_vyos: Update VyOS ------------ +=========== -Finally, new system images can be added using the :code:`add system image` command. -The add image command will extract the image from the release ISO (either on -the local filesystem or remotely if a URL is provided). The image install -process 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. 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. -.. code-block:: none +.. note:: Only LTS releases are PGP-signed. + +.. opcmd:: add system image [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. + + 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. - vyos@vyos:~$ add system image https://downloads.vyos.io/rolling/current/amd64/vyos-1.2.0-rolling%2B201810030440-amd64.iso - Trying to fetch ISO file from https://downloads.vyos.io/rolling/current/amd64/vyos-1.2.0-rolling%2B201810030440-amd64.iso - % Total % Received % Xferd Average Speed Time Time Time Current - Dload Upload Total Spent Left Speed - 100 338M 100 338M 0 0 3837k 0 0:01:30 0:01:30 --:--:-- 3929k - ISO download succeeded. - Checking for digital signature file... - % Total % Received % Xferd Average Speed Time Time Time Current - Dload Upload Total Spent Left Speed - 0 0 0 0 0 0 0 0 --:--:-- --:--:-- --:--:-- 0 - curl: (22) The requested URL returned error: 404 Not Found +If there is not enough **free disk space available**, the installation +will be canceled. To delete images use the :opcmd:`delete system image` +command. - Unable to fetch digital signature file. - Do you want to continue without signature check? (yes/no) [yes] - Checking MD5 checksums of files on the ISO image...OK. - Done! +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. - What would you like to name this image? [1.2.0-rolling+201810030440]: +.. 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. - OK. This image will be named: 1.2.0-rolling+201810030440 - We do not have enough disk space to install this image! - We need 344880 KB, but we only have 17480 KB. - Exiting... +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: -.. note:: Rolling releases are not GPG signed, only the real release build - will have a proper GPG signature. +.. code:: -.. note:: 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. + copy file 1.2.1://config/config.boot to /tmp/config.boot.1.2.1 -If you need some files from a previous images - take a look inside a -:code:`/live` directory. -After reboot you might want to verify the version you are running with :code:`show version` +Example +""""""" .. code-block:: none - vyos@vyos:~$ show version - Version: VyOS 1.2.0-rolling+201810030440 - Built by: autobuild@vyos.net - Built on: Mon 10 Mar 2018 03:37 UTC - Build UUID: 2ed16684-875c-4a19-8a34-1b03099eed35 - Build Commit ID: 3305dca496d814 + vyos@vyos:~$ add system image https://downloads.vyos.io/rolling/current/amd64/vyos-rolling-latest.iso + Trying to fetch ISO file from https://downloads.vyos.io/rolling/current/amd64/vyos-rolling-latest.iso + % Total % Received % Xferd Average Speed Time Time Time Current + Dload Upload Total Spent Left Speed + 100 338M 100 338M 0 0 3837k 0 0:01:30 0:01:30 --:--:-- 3929k + ISO download succeeded. + Checking for digital signature file... + % Total % Received % Xferd Average Speed Time Time Time Current + Dload Upload Total Spent Left Speed + 0 0 0 0 0 0 0 0 --:--:-- --:--:-- --:--:-- 0 + curl: (22) The requested URL returned error: 404 Not Found + + Unable to fetch digital signature file. + Do you want to continue without signature check? (yes/no) [yes] + Checking MD5 checksums of files on the ISO image...OK. + Done! + + What would you like to name this image? [vyos-1.3-rolling-201912201452]: + + OK. This image will be named: vyos-1.3-rolling-201912201452 + + +.. hint:: | The most up-do-date Rolling Release for AMD64 can be accessed using the following URL: + | https://downloads.vyos.io/rolling/current/amd64/vyos-rolling-latest.iso + +After reboot you might want to verify the version you are running with +the :opcmd:`show version` command. + + +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: + +.. opcmd:: set system image default-boot [image-name] + + Select the default boot image which will be started on the next boot + of the system. - Architecture: x86_64 - Boot via: installed image - System type: Microsoft Hyper-V guest +Then reboot the system. - Hardware vendor: Microsoft Corporation - Hardware model: Virtual Machine - Hardware S/N: 9705-6585-6578-0429-1204-0427-62 - Hardware UUID: 5260b1ce-4028-4d9c-bc5d-4f8425e5c056 +.. 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. - Copyright: VyOS maintainers and contributors +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. -- cgit v1.2.3