diff --git a/doc/cli/upgrade.md b/doc/cli/upgrade.md index 21ecce6a..10cdf5c1 100644 --- a/doc/cli/upgrade.md +++ b/doc/cli/upgrade.md @@ -38,12 +38,9 @@ The secondary partition (`rootfs.1`) has now been upgraded and will be used as the *active* partition on the next boot. Leaving the primary partition, with the version we are currently running, intact in case of trouble. -See [upgrading procedures and boot order][2] for more information on - upgrading. +See [Upgrade & Boot Order](../upgrade.md) for more information on upgrading. [^1]: It is not possible to upgrade the partition we booted from. Thankfully the underlying "rauc" subsystem keeps track of this. Hence, to upgrade both partitions you must reboot to the new version (to verify it works) and then repeat the same command. - -[2]: ../system.md#upgrade-procedures-and-boot-order diff --git a/doc/management.md b/doc/management.md index 47faff6a..fafb3a32 100644 --- a/doc/management.md +++ b/doc/management.md @@ -194,10 +194,6 @@ admin@example:/config/web/restconf/> no enabled admin@example:/config/web/restconf/> ``` -# System Upgrade +## System Upgrade -See [upgrading procedures and boot order][1] for information on - upgrading. - - -[1]: system.md#upgrade-procedures-and-boot-order +See [Upgrade & Boot Order](upgrade.md) for information on upgrading. diff --git a/doc/system.md b/doc/system.md index 1f61e15e..02d9b644 100644 --- a/doc/system.md +++ b/doc/system.md @@ -323,439 +323,7 @@ reference ID, stratum, time offsets, frequency, and root delay. > The system uses `chronyd` Network Time Protocol (NTP) daemon. The > output shown here is best explained in the [Chrony documentation][4]. -## Upgrade procedures and boot order - -For resilience purposes, Infix maintains two software -images referred to as the _primary_ and _secondary_ partition image. -In addition, some bootloaders support [netbooting][6]. - -The _boot order_ defines which image is tried first, and is listed -with the CLI `show software` command. It also shows Infix version -installed per partition, and which image was used when booting (`STATE -booted`). - -``` -admin@example:/> show software -BOOT ORDER -primary secondary net - -NAME STATE VERSION DATE -primary booted v25.01.0 2025-04-25T10:15:00+00:00 -secondary inactive v25.01.0 2025-04-25T10:07:20+00:00 -admin@example:/> -``` - -YANG support for upgrading Infix, inspecting and _modifying_ the -boot-order, is defined in [infix-system-software][5]. - - -### Upgrading Infix - -Upgrading Infix is done one partition at a time. If the system has -booted from one partition, an `upgrade` will apply to the other -(inactive) partition. - -1. Download and unpack the release to install. Make the image *pkg* - bundle available at some URL[^10] -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 -4. As part of a successful upgrade, the boot-order is implictly - changed to boot the newly installed image -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 (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-5. - -*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 -installing - 0% Installing - 0% Determining slot states - 10% Determining slot states done. -... - 98% Copying image to rootfs.1 - 99% Copying image to rootfs.1 - 99% Copying image to rootfs.1 done. - 99% Updating slots done. -100% Installing done. -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 -installed image. The `Loading startup-config` step conducts migration -of startup configuration if applicable. - -``` -admin@example:/> reboot -[ OK ] Stopping Static routing daemon -[ OK ] Stopping Zebra routing daemon -... -[ OK ] Loading startup-config -[ OK ] Verifying self-signed https certificate -[ OK ] Update DNS configuration -[ OK ] Starting Status daemon - -Infix OS — Immutable.Friendly.Secure v25.03.1 (ttyS0) -example login: admin -Password: -.-------. -| . . | Infix OS — Immutable.Friendly.Secure -|-. v .-| https://kernelkit.org -'-'---'-' - -Run the command 'cli' for interactive OAM - -admin@example:~$ cli - -See the 'help' command for an introduction to the system - -admin@example:/> show software -BOOT ORDER -secondary primary net - -NAME STATE VERSION DATE -primary inactive v25.01.0 2025-04-25T10:15:00+00:00 -secondary booted v25.03.1 2025-04-25T10:24:31+00:00 -admin@example:/> -``` - -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 (optionally) reboot. - -### Configuration Migration - -The example above illustrated an upgrade from Infix v25.01.0 to -v25.03.1. Inbetween these versions, YANG configuration definitions -changed slightly (more details given below). - -During boot, Infix inspects the `version` meta information within the -startup configuration file to determine if configuration migration is -needed. In this specific case, the configuration file has version -`1.4` while the booted software expects version `1.5` (the -configuration version numbering differs from the Infix image version -numbering). The startup configuration is migrated to `1.5` -definitions and stored, while a backup previous startup configuration -is stored in directory `/cfg/backup/`. - -``` -admin@example:/> dir /cfg/backup/ -/cfg/backup/ directory -startup-config-1.4.cfg - -admin@example:/> -``` - -The modifications made to the startup configuration can be viewed by -comparing the files from the *shell*. An example is shown below. - -``` -admin@example:/> exit -admin@example:~$ diff /cfg/backup/startup-config-1.4.cfg /cfg/startup-config.cfg ---- /cfg/backup/startup-config-1.4.cfg -+++ /cfg/startup-config.cfg -... -- "public-key-format": "ietf-crypto-types:ssh-public-key-format", -+ "public-key-format": "infix-crypto-types:ssh-public-key-format", -... -- "private-key-format": "ietf-crypto-types:rsa-private-key-format", -+ "private-key-format": "infix-crypto-types:rsa-private-key-format", -... -- "version": "1.4" -+ "version": "1.5" -... -admin@example:~$ -``` - -### Downgrading Infix - -Downgrading to an earlier Infix version is possible, however, -downgrading is **not** guaranteed to work smoothly. In particular, -when the unit boots up with the downgraded version, it may fail to -apply the *startup config*, and instead apply its [failure config][7]. - -We consider two cases: downgrading with or without applying a backup -startup configuration before rebooting. - -In both cases we start out with a unit running Infix v25.03.1, and -wish to downgrade to v25.01.0. - -``` -admin@example:/> show software -BOOT ORDER -primary secondary net - -NAME STATE VERSION DATE -primary booted v25.03.1 2025-04-25T11:36:26+00:00 -secondary inactive v25.03.1 2025-04-25T10:24:31+00:00 -admin@example:/> -``` - -#### Downgrading when applying a backup startup configuration - -This is the recommended approach to downgrade, given that you have a -backup configuration available. The objective is to avoid ending up -with the unit in *failure config*. - -1. Find the backup configuration file. -2. Run `upgrade URL` to install Infix image to downgrade to. -3. Copy backup startup configuration to current startup configuration - (from shell). -4. Reboot. - -*Find the backup configuration file:* - -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/ -/cfg/backup/ directory -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:* - -``` -admin@example:/> upgrade tftp://198.18.117.1/infix-aarch64-25.01.0.pkg -installing - 0% Installing - 0% Determining slot states - 10% Determining slot states done. - ... - 99% Copying image to rootfs.1 done. - 99% Updating slots done. -100% Installing done. -Installing `tftp://198.18.117.1/infix-aarch64-25.01.0.pkg` succeeded -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 -admin@example:/> -``` - -*Reboot:* - -The unit will come up with the applied backup configuration. - -``` -admin@example:/> reboot -[ OK ] Saving system clock to file -[ OK ] Stopping Software update service -[ OK ] Stopping Status daemon -... -[ OK ] Bootstrapping YANG datastore -[ OK ] Starting Configuration daemon -[ OK ] Loading startup-config -[ OK ] Update DNS configuration -[ OK ] Verifying self-signed https certificate -[ OK ] Starting Status daemon - -Infix OS — Immutable.Friendly.Secure 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 - -This procedure assumes you have access to the unit's console port and -its default login credentials[^9]. - -1. Downgrade -2. Reboot -3. Login with unit's default credentials -4. Conduct factory reset -5. (Then go on configure the unit as you wish) - -*Use `upgrade` command to downgrade:* - -``` -admin@example:/> upgrade tftp://198.18.117.1/infix-aarch64-25.01.0.pkg -installing - 0% Installing - 0% Determining slot states - 10% Determining slot states done. - ... - 99% Copying image to rootfs.1 done. - 99% Updating slots done. -100% Installing done. -Installing `tftp://198.18.117.1/infix-aarch64-25.01.0.pkg` succeeded -admin@example:/> -``` - -*Reboot:* - -Conduct a reboot. During boot, the unit fails to apply the existing -startup configuration (config version `1.5` while software expects -version `1.4` or earlier), and instead applies its [failure -config][7]. This is what is seen on the console when this situation -occurs. Note that the login prompt displays `failed` as part of the -*hostname*. - -``` -admin@example:/> reboot -[ OK ] Saving system clock to file -[ OK ] Stopping Software update service -[ OK ] Stopping Status daemon -... -[ OK ] Verifying SSH host keys -[ OK ] Bootstrapping YANG datastore -[ OK ] Starting Configuration daemon -[FAIL] Loading startup-config -[ OK ] Loading failure-config -[ OK ] Verifying self-signed https certificate -[ OK ] Starting Status daemon - -Infix OS — Immutable.Friendly.Secure v25.01.0 (ttyS0) - -ERROR: Corrupt startup-config, system has reverted to default login credentials -failed-00-00-00 login: -``` - -To remedy a situation like this, you can login with the unit's *default -login credentials*, preferrably via a [console port][8]. -The unit's default credentials are typically printed on a sticker on -the unit. - -``` -failed-00-00-00 login: admin -Password: - -Run the command 'cli' for interactive OAM - -admin@failed-00-00-00:~$ -``` - -When it is *safe* from a network operations perspective, you can -conduct a factory reset and reboot. It is recommended to remove the -unit from any production network before doing this, as a factory reset -may enable undesired connectivity between the unit's ports. - -``` -admin@failed-00-00-00:~$ factory -Factory reset device (y/N)? y -factory: scheduled factory reset on next boot. -Reboot now to perform reset, (y/N)? y -[ OK ] Saving system time (UTC) to RTC -[ OK ] Stopping mDNS alias advertiser -... -[ OK ] Starting Configuration daemon -[ OK ] Loading startup-config -[ OK ] Update DNS configuration -[ OK ] Verifying self-signed https certificate -[ OK ] Starting Status daemon -[ OK ] Starting Status daemon - - -Please press Enter to activate this console. - -Infix OS — Immutable.Friendly.Secure v25.01.0 (ttyS0) -example login: -``` - -Continued configuration is done as with any unit after factory reset. - [1]: https://www.rfc-editor.org/rfc/rfc7317 [2]: https://github.com/kernelkit/infix/blob/main/src/confd/yang/infix-system%402024-02-29.yang [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]: 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 diff --git a/doc/upgrade.md b/doc/upgrade.md new file mode 100644 index 00000000..a44e626a --- /dev/null +++ b/doc/upgrade.md @@ -0,0 +1,429 @@ +# Upgrading & Boot Order + +For resilience purposes, Infix maintains two software images referred to +as the _primary_ and _secondary_ partition image. In addition, some +bootloaders support [netbooting][1]. + +The _boot order_ defines which image is tried first, and is listed with +the CLI `show software` command. It also shows Infix version installed +per partition, and which image was used when booting (`STATE booted`). + +``` +admin@example:/> show software +BOOT ORDER +primary secondary net + +NAME STATE VERSION DATE +primary booted v25.01.0 2025-04-25T10:15:00+00:00 +secondary inactive v25.01.0 2025-04-25T10:07:20+00:00 +admin@example:/> +``` + +YANG support for upgrading Infix, inspecting and _modifying_ the +boot-order, is defined in [infix-system-software][2]. + + +## Upgrading + +Upgrading Infix is done one partition at a time. If the system has +booted from one partition, an `upgrade` will apply to the other +(inactive) partition. + +1. Download and unpack the release to install. Make the image *pkg* + bundle available at some URL[^2] +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 +4. As part of a successful upgrade, the boot-order is implictly + changed to boot the newly installed image +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 (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-5. + +*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) a smoother +process. + +``` +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 +installing + 0% Installing + 0% Determining slot states + 10% Determining slot states done. +... + 98% Copying image to rootfs.1 + 99% Copying image to rootfs.1 + 99% Copying image to rootfs.1 done. + 99% Updating slots done. +100% Installing done. +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 +installed image. The `Loading startup-config` step conducts migration +of startup configuration if applicable. + +``` +admin@example:/> reboot +[ OK ] Stopping Static routing daemon +[ OK ] Stopping Zebra routing daemon +... +[ OK ] Loading startup-config +[ OK ] Verifying self-signed https certificate +[ OK ] Update DNS configuration +[ OK ] Starting Status daemon + +Infix OS — Immutable.Friendly.Secure v25.03.1 (ttyS0) +example login: admin +Password: +.-------. +| . . | Infix OS — Immutable.Friendly.Secure +|-. v .-| https://kernelkit.org +'-'---'-' + +Run the command 'cli' for interactive OAM + +admin@example:~$ cli + +See the 'help' command for an introduction to the system + +admin@example:/> show software +BOOT ORDER +secondary primary net + +NAME STATE VERSION DATE +primary inactive v25.01.0 2025-04-25T10:15:00+00:00 +secondary booted v25.03.1 2025-04-25T10:24:31+00:00 +admin@example:/> +``` + +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 (optionally) reboot. + +## Configuration Migration + +The example above illustrated an upgrade from Infix v25.01.0 to +v25.03.1. Inbetween these versions, YANG configuration definitions +changed slightly (more details given below). + +During boot, Infix inspects the `version` meta information within the +startup configuration file to determine if configuration migration is +needed. In this specific case, the configuration file has version +`1.4` while the booted software expects version `1.5` (the +configuration version numbering differs from the Infix image version +numbering). The startup configuration is migrated to `1.5` +definitions and stored, while a backup previous startup configuration +is stored in directory `/cfg/backup/`. + +``` +admin@example:/> dir /cfg/backup/ +/cfg/backup/ directory +startup-config-1.4.cfg + +admin@example:/> +``` + +The modifications made to the startup configuration can be viewed by +comparing the files from the *shell*. An example is shown below. + +``` +admin@example:/> exit +admin@example:~$ diff /cfg/backup/startup-config-1.4.cfg /cfg/startup-config.cfg +--- /cfg/backup/startup-config-1.4.cfg ++++ /cfg/startup-config.cfg +... +- "public-key-format": "ietf-crypto-types:ssh-public-key-format", ++ "public-key-format": "infix-crypto-types:ssh-public-key-format", +... +- "private-key-format": "ietf-crypto-types:rsa-private-key-format", ++ "private-key-format": "infix-crypto-types:rsa-private-key-format", +... +- "version": "1.4" ++ "version": "1.5" +... +admin@example:~$ +``` + +## Downgrading + +Downgrading to an earlier version is possible, however, downgrading is +**not** guaranteed to work smoothly. In particular, when the unit boots +up with the downgraded version, it may fail to apply the *startup +config*, and instead apply its [failure config][3]. + +We consider two cases: downgrading with and without applying a backup +startup configuration before rebooting. + +In both cases we start out with a unit running Infix v25.03.1, and +wish to downgrade to v25.01.0. + +``` +admin@example:/> show software +BOOT ORDER +primary secondary net + +NAME STATE VERSION DATE +primary booted v25.03.1 2025-04-25T11:36:26+00:00 +secondary inactive v25.03.1 2025-04-25T10:24:31+00:00 +admin@example:/> +``` + +### With Backup `startup-config` + +This is the recommended approach to downgrade, given that you have a +backup configuration available. The objective is to avoid ending up +with the unit in *failure config*. + +1. Find the backup configuration file +1. Run `upgrade URL` to install Infix image to downgrade to +1. Copy backup startup configuration to current startup configuration + (from shell) +1. Reboot + +*Find the backup configuration file:* + +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 section [Upgrading](#upgrading) +above for more information. In the following example, 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/ +/cfg/backup/ directory +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:* + +``` +admin@example:/> upgrade tftp://198.18.117.1/infix-aarch64-25.01.0.pkg +installing + 0% Installing + 0% Determining slot states + 10% Determining slot states done. + ... + 99% Copying image to rootfs.1 done. + 99% Updating slots done. +100% Installing done. +Installing `tftp://198.18.117.1/infix-aarch64-25.01.0.pkg` succeeded +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 +admin@example:/> +``` + +*Reboot:* + +The unit will come up with the applied backup configuration. + +``` +admin@example:/> reboot +[ OK ] Saving system clock to file +[ OK ] Stopping Software update service +[ OK ] Stopping Status daemon +... +[ OK ] Bootstrapping YANG datastore +[ OK ] Starting Configuration daemon +[ OK ] Loading startup-config +[ OK ] Update DNS configuration +[ OK ] Verifying self-signed https certificate +[ OK ] Starting Status daemon + +Infix OS — Immutable.Friendly.Secure 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. + +### Without a Backup `startup-config` + +This procedure assumes you have access to the unit's console port and +its default login credentials[^1]. + +1. Downgrade +1. Reboot +1. Login with unit's default credentials +1. Conduct factory reset +1. (Then go on configure the unit as you wish) + +*Use `upgrade` command to downgrade:* + +``` +admin@example:/> upgrade tftp://198.18.117.1/infix-aarch64-25.01.0.pkg +installing + 0% Installing + 0% Determining slot states + 10% Determining slot states done. + ... + 99% Copying image to rootfs.1 done. + 99% Updating slots done. +100% Installing done. +Installing `tftp://198.18.117.1/infix-aarch64-25.01.0.pkg` succeeded +admin@example:/> +``` + +*Reboot:* + +Conduct a reboot. During boot, the unit fails to apply the existing +startup configuration (config version `1.5` while software expects +version `1.4` or earlier), and instead applies its [failure +config][3]. This is what is seen on the console when this situation +occurs. Note that the login prompt displays `failed` as part of the +*hostname*. + +``` +admin@example:/> reboot +[ OK ] Saving system clock to file +[ OK ] Stopping Software update service +[ OK ] Stopping Status daemon +... +[ OK ] Verifying SSH host keys +[ OK ] Bootstrapping YANG datastore +[ OK ] Starting Configuration daemon +[FAIL] Loading startup-config +[ OK ] Loading failure-config +[ OK ] Verifying self-signed https certificate +[ OK ] Starting Status daemon + +Infix OS — Immutable.Friendly.Secure v25.01.0 (ttyS0) + +ERROR: Corrupt startup-config, system has reverted to default login credentials +failed-00-00-00 login: +``` + +To remedy a situation like this, you can login with the unit's *default +login credentials*, preferrably via a [console port][4]. +The unit's default credentials are typically printed on a sticker on +the unit. + +``` +failed-00-00-00 login: admin +Password: + +Run the command 'cli' for interactive OAM + +admin@failed-00-00-00:~$ +``` + +When it is *safe* from a network operations perspective, you can +conduct a factory reset and reboot. It is recommended to remove the +unit from any production network before doing this, as a factory reset +may enable undesired connectivity between the unit's ports. + +``` +admin@failed-00-00-00:~$ factory +Factory reset device (y/N)? y +factory: scheduled factory reset on next boot. +Reboot now to perform reset, (y/N)? y +[ OK ] Saving system time (UTC) to RTC +[ OK ] Stopping mDNS alias advertiser +... +[ OK ] Starting Configuration daemon +[ OK ] Loading startup-config +[ OK ] Update DNS configuration +[ OK ] Verifying self-signed https certificate +[ OK ] Starting Status daemon +[ OK ] Starting Status daemon + + +Please press Enter to activate this console. + +Infix OS — Immutable.Friendly.Secure v25.01.0 (ttyS0) +example login: +``` + +Continued configuration is done as with any unit after factory reset. + +[1]: netboot.md +[2]: https://github.com/kernelkit/infix/blob/main/src/confd/yang/confd/infix-system-software.yang +[3]: introduction.md#system-boot +[4]: management.md#console-port +[5]: scripting.md#-backup-configuration-using-sysrepocfg-and-scp + +[^1]: 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. +[^2]: Set up an FTP/TFTP/SFTP or HTTP/HTTPS server on the same LAN. diff --git a/mkdocs.yml b/mkdocs.yml index 32972402..16a3b7cd 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -17,9 +17,10 @@ exclude_docs: | nav: - About: index.md - Introduction: introduction.md + - Network Configuration: networking.md - System Configuration: system.md - System Management: management.md - - Network Configuration: networking.md + - System Upgrade: upgrade.md - CLI: - Introduction : cli/introduction.md - Configuration: cli/configure.md