How to override a packaged unit file with systemd drop-ins

How to override a packaged unit file with systemd drop-ins

Customize a vendor-provided systemd unit file without editing the original using drop-in override files.

Prerequisites

• Root or sudo access on a Linux system running systemd.
• A packaged unit file to customize (e.g., nginx.service installed by apt).

Step-by-Step: Override a Unit File with Drop-Ins

1. Create a drop-in directory and override file using systemctl edit. This command opens an editor for a new drop-in file:

   sudo systemctl edit nginx.service

   systemd creates /etc/systemd/system/nginx.service.d/override.conf automatically.

2. Add the directives to override. Drop-in files only need the sections and directives being changed. To increase the restart delay and add an environment variable:

   [Service]
   RestartSec=10
   Environment=NGINX_WORKER_CONNECTIONS=4096

   For directives that are lists (like ExecStart), clear the original value first with an empty assignment, then set the new value:

   [Service]
   ExecStart=
   ExecStart=/usr/sbin/nginx -g 'daemon off;' -c /etc/nginx/custom.conf

3. Save and close the editor. systemd runs daemon-reload automatically after systemctl edit.

4. Restart the service to apply the override:

   sudo systemctl restart nginx.service

How to Verify the Override Is Active

systemd shows applied drop-in files in the systemctl status output under the Drop-In line. Verify with systemctl cat:

systemctl cat nginx.service

This command displays the merged unit file content — the original plus all drop-in overrides.

Common Issues When Using systemd Drop-Ins

Forgetting to clear list-type directives before redefining them causes both the original and new values to apply. Always set ExecStart= (empty) before the new ExecStart=/path/to/binary.

Editing the original file at /usr/lib/systemd/system/ instead of using drop-ins causes package updates to overwrite the changes. Always use systemctl edit or create files under /etc/systemd/system/.