table of contents
| SAUNAFS-MIGRATIONS(7) | SAUNAFS-MIGRATIONS(7) |
NAME¶
saunafs-migrations - Overview of migrating SaunaFS between major versions
SYNOPSIS¶
SaunaFS migration documentation for system administrators.
DESCRIPTION¶
We use semantic versioning to determine whether something is a breaking change. Sometimes, it’s as simple as a command-line interface change. Other times, it involves changes to SaunaFS’s data formats. Most of the time however, upgrades should be smooth.
A key goal is to support smooth downgrades between versions within the same minor bracket (y in x.y.z). When downgrades are no longer simple, we treat them as breaking changes.
This document outlines the upgrade/downgrade procedures for various versions.
As a general rule:
The same logic applies to downgrading:
Direct upgrades or downgrades between arbitrary minor versions (other than the latest or first in the major series) might appear to work, but may cause unexpected behavior or data corruption. This approach is unsupported and discouraged. However, these behaviors may be documented below.
SCRIPTS¶
This document describes the more technical details of the migration, in such a way you can even do it on your own by hand. However, scripts and programs are provided in the source files (located under /migrations/) that allows performing the migration more easily and with backups/error checking. A more step-by-step procedure may be published on https://docs.saunafs.com in regards to the official Ubuntu packages and may linked here.
4.X.X TO 5.X.X¶
The main breaking change in 5.x.x relates to the changelog format. The LENGTH operation format now has three variables. The third variable adds whether to scan chunks further or not. On older versions, this would be always 1.
UPGRADE PROCEDURE¶
No action is required during upgrade. 5.0.0 and later can parse both LENGTH operations correctly.
DOWNGRADE PROCEDURE¶
Older versions cannot parse the new LENGTH format correctly. Version 4.11.0 will correctly print out that why it failed to be parsed. Earlier versions may simply report a parse error and "Unknown SaunaFS Error". While this typically doesn’t affect daily operations, if a stale lock appears and sfsmetarestore or sfsmaster (through the option AUTO_RECOVERY or -o auto-recovery) try to restore from changelog, this will fail.
To fix this, manually revert new LENGTH operations to the old format by removing the third argument in the changelog.sfs files located in the DATA_PATH (typically /var/lib/saunafs/).
Example: This line must be converted from:
"122087244: 1748937259|LENGTH(57605,1536,0)"
To this:
"122087244: 1748937259|LENGTH(57605,1536)"
This will not affect the metadata consistency, it is safe to do this on newer metadata where this new variable was used.
Programs that use these changelogs (typically master, metalogger or shadow) must not be running while performing this operation.
Warning
Do not perform this operation while master, metalogger, or shadow are running and accessing the changelog. Doing so may corrupt the changelog and result in data loss.
Apply this change to master, metalogger and shadow changelogs.
REPORTING BUGS¶
Report bugs to the Github repository https://github.com/leil/saunafs as an issue. Include version information and relevant logs when reporting bugs.
COPYRIGHT¶
Copyright 2025 Leil Storage OÜ
SaunaFS is free software: you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation, version 3.
SaunaFS is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details.
You should have received a copy of the GNU General Public License along with SaunaFS. If not, see http://www.gnu.org/licenses/.
SEE ALSO¶
| 08/28/2025 |