Manage Temporary Files Safely with systemd-tmpfiles

You will create a directory with a tmpfiles.d rule, apply it without rebooting, and set an age-based cleanup policy that systemd can run later. The same workflow helps with runtime directories, caches and other files whose lifetime is independent of one service. Allow about fifteen minutes. You need systemd 255 or later, a shell, and root access for rules that write below system directories.

This guide describes the installed systemd package here: 255.4-1ubuntu8.17. The command reports systemd 255. Small details can differ in other releases, so check the local manual with man systemd-tmpfiles when adapting a rule.

1. Check the command and the cleanup timer

Start with read-only checks. These do not need elevated privileges:

$ command -v systemd-tmpfiles
/usr/bin/systemd-tmpfiles
$ systemd-tmpfiles --version
systemd 255
$ systemctl status systemd-tmpfiles-clean.timer --no-pager

The installed timer is scheduled 15 minutes after boot and then once per day. It starts systemd-tmpfiles-clean.service, which runs systemd-tmpfiles --clean. The timer is not a guarantee that every temporary file is removed: only rules with an age field participate, and the age calculation uses timestamps described by the rule.

Checkpoint: if the timer is inactive, do not enable it blindly on a production host. Find out why it is inactive and decide whether that host's systemd policy permits starting it.

2. Choose the right ownership model

For a daemon's private runtime directory, prefer RuntimeDirectory= in its service unit when that is sufficient. It ties the directory to the service lifetime. Use tmpfiles.d when the path is shared, must outlive a service, needs time-based cleanup, or needs more elaborate creation rules.

Local administrator rules belong in /etc/tmpfiles.d/. Vendor rules normally live in /usr/lib/tmpfiles.d/; a file with the same name in /etc/tmpfiles.d/ takes precedence. To disable a vendor file, the documented method is an /etc/tmpfiles.d/ symlink with the same name pointing to /dev/null. Do not edit files under /usr/lib/tmpfiles.d/, because a package upgrade can replace them.

3. Write a small creation rule

Suppose an application needs /var/cache/example-app. Create a local rule with elevated privileges:

$ sudo install -m 0644 /dev/null /etc/tmpfiles.d/example-app.conf
$ sudo sh -c 'printf "%s\n" "d /var/cache/example-app 0750 example example 30d -" > /etc/tmpfiles.d/example-app.conf'

That line means: create a directory, set mode 0750, assign it to the example user and group, and make entries inside it eligible for cleanup after 30 days. Replace both names with an existing system account. If the account is created by a package later in boot, use --graceful only when ignoring an unresolved account is genuinely safe.

The mode, user and group affect existing objects too, not only new ones. That is a security-sensitive change. Check the target and account before applying it:

$ getent passwd example
$ getent group example
$ sudo systemd-tmpfiles --cat-config --no-pager example-app.conf

The basename form makes systemd search the tmpfiles.d directories and use the highest-priority matching file. The output should show the rule and its filename.

4. Apply creation without waiting for boot

Apply only the named rule first. This limits the scope of the change:

$ sudo systemd-tmpfiles --create example-app.conf
$ sudo stat -c '%A %U %G %n' /var/cache/example-app
drwxr-x--- example example /var/cache/example-app

A successful command returns status 0. The rule's parent directories may be created implicitly with root ownership and mode 0755. Add separate d rules if a parent needs another mode or owner.

Do not add --boot to ordinary maintenance commands. It enables entries marked with !, which are reserved for actions safe only during boot and may break a running system.

5. Test cleanup before trusting it

--clean acts on every applicable configuration file unless you provide a narrower configuration argument. It can remove data, so inspect the rule and directory first:

$ sudo find /var/cache/example-app -maxdepth 1 -printf '%TY-%Tm-%Td %TH:%TM %p\n'
$ sudo systemd-tmpfiles --clean example-app.conf

Files newer than the configured age should remain. The installed documentation says that the default age check considers file access, modification and status-change timestamps, with a different default for directories. A file or directory protected by a shared or exclusive BSD lock, or anything below a locked entry, is skipped.

Do not use age 0 casually. It means unconditional cleanup whenever --clean runs. A D rule also removes directory contents when --remove runs. Those are destructive operations; preserve a backup or use a disposable test path before adopting them.

6. Use a disposable root for a safe dry run

For a new rule, test against a temporary filesystem tree instead of your live root. The command below uses an unprivileged rule, so it does not need sudo:

$ ROOT=\$(mktemp -d)
$ mkdir -p "\$ROOT/etc/tmpfiles.d" "\$ROOT/var/tmp"
$ printf '%s\n' 'd /var/tmp/example-cache 0700 - - -' > "\$ROOT/etc/tmpfiles.d/example.conf"
$ systemd-tmpfiles --create --root="\$ROOT" --no-pager "\$ROOT/etc/tmpfiles.d/example.conf"
$ stat -c '%A %U %G %n' "\$ROOT/var/tmp/example-cache"
drwx------ YOUR_USER YOUR_GROUP .../var/tmp/example-cache

--root= prefixes paths and configuration search locations with the alternate root. It also reads users and groups from that root rather than using network-backed name services. For an operating-system image, consider -E as well, which excludes virtual and memory-backed paths such as /dev, /proc, /run and /sys.

When finished, remove the disposable tree with rm -rf -- "\$ROOT" only after checking that ROOT contains the temporary path you intended. Never substitute an unresolved variable or a broad directory in a destructive command.

7. Diagnose failures and undo the rule

Status 65 means the configuration had syntax errors and some lines were ignored. Status 73 means the syntax was valid but an operation could not be carried out, commonly because of permissions, a missing parent or unsuitable filesystem content. Status 1 covers other failures.

For a rule that should no longer apply, first move it aside or delete it from /etc/tmpfiles.d/, then rerun the relevant operation. Removing a creation rule does not remove the directory it created. If the directory and its contents are no longer needed, review them explicitly and remove them with a separate, carefully targeted command. To restore only the configuration, use:

$ sudo mv /etc/tmpfiles.d/example-app.conf /etc/tmpfiles.d/example-app.conf.disabled
$ test ! -e /etc/tmpfiles.d/example-app.conf && echo 'rule disabled'

Do not run --clean as part of a configuration rollback: it may clean data, and removing a rule does not undo files already created. A configuration rollback and data deletion are separate decisions.