SAUNAFS-MIGRATIONS(7)

📦
version 5.8.0 · 4 versions
, in ubuntu stonking

💖 SAUNAFS-MIGRATIONS 💖

okay bestie, welcome to saunafs-migrations — the little guide that walks you through moving SaunaFS between major versions without your data having a whole meltdown. it's a section 7 page, so it's documentation-coded, and it's literally just for sysadmins doing the glow-up (or the un-glow-up 👀). let's get into it 🫶

✨ SYNOPSIS ✨

SaunaFS migration documentation for system administrators. that's it, that's the vibe. you're the system administrator. this is for you. 💅

🌸 DESCRIPTION 🌸

so here's the tea: SaunaFS uses semantic versioning to decide whether something counts as a breaking change. sometimes it's giving "we changed the command-line interface, deal with it." other times it's giving "we changed SaunaFS's data formats, so actually pay attention." but honestly? most of the time upgrades should be smooth like butter. ✨

a key goal is to support smooth downgrades between versions within the same minor bracket — that's the y in x.y.z, iykyk. and the moment downgrades stop being simple, we call that a breaking change. no cap.

this doc lays out the upgrade/downgrade procedures for the various versions. 📋

as a general rule:

  • Upgrade to the latest minor version of your current major version (e.g., from 4.9.0 to 4.11.0).
  • Verify everything works correctly.
  • Review the NEWS file for breaking changes.
  • Proceed with the upgrade to the next major version (e.g., 5.0.0).

and the same logic applies to downgrading, bestie, we keep it symmetric 💜:

  • Downgrade to the first minor version of your current major version (e.g., from 5.1.0 to 5.0.0).
  • Verify everything works correctly.
  • Review the NEWS file for breaking changes.
  • Proceed with the downgrade to the last major and minor version (e.g., 4.11.0).

Direct upgrades or downgrades between arbitrary minor versions (like, anything that isn't the latest or the 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. so like, read on if you're chaotic. 😭

🛠️ SCRIPTS 🛠️

this document is the more technical breakdown of the migration — detailed enough that you could technically do the whole thing by hand, all by yourself, main character energy. but!! scripts and programs are provided in the source files (located under /migrations/) that let you perform the migration more easily, with backups and error checking included. 🎀

a more step-by-step procedure may be published on https://docs.saunafs.com in regards to the official Ubuntu packages, and may be linked here. watch this space. 👑

🚀 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 always be 1. wild, right? 💀

⬆️ UPGRADE PROCEDURE ⬆️

No action is required during upgrade. 5.0.0 and later can parse both LENGTH operations correctly. slay, nothing to do. ✨

⬇️ DOWNGRADE PROCEDURE ⬇️

here's where it gets spicy 🌶️ — older versions cannot parse the new LENGTH format correctly. version 4.11.0 will correctly print out why it failed to be parsed (ate, honestly). 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 it, 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. like, actual data loss. do not do this. 💀

Apply this change to master, metalogger and shadow changelogs. all three, no skipping. ✅

🐛 REPORTING BUGS 🐛

found a bug? (rude of it.) Report bugs to the GitHub repository https://github.com/leil-io/saunafs as an issue. Include version information and relevant logs when reporting bugs — the logs are the receipts, bestie, bring them. 🧾✨

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 👀

that's the whole page, babes 🌈 — SaunaFS migrations, section 7, dated 2026-07-29, straight from the SaunaFS project. go forth and migrate responsibly, and pls pls pls read the NEWS file before you do anything brave. mwah 💋💖

📦 where this page comes from