====== System upgrade ======

This page explains system upgrades on KerOS >= v.4 and also:
  * Configuration management (sysupgrade).
  * Hotfix packages management during upgrades.

===== Introduction =====

==== Software upgrade files ====

The firmware is released in two formats: __KerOS__ and __Liveburner__.
These have very different behavior, so please use the appropriate file before updating, see the difference in [[wiki:keros_custo:upgrade#upgrade_process| upgrade process]] section.

==== Major firmware upgrades ====

=== From KerOS version 4.3.3 to KerOS version 5.X ===

To upgrade the system from KerOS version 4.3.3 to KerOS version 5.X the use of a liveburner is mandatory. 
Two possibilities are available:

  * Upgrade with a custom liveburner. It allows to keep some elements like gateway configuration. To use a custom liveburner, please refer to the dedicated page: [[..:keros_custo:upgrade_major_version|Major version upgrade with a custom liveburner]]
  * Upgrade with a regular liveburner (erasing the whole partition to reinstall the firmware). Use the liveburner provided in the [[..:resources:resources#keros_firmware_and_toolchain|Wirnet gateways resources page]] and the upgrade process below.


=== From KerOS version 3.x to KerOS version 4.1 ===

The upgrade from KerOS version 3.x to KerOS version 4.1 directly is not recommended by Kerlink. To do so, it must be done in 2 steps:
  - Upgrade to KerOS version 4.0 using a liveburner
  - Upgrade from KerOS version 4.0 to KerOS version 4.1 using a KerOS package


=== From KerOS version 3.x to KerOS version 4.0 ===

To upgrade the system from KerOS version 3.x to KerOS version 4.0 the use of a liveburner is mandatory. 
Two possibilities are available:

  * Upgrade with a custom liveburner. It allows to keep some elements like gateway configuration. To build a custom liveburner, please refer to the dedicated page: [[wiki:keros_custo:upgrade_keros3_to_4|Upgrade from KerOS version 3.x to 4.0]]
  * Upgrade with a regular liveburner (erasing the whole partition to reinstall the firmware). Use the liveburner provided in the [[wiki:keros_custo:upgrade_keros3_to_4|Upgrade from KerOS version 3.x to 4.0]] page and the upgrade process below.

===== Upgrade process =====

==== Upgrade using a KerOS package ====

Upgrade using a KerOS package (i.e. ''keros_4.X.Y_klk-lpbs-signed.ipk'' file) could be done only with the same major version. \\
Example: \\
  * Upgrade from Keros 4.X.X to KerOS 4.Y.Y is possible with a KerOS package (same major version)
  * Upgrade from Keros 4.X.X to KerOS 5.X.X is not possible with a KerOS package (major version is different)

The upgrade will install the new KerOS firmware with some consequences on the data:
  * User partition files will be preserved.
  * Passwords will be preserved.
  * The stock restore version will not be updated.
  * RootFS modifications will NOT be kept except files indicated in [[#configuration_management_sysupgrade|sysupgrade]] configuration files

The upgrade process itself is the following sequence:
  - Backup files indicated in configuration (system files and software/customer defined files).
  - Remove hotfix packages.
  - Upgrade the system itself.
  - Restore sysupgrade files => will override new firmware files!!

To upgrade your system, follow the software update process. Information [[wiki:keros_custo:sw_updates|here]].

==== Upgrade using a liveburner package ====

The upgrade will install the new KerOS firmware with some consequences on the data:

  * Updates stock restore version with liveburner package version.
  * Resets the default password on your gateway.
  * Erases the whole partition to reinstall the firmware.

To upgrade your system, follow the software update process. Information [[wiki:keros_custo:sw_updates|here]].

===== Configuration management (sysupgrade) =====

Sysupgrade process is available in case of an upgrade using a ''kerOS'' package or using a ''liveburner'' package.\\
During an upgrade, the only way to keep system files (network configuration, password...) is to make a backup during the upgrade. This is done by the **sysupgrade** mechanism.

This mecanism is divided in 2 elements:
  * **''/etc/sysupgrade.conf''**: Contains the system (KerOS) elements to backup/restore in case of upgrade.
  * **''/etc/sysupgrade.d/''**: a directory with ''.conf'' files where additional elements to backup/restore can be added (i.e. by additional packages).

By default, the system has a predefined list of configuration files to preserve:


++++
File to download - /etc/sysupgrade.conf |
<code conf sysupgrade.conf>
## This file contains files and directories that should
## be preserved during an upgrade.

# /etc/example.conf

# System Configuration files
#############

/etc/profile
/etc/strongswan.conf
/etc/timestamp
/etc/network/
/etc/bnm/bnm.conf
/etc/hosts
/etc/kgpsd.conf
/etc/default/
/etc/firewall.d/
/etc/ssh/
/etc/ipsec.secrets
/etc/ipsec.conf
/etc/monit.d/
/etc/strongswan.d/
/etc/cron/
/etc/shadow
/etc/udhcpc.d/50default
/etc/ntp.conf

# System persistent data
############

/var/log/
</code>
++++

If a specific software also needs to keep configurations between upgrades, it is possible to add a ''.conf'' file in the ''/etc/sysupgrade.d'' directory:

++++
File to download - /etc/sysupgrade.d/myapp.conf |
<code conf myapp.conf>
## This file contains files and directories that should
## be preserved during an upgrade.

/etc/myapp.conf
</code>
++++

A specific reporting file is generated when an upgrade is done: **''/user/.sysupgrade.log''**.

===== Hotfix packages management =====

Hotfix packages are only available for a specific version of the firmware. So in case of upgrade, they will be automatically removed.
More information on hotfix package [[wiki:keros_custo:package_management#hotfix_packages|here]].