systemd.v(7)

NAME#

systemd.v - Directory with Versioned Resources

DESCRIPTION#

In various places systemd components accept paths whose trailing components have the ".v/" suffix, pointing to a directory. These components will then automatically look for suitable files inside the directory, do a version comparison and open the newest file found (by version). Available since version v256. Specifically, two expressions are supported:

To illustrate this in an example, consider a directory /var/lib/machines/mymachine.raw.v/, which is populated with three files:

Invoke a tool such as systemd-nspawn(1) with a command line like the following:

# systemd-nspawn --image=/var/lib/machines/mymachine.raw.v --boot

Then this would automatically be resolved to the equivalent of:

# systemd-nspawn --image=/var/lib/machines/mymachine.raw.v/mymachine_7.6.0.raw --boot

Much of systemd's functionality that expects a path to a disk image or OS directory hierarchy support the ".v/" versioned directory mechanism, for example systemd-nspawn(1), systemd-dissect(1) or the RootDirectory=/RootImage= settings of service files (see systemd.exec(5)).

Use the systemd-vpick(1) tool to resolve ".v/" paths from the command line, for example for usage in shell scripts.

FILTERING AND SORTING#

The variable part of the filenames in the ".v/" directories are filtered and compared primarily with a version comparison, implementing Version Format Specification[1]. However, additional rules apply:

Or in other words, the files in the ".v/" directories should follow one of these naming structures:

EXAMPLE#

Here's a more comprehensive example, further extending the one described above. Consider a directory /var/lib/machines/mymachine.raw.v/, which is populated with the following files:

Now invoke the following command on an x86-64 machine:

$ systemd-vpick --suffix=.raw /var/lib/machines/mymachine.raw.v/

This would resolve the specified path to /var/lib/machines/mymachine.raw.v/mymachine_7.5.14_x86-64.raw. Explanation: even though mymachine_7.7.0_x86-64+0-5.raw has the newest version, it is not preferred because its tries left counter is zero. And even though mymachine_7.6.0_arm64.raw has the second newest version it is also not considered in this case, because we operate on an x86_64 system and the image is intended for arm64 CPUs. Finally, the mymachine_7.5.13.raw image is not considered because it is older than mymachine_7.5.14_x86-64.raw.

SEE ALSO#

systemd(1), systemd-vpick(1), systemd-nspawn(1), systemd-dissect(1), systemd.exec(5), systemd-sysupdate(8)

NOTES#

1.

Version Format Specification

2.

Automatic Boot Assessment