summaryrefslogtreecommitdiff
diff options
context:
space:
mode:
-rw-r--r--docs/image-mgmt.rst225
1 files 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 <url | path> [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.