From 7d93e4af8088fae7b50eb638c6e297fb8371e307 Mon Sep 17 00:00:00 2001 From: Lennart Poettering Date: Thu, 16 Nov 2023 11:31:02 +0100 Subject: man: document the new vpick concept --- man/rules/meson.build | 2 + man/systemd-dissect.xml | 5 ++ man/systemd-nspawn.xml | 26 ++++--- man/systemd-vpick.xml | 198 ++++++++++++++++++++++++++++++++++++++++++++++++ man/systemd.exec.xml | 8 ++ man/systemd.v.xml | 163 +++++++++++++++++++++++++++++++++++++++ 6 files changed, 391 insertions(+), 11 deletions(-) create mode 100644 man/systemd-vpick.xml create mode 100644 man/systemd.v.xml diff --git a/man/rules/meson.build b/man/rules/meson.build index c99f79eba8..3592b862f7 100644 --- a/man/rules/meson.build +++ b/man/rules/meson.build @@ -1131,6 +1131,7 @@ manpages = [ 'HAVE_LIBCRYPTSETUP'], ['systemd-vmspawn', '1', [], 'ENABLE_VMSPAWN'], ['systemd-volatile-root.service', '8', ['systemd-volatile-root'], ''], + ['systemd-vpick', '1', [], ''], ['systemd-xdg-autostart-generator', '8', [], 'ENABLE_XDG_AUTOSTART'], ['systemd', '1', ['init'], ''], ['systemd.automount', '5', [], ''], @@ -1165,6 +1166,7 @@ manpages = [ ['systemd.time', '7', [], ''], ['systemd.timer', '5', [], ''], ['systemd.unit', '5', [], ''], + ['systemd.v', '7', [], ''], ['sysupdate.d', '5', [], 'ENABLE_SYSUPDATE'], ['sysusers.d', '5', [], 'ENABLE_SYSUSERS'], ['telinit', '8', [], 'HAVE_SYSV_COMPAT'], diff --git a/man/systemd-dissect.xml b/man/systemd-dissect.xml index b238a9f7d0..85166f23d3 100644 --- a/man/systemd-dissect.xml +++ b/man/systemd-dissect.xml @@ -120,6 +120,10 @@ mounted directly by mount and fstab5. For details see below. + + In place of the image path a .v/ versioned directory may be specified, see + systemd.v7 for + details. @@ -543,6 +547,7 @@ systemd1 systemd-nspawn1 systemd.exec5 + systemd.v7 Discoverable Partitions Specification mount8 umount8 diff --git a/man/systemd-nspawn.xml b/man/systemd-nspawn.xml index e721f0e5ab..1a9fb09aae 100644 --- a/man/systemd-nspawn.xml +++ b/man/systemd-nspawn.xml @@ -209,21 +209,21 @@ - Directory to use as file system root for the - container. + Directory to use as file system root for the container. - If neither , nor - is specified the directory is - determined by searching for a directory named the same as the - machine name specified with . See + If neither , nor is specified the + directory is determined by searching for a directory named the same as the machine name specified + with . See machinectl1 section "Files and Directories" for the precise search path. - If neither , - , nor - are specified, the current directory will - be used. May not be specified together with - . + In place of the directory path a .v/ versioned directory may be specified, see + systemd.v7 for + details. + + If neither , , nor + are specified, the current directory will be used. May not be specified + together with . @@ -317,6 +317,10 @@ Any other partitions, such as foreign partitions or swap partitions are not mounted. May not be specified together with , . + In place of the image path a .v/ versioned directory may be specified, see + systemd.v7 for + details. + diff --git a/man/systemd-vpick.xml b/man/systemd-vpick.xml new file mode 100644 index 0000000000..95f946a84c --- /dev/null +++ b/man/systemd-vpick.xml @@ -0,0 +1,198 @@ + + + + + + + + systemd-vpick + systemd + + + + systemd-vpick + 1 + + + + systemd-vpick + Resolve paths to .v/ versioned directories + + + + + systemd-vpick OPTIONS PATH + + + + + Description + + systemd-vpick resolves a file system path referencing a .v/ + versioned directory to a path to the newest (by version) file contained therein. This tool provides a + command line interface for the + systemd.v7 + logic. + + The tool expects a path to a .v/ directory as argument (either directly, or with + a triple underscore pattern as final component). It then determines the newest file contained in that + directory, and writes its path to standard output. + + Unless the triple underscore pattern is passed as last component of the path, it is typically + necessary to at least specify the switch to configure the file suffix to look + for. + + If the specified path does not reference a .v/ path (i.e. neither the final + component ends in .v, nor the penultimate does or the final one does contain a triple + underscore) it specified path is written unmodified to standard output. + + + + Options + + The following options are understood: + + + + + + + Overrides the "basename" of the files to look for, i.e. the part to the left of the + variable part of the filenames. Normally this is derived automatically from the filename of the + .v component of the specified path, or from the triple underscore pattern in the + last component of the specified path. + + + + + + + + Explicitly configures the version to select. If specified, a filename with the + specified version string will be looked for, instead of the newest version + available. + + + + + + + + Explicitly configures the architecture to select. If specified, a filename with the + specified architecture identifier will be looked for. If not specified only filenames with a locally + supported architecture are considered, or those without any architecture identifier. + + + + + + + + + Configures the suffix of the filenames to consider. For the .v/ + logic it is necessary to specify the suffix to look for, and the .v/ component + must also carry the suffix immediately before .v in its name. + + + + + + + + + Configures the inode type to look for in the .v/ directory. Takes + one of reg, dir, sock, + fifo, blk, chr, lnk as + argument, each identifying an inode type. See inode7 for + details about inode types. If this option is used inodes not matching the specified type are filtered + and not taken into consideration. + + + + + + + + + Configures what precisely to write to standard output. If not specified prints the + full, resolved path of the newest matching file in the .v/ directory. This switch can be set to one of the following: + + + If set to filename, will print only the filename instead of the full path of the resolved file. + If set to version, will print only the version of the resolved file. + If set to type, will print only the inode type of the resolved + file (i.e. a string such as reg for regular files, or dir for + directories). + If set to arch, will print only the architecture of the resolved + file. + If set to tries, will print only the tries left/tries done of the + resolved file. + If set to all, will print all of the above in a simple tabular + output. + + + + + + + + + Takes a boolean argument. If true the path to the versioned file is fully + canonicalized (i.e. symlinks resolved, and redundant path components removed) before it is shown. If + false (the default) this is not done, and the path is shown without canonicalization. + + + + + + + + + + + Examples + + Use a command like the following to automatically pick the newest raw disk image from a + .v/ directory: + + $ systemd-vpick --suffix=.raw --type=reg /var/lib/machines/quux.raw.v/ + + This will enumerate all regular files matching + /var/lib/machines/quux.raw.v/quux*.raw, filter and sort them according to the rules + described in + systemd.v7, and then + write the path to the newest (by version) file to standard output. + + Use a command like the following to automatically pick the newest OS directory tree from a + .v/ directory: + + $ systemd-vpick --type=dir /var/lib/machines/waldo.v/ + + This will enumerate all directory inodes matching + /var/lib/machines/waldo.v/waldo*, filter and sort them according to the rules + described in + systemd.v7, and then + write the path to the newest (by version) directory to standard output. + + For further examples see + systemd.v7. + + + + Exit status + + On success, 0 is returned, a non-zero failure code + otherwise. + + + + See Also + + systemd1 + systemd.v7 + + + diff --git a/man/systemd.exec.xml b/man/systemd.exec.xml index e2b2910084..42e6ff8fd7 100644 --- a/man/systemd.exec.xml +++ b/man/systemd.exec.xml @@ -155,6 +155,10 @@ BindReadOnlyPaths=/dev/log /run/systemd/journal/socket /run/systemd/journal/stdout + In place of the directory path a .v/ versioned directory may be specified, + see systemd.v7 for + details. + @@ -191,6 +195,10 @@ systemd-soft-reboot.service8), in case the service is configured to survive it. + In place of the image path a .v/ versioned directory may be specified, see + systemd.v7 for + details. + diff --git a/man/systemd.v.xml b/man/systemd.v.xml new file mode 100644 index 0000000000..6cc6122a34 --- /dev/null +++ b/man/systemd.v.xml @@ -0,0 +1,163 @@ + + + + + + + + systemd.v + systemd + + + + systemd.v + 7 + + + + 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). Specifically, two expressions are supported: + + + + When looking for files with a suffix .SUFFIX, and a path + …PATH/NAME.SUFFIX.v/ + is specified, then all files + …PATH/NAME.SUFFIX.v/NAME_*.SUFFIX + are enumerated, filtered, sorted and the newest file used. The primary sorting key is the + variable part, here indicated by the wildcard + *. + + When a path + …PATH.v/NAME___.SUFFIX + is specified (i.e. the penultimate component of the path ends in .v and the final + component contains a triple underscore), then all files + …PATH.v/NAME_*.SUFFIX + are enumerated, filtered, sorted and the newest file used (again, by the variable + part, here indicated by the wildcard *). + + + To illustrate this in an example, consider a directory /var/lib/machines/mymachine.raw.v/, which is populated with three files: + + + mymachine_7.5.13.raw + mymachine_7.5.14.raw + mymachine_7.6.0.raw + + + Invoke a tool such as systemd-nspawn1 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-nspawn1, + systemd-dissect1 or + the RootDirectory=/RootImage= settings of service files (see + systemd.exec5). + + Use the + systemd-vpick1 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. However, additional rules apply: + + + If the variable part is suffixed by one or two integer values ("tries left" and "tries + done") in the formats +LEFT or + +LEFT-DONE, then these + indicate usage attempt counters. The idea is that each time before a file is attempted to be used, its + "tries left" counter is decreased, and the "tries done" counter increased (simply by renaming the + file). When the file is successfully used (which for example could mean for an OS image: successfully + booted) the counters are removed from the file name, indicating that the file has been validated to + work correctly. This mechanism mirrors the boot assessment counters defined by Automatic Boot Assessment. Any filenames + with no boot counters or with a non-zero "tries left" counter are sorted before filenames with a zero + "tries left" counter. + + Preceeding the use counters (if they are specified), an optional CPU architecture + identifier may be specified in the filename (separated from the version with an underscore), as defined + in the architecture vocabulary of the ConditionArchitecture= unit file setting, as + documented in + systemd.unit5. Files + whose name indicates an architecture not supported locally are filtered and not considered for the + version comparison. + + The rest of the variable part is the version string. + + + Or in other words, the files in the .v/ directories should follow one of these + naming structures: + + + NAME_VERSION.SUFFIX + NAME_VERSION_ARCHITECTURE.SUFFIX + NAME_VERSION+LEFT.SUFFIX + NAME_VERSION+LEFT-DONE.SUFFIX + NAME_VERSION_ARCHITECTURE+LEFT.SUFFIX + NAME_VERSION_ARCHITECTURE+LEFT-DONE.SUFFIX + + + + + 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: + + + mymachine_7.5.13.raw + mymachine_7.5.14_x86-64.raw + mymachine_7.6.0_arm64.raw + mymachine_7.7.0_x86-64+0-5.raw + + + 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 + + systemd1 + systemd-vpick1 + systemd-nspawn1 + systemd-dissect1 + systemd.exec5 + systemd-sysupdate1 + + + + -- cgit v1.2.3