Man page - rpi-setup-loop@.service(8)

Packages contains this manual

Package: rpi-loop-utils
apt-get install rpi-loop-utils

Manuals in package:

Documentations in package:

rpi-loop-utils

Manual

RPI-SETUP-LOOP@.SERVICE

NAME
SYNOPSIS
DESCRIPTION
LIFECYCLE
Service Start (ExecStart)
Service Stop (ExecStop)
INSTANCE NAMING
DEPENDENCIES
EXAMPLES
Setting up a disk image
FILES
SEE ALSO
NOTES

NAME

rpi-setup-loop@.service - systemd template service for loop device management

SYNOPSIS

rpi-setup-loop@{device}.service

DESCRIPTION

rpi-setup-loop@.service is a systemd template service that manages the lifecycle of loop devices by setting up and tearing down loop devices for specified backing files. The service uses the systemd instance name to determine which file to attach to a loop device.

The service is designed to run during early boot with minimal dependencies, making it suitable for setting up loop devices that other services depend on, such as swap files or disk images.

LIFECYCLE

Service Start (ExecStart)

When the service starts:

	1.		The systemd instance name is unescaped using systemd-escape --unescape --path
	2.		losetup -f finds the first available loop device
	3.		The backing file is attached to the loop device
	4.		The 70-rpi-symlink-loop-devices.rules (7) udev rule automatically creates a stable symlink

Service Stop (ExecStop)

When the service stops:

	1.		The service uses the stable symlink created by 70-rpi-symlink-loop-devices.rules (7)
	2.		losetup -d detaches the loop device
	3.		The udev rule automatically removes the corresponding symlink

INSTANCE NAMING

The service uses systemd-escaped file paths as instance names. For example:
rpi-setup-loop@home-pi-backup\x2ddisk.img.service

Sets up a loop device for /home/pi/backup-disk.img

rpi-setup-loop@mnt-data-image.iso.service

Sets up a loop device for /mnt/data/image.iso

Use systemd-escape --path to generate the correct instance name for a given file path.

DEPENDENCIES

The service has minimal dependencies to ensure early availability:
Requires=sysinit.target

Ensures basic system initialisation is complete

After=sysinit.target

Waits for system initialisation before starting

DefaultDependencies=no

Disables default systemd dependencies for early boot operation

EXAMPLES

Setting up a disk image

# Enable the service using systemd-escape to generate the correct name
sudo systemctl enable "rpi-setup-loop@$(systemd-escape --path /home/pi/backup-disk.img).service"

# Start the service (note the backslash escaping for the shell)
sudo systemctl start "rpi-setup-loop@home-pi-backup\x2ddisk.img.service"

# The loop device is now available as:
# /dev/disk/by-backingfile/home-pi-backup\x2ddisk.img -> /dev/loop<N>

FILES

/usr/lib/systemd/system/rpi-setup-loop@.service

The systemd template service file.

NOTES

The service uses RemainAfterExit=yes to ensure systemd considers it active after the loop device is set up, even though the setup command completes immediately. This allows proper dependency tracking for other services that require the loop device.