dissect: allow setting "lo_file_name" field of loopback block devices

When attaching a loopback file this allows us to set an explicit name
for it. This is useful since it allows a caller to pre-select a string
that is directly attached to the loopback file. Via udev rules we'l
later make the device accessible through this name.

Note that "lo_file_name" is supposed to carry a file name of the backing
file, but the kernel actually does not care or enforce any of that, it
just stores the filename and returns it later. This makes it so useful,
as userspace has total control of that field.

"lo_file_name" should not be confused with the sysattr
"loop/backing_file" which is actually maintained by the kernel itself,
and always shows the file to the backing inode without userspace having
direct control over the returned string. Because the sysattr is
generated by the kernel it is subject to file system namespacing and
everything, while "lo_file_name" is not, it's really just a string
passed through the kernel.

1 files changed, 19 insertions, 0 deletions

diff --git a/man/systemd-dissect.xml b/man/systemd-dissect.xml
index 1d0532713d..06c57a22ec 100644
--- a/man/systemd-dissect.xml
+++ b/man/systemd-dissect.xml
@@ -386,6 +386,25 @@
         </para></listitem>
       </varlistentry>
 
+      <varlistentry>
+        <term><option>--loop-ref=</option></term>
+
+        <listitem><para>Configures the "reference" string the kernel shall report as backing file for the
+        loopback block device. While this is supposed to be a path or filename referencing the backing file,
+        this is not enforced and the kernel accepts arbitrary free-form strings, chosen by the user. Accepts
+        arbitrary strings up to a length of 63 characters. This sets the kernel's
+        <literal>.lo_file_name</literal> field for the block device. Note this is distinct from the
+        <filename>/sys/class/block/loopX/loop/backing_file</filename> attribute file that always reports a
+        path referring to the actual backing file. The latter is subject to mount namespace translation, the
+        former is not.</para>
+
+        <para>This setting is particularly useful in combination with the <option>--attach</option> command,
+        as it allows later referencing the allocated loop device via <filename>/dev/loop/by-ref/…</filename>
+        symlinks. Example: first, set up the loopback device via <command>systemd-dissect attach
+        --loop-ref=quux foo.raw</command>, and then reference it in a command via the specified filename:
+        <command>cfdisk /dev/loop/by-ref/quux</command>.</para></listitem>
+      </varlistentry>
+
       <xi:include href="standard-options.xml" xpointer="no-pager" />
       <xi:include href="standard-options.xml" xpointer="no-legend" />
       <xi:include href="standard-options.xml" xpointer="json" />