Merge pull request #1048 from kernelkit/fix-downgrade-documentation

Fix downgrade documentation

Author: mattiaswal

doc/boot.md

@@ -63,7 +63,7 @@ bootloader's validation procedure, user configuration is kept to a
 minimum.  Two settings are available:
 
 - **Boot order**: Since Infix maintains two copies of its software image,
-  and as some bootloaders support netbooting, the order in which boot
+  and as some bootloaders support [netbooting][2], the order in which boot
   sources are considered can be configured. To select the active
   source, use [RAUC][]:
 
@@ -352,3 +352,5 @@ If `var` is not available, Infix will still persist `/var/lib` using
 [^1]: See [Upgrading procedures and boot
     order](system.md#upgrade-procedures-and-boot-order) for
     information on upgrading via CLI.
+
+[2]: netboot.md

doc/system.md

@@ -357,25 +357,45 @@ booted from one partition, an `upgrade` will apply to the other
 
 1. Download and unpack the release to install. Make the image *pkg*
    bundle available at some URL[^10]
-2. Assume the unit has booted the `primary` image. Then running the
+2. (Optional) Backup the startup configuration
+3. Assume the unit has booted the `primary` image. Then running the
    `upgrade` command installs a new image on the `secondary`
    partition
-3. As part of a successful upgrade, the boot-order is implictly
+4. As part of a successful upgrade, the boot-order is implictly
    changed to boot the newly installed image
-4. Reboot the unit
-5. The unit now runs the new image. To upgrade the remaining partition
+5. Reboot the unit
+6. The unit now runs the new image. To upgrade the remaining partition
    (`primary`), run the same upgrade command again, and (optionally)
    reboot to verify the upgrade
 
 > [!CAUTION]
-> During boot, the unit may [migrate](#configuration-migration) the
-> startup configuration for any syntax changes.  It is therefore
-> important that you make sure to upgrade the other partition as well
-> after reboot, of course after having verified your setup.
+> During boot (step 5), the unit may
+> [migrate](#configuration-migration) the startup configuration for
+> any syntax changes.  It is therefore important that you make sure to
+> upgrade the other partition as well after reboot, of course after
+> having verified your setup.
 
-The CLI example below shows steps 2-4.
+The CLI example below shows steps 2-5.
 
-Upgrade: here the image *pkg bundle* was made available via TFTP.
+*Backup startup configuration:* It is recommended to backup the
+startup configuration before performing an upgrade. The backup is
+useful if the upgrade fails, and makes a later
+[downgrade](#downgrading-infix) smoother to conduct.
+
+```
+admin@example:/> dir /cfg
+/cfg directory
+backup/             ssl/                startup-config.cfg
+
+admin@example:/> copy /cfg/startup-config.cfg /cfg/v25.01.0-startup-config.cfg
+admin@example:/> dir /cfg
+/cfg directory
+backup/             ssl/                startup-config.cfg           v25.01.0-startup-config.cfg
+
+admin@example:/> 
+```
+
+*Upgrade:* Here the image *pkg bundle* was made available via TFTP.
 
 ```
 admin@example:/> upgrade tftp://198.18.117.1/infix-aarch64-25.03.1.pkg
@@ -393,7 +413,7 @@ Installing `tftp://198.18.117.1/infix-aarch64-25.03.1.pkg` succeeded
 admin@example:/>
 ```
 
-Reboot: The unit will boot on the other partition, with the newly
+*Reboot:* The unit will boot on the other partition, with the newly
 installed image. The `Loading startup-config` step conducts migration
 of startup configuration if applicable.
 
@@ -435,7 +455,7 @@ As shown, the *boot order* has been updated, so that *secondary* is
 now the preferred boot source.
 
 To upgrade the remaining partition (`primary`), run the `upgrade URL`
-command again, and reboot.
+command again, and (optionally) reboot.
 
 ### Configuration Migration
 
@@ -519,8 +539,25 @@ with the unit in *failure config*.
 
 *Find the backup configuration file:*
 
-Assume you have a backup startup config for the version to downgrade
-to (here Infix v25.01.0, config `version 1.4`).
+Assume you have a backup startup config for the Infix version to
+downgrade to (here Infix v25.01.0, config `version 1.4`).
+
+The preferred approach is to use a startup configuration backed up
+when running Infix v25.01.0 on the unit. See the section on [upgrading
+Infix](#upgrading-infix) above for more information. In the example
+below, there is a backup file available named
+*v25.01.0-startup-config.cfg* 
+
+```
+admin@example:/> dir /cfg
+/cfg directory
+backup/             ssl/                startup-config.cfg           v25.01.0-startup-config.cfg
+
+admin@example:/> 
+```
+
+The alternative is to use a startup config implicitly backed up by the
+system as part of [configuration migration](#configuration-migration).
 
 ```
 admin@example:/> dir /cfg/backup/
@@ -530,6 +567,23 @@ startup-config-1.4.cfg
 admin@example:/>
 ```
 
+> [!CAUTION] Using a backup configuration file stored when the unit
+> was running the old version (e.g., v25.01.0-startup-config.cfg) is
+> preferred. Although backup files stored due to configuration
+> migration (e.g., startup-config-1.4.cfg) usually works too if the
+> configuration file version (`1.4`) matches, there are
+> situations when the system may fail to apply it as described below.
+
+The *configuration file version* (`1.4`) is only incremented when
+changes in YANG configuration syntax mandates it to handle
+*upgrading*.  Say the next Infix version includes a new feature
+setting, it can still have version `1.4`, as upgrading to it would not
+need migration. If a user then enables the new feature setting, the
+new configuration will no longer be compatible with the previous *Infix
+version*. A downgrade after enabling new features risks ending up with
+the unit in *failure config*. 
+
+
 *Use `upgrade` command to downgrade:*
 
 ```
@@ -548,6 +602,19 @@ admin@example:/>
 
 *Apply the backup configuration file:*
 
+It is recommended to use a backup configuration file for the Infix version to
+downgrade to, if there is one available.
+
+```
+admin@example:/> copy /cfg/v25.01.0-startup-config.cfg /cfg/startup-config.cfg
+Overwrite existing file /cfg/startup-config.cfg (y/N)? y
+admin@example:/>
+```
+
+An alternative is to use a backup file stored when the system
+conducted a [configuration migration](#configuration-migration). See
+the *caution* note above.
+
 ```
 admin@example:/> copy /cfg/backup/startup-config-1.4.cfg /cfg/startup-config.cfg
 Overwrite existing file /cfg/startup-config.cfg (y/N)? y
@@ -556,8 +623,7 @@ admin@example:/>
 
 *Reboot:*
 
-The unit will come up with the applied backup configuration instead of
-failure config.
+The unit will come up with the applied backup configuration. 
 
 ```
 admin@example:/> reboot
@@ -575,6 +641,9 @@ admin@example:/> reboot
 Infix -- a Network Operating System v25.01.0 (ttyS0)
 example login:
 ```
+> [!NOTE]
+> If the unit despite these measures ends up in *failure config*, see
+> the next section for more information on how to recover.
 
 #### Downgrading without applying a backup startup configuration
 
@@ -680,11 +749,13 @@ Continued configuration is done as with any unit after factory reset.
 [3]: https://www.rfc-editor.org/rfc/rfc8341
 [4]: https://chrony-project.org/doc/4.6.1/chronyc.html
 [5]: https://github.com/kernelkit/infix/blob/main/src/confd/yang/confd/infix-system-software.yang
-[6]: boot.md#system-configuration
+[6]: netboot.md
 [7]: introduction.md#system-boot
 [8]: management.md#console-port
 [^9]: In failure config, Infix puts all Ethernet ports as individual
     interfaces. With direct access, one can connect with e.g., SSH,
     using link local IPv6 addresses. This as an alternative to
     connecting via a console port.
 [^10]: Set up an FTP/TFTP/SFTP or HTTP/HTTPS server on the same LAN. 
+
+[11]: scripting.md#-backup-configuration-using-sysrepocfg-and-scp