Add Image Management chapter

1 files changed, 104 insertions, 0 deletions

diff --git a/docs/ch15-image-mgmt.rst b/docs/ch15-image-mgmt.rst
new file mode 100644
index 00000000..05370d8c
--- /dev/null
+++ b/docs/ch15-image-mgmt.rst
@@ -0,0 +1,104 @@
+System 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.
+
+The directory structure of the boot device:
+
+.. code-block:: sh
+
+  /
+  /boot
+  /boot/grub
+  /boot/1.2.0-rolling+201810021347
+
+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.
+
+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.
+
+The default boot image can be set using the :code:`set system image
+default-boot` command in operational mode.
+
+A list of available images can be shown using the :code:`show system image`
+command in operational mode.
+
+.. code-block:: sh
+
+  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+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:~$
+
+Images no longer needed can be removed using the :code:`delete system image`
+command.
+
+
+Update VyOS Installation
+------------------------
+
+Finally, new system images can be added using the `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.
+
+.. code-block:: sh
+
+  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
+
+  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? [1.2.0-rolling+201810030440]:
+
+  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...
+
+**NOTE #1:** Rolling releases are not GPG signed, only the real release build
+will have a proper GPG signature.
+
+**NOTE #2:** 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.
+
+If you need some files from a previous images - take a look inside a
+:code:`/live` directory.
+