Merge pull request #330 from currite/backport-image-mgmt

image management: backport add rollback subsection and last changes

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.