From 50063d496d69c25f2088a193a769b976bea05f56 Mon Sep 17 00:00:00 2001
From: Lennart Poettering <lennart@poettering.net>
Date: Fri, 7 Feb 2025 16:33:17 +0100
Subject: [PATCH] units: add generic service for attaching a file to a loopback
 device

This is mostly just a friendly unit wrapper around "systemd-dissect
--attach".

This is useful so that we can automatically attach disk images as
block device at boot.
---
 man/rules/meson.build         |  1 +
 man/systemd-loop@.service.xml | 51 +++++++++++++++++++++++++++++++++++
 units/meson.build             |  1 +
 units/systemd-loop@.service   | 24 +++++++++++++++++
 4 files changed, 77 insertions(+)
 create mode 100644 man/systemd-loop@.service.xml
 create mode 100644 units/systemd-loop@.service

diff --git a/man/rules/meson.build b/man/rules/meson.build
index 9fd648392c2..7f147d2dd72 100644
--- a/man/rules/meson.build
+++ b/man/rules/meson.build
@@ -997,6 +997,7 @@ manpages = [
  ['systemd-keyutil', '1', [], ''],
  ['systemd-localed.service', '8', ['systemd-localed'], 'ENABLE_LOCALED'],
  ['systemd-logind.service', '8', ['systemd-logind'], 'ENABLE_LOGIND'],
+ ['systemd-loop@.service', '8', [], ''],
  ['systemd-machine-id-commit.service', '8', [], ''],
  ['systemd-machine-id-setup', '1', [], ''],
  ['systemd-machined.service', '8', ['systemd-machined'], 'ENABLE_MACHINED'],
diff --git a/man/systemd-loop@.service.xml b/man/systemd-loop@.service.xml
new file mode 100644
index 00000000000..57ed1812638
--- /dev/null
+++ b/man/systemd-loop@.service.xml
@@ -0,0 +1,51 @@
+<?xml version="1.0"?>
+<!--*-nxml-*-->
+<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN"
+  "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd">
+<!-- SPDX-License-Identifier: LGPL-2.1-or-later -->
+<refentry id="systemd-loop_.service">
+
+  <refentryinfo>
+    <title>systemd-loop@.service</title>
+    <productname>systemd</productname>
+  </refentryinfo>
+
+  <refmeta>
+    <refentrytitle>systemd-loop@.service</refentrytitle>
+    <manvolnum>8</manvolnum>
+  </refmeta>
+
+  <refnamediv>
+    <refname>systemd-loop@.service</refname>
+    <refpurpose>Attach a loopback block device</refpurpose>
+  </refnamediv>
+
+  <refsynopsisdiv>
+    <para><filename>systemd-loop@<replaceable>path</replaceable>.service</filename></para>
+  </refsynopsisdiv>
+
+  <refsect1>
+    <title>Description</title>
+
+    <para><filename>systemd-loop@.service</filename> is a template service that may be used to automatically
+    attach a loopback block device at boot (or later). Its instance string may reference an (escaped) file
+    system path pointing to a disk image to attach as loopback block device. Use
+    <citerefentry><refentrytitle>systemd-escape</refentrytitle><manvolnum>1</manvolnum></citerefentry>'s
+    <option>--path</option> to properly escape a file system path.</para>
+
+    <para>This unit invokes <command>systemd-dissect --attach --quiet --loop-ref-auto</command> on the
+    specified files, see
+    <citerefentry><refentrytitle>systemd-dissect</refentrytitle><manvolnum>1</manvolnum></citerefentry> for
+    details.</para>
+  </refsect1>
+
+  <refsect1>
+    <title>See Also</title>
+    <para><simplelist type="inline">
+      <member><citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry></member>
+      <member><citerefentry><refentrytitle>systemd-dissect</refentrytitle><manvolnum>1</manvolnum></citerefentry></member>
+      <member><citerefentry><refentrytitle>systemd-import-generator</refentrytitle><manvolnum>8</manvolnum></citerefentry></member>
+    </simplelist></para>
+  </refsect1>
+
+</refentry>
diff --git a/units/meson.build b/units/meson.build
index 2f2a1d5fe9e..3ae3ef8311d 100644
--- a/units/meson.build
+++ b/units/meson.build
@@ -447,6 +447,7 @@ units = [
           'conditions' : ['ENABLE_LOGIND'],
           'symlinks' : ['multi-user.target.wants/', 'dbus-org.freedesktop.login1.service'],
         },
+        { 'file' : 'systemd-loop@.service' },
         {
           'file' : 'systemd-machine-id-commit.service',
           'symlinks' : ['sysinit.target.wants/'],
diff --git a/units/systemd-loop@.service b/units/systemd-loop@.service
new file mode 100644
index 00000000000..a063dcec869
--- /dev/null
+++ b/units/systemd-loop@.service
@@ -0,0 +1,24 @@
+#  SPDX-License-Identifier: LGPL-2.1-or-later
+#
+#  This file is part of systemd.
+#
+#  systemd is free software; you can redistribute it and/or modify it
+#  under the terms of the GNU Lesser General Public License as published by
+#  the Free Software Foundation; either version 2.1 of the License, or
+#  (at your option) any later version.
+
+[Unit]
+Description=Attach File %f to Loopback Block Device
+Documentation=man:systemd-loop@.service(8)
+DefaultDependencies=no
+RequiresMountsFor=%f
+IgnoreOnIsolate=yes
+Wants=modprobe@loop.service
+After=modprobe@loop.service
+
+[Service]
+Type=oneshot
+RemainAfterExit=yes
+TimeoutSec=infinity
+ExecStart=systemd-dissect --attach --loop-ref-auto --quiet %f
+ExecStop=systemd-dissect --detach %f
-- 
2.47.3