Systemd-tmpfiles: Managing Ephemeral Filesystem Lifecycles, Provisioning Runtime Directories, and Enforcing Inode Security Policies in Production

This is a scenario every system administrator eventually encounters. In modern Linux systems, directories like /run live purely in temporary memory—a pristine slate that is wiped clean on every power cycle. When an unprivileged service boots up and finds its essential communication sockets or lock files missing, it panics and halts. For decades, sysadmins tried to patch over this instability with brittle shell scripts, custom startup wrappers, and blunt cron jobs that occasionally deleted active database files by mistake.

The modern Unix solution to this chaos is systemd-tmpfiles—a declarative engine designed to automatically create, clean, and manage the lifecycle of temporary files and volatile directories.

To see what this tool is doing on your server right now without risking any unintended changes, run this safe dry-run command:

systemd-tmpfiles --dry-run --clean

% systemd-tmpfiles --dry-run --clean
Would remove directory "/tmp/systemd-private-7c5b12879c934988bb1b82-systemd-resolved.service-w4Hj8a/tmp" (age 3d 14h > 1d)
Would remove file "/var/tmp/ccK9Z4j1.o" (age 31d 2h > 30d)
Would purge sub-tree "/var/cache/nginx/client_temp/0000000014" (age 48h 12m > 24h)

In a single pass, this command inspects your storage against system retention policies, showing you exactly which stale caches, dead sockets, and leftover temporary files are queued for removal.

What It Does in Plain English

Rather than relying on uncoordinated shell scripts to create folders on boot and purge old files on schedules, systemd-tmpfiles lets administrators state what the filesystem should look like using simple, structured configuration files.

At system boot, the utility reads these definitions and deterministically provisions every required path with the exact ownership, permissions, and security contexts specified. In the background, automated timers periodically invoke the engine to sweep expired files based on explicit age thresholds, ensuring disks do not fill up unnoticed.

The Architecture of Declarative Filesystem Management

Historically, Linux distributions relied on tools like tmpwatch and tmpreaper, driven by periodic cron jobs that traversed /tmp and /var/tmp. This imperative model had three major design flaws:

1. Time-of-Check to Time-of-Use (TOCTOU) Exploits: Attackers could watch for cleanup scripts running as root and swap out targeted temporary files with symlinks, tricking the script into deleting system files or changing permissions on critical host resources.
2. Inconsistent Boot States: When individual applications used their own bespoke scripts to provision directories under /var/run or /tmp, any unexpected crash or restart left directories missing or misconfigured.
3. Security Context Ignorance: Traditional shell scripts often failed to apply SELinux security contexts and POSIX Access Control Lists (ACLs), leaving runtime files in insecure states.

systemd-tmpfiles addresses these vulnerabilities by integrating directly with modern Linux kernel primitives. It uses secure directory traversal syscalls like openat2(2) with flags such as RESOLVE_NO_SYMLINKS and O_NOFOLLOW to block symlink manipulation attacks, performing path creation and permission adjustments atomically.

Configuration File Precedence

Configuration files are organized into a strict three-tier hierarchy evaluated in lexical order:

