What is Unit File? | DevOps Dictionary

What Is a Unit File in Simple Terms

A unit file is a recipe card for systemd. It tells systemd everything it needs to know about a service: what to run, who to run it as, what it depends on, what to do if it crashes, and whether to start it at boot.

Before systemd, starting a service required writing a shell script with dozens of lines handling process management, PID files, logging, and restart logic. A systemd unit file does all of that in 15-20 lines of declarative configuration.

Unit file structure:

◈ DIAGRAM

/etc/systemd/system/payment-service.service
+----------------------------------------+
| [Unit]                                  |
|   Description=Payment Processing API    |
|   After=postgresql.service              |
+----------------------------------------+
| [Service]                               |
|   User=payment-svc                      |
|   ExecStart=/usr/bin/node index.js      |
|   EnvironmentFile=/etc/payment/env      |
|   Restart=on-failure                    |
|   RestartSec=5                          |
+----------------------------------------+
| [Install]                               |
|   WantedBy=multi-user.target            |
+----------------------------------------+

How It Works

Unit files are INI-style configuration with three sections. systemd reads them from specific directories, with later directories overriding earlier ones.

TEXT

Unit file search order (later wins):
/usr/lib/systemd/system/   Installed by packages -- do not edit
/etc/systemd/system/       Admin overrides -- edit these

Complete unit file anatomy:

INI

[Unit]
## Description shown in systemctl status
Description=My Payment Service
 
## Start after these units are active
After=network.target postgresql.service redis.service
 
## If these fail, this unit fails too
Requires=postgresql.service
 
## If these fail, try to start anyway
Wants=redis.service
 
[Service]
## Run as this user and group (never root)
User=payment-svc
Group=payment-svc
 
## Working directory
WorkingDirectory=/opt/payment-service
 
## The command to run
ExecStart=/usr/bin/node /opt/payment-service/index.js
 
## Command to gracefully stop (optional -- default is SIGTERM)
ExecStop=/bin/kill -TERM $MAINPID
 
## Command to reload config without restarting
ExecReload=/bin/kill -HUP $MAINPID
 
## Load environment variables from a file
## This is how secrets stay out of unit files
EnvironmentFile=/etc/payment-service/env
 
## Or set individual environment variables
Environment=NODE_ENV=production
Environment=PORT=4000
 
## Restart policy
## on-failure: restart if exits with non-zero or killed by signal
Restart=on-failure
RestartSec=5            ## wait 5 seconds before restarting
StartLimitInterval=60   ## within 60 seconds
StartLimitBurst=3       ## allow max 3 restarts before giving up
 
## Service type
## simple: ExecStart process IS the service (most common)
## forking: service forks and the parent exits (old-style daemons)
## oneshot: runs once and exits (good for setup scripts)
Type=simple
 
## File descriptor limits
LimitNOFILE=65536       ## override ulimit for this service
 
[Install]
## Which target to start this service in
## multi-user.target = standard server mode (no GUI)
WantedBy=multi-user.target

Overriding package unit files without editing them:

Bash

## Create an override directory
sudo mkdir -p /etc/systemd/system/nginx.service.d/
 
## Create an override file -- only the sections you change
sudo tee /etc/systemd/system/nginx.service.d/override.conf << 'EOF'
[Service]
LimitNOFILE=65536
Restart=always
RestartSec=3
EOF
 
## Reload and restart
sudo systemctl daemon-reload
sudo systemctl restart nginx
 
## The easier way -- systemctl edit opens editor and creates override
sudo systemctl edit nginx

Practical Commands

Bash

## Show full unit file content
systemctl cat nginx
 
## Show all overrides applied
systemctl cat nginx | head -5  ## first line shows which file
 
## Validate unit file syntax before applying
systemd-analyze verify /etc/systemd/system/myapp.service
 
## Show unit file location
systemctl show -p FragmentPath nginx
 
## List all unit files and their state
systemctl list-unit-files --type=service

Troubleshooting

Symptom	Command	What to Look For
Unit file change ignored	`sudo systemctl daemon-reload`	Must reload after any file edit
Service exits immediately	`journalctl -u service -n 20`	Exit code and error message
Wrong user running service	`systemctl show service -p User`	User directive in unit file
Environment not loading	`systemctl show service -p EnvironmentFiles`	Path and whether file exists

PLACEMENT PRO TIP
**Tip:** Use `systemd-analyze verify /etc/systemd/system/myapp.service` before reloading. It catches syntax errors in unit files before you try to start the service. A syntax error can make the service silently do nothing or fail to load.

COMMON MISTAKE / WARNING
**Security:** Never put secrets (passwords, API keys) directly in unit files. Unit files are readable by any user with `systemctl cat`. Use `EnvironmentFile=/etc/service/env` to load secrets from a file with restricted permissions (chmod 640, chown root:service-group). The environment file is not readable by ordinary users but is loaded by systemd before starting the service.