r0kk3rz / sfos-upgrade

Scripts for safe and automated upgrading of SailfishOS with logging

sfos-upgrade

Scripts for safe and automated upgrading of SailfishOS with logging

Upgrading SailfishOS at the GUI (per Settings -> SailfishOS updates) provides very little information about its progress / process / success, beyond reading /var/log/systemupdate.log after an upgrade. This can make troubleshooting issues hard.
Furthermore the GUI offers no control which SailfishOS version to upgrade to.

In contrast to that, Jolla's guide how to upgrade SailfishOS at the command line offers full control, while lacking any logs or safety checks.
And it is tedious and error prone to issue multiple, critical commands manually at the command line.

sfos-upgrade performs the steps to upgrade SailfishOS at the command line in an automated manner, while providing extensive safety measures plus full log output at the screen and in a log file.

Safety measures:

• Check free space on the root filesystem.
• Check BTRFS allocation, if the root filesystem uses BTRFS.
• Check battery state (since v1.0).
• Check if upgrading to a correct and available SailfishOS version.
• Check if omitting (i.e., "jumping over") a stop release (since v0.3).
• Automatically unapply all Patches, if Patchmanager is installed.
• Stop systemd services for cron, btrfs-balance-checker etc. (since v2.2).
• Terminate running processes, which may disturb upgrading SailfishOS (since v2.7).
• Disable all OpenRepos' repositories, when upgrading from a SailfishOS version below 1.0.4 (since v0.4).
• Emit a warning when downgrading.
• Prevent downgrades, which would likely break the SailfishOS installation (since v3).

Usage (as root user):

• sfos-upgrade [<version>]
  With a version number provided as parameter, it sets SSU to this version and in release mode before upgrading. This is the regular use case.
  Without a version number, it retrieves the one set for SSU to perform slightly relaxed checks, but does not alter SSU's settings for upgrading.

• sfos-upgrade -h|--help
  Emits a brief usage description.

When an upgrade succeeded, reboot, and do not miss to run post_sfos-upgrade (as root) then!
Not running it will result in an huge upgrade log file (containing many duplicate entries), plus may result (as any SailfishOS upgrade at the command line without tidying efforts afterwards) in RPMs failing to install (with "unmet dependency" / "Fatal error: nothing provides X needed by Y" errors) and annoying notifications from the store-client that an upgrade to the installed version is available.

Logs are originally written to /var/log/systemupdate_*.log-dupes.txt and tidied by tidy_log-dupes (which is called by post_sfos-upgrade) to /var/log/systemupdate_*.log.txt.

Notes:

• Built RPMs are available in the release section and for easy installation on SailfishOS at OpenRepos.
• When upgrading from a long outdated SailfishOS version (e.g., after a "factory reset"), sfos-upgrade eases and speeds up the process of upgrading to a recent SailfishOS release via consecutively installing all "stop releases" on the way.
  Simply run sfos-upgrade <intended version>, reboot, and repeat: it will guide you through all stop releases.
  Omit running post_sfos-upgrade between consecutive SailfishOS upgrades (but do reboot each time!), only run it once after having upgraded to the intended version.
• To ensure that a SailfishOS installation is complete and up to date, use sfos-upgrade "$(version | grep -o '[0-9][0-9]*\.[0-9][0-9]*\.[0-9][0-9]*\.[0-9][0-9]*' | sed -n '1p')"; this will "samegrade" to the installed version, which is as close as one can get to the version --verify lost since SailfishOS 2.2.1 (which only checked for missing or not up-to-date RPMs, while "samegrading" will also install them) without zypper. With it (per pkcon install zypper), a zypper refresh && zypper verify --dry-run -y comes closer to what version --verify did (only checking). While zypper can also be used for up-/down-/same-grading, that is rather a "last resort"-measure than the primary recommendation, hence use sfos-upgrade for that.
• sfos-upgrade supports all public SailfishOS releases and should work fine for upgrading from / to any release (it accepts only version numbers of at least 1.0.0.0 at the command line, but omits this check when called without a parameter after utilising ssu to pre-set a version to upgrade to).
• sfos-upgrade is simply a frontend for ssu re and version --dup, performing a multitude of checks before initiating the upgrade proper, while post_sfos-upgrade carries out the "Final clean up" steps from Jolla's guide and an also necessary pkcon refresh, which some seem to omit when upgrading manually at the command line (often running into aforementioned issues later, then).