• /etc/tmpfiles.d/*.conf: The top tier, reserved for local site administrators. Directives placed here override all others.
• /run/tmpfiles.d/*.conf: Transient configurations generated dynamically by running system services or container runtimes.
• /usr/lib/tmpfiles.d/*.conf: Default lifecycle rules supplied by the operating system and package managers.

If configuration files across different tiers share the same filename (such as redis.conf), the version in the higher directory completely replaces the lower one. To disable a vendor-supplied rule without editing package files, an administrator can simply link that filename in /etc/tmpfiles.d/ to /dev/null.

The Grammar of tmpfiles.d

Every configuration file inside tmpfiles.d uses a clean seven-column, whitespace-separated format:

# Type  Path              Mode  User  Group  Age  Argument
d       /run/api-gateway  0755  app   app    -    -

Each column controls a specific aspect of the target path: * Type: A single letter defining the filesystem action to perform (e.g. create a directory, write a file, purge old contents). * Path: The target file or directory path, supporting wildcards. * Mode: The file creation mask (such as 0755 or 0644), or - to keep defaults. * User: The owner username or numeric UID, or - for root (0). * Group: The owning group name or numeric GID, or - for root (0). * Age: The retention limit before cleanup (e.g. 10d, 24h, 30m), or - to disable age-based removal. * Argument: Extra parameters, such as symlink targets, POSIX ACL strings, file content, or copy sources.

Core Operational Modes

The systemd-tmpfiles command executes specific lifecycle tasks depending on the operational flag supplied:

• --create: Creates all declared directories, files, pipes, and symlinks, applying permissions and owners.
• --clean: Evaluates file ages against access, modification, and status timestamps, pruning expired items.
• --remove: Deletes items specified by removal directives (r, R, D).
• --boot: Instructs the engine that the system is booting; executes lines marked with an exclamation mark (!) meant for one-time startup initialization.
• --dry-run: Validates configuration syntax and displays all proposed filesystem changes without writing anything to disk.
• --cat-config: Prints all active configuration directives across all tiers in order of precedence.
• --prefix=PATH: Restricts execution to directives that match the given path prefix.

Five Real-World Production Use Cases

Use Case 1: Provisioning Volatile IPC Sockets and FIFOs under /run

The Scenario

An unprivileged gRPC microservice (micro-proxy), running as the system user proxy-svc (UID 980, GID 980), requires a dedicated socket directory /run/micro-proxy and a named pipe /run/micro-proxy/control.pipe before the service starts. Because /run is mounted as temporary memory (tmpfs), the directory disappears every time the machine restarts. Because the service runs without root privileges, it cannot create the directory itself, causing the service to fail on boot.

The Configuration and Execution

The administrator declares the runtime requirements in /etc/tmpfiles.d/micro-proxy.conf:

# /etc/tmpfiles.d/micro-proxy.conf
# Type  Path                          Mode  User       Group      Age  Argument
d       /run/micro-proxy              1750  proxy-svc  proxy-svc  -    -
p       /run/micro-proxy/control.pipe 0660  proxy-svc  proxy-svc  -    -

The administrator then applies the configuration immediately:

systemd-tmpfiles --create /etc/tmpfiles.d/micro-proxy.conf --verbose

Realistic Terminal Output

% systemd-tmpfiles --create /etc/tmpfiles.d/micro-proxy.conf --verbose
Created directory "/run/micro-proxy".
Setting mode 1750 on "/run/micro-proxy".
Setting owner 980:980 on "/run/micro-proxy".
Created FIFO "/run/micro-proxy/control.pipe".
Setting mode 0660 on "/run/micro-proxy/control.pipe".
Setting owner 980:980 on "/run/micro-proxy/control.pipe".

Detailed Breakdown

• d /run/micro-proxy 1750 proxy-svc proxy-svc - -: Ensures the directory exists. The 1750 mode grants read/write/execute to the user, read/execute to the group, no access to others, and adds the sticky bit (1) so users cannot delete files they do not own.
• p /run/micro-proxy/control.pipe 0660 proxy-svc proxy-svc - -: Creates the named pipe (FIFO) with read and write permissions for the service user and group.
• The - dashes in the Age and Argument columns mean these paths are excluded from automatic age-based deletion.

What the Sysadmin Does Next

The administrator verifies the permissions using ls -ld /run/micro-proxy and ls -l /run/micro-proxy/control.pipe, checking that the FIFO file type indicator (prw-rw----) is present. They then add Wants=systemd-tmpfiles-setup.service and After=systemd-tmpfiles-setup.service to the service unit file to ensure systemd sets up the directory before launching the daemon.

Use Case 2: Automating Age-Based Garbage Collection on Batch Upload Trees

The Scenario

A video processing server stores incoming upload chunks in /var/cache/media-ingest/uploads. Client dropouts and network interruptions leave orphaned file fragments on disk. Over time, the storage volume fills up, triggering disk capacity alerts. The team needs an automated cleanup policy that removes upload files older than 24 hours without deleting the parent folder structure.

The Configuration and Execution

The administrator declares the retention policy in /etc/tmpfiles.d/media-ingest.conf:

# /etc/tmpfiles.d/media-ingest.conf
# Type  Path                             Mode  User        Group       Age  Argument
d       /var/cache/media-ingest          0775  media-proc  media-proc  -    -
e       /var/cache/media-ingest/uploads  0770  media-proc  media-proc  24h  -

The administrator runs a cleanup cycle:

systemd-tmpfiles --clean /etc/tmpfiles.d/media-ingest.conf --verbose

Realistic Terminal Output

% systemd-tmpfiles --clean /etc/tmpfiles.d/media-ingest.conf --verbose
Directory "/var/cache/media-ingest" already exists, mode 0775, owner 1001:1001.
Scanning directory "/var/cache/media-ingest/uploads" for age cleanup.
Removed file "/var/cache/media-ingest/uploads/chunk_9841a_part12.tmp" (atime 27h 14m ago > 24h).
Removed file "/var/cache/media-ingest/uploads/chunk_1102f_part03.tmp" (mtime 25h 02m ago > 24h).
Removed empty directory "/var/cache/media-ingest/uploads/session_88192" (mtime 26h 45m ago > 24h).
Cleaned directory contents in "/var/cache/media-ingest/uploads".

Detailed Breakdown

• d /var/cache/media-ingest 0775 media-proc media-proc - -: Provisions the parent directory with 0775 permissions.
• e /var/cache/media-ingest/uploads 0770 media-proc media-proc 24h -: The e directive cleans directory contents based on age without recreating the folder if it is absent.
• 24h: Instructs the engine to check access (atime), modification (mtime), and metadata change (ctime) timestamps. If all three exceed 24 hours, the file or sub-directory is safely deleted.

What the Sysadmin Does Next

The administrator checks that the native systemd cleanup timer is enabled with systemctl list-timers systemd-tmpfiles-clean.timer. This built-in timer runs systemd-tmpfiles --clean once every 24 hours across all configured paths automatically.

Use Case 3: Enforcing Recursive SELinux Contexts and POSIX ACL Drift Remediation

The Scenario

A shared data warehouse directory, /srv/analytics/warehouse, is accessed by automated data loaders and data scientists via SFTP and NFS mounts. Over time, restrictive default user masks leave new files with permissions like 0600, blocking colleagues from reading them. In addition, external dataset imports lack the mandatory SELinux label (analytics_data_t), causing access denial errors in production.

The Configuration and Execution

The administrator creates /etc/tmpfiles.d/analytics-perms.conf to enforce default permissions and SELinux security contexts:

# /etc/tmpfiles.d/analytics-perms.conf
# Type  Path                      Mode  User        Group     Age  Argument
d       /srv/analytics/warehouse  2770  etl-worker  analysts  -    -
Z       /srv/analytics/warehouse  -     -           -         -    -
A+      /srv/analytics/warehouse  -     -           -         -    default:group:analysts:rwx,default:mask::rwx

The administrator applies the rules across the entire storage tree:

systemd-tmpfiles --create /etc/tmpfiles.d/analytics-perms.conf --verbose

Realistic Terminal Output

% systemd-tmpfiles --create /etc/tmpfiles.d/analytics-perms.conf --verbose
Directory "/srv/analytics/warehouse" exists, mode 2770, owner 1004:1005.
Relabeling SELinux context on "/srv/analytics/warehouse" and all sub-paths (Z directive).
Updated SELinux label on "/srv/analytics/warehouse/2026/q1_metrics.parquet" -> system_u:object_r:analytics_data_t:s0.
Updated SELinux label on "/srv/analytics/warehouse/2026/q2_metrics.parquet" -> system_u:object_r:analytics_data_t:s0.
Applying POSIX ACLs recursively via A+ directive on "/srv/analytics/warehouse".
Setfacl applied: default:group:analysts:rwx,default:mask::rwx.

Detailed Breakdown

• d ... 2770 etl-worker analysts: Applies the setgid bit (2), ensuring all newly created subdirectories automatically inherit the analysts group.
• Z /srv/analytics/warehouse - - - - -: The uppercase Z directive recursively applies the correct SELinux security label from the system policy across all nested files and folders (similar to running restorecon -R).
• A+ /srv/analytics/warehouse ...: The A+ directive recursively applies default POSIX ACLs, guaranteeing that future files created inside this tree always inherit read, write, and execute permissions for the analysts group.

What the Sysadmin Does Next

The administrator audits the directory with getfacl /srv/analytics/warehouse and ls -laZ /srv/analytics/warehouse to verify that both the default ACL mask and the SELinux context system_u:object_r:analytics_data_t:s0 are active.

Use Case 4: Provisioning Copy-on-Write Subvolumes and Btrfs Quota Scratch Spaces

The Scenario

A container build platform generates staging root filesystems inside /var/lib/containers/scratch on a Btrfs storage pool. The staging directory needs to be an independent Btrfs subvolume to support instant copy-on-write snapshotting. To prevent unconstrained container builds from exhausting the host disk, the subvolume must have an enforced quota limit of 50 GiB upon creation.

The Configuration and Execution

The administrator declares the Btrfs subvolume in /etc/tmpfiles.d/container-scratch.conf:

# /etc/tmpfiles.d/container-scratch.conf
# Type  Path                         Mode  User  Group  Age  Argument
q       /var/lib/containers/scratch  0700  root  root   -    50G

The administrator runs the creation command:

systemd-tmpfiles --create /etc/tmpfiles.d/container-scratch.conf --verbose

Realistic Terminal Output

% systemd-tmpfiles --create /etc/tmpfiles.d/container-scratch.conf --verbose
Detected Btrfs filesystem at "/var/lib/containers".
Creating Btrfs subvolume at "/var/lib/containers/scratch".
Btrfs subvolume "/var/lib/containers/scratch" successfully instantiated.
Assigning Btrfs qgroup quota limit 53687091200 bytes (50G) to "/var/lib/containers/scratch".
Setting mode 0700 on "/var/lib/containers/scratch".
Setting owner 0:0 on "/var/lib/containers/scratch".

Detailed Breakdown

• q: Directs systemd-tmpfiles to check the filesystem. When Btrfs is detected, it runs btrfs subvolume create rather than a standard directory creation call, and sets up a Btrfs quota group (qgroup).
• /var/lib/containers/scratch: The target subvolume path.
• 0700 root root: Restricts read and write permissions exclusively to the root user.
• 50G: Sets the maximum referenced data quota limit for the subvolume.

What the Sysadmin Does Next

The administrator verifies the subvolume and quota allocation with native Btrfs management tools:

btrfs subvolume list /var/lib/containers
btrfs qgroup show -pcre /var/lib/containers/scratch

Use Case 5: Configuring Safe Exclusion Masks to Shield Database Lock Files and Active Mapped Caches

The Scenario

An embedded database stores its active lock files, shared memory segments, and transaction files in /tmp/db-engine/. During regular maintenance, the system cleanup job purges files older than 10 days. Because some database locks remain untouched for weeks during normal operations, the cleanup script unlinks active locks, causing concurrent worker processes to write simultaneously and corrupt the database.

The Configuration and Execution

The administrator creates an explicit exclusion policy in /etc/tmpfiles.d/db-engine-shield.conf:

# /etc/tmpfiles.d/db-engine-shield.conf
# Type  Path                       Mode  User       Group      Age  Argument
d       /tmp/db-engine             0750  db-engine  db-engine  -    -
x       /tmp/db-engine/*.lock      -     -          -          -    -
x       /tmp/db-engine/mmap.*      -     -          -          -    -
X       /tmp/db-engine/active-tx/  -     -          -          -    -

The administrator verifies that active database files are protected using a dry run:

systemd-tmpfiles --clean --dry-run --verbose

Realistic Terminal Output

% systemd-tmpfiles --clean --dry-run --verbose
Evaluating /tmp cleanup configuration against active exclusions.
Exclusion matched: "/tmp/db-engine/catalog.lock" matching pattern "/tmp/db-engine/*.lock", skipping.
Exclusion matched: "/tmp/db-engine/mmap.shm" matching pattern "/tmp/db-engine/mmap.*", skipping.
Exclusion matched: "/tmp/db-engine/active-tx" (directory contents protected via X directive), skipping.
Would remove file "/tmp/unrelated-stale-upload.tmp" (age 14d 2h > 10d).
Cleanup dry-run complete: 3 protected paths shielded, 1 path marked for deletion.

Detailed Breakdown

• d /tmp/db-engine 0750 db-engine db-engine - -: Ensures the base directory is configured with restricted permissions.
• x /tmp/db-engine/*.lock - - - - -: The lowercase x directive marks matching filenames for absolute exclusion from age-based cleanup, regardless of age.
• x /tmp/db-engine/mmap.* - - - - -: Protects memory-mapped backing files while they are attached to active daemons.
• X /tmp/db-engine/active-tx/ - - - - -: The uppercase X directive shields all files inside the specified folder from automatic removal while still allowing the directory itself to be managed.

What the Sysadmin Does Next

The administrator commits the configuration file to their infrastructure repository (such as Ansible, Puppet, or Terraform), confident that automated background cleanups will never delete essential database state.

Common Pitfalls and How to Avoid Them

1. The Dangerous Difference Between d and D

The most critical mistake is using the uppercase D directive instead of lowercase d on directories that hold important data:

# DANGEROUS:
D /var/log/audit-pipeline 0755 root root - -

While d creates a directory if missing and updates its permissions, D is designed to wipe the contents of the target directory when systemd-tmpfiles --remove is invoked. If an administrator uses D on a directory containing logs or state files, maintenance tasks will delete all files inside it. Always use lowercase d for any directory that stores persistent data.

2. File Age Calculations on noatime Filesystems

When systemd-tmpfiles --clean runs, it checks three timestamps: access time (atime), modification time (mtime), and metadata change time (ctime).

On high-performance servers, filesystems are often mounted with the noatime option to improve disk performance. Under noatime, reading a file does not update its atime. If an application continuously reads a static configuration or cache file without changing its contents, the file's timestamps remain unchanged. Once the elapsed time exceeds the configured age, systemd-tmpfiles will assume the file is abandoned and delete it.

To prevent this, you can specify which timestamp the engine should evaluate: * m24h: Check only modification time. * a7d: Check only access time. * c12h: Check only metadata change time. * Or use x to exclude critical static files entirely.

3. Finding Active Rules with --cat-config

When troubleshooting why a configuration rule is not behaving as expected, administrators often look only at /usr/lib/tmpfiles.d/, unaware that a file in /etc/tmpfiles.d/ is overriding it.

To see all merged rules currently running on your system across every tier, use:

systemd-tmpfiles --cat-config

To see detailed debug output when testing a new rule:

SYSTEMD_LOG_LEVEL=debug systemd-tmpfiles --create /etc/tmpfiles.d/custom.conf

Today's Takeaway

To gain immediate clarity over how temporary files and runtime directories are managed on your system, open a terminal right now and run systemd-tmpfiles --cat-config. Spend five minutes reviewing the merged output to see what vendor and local rules govern your /tmp, /var/tmp, and /run directories. You can replace messy cron jobs and ad-hoc mkdir startup scripts by placing clean .conf files in /etc/tmpfiles.d/, validating every change safely using systemd-tmpfiles --dry-run --create.

Authoritative Documentation & Reference Links

• systemd-tmpfiles(8) Manual — freedesktop.org
• tmpfiles.d(5) Configuration Specification — freedesktop.org
• systemd-tmpfiles Architecture & Usage — ArchWiki
• openat2(2) Linux Kernel System Calls Manual
• btrfs-subvolume(8) Administration Manual
• POSIX Access Control Lists (acl(5)) Manual
• SELinux Runtime Architecture and Contexts