blog story

Posted Jun 12, 2024 18:40 UTC (Wed) by dskoll (subscriber, #1630)
In reply to: blog story by mezcalero
Parent article: systemd 256 released

The .v/ directories are a great idea. I hope other packages adopt this.

What are .v/ directories used for?

Posted Jun 13, 2024 1:16 UTC (Thu) by python (guest, #171317) [Link] (4 responses)

What are .v/ directories useful for for? (I am a new to this)

What are .v/ directories used for?

Posted Jun 13, 2024 8:53 UTC (Thu) by fishface60 (subscriber, #88700) [Link]

The idea is that .d directories which specify a bunch of config that all gets merged together are really convenient for just being able to drop an extra file in there and have less trouble resolving file conflicts when something updates,
but not everything can be merged like that so .v directories let you drop stuff in and pick the best option.

Suppose you had an application that was packaged as a container, in a disk image called /var/lib/machines/myapp.raw.
You could boot the container with systemd-nspawn or use the RootDirectory/RootImage options in a service file.

When an updated image is released you'd want to download it and try it out, but also keep the old version around so that you can roll back.

Instead of managing the container image by hand you can let the .v directory logic pick the most appropriate version, so in the directory named /var/lib/machines/myapp.raw.v/ you could have myapp_1.0.raw and myapp_2.0.raw. It will do a version sort of the version component of the file names and pick the latest.

If myapp_2.0.raw is broken though you don't want it to just keep attempting to boot the same image that failed forever, so it also supports a counter for the number of attempts in the file name,
so instead of saving the image as myapp_2.0.raw it could be saved as myapp_2.0+2.raw, which means try running it twice.
The first time it starts to boot it renames it to myapp_2.0+1-1.raw, then if that fails it starts again, renames it to myapp_2.0+0-2.raw, but because the tries counter after the + is 0, if it fails and is restarted, myapp_2.0+0-2.raw won't be tried again and myapp_1.0.raw will be booted instead.
If myapp_2.0+M-N.raw does successfully boot though it gets renamed to myapp_2.0.raw and bypasses the counter logic in future because it's known to be good.

It can also select by CPU architecture so you could have myapp_2.0_arm64.raw and myapp_2.0_x86-64.raw on some network share used by a heterogeneous server farm and it pick the correct version.

What are .v/ directories used for?

Posted Jun 13, 2024 9:26 UTC (Thu) by farnz (subscriber, #17727) [Link] (2 responses)

They replace symlinks/hardlinks used to point you at "the latest" version of something like a container image or a discoverable disk image.

In a traditional setup, you have a file such as foo_container_v1.img, containing v1 of foo_container. You then have a symlink or hardlink pointing foo_container_current.img to foo_container_v1.img, and configure everything to point to foo_container_current.img. To update to foo_container_v2.img, you download foo_container_latest.img, rename it to foo_container_v2.img, then change the link to point to it.

.v directories solve this differently; you put files in foo_container.img.v, and when you give them the right names, systemd-vpick and other systemd tools like systemd-nspawn will pick up the latest version.

That's the basic mechanism, but systemd adds a couple of extras that aren't easily possible with the link-based version; firstly, systemd is architecture-aware, so you can use the same .vdirectory with the same contents across multiple systems (e.g. just copying it down as part of your fleet management). More usefully, systemd knows how to keep a retry counter in the filename, so you can download a new image, but if it fails to run, systemd will track this and do the "normal" automatic fallback to the old version. And you can look at ls in that directory to see the retry count.

So, using this with foo_container version 2, you'd download foo_container_latest.x86-64.img into the .v directory, then rename it to foo_container_2_x86-64+5-0.img. This is now a newer version than the existing v1, so the next time a systemd tool on x86-64 looks for foo_container.img in foo_container.img.v, it'll find this v2 image. Before it attempts to start it, it'll rename it to foo_container_2_x86-64+4-1.img, showing you that it's used up one retry. If it succeeds, it'll rename the file again to foo_container_2_x86-64.img, which will cause this to be used unconditionally if v2 is the latest. If it fails, it's kept under the new name; if it keeps failing, it'll eventually be renamed to foo_container_2_x86-64+0-5.img, which causes it to be ignored in favour of foo_container_1.img. And this is all ignored by an aarch64 host, which will stick to v1 until you bring in a new aarch64 container.

What are .v/ directories used for?

Posted Jun 13, 2024 9:40 UTC (Thu) by epa (subscriber, #39769) [Link] (1 responses)

That sounds cool, but systemd could also create and update a 'latest' symlink within the .v directory once it has decided what version to run, so that other less smart programs can easily find the version currently in use.

Finding the latest in a .v if you're not systemd

Posted Jun 13, 2024 9:44 UTC (Thu) by farnz (subscriber, #17727) [Link]

systemd provides systemd-vpick for that purpose.