S6-RC-FORMAT-UPGRADE(8)

📦 version 0.7.0.0, in nixpkgs unstable

💅 s6-rc-format-upgrade — the manual page, but make it make sense

okay so real talk: this is s6-rc-format-upgrade, from section 8 of the System Manager's Manual, and it's the glow-up your live directory deserves when the database format changes under your feet. it's niche, it's rare, it's iconic. let's get into it 🎀

✨ NAME ✨

s6-rc-format-upgrade — transitions a live directory using a database with the old s6-rc format so that it uses a database with the new s6-rc format.

like, it walks your live dir out of its old-format era and into its new-format era. no cap, that's the whole job 🦋

🌸 SYNOPSIS 🌸

s6-rc-format-upgrade [-v verbosity] [-l live] [-t timeout] [-b]
                     newcompiled

that's it. one positional argument, four little flags. cute, right? 🫶

💖 DESCRIPTION 💖

so s6-rc-format-upgrade is a program that is normally used very rarely — and i mean it, this is not your everyday bestie. the situation is: the s6-rc package gets upgraded, some services are currently being managed with s6-rc(8), and the database format has changed. that's when this bad boy shows up. it transitions a live directory using a database with the old s6-rc format (the one being replaced) so that it uses a database with the new s6-rc format. periodt 💅

the whole point? ensuring a smooth transition between different versions of s6-rc without needing a reboot. no reboot. none. we stay uptime-pilled ✨

now, s6-rc-format-upgrade is very different from s6-rc-update(8) and does not duplicate its functionality. it's giving complementary, not competitive:

  • s6-rc-update(8) updates a live directory to use a different compiled database, compiled from a different source, where services may have changed, be renamed, etc. but — and this is the catch — it can only handle databases with the format that it knows: the format created by the s6-rc-compile(8) binary that comes in the same package as s6-rc-update(8).
  • s6-rc-format-upgrade is the opposite vibe entirely: it cannot handle service changes, it can only update a live directory to use a compiled database corresponding to the same source as the compiled database the live directory is currently using. but it will replace an obsolete compiled database with a compiled database that uses the new format (provided both compiled databases come from the same source, and have just been produced by invocation of different versions of s6-rc-compile(8)), ensuring the s6-rc installation can live through database format changes. queen behavior 👑
⚠️ newcompiled must be an absolute path. not relative, not vibes-based. absolute. fr fr.

s6-rc-format-upgrade expects to find a compiled service database with the new format in compiled. (yes, the man page says compiled there — we're keeping it exactly as written, bestie, no editing the source of truth 💀)

newcompiled must be compiled from the same source database as the current compiled database currently being used by live. s6-rc-format-upgrade then updates the live directory in live so it uses newcompiled as its compiled database.

on success, it exits 0. slay 🎀

🌈 Typical usage

s6-rc-format-upgrade is only necessary when the database format changes, which only happens when s6-rc's major version number (the third number from the right) changes. yep, third from the right. write that down 📝

the correct order of operations is then the following:

  1. make sure your current compiled database is up-to-date with your source database. if it's not, update it, by invoking the s6-rc-compile(8) and s6-rc-update(8) binaries from your old s6-rc installation — the ones that understand the old format. old binaries for old format, iykyk.
  2. from the same source, compile a new database with the new format, using the s6-rc-compile(8) binary from the new s6-rc package.
  3. update your live directories with this new database, using s6-rc-format-upgrade. (that's us! hi! 👋)
  4. you can now remove the old databases, and delete the old s6-rc package. goodbye old era, it was real 🦋

🔥 OPTIONS 🔥

  • -v verbosity — be more or less verbose. default is 1. talk to me more, or less, your call 💬
  • -t timeout — if all operations have not completed after timeout milliseconds, complain and exit 1. yes, complain. officially. dramatically. then bail 😭
  • -l live — work with the live state in the live directory. default is /run/s6-rc. the default can be changed at compile time by giving the --livedir=live option to ./configure. custom build, custom home 🏡
  • -b — blocking lock. if live is currently being used by another program, s6-rc-format-upgrade will wait until that other program has released its lock on the directory, then proceed. by default, s6-rc-format-upgrade fails with an error message if the live directory is currently in use. so like, -b says "i'll wait, it's fine", and no -b says "nope, occupied, i'm out" 💀

🧚 SEE ALSO 🧚

s6-rc-faq(7), s6-rc-overview(7), s6-rc-why(7), s6-rc(8), s6-rc-bundle(8), s6-rc-compile(8), s6-rc-db(8), s6-rc-dryrun(8), s6-rc-fdholder-filler(8), s6-rc-init(8), s6-rc-oneshot-run(8), s6-rc-update(8)

this man page is ported from the authoritative documentation at: https://skarnet.org/software/s6-rc/s6-rc-format-upgrade.html — go read the source, it's giving academic integrity 📚✨

👑 AUTHORS 👑

Laurent Bercot Alexis <flexibeast@gmail.com> (man page port)

okay that's the whole page!! and before you close the tab — this little beauty shipped as part of Debian's collection, dated April 6, 2023. cute, iconic, timestamped. mwah 💋💖

go forth and format-upgrade responsibly, bestie. and remember: absolute path. third number from the right. no reboot. 🫶✨
📦 where this page comes from