Customizing Systemd Services with Override Files

1. Introduction – Why Override Instead of Edit

One of the most common mistakes new Linux users make when trying to tweak a service is editing its original systemd unit file directly under /usr/lib/systemd/system/.
Sure, it works — until your next system update, when your carefully tuned masterpiece is replaced by a shiny, new default file from the package manager.

That’s where override files (also called drop-in files) come in. These are small configuration snippets stored in a separate directory, allowing you to modify or add to an existing service’s configuration without touching the original file.

Think of it as writing a sticky note for systemd:

“Hey, keep everything the same — but restart this service every 30 seconds if it fails.”

2. How Override Files Work

When systemd starts a service, it reads configuration files in a specific order, from the lowest to the highest priority.
If a directive appears in multiple files, the last one read takes precedence.

Here’s the order of precedence:

/usr/lib/systemd/system/<service_name>.service
/usr/lib/systemd/system/<service_name>.d/*.conf
/run/systemd/system/<service_name>.d/*.conf
/etc/systemd/system/<service_name>.d/*.conf

That means your custom configuration in /etc/systemd/system/<service_name>.service.d/ always wins.

Example:

Let’s say you have a service called example.service.
You can place your custom configuration in:

/etc/systemd/system/example.service.d/override.conf

Systemd will merge the directives from this file with the main one.

3. The Recommended Method: systemctl edit

The safest and easiest way to create an override file is by using the systemctl edit command.

Step 1: Open the Override Editor

sudo systemctl edit example.service

This opens a temporary file in your default editor (Vim, Nano, etc.).
When you save and exit, systemd will automatically:

• Create the proper directory (/etc/systemd/system/example.service.d/)
• Save your configuration as override.conf
• Reload its configuration files

Step 2: Add Your Customizations

Inside the file, you can add or override any section of the service configuration.
For instance, let’s make sure a service restarts automatically after 30 seconds:

# /etc/systemd/system/example.service.d/override.conf
[Service]
Restart=always
RestartSec=30s

That’s it! Your service now restarts automatically if it crashes.

4. Overriding Command Execution (ExecStart)

Sometimes, you might want to replace the command that systemd runs to start your service.
However, you can’t just write another ExecStart line — systemd will merge both, not replace.
To override it completely, you must first reset the original directive.

Example:

# Clear the original ExecStart and set a new one
[Service]
ExecStart=
ExecStart=/usr/local/bin/my-custom-command

That empty ExecStart= line tells systemd: “Forget the previous start command, I’m defining my own.”

5. Applying Your Changes

After saving the file, reload the systemd manager configuration so it picks up your changes:

sudo systemctl daemon-reload

Then restart the service to apply the new configuration:

sudo systemctl restart example.service

6. Manual Creation of Override Files

Prefer doing things the old-school way? You can manually create override files too.

Step 1: Create the Drop-in Directory

sudo mkdir -p /etc/systemd/system/example.service.d

Step 2: Create and Edit the Override File

sudo nano /etc/systemd/system/example.service.d/override.conf

Then add your configuration:

[Service]
Environment="MY_CUSTOM_SETTING=true"
Restart=on-failure

Step 3: Reload and Restart

sudo systemctl daemon-reload
sudo systemctl restart example.service

7. Full Unit File Replacement (Advanced Method)

If you need to make extensive modifications — like changing dependencies, service type, or other core attributes — you can fully replace the unit file.

Step 1: Copy and Edit the Entire File

sudo systemctl edit --full example.service

This command copies the original unit file from /usr/lib/systemd/system/ into /etc/systemd/system/ and opens it in your editor.
You can then edit it freely.

Step 2: Save and Reload

When you save and close the editor, systemd automatically reloads the configuration.
Apply your changes by restarting the service:

sudo systemctl restart example.service

Warning

Replacing a full unit file disables automatic updates for that service’s configuration.
If the package that provides it is updated, your local copy will not be updated automatically.
You’ll need to manually review and merge any changes from future updates.

8. Viewing and Verifying Overrides

To verify that your changes are applied, run:

systemctl cat example.service

This shows the full active configuration of the service, including the main file and all drop-ins.
You’ll see something like:

# /usr/lib/systemd/system/example.service
[Service]
ExecStart=/usr/bin/example

# /etc/systemd/system/example.service.d/override.conf
[Service]
Restart=always
RestartSec=30s

Perfect — your override file is merged correctly.

9. Removing or Resetting Overrides

If you ever want to remove your customizations, simply delete the override directory:

sudo rm -r /etc/systemd/system/example.service.d

Then reload and restart:

sudo systemctl daemon-reload
sudo systemctl restart example.service

Alternatively, you can use:

sudo systemctl revert example.service

This command safely removes all drop-in overrides created via systemctl edit.

10. Practical Examples

Here are a few real-world use cases you’ll actually run into:

Example 1: Adding Environment Variables

[Service]
Environment="DEBUG=true"
Environment="PORT=8080"

Example 2: Extending Timeouts

[Service]
TimeoutStartSec=90s

Example 3: Running with a Custom Working Directory

[Service]
WorkingDirectory=/opt/myapp

Example 4: Preventing Auto-Restart on Failure

[Service]
Restart=no

11. Troubleshooting Common Problems

12. Summary

Using systemd override files is the right way to customize services in Ubuntu and other Linux distributions that use systemd.
They’re modular, update-safe, and easily reversible.

Whenever you feel the urge to edit /usr/lib/systemd/system/some.service, take a deep breath — and instead type:

sudo systemctl edit some.service

It’s faster, safer, and your future self will thank you.