Skip to main content
Version: 5.0.0

Migrations

This is a high level guide to how to handle migrations between major versions with the official packages. For more technical details, see saunafs-migrations 7

Downgrade scripts​

The official packages include saunafs-common, which includes helper scripts to help with downgrades/upgrades. They can be found /usr/lib/saunafs/package-scripts/migrations. This package is automatically installed when any other SaunaFS package is installed. These scripts handle the downgrade/upgrade automatically between the major versions. In particular, it will automatically install old/newer packages using apt and then apply the correct migrations. Please read the README located in the specific versions to understand the specifics and run <script> --help for more details.

5.0.0​

Upgrade to 5.0.0​

No action should be needed. Simply updating to the latest versions should work fine. However, note that newer chunkservers will not work with older metadata servers.

Downgrade from 5.0.0​

You will find the main downgrade script in /usr/lib/saunafs/migration-scripts/5.0.0/downgrade-master.sh. This script is responsible for orchestrating the downgrade process for master, metalogger, and uraft components.

It performs the following steps:

  1. Service Control: It intelligently stops the relevant service. If saunafs-uraft is installed and active, it will stop saunafs-uraft. Otherwise, it will stop saunafs-master (if installed and active). It also stops saunafs-metalogger (if installed and active).
  2. Data Migration: It calls a separate data migration script located at /usr/lib/saunafs/migrations/5.0.0/rollback/downgrade-changelogs.sh. This script handles the necessary data fixes and migrations. It also creates a backup in /usr/lib/
  3. Package Downgrade: It downgrades the saunafs-master, saunafs-metalogger, and saunafs-uraft packages (if installed) to version 4.11.0-1 using apt.
  4. Service Restart: Finally, it restarts the services that were stopped in step 1.

Logging for the data migration process is handled by the migration script itself and is saved to /var/log/saunafs/downgrade/changelog.log.

Instructions​

  1. First, downgrade your chunkservers manually with apt upgrade saunafs-chunkserver=4.11.0-2. This is not done by the script above and must be done by hand. This is needed because newer chunkservers do not work with 4.11.0 or earlier.
  2. Execute bash /usr/lib/saunafs/migration-scripts/5.0.0/downgrade-master.sh --help and read the help thoroughly, it contains important information!
  3. Execute sudo bash /usr/lib/saunafs/migration-scripts/5.0.0/downgrade-master.sh first on the master, and then shadow(s). If you are on uraft, note that older shadows (followers) cannot connect to newer masters (leaders), so you need to downgrade all or most of them before the cluster can start.
  4. After everything works, you may delete the backup in /var/lib/.