systemd_unit
systemd_unit installs one systemd unit file, or one named drop-in of a
unit, on the node, after systemd's own check (systemd-analyze verify)
accepts the new file. It installs units of the kinds .service, .timer,
.path, .socket, .mount, .target, .swap, .slice, and
.automount, templates such as app@.service included. A drop-in changes
part of an existing unit, such as a vendor's.
systemd_unit only writes the file. systemd_service
starts, stops, enables, and masks the unit, and restarts or reloads it after
a change. For a command on a schedule,
systemd_scheduled_job writes a service and its
timer from one node task, and cron_job manages a cron entry;
write the units by hand with systemd_unit when the service needs settings
those modules do not offer. For a mount kept in /etc/fstab, use
fstab_mount, and for a swap file,
swap_file, which does all the steps.
Keep secret values in a separate private file that the unit references, not in the unit file.
Inputs
name(string; required): a unit filename, such as app.service, app@.service, or backup.timer; a .mount is named for its escaped mount point (systemd-escape --path --suffix=mount)drop_in(string; optional): a single .conf filename; manages/etc/systemd/system/<name>.d/<drop_in>in_systemd_of_user_account(string; optional): an account other than root: the unit belongs to that account's own systemd, its file goes to<home>/.config/systemd/user/owned by the account, and MMX turns on lingering for the account so that its units start at boot and keep running after logoutcontent(string; optional): inline text; exactly one of content or templatetemplate(string; optional): local Go template, relative to the project root, or to the role's directory inside a role; exactly one of content or templatestate(presentorabsent; defaultpresent): absent removes only the selected unit file or drop-in and accepts only name, drop_in, in_systemd_of_user_account, and state
Outputs
The node task's result holds these fields. A later node task reads them as .node_tasks.<id>.<field>, where <id> is the node task's id.
statuschange
What a dryrun reports
Supported; previews contents; validation of a changed unit is not checked.
Retries and time limits
Bounded automatic retries by default; retry: false turns them off.
The node task takes the time limits time_limit and time_limit_per_try; without them, the project's node_task_defaults apply. mmx describe-module task describes the settings every node task accepts.
Examples
Change part of a unit with a drop-in
- systemd_unit:
name: app.service
drop_in: 20-limits.conf # a drop-in filename you choose
content: |
[Service]
MemoryMax=512M
This example manages only
/etc/systemd/system/app.service.d/20-limits.conf on the node. Other
drop-ins stay intact. Before replacement, systemd checks the base unit, the
installed drop-ins, and the proposed file together. When systemd rejects the
new file, the existing 20-limits.conf stays, and the task fails.
A timer that runs a service
A timer runs a service, usually a oneshot without an [Install] section:
- task_block:
id: backup # a node task block ID you choose
changes:
- systemd_unit:
name: backup.service
content: |
[Service]
Type=oneshot
User=backup
ExecStart=/usr/local/bin/backup
- systemd_unit:
name: backup.timer
content: |
[Timer]
OnCalendar=*-*-* 03:00:00
RandomizedDelaySec=15m
Persistent=true
[Install]
WantedBy=timers.target
activate:
- systemd_service:
name: backup.timer
start_at_boot: true
state: running
Name the timer, path, or socket in activate, rather than the service the
timer, path, or socket starts. Changing a timer, path, or socket definition
makes the systemd_service task restart the timer, path, or socket once.
The triggered service needs no node task. Reloading the node's systemd
manager makes the service's next activation use the new service definition.
For .path and .socket units, also activate the triggering unit and let
the triggered service use the new definition on the next activation.
A target that restarts a group of services
A target can group services so the services restart together.
In the following example, PartOf=report-workers.target makes the two
worker services restart when someone restarts report-workers.target.
When the target's definition changes, MMX restarts report-workers.target,
which restarts the workers through PartOf=.
When report-worker@.service changes, MMX restarts the workers through the
two worker systemd_service tasks in activate:
- task_block:
id: report_workers # a node task block ID you choose
changes:
- systemd_unit:
name: report-worker@.service
content: |
[Unit]
PartOf=report-workers.target
[Service]
ExecStart=/usr/local/bin/report-worker --queue %i
[Install]
WantedBy=report-workers.target
- systemd_unit:
name: report-workers.target
content: |
[Unit]
Description=Report workers
[Install]
WantedBy=multi-user.target
activate:
- systemd_service:
name: report-worker@invoices
start_at_boot: true
state: running
- systemd_service:
name: report-worker@exports
start_at_boot: true
state: running
- systemd_service:
name: report-workers.target
start_at_boot: true
state: running
A unit in an account's own systemd
Every Linux account can have its own systemd, which runs that account's units
without root. Containers that run without root use the account's systemd.
in_systemd_of_user_account on systemd_unit and systemd_service (and on
podman_quadlet) names the account whose systemd owns
the unit, instead of the system's systemd.
Install /home/reports/bin/report-worker before the following node task
block:
# roles/report_worker/main.yml
node_tasks:
- user:
create_home_directory: true
name: reports
home: /home/reports
shell: /bin/sh
- directory:
path: /home/reports
owner: reports
group: reports
permissions_mode: "0750"
- task_block:
id: report_worker
changes:
- systemd_unit:
name: report-worker.service
in_systemd_of_user_account: reports
content: |
[Service]
ExecStart=/home/reports/bin/report-worker
[Install]
WantedBy=default.target
activate:
- systemd_service:
name: report-worker.service
in_systemd_of_user_account: reports
start_at_boot: true
state: running
The unit file goes to /home/reports/.config/systemd/user/, owned by
reports, and the service runs as reports. Everything else works as for a
system unit: drop-ins, the check before installation, the restart after a
changed unit, and state: absent.
To look at such a unit by hand, become the account with its runtime directory set:
sudo runuser -u reports -- env XDG_RUNTIME_DIR=/run/user/$(id -u reports) \
systemctl --user status report-worker.service
How it works
Installation and the check before it
systemd_unit takes exactly one of content or template. It installs a
root-owned 0644 file under /etc/systemd/system on the node, through the
file module's atomic replacement, after systemd-analyze verify accepts
the temporary new file.
That check refuses a unit whose program does not exist yet, with a message
such as Command /usr/local/bin/myapp is not executable: No such file or directory. Put the systemd_unit task after the node task that installs
the program, such as a file, unpack_archive, or package task.
With drop_in (a single .conf filename), it manages only
/etc/systemd/system/<name>.d/<drop_in>, creating that directory when
needed. The new drop-in is checked together with the base unit and the other
installed drop-ins.
The manager reload and the restart
After a changed unit, MMX runs systemctl daemon-reload on the node. An
unchanged unit that is not a template, and each
systemd_service task, also check systemd's
NeedDaemonReload. So an interrupted manager reload is recovered through
systemd's own pending-reload state, without a separate MMX record: the next
run reloads systemd for the unchanged file and reports changed, and a dryrun
before it reports would_change.
systemd cannot inspect a template as a unit. A template's instances have
their pending manager reload completed by their systemd_service node tasks.
Put a unit in the same node task block's changes as its service's
configuration
(execution design).
Unit and drop-in changes, including removal, are tracked in the service's
definition hash. Within a node task block, they require a restart of the unit
that a systemd_service task in activate names, even when its configured
refresh is reload. Ordinary configuration changes use the service's
selected refresh action instead. The page
Service recovery describes the record
of what each service loaded.
Removal
state: absent removes the named complete unit file or drop-in. It accepts
only name, drop_in, in_systemd_of_user_account, and state, and removes
only that regular file. It leaves vendor definitions, other drop-ins, and
directories intact.
It does not stop or disable the unit. A decommissioning playbook declares
those service actions first, with a systemd_service task, before removing
unit files and accounts. Running it again succeeds when the service is
already stopped and its unit is gone, and also when the account of a unit in
an account's own systemd is gone: such a removal, and such a stop or disable
by systemd_service, then reports unchanged.
Unit kinds and their names
- A
.mountunit must be named for its escaped mount point:srv-data.mountfor/srv/data, andsrv-my\x2ddata.mountfor/srv/my-data, assystemd-escape --path --suffix=mount /srv/my-dataprints it. systemd's check rejects a mismatched name before installation. Starting the mount unit mounts the filesystem at the mount point. Enabling the mount unit with an[Install]section mounts the filesystem at boot. - A
.swapand an.automountunit are named for their escaped path, like a.mountunit:systemd-escape --path --suffix=swap /var/swapfileprintsvar-swapfile.swap. - An automount needs the
.mountunit of the same path, and that mount must not be mounted when the automount starts. .service,.timer,.path,.socket,.target, and.sliceunits need no additionalsystemd_unitYAML fields for the unit kind. Whatsystemd_servicedoes with each kind is on its page.
Units in an account's own systemd
- The unit file goes to
<home>/.config/systemd/user/of the account, owned by the account; a drop-in goes to the matching.ddirectory there. - The account and its home directory must exist when a task installs a unit
file. Create them with
useranddirectorytasks before the node task block, as in the example. A removal of a unit file of an account that does not exist reports unchanged. - MMX writes the file as root into the account's home and never follows a link there that leads out of the home.
- The account runs systemd's check of its new unit file
(
systemd-analyze verify --user), as its own systemd reads its units. MMX gives the check a copy of the new file in the node task's private directory, which is the account's for the check. MMX ends a check that does not end within one minute.podman_quadletchecks an account's Quadlet file in the same way. - Lingering. An account's systemd normally stops when the account's last
login session ends, and does not start at boot. A task with
in_systemd_of_user_accountthat installs, starts, or enables a unit turns on what systemd calls lingering for the account: its units start at boot and keep running after logout. A task that only stops, disables, or removes leaves lingering as it is. The task reports it the first time: "Enabled lingering for account reports, so its services start at boot and keep running after logout". There is no setting for it. - While the account's systemd is not running. With lingering off and
nobody logged in, the account's systemd does not run, so none of its units
runs either. A
systemd_servicetask that only stops, disables, masks, or unmasks then reads and changes whether the unit is enabled or masked in the account's unit files themselves (systemctl --userwithSYSTEMD_OFFLINE=1). It starts nothing, also in a dryrun, which reports what a run would change. - A unit in an account's systemd is enabled for
default.target, notmulti-user.target, which belongs to the system. - Root's units are system units. Validation rejects
in_systemd_of_user_account: root. - The service record of such a unit is kept for the account and the unit
together, so
report-worker.serviceof two accounts are two services.
Examples that combine the unit modules
The application-service example and
the account-and-unit example
exercise systemd_unit together with the account and service modules. The
limited application controls
use a .path unit that systemd_unit installs.
Errors and what they mean
systemd_unit: systemd's check of the new unit file failed: ...systemd rejected the new file, together with the base unit and the installed drop-ins. The installed file stays. Read systemd's words after the colon and correct the unit.- A drop-in whose base unit is missing. The run fails as a missing prerequisite, and the node task is not tried again. Install the base unit, or the package that brings it, in an earlier node task. A dryrun reports the check of a changed unit as not checked, because its prerequisites may not exist yet. A dryrun previews the contents and writes no temporary new unit file.
- A
.mount,.swap, or.automountunit with the wrong name. systemd's check rejects it before installation. Name it assystemd-escapeprints. in_systemd_of_user_account: root. Validation rejects it. Write the unit without the field; it is a system unit.- The account's check does not end within one minute. MMX ends it and the task fails. Look for a file in the account's unit directory that is not a regular file, such as a named pipe.
Tested on
Distributions: Debian 12 and 13, Ubuntu 24.04 and 26.04, Arch Linux, openSUSE Leap 16.1, Rocky Linux 9, AlmaLinux 10, Fedora 45.
The base suite covers this module (account_units.py, file_resources.py, external_modules.py) and runs on every tested distribution.
The suite account_units.py covers every unit kind that systemd_unit
installs: a service with a drop-in, a timer, a socket, a mount, a target with
a member service in a slice, an automount, and a swap file. It also covers a
unit in an account's own systemd, whose new file the account itself checks,
with a link in its unit directory to a file that only root can read. The
suite runs in a virtual machine on Debian 12 and 13 and Ubuntu 24.04 and 26.04, because its automount
unit needs autofs, which a container cannot use. server_resources.py
covers new unit files and template and alias drop-ins.
The whole catalog runs both suites on Debian 12 and 13 and Ubuntu 24.04 and 26.04 (validation record).
Why it works this way
- systemd checks the new file before it replaces the installed one. A unit that systemd rejects never reaches the node's running configuration.
- An interrupted manager reload needs no MMX record. systemd's own
NeedDaemonReloadsays that a reload is still owed. - The triggering unit is named in
activate, not the service it starts. After a changed definition, the manager reload means the service's next activation uses the new one. - The account itself checks its new unit file, on a copy. The account fills its unit directory, so a check that root ran there would read whatever a link in it points to, such as a file that only root may read. Root does nothing there by a path either.
- The account's check ends after one minute at the latest. A file in the unit directory that is not a regular file, such as a named pipe, can make systemd wait without end.
- Lingering is turned on without a setting. A unit that MMX manages must not stop because somebody logged out; the opposite is never what such a task means.
This page is docs/reference/modules/systemd_unit.md in the MMX repository.