systemd.path — File-Based Task Trigger
systemd.path is a built-in systemd mechanism that monitors files or directories for changes and automatically activates a corresponding .service unit when a filesystem event occurs. Instead of polling with cron or writing fragile inotifywait loops, you declare a tiny .path unit file and let the kernel handle the rest.
Who This Track Is For
- Linux administrators managing WordPress VPS, web servers, or any production workload
- DevOps engineers building event-driven automation pipelines
- Developers who need instant reactions to file changes without manual SSH
What You Will Build
- Event-driven file watchers that trigger services instantly
- Drop-folder queues that process files one at a time
- Signal-file patterns for remote cache flush, deployment, and maintenance
- Production-hardened path units with rate limiting and security sandboxing
How To Use This Track
- Follow the lessons in order (1 → 9). Each lesson builds on concepts from the previous one.
- Every lesson includes hands-on examples with expected output — run them on a test server.
- Treat this documentation as a reference after the first read-through.
Learning Path
| Module | Focus | What You Learn |
|---|---|---|
| 1. How It Works | Architecture and lifecycle | Two-unit model, event loop, kernel inotify integration |
| 2. Watch Directives | The 5 watch directives deep dive | PathExists, PathChanged, PathModified, DirectoryNotEmpty, PathExistsGlob |
| 3. Unit File Anatomy | Complete unit file reference | Every directive in [Path], [Unit], [Service], [Install] |
| 4. Commands and Management | CLI operations | systemctl, journalctl, daemon-reload, user units |
| 5. Practical Examples | 20 complete examples | Drop folders, signal files, config watchers, glob triggers |
| 6. Production Patterns | Hardening and reliability | Security sandboxing, rate limiting, timer fallback |
| 7. Debugging and Troubleshooting | Root-cause debugging | Common failures, inotify limits, step-by-step workflow |
| 8. Study Cases | Real-world scenarios | WordPress VPS, CI/CD, media pipeline, multi-tenant SaaS |
| 9. Cheatsheet and Quiz | Quick reference | One-page cheat sheet, 10-question quiz, hands-on lab |
Architecture at a Glance
Why systemd.path Over Alternatives
| Approach | Polling? | Built-in? | Concurrency Safe? | Logging? |
|---|---|---|---|---|
| systemd.path | No (event-driven) | Yes | Yes (oneshot queuing) | journald native |
| Cron + test -f | Yes (every minute) | Yes | No | Manual |
inotifywait loop | No | Requires inotify-tools | No | Manual |
| Custom daemon | No | No | Depends | Manual |
System Check
systemctl --version # Expected: systemd 230+ (path units require 230+)
Quick Start
5-minute-quick-start.sh
# 1) Create a service that processes dropped files
sudo tee /etc/systemd/system/test-drop.service > /dev/null <<'EOF'
[Unit]
Description=Process files from the test drop folder
[Service]
Type=oneshot
ExecStart=/bin/sh -c 'echo "[$(date +%%F\ %%T)] Processing:" && ls /tmp/drop && rm -f /tmp/drop/*'
EOF
# 2) Create a path unit that watches the folder
sudo tee /etc/systemd/system/test-drop.path > /dev/null <<'EOF'
[Unit]
Description=Watch /tmp/drop for incoming files
[Path]
DirectoryNotEmpty=/tmp/drop
MakeDirectory=yes
[Install]
WantedBy=paths.target
EOF
# 3) Activate
sudo systemctl daemon-reload
sudo systemctl enable --now test-drop.path
# 4) Test it
touch /tmp/drop/hello.txt
sleep 1
journalctl -u test-drop.service -n 10 --no-pager
Terminology
| Term | Meaning |
|---|---|
| Path unit | A .path file that defines what filesystem event to watch |
| Service unit | A .service file that defines what command to run |
| Unit pair | The .path + .service combination (same base name by default) |
| Watch directive | The PathExists=, PathChanged=, etc. line in the [Path] section |
| Trigger file | A file whose existence or modification activates the path unit |
| Signal file | An empty file created to signal an action (e.g., deploy.me) |
| Drop folder | A directory where files are placed for automated processing |
| inotify | The Linux kernel subsystem that provides filesystem event notifications |
paths.target | The systemd target that groups all path units |
daemon-reload | The command that tells systemd to re-read unit files from disk |
Next Step
Start with How It Works to understand the two-unit model and event-driven lifecycle.