LEIL-MIGRATIONS(7)

📦 version 5.12.0, in nixpkgs unstable

💅 LEIL-MIGRATIONS(7) — the migration glow-up guide

ok so this is the leil-migrations manual page, and it's literally your bestie's guide to moving LeilFS between major versions without breaking everything. System admins, this one's for you 🫶

✨ SYNOPSIS

LeilFS migration documentation for system administrators.

🌸 DESCRIPTION

So here's the tea ☕ — we use semantic versioning to decide whether something counts as a breaking change. Sometimes it's as simple as a command-line interface glow-up. Other times it's a whole data-format situation in LeilFS. But most of the time? Upgrades should be smooth, no cap.

A big goal of ours is supporting smooth downgrades between versions within the same minor bracket (that's the y in x.y.z, iykyk). And when downgrades stop being simple, we just treat them as breaking changes. Periodt.

This doc walks you through the upgrade/downgrade procedures for the various versions.

The general rule, bestie:

  • 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. like, actually verify ✨
  • Review the NEWS file for breaking changes.
  • Proceed with the upgrade to the next major version (e.g., 5.0.0).

Same logic applies to downgrading:

  • 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 (so, anything other than the latest or first in the major series) might appear to work, but they may cause unexpected behavior or data corruption. This approach is unsupported and discouraged, fr fr. That said, these behaviors may be documented below 👀

🎀 SCRIPTS

This doc gets into the more technical details of the migration, in a way where you can honestly just do it on your own by hand if you want to be all main character about it 💅. BUT — scripts and programs are provided in the source files (located under /migrations/) that let you do the migration way more easily, with backups and error checking included. Slay.

A more step-by-step procedure may be published on https://docs.leil.io in regards to the official Ubuntu packages, and may be linked here later.

🔥 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. That third variable adds whether to scan chunks further or not. On older versions, this would always be 1.

⭐ UPGRADE PROCEDURE

No action is required during upgrade, bestie — you're chilling. 5.0.0 and later can parse both LENGTH operations correctly. Go off 👑

💀 DOWNGRADE PROCEDURE

ok so this is where it gets real. Older versions cannot parse the new LENGTH format correctly. Version 4.11.0 will correctly print out why it failed to be parsed — iconic of it, honestly. Earlier versions may simply report a parse error and "Unknown LeilFS Error" 😭.

While this typically doesn't affect daily operations, if a stale lock appears and leil-metarestore or leil-master (through the option AUTO_RECOVERY or -o auto-recovery) try to restore from changelog, this will fail. Not the vibe.

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/leil/).

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, so 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, genuinely do not. 🙈

Apply this change to master, metalogger and shadow changelogs.

🐛 REPORTING BUGS

Report bugs to the GitHub repository https://github.com/leil-io/leilfs as an issue. Include version information and relevant logs when reporting bugs — the more context you give, the faster someone can help you. tysm 💖

Copyright 2025 Leil Storage OÜ

LeilFS 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.

LeilFS 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 LeilFS. If not, see http://www.gnu.org/licenses/.

🦋 SEE ALSO

🌈 and that's the whole page, bestie! this one's LEIL-MIGRATIONS(7), dated 1980-01-01 — yes, the date is giving time traveler, don't ask 💀 — go forth and migrate responsibly 💜

📦 where this page comes from