Linux: tmpfiles.d
tmpfiles.d is a declarative way to say “this path must exist, with this owner and mode, and old files inside it must be removed”.
The configs are applied by systemd-tmpfiles at boot and on a timer.
Typical uses:
- create directories in
/run(tmpfs, empty after every reboot) - clean up
/tmp,/var/tmp, caches, and old logs by age - fix owner and permissions on existing paths
- create symlinks, copy default configs
- write values to
/sysand/procat boot
Contents#
- Where configs live
- Line format
- Types
- Modifiers
- Mode, owner, age
- Specifiers
- When it runs
- Commands
- Examples
- User tmpfiles
- tmpfiles.d vs unit directives
- Gotchas
1. Where configs live#
| Directory | Who writes it |
|---|---|
/etc/tmpfiles.d/ |
admin, highest priority |
/run/tmpfiles.d/ |
runtime generated |
/usr/local/lib/tmpfiles.d/ |
locally installed software |
/usr/lib/tmpfiles.d/ |
distribution packages |
Rules:
- Files must end in
.conf. - A file in
/etc/tmpfiles.d/with the same name as one in/usr/lib/tmpfiles.d/replaces it completely. - To disable a vendor file, symlink it to
/dev/null:
ln -s /dev/null /etc/tmpfiles.d/tmp.conf
- All files from all directories are sorted by file name and processed in that order, regardless of the directory.
- If two files contain a line for the same path, the line from the file whose name sorts first wins. That is why local overrides often get names like
00-local.conf.
See the final merged config:
systemd-tmpfiles --cat-config
2. Line format#
#Type Path Mode User Group Age Argument
d /run/myapp 0750 myapp myapp - -
- Fields are separated by whitespace. Lines starting with
#are comments. -means “default” or “not used”.- Trailing fields can be omitted.
- A path with spaces must be quoted. C-style escapes like
\x20also work. - Most types accept glob patterns in the path (
r,R,w,z,Z,x,X,eand others).
3. Types#
Create things:
| Type | What it does |
|---|---|
f |
Create a file if it does not exist. If Argument is set, write it into the file only on creation |
f+ |
Create a file or truncate an existing one, then write Argument |
w |
Write Argument into an existing file. Does not create it. Typical for /sys and /proc |
w+ |
Same as w, but append |
d |
Create a directory. If it exists, fix mode and owner. Contents are cleaned by Age |
D |
Like d, but the contents are removed on --remove (at boot) |
e |
Like d, but only for an existing directory, never creates it. Useful for cleanup only |
v |
Create a btrfs subvolume, a plain directory on other filesystems |
q, Q |
Like v, plus btrfs quota group settings |
p, p+ |
Create a named pipe (FIFO). + replaces whatever exists at the path |
L, L+ |
Create a symlink to Argument. L+ replaces an existing file or symlink |
c, c+ |
Create a character device node |
b, b+ |
Create a block device node |
C, C+ |
Copy a file or directory tree from Argument, only if the target does not exist (or is an empty directory). C+ copies recursively into an existing directory, skipping files that already exist. If Argument is omitted, the source is /usr/share/factory/<path> |
Remove things:
| Type | What it does |
|---|---|
r |
Remove a file or an empty directory |
R |
Remove recursively |
Exclude from cleanup:
| Type | What it does |
|---|---|
x |
Do not clean this path and its contents |
X |
Do not clean this path itself, but its contents can still be cleaned |
Fix attributes of existing paths:
| Type | What it does |
|---|---|
z |
Set mode, owner, SELinux label. Not recursive |
Z |
Same, recursively |
t, T |
Set extended attributes (xattr). T is recursive |
h, H |
Set file attributes like chattr (+C, +i, …). H is recursive |
a, a+ |
Set POSIX ACL. a+ adds to the existing ACL instead of replacing it |
A, A+ |
Same, recursively |
4. Modifiers#
Modifiers are appended to the type letter, for example d!, L+, w-.
| Modifier | Meaning |
|---|---|
! |
Apply the line only at boot (--boot). Safe for things that must not run again on a live system |
- |
Ignore errors when creating the path |
= |
If the path exists but has the wrong type (a file instead of a directory, for example), remove it first |
~ |
Argument is base64-encoded |
^ |
Argument is the name of a systemd credential, its value is used as content |
+ |
Type-specific: replace, overwrite, append. See the tables above |
5. Mode, owner, age#
Mode
-uses the default:0644for files,0755for directories.~0750: mask by the existing mode. If the path has no execute bits, they are not added (same for read and write). Useful withZto avoid making all files executable.:0640: apply the mode only when the path is created. An existing path keeps its mode.
User / Group
- A name or a numeric ID.
-meansroot(or the current user in--usermode). - A
:prefix (:myapp) means the same as for mode: set only on creation. - The user must exist when the line is applied. For service users, create them with
sysusers.dfirst. At bootsystemd-sysusersruns beforesystemd-tmpfiles.
Age
How old a file must be to be removed during cleanup. - means “never clean”.
10s 30min 12h 7d 4w
By default the newest of atime, mtime, ctime (and btime) is compared with the age.
This can be narrowed with a prefix before ::
| Letter | Timestamp | Applies to |
|---|---|---|
a / A |
access | files / directories |
b / B |
birth | files / directories |
c / C |
change | files / directories |
m / M |
modify | files / directories |
# Remove files that have not been modified for 7 days, ignore atime
d /var/cache/myapp 0755 myapp myapp mM:7d
A ~ before the age (~7d) cleans only the second level and below. Files and directories directly inside the path are kept.
Cleanup also skips:
- files and directories that are excluded with
x/X - directories that are locked with
flock(LOCK_EX)orflock(LOCK_SH). An application can lock its directory in/tmpso nothing is deleted while it runs - mount points
6. Specifiers#
Lines can contain % specifiers. Most useful:
| Specifier | Value |
|---|---|
%h |
user home directory |
%u / %U |
user name / UID |
%g / %G |
group name / GID |
%t |
runtime directory: /run or $XDG_RUNTIME_DIR |
%S |
state directory: /var/lib or ~/.local/state |
%C |
cache directory: /var/cache or ~/.cache |
%L |
logs directory: /var/log or ~/.local/state/log |
%T |
/tmp |
%V |
/var/tmp |
%H |
hostname |
%m |
machine ID |
%b |
boot ID |
%% |
a literal % |
%h, %t, %S, %C are most useful in user mode, see User tmpfiles.
7. When it runs#
| Unit | When | What |
|---|---|---|
systemd-tmpfiles-setup-dev-early.service, systemd-tmpfiles-setup-dev.service |
early boot | only device nodes and /dev related lines |
systemd-tmpfiles-setup.service |
boot | --create --remove --boot |
systemd-tmpfiles-clean.timer |
15 min after boot, then daily | --clean |
Change the cleanup schedule:
systemctl edit systemd-tmpfiles-clean.timer
[Timer]
OnUnitActiveSec=
OnUnitActiveSec=6h
Package managers also apply a new config right after install: Arch has a pacman hook, RPM-based distributions use the %tmpfiles_create macro, Debian uses a dh_installtmpfiles snippet.
8. Commands#
# Apply create lines from all configs
systemd-tmpfiles --create
# Apply only one file (name or full path)
systemd-tmpfiles --create myapp.conf
systemd-tmpfiles --create /etc/tmpfiles.d/myapp.conf
# Run cleanup by age
systemd-tmpfiles --clean
# Remove paths marked with r, R, D
systemd-tmpfiles --remove
# Only for paths under a prefix
systemd-tmpfiles --create --prefix=/run/myapp
# Show what would happen, change nothing (systemd 256+)
systemd-tmpfiles --dry-run --clean
# Merged config
systemd-tmpfiles --cat-config
# Short syntax reference (systemd 255+)
systemd-tmpfiles --tldr
Debugging:
SYSTEMD_LOG_LEVEL=debug systemd-tmpfiles --clean
journalctl -u systemd-tmpfiles-setup.service -u systemd-tmpfiles-clean.service
Lines with ! are applied only together with --boot. If a manual --create “does nothing”, check for !.
9. Examples#
Runtime directory for a daemon (/run is empty after reboot)
# /etc/tmpfiles.d/myapp.conf
d /run/myapp 0750 myapp myapp -
Cache with cleanup by age
d /var/cache/myapp 0750 myapp myapp 14d
Clean an existing directory, do not create it
e /srv/uploads/tmp - - - 2d
Keep some files in /tmp from cleanup
x /tmp/build-cache-*
X /tmp/shared
Change /tmp cleanup age
Find the vendor file first:
systemd-tmpfiles --cat-config | grep -E '^[^#].* /tmp( |$)'
Then override it with a file of the same name in /etc/tmpfiles.d/ (usually tmp.conf):
# /etc/tmpfiles.d/tmp.conf
q /tmp 1777 root root 3d
q /var/tmp 1777 root root 30d
Remember that a file with the same name replaces the whole vendor file. Copy all lines you want to keep.
Kernel settings in /sys at boot
# /etc/tmpfiles.d/thp.conf
w- /sys/kernel/mm/transparent_hugepage/enabled - - - - madvise
w- /sys/kernel/mm/transparent_hugepage/defrag - - - - defer+madvise
- ignores the error on hosts where the file does not exist. For /proc/sys values prefer sysctl.d.
Fix owner and permissions of logs
Z /var/log/myapp ~0750 myapp adm -
With ~ files without execute bits get 0640, directories get 0750.
Symlink
L+ /etc/myapp/config.toml - - - - /srv/config/myapp.toml
Default config, copied only once
C /etc/myapp/config.toml - - - - /usr/share/myapp/config.toml.example
File with initial content
f /var/lib/myapp/settings.ini 0640 myapp myapp - mode=default
The content is written only on creation. Edits made later are not overwritten.
Remove leftovers at boot
r! /var/lib/myapp/*.pid
R! /var/tmp/myapp-*
Disable copy-on-write for database files on btrfs
d /var/lib/postgres/data 0700 postgres postgres -
h /var/lib/postgres/data - - - - +C
+C only affects files created after the attribute is set.
10. User tmpfiles#
The same mechanism works per user with --user. Directories:
| Directory | Scope |
|---|---|
~/.config/user-tmpfiles.d/ |
this user |
~/.local/share/user-tmpfiles.d/ |
this user |
/etc/xdg/user-tmpfiles.d/ |
all users, admin |
/usr/share/user-tmpfiles.d/ |
all users, packages |
Units (in the user’s systemd instance):
systemd-tmpfiles-setup.service: at loginsystemd-tmpfiles-clean.timer: periodic cleanup
Example: clean ~/Downloads and ~/.cache automatically:
# ~/.config/user-tmpfiles.d/cleanup.conf
e %h/Downloads - - - 30d
e %C - - - 60d
Check and apply:
systemd-tmpfiles --user --dry-run --clean
systemctl --user enable --now systemd-tmpfiles-clean.timer
11. tmpfiles.d vs unit directives#
For a directory used by a single service, unit directives are usually simpler:
[Service]
RuntimeDirectory=myapp # /run/myapp, removed when the service stops
StateDirectory=myapp # /var/lib/myapp
CacheDirectory=myapp # /var/cache/myapp
LogsDirectory=myapp # /var/log/myapp
RuntimeDirectoryMode=0750
They create the directory with the service user as owner and work with DynamicUser=.
Use tmpfiles.d when:
- the path must exist before the service starts, or without any service
- several services or users share the path
- cleanup by age is needed
- the path must survive service restarts (
RuntimeDirectory=is removed on stop unlessRuntimeDirectoryPreserve=yes) - you need symlinks, copies, ACLs, xattrs, or writes to
/sys
12. Gotchas#
- Same file name = full replacement.
/etc/tmpfiles.d/tmp.confhides every line of/usr/lib/tmpfiles.d/tmp.conf, not just the one you changed. fdoes not overwrite. If the file already exists, the content is ignored. Usef+orwto enforce it.Zwith a plain mode makes every file executable if the mode hasx. Use~orzon the top directory only.dfixes permissions every time it runs. If an application changes them deliberately, use:0750so the mode is set only on creation.- Cleanup by atime. With
noatimeorrelatimeatime is updated rarely or never. Files that are read often may still look old. Use them:/mM:prefix if only modification matters. - Long running jobs in
/tmp. A file unchanged for 10 days can be removed while a process still has it open. Lock the directory withflockor exclude it withx. - Service user does not exist yet. The line fails. Ship a
sysusers.dfile next to thetmpfiles.dfile. PrivateTmp=yes. The service sees its own/tmp, lines for/tmp/...affect the host/tmp, not the private one.- Syntax errors do not stop processing. Bad lines are skipped and logged. Check after editing:
systemd-tmpfiles --create --dry-run /etc/tmpfiles.d/myapp.conf
References#
man 5 tmpfiles.dman 8 systemd-tmpfilesman 5 sysusers.dman 5 systemd.exec(RuntimeDirectory=and friends)