systemctl-edit

Replace a unit file non-destructively

$ sudo systemctl edit [unit_file]

$ sudo systemctl edit [[-l|--full]] [unit_file]

$ sudo systemctl edit [[-lf|--full --force]] [unit_file]

systemctl edit [OPTIONS...] UNIT...

UNIT...
    One or more systemd unit names (e.g., `apache2.service`, `multi-user.target`) to edit. If the unit does not exist, a new drop-in directory and file will be created.

--full
    Edit the entire main unit file in `/etc/systemd/system/` directly, instead of creating a drop-in snippet. This implies `--force` if editing a vendor unit and creates the unit file if it doesn't exist.

--runtime
    Edit a transient drop-in snippet file in `/run/systemd/system/<unit>.d/override.conf`. Changes made with this option are ephemeral and will be lost upon the next system reboot.

--force
    Override protection against editing vendor-shipped units. This is automatically implied when using `--full` on a vendor unit or if the `/etc` unit file is already a symlink to `/lib`.

--suffix=SUFFIX
    Specify a custom suffix for the drop-in snippet file (e.g., `.conf`). The default suffix is `.conf`.

The `systemctl edit` command is a powerful utility for safely customizing systemd unit files without directly modifying the original files provided by packages. When invoked, it opens a temporary file in your preferred text editor (defined by `EDITOR` or `VISUAL` environment variables). Upon saving and exiting the editor, systemd automatically creates or updates a "drop-in" snippet file for the specified unit. These drop-in files are typically located in `/etc/systemd/system/<unit>.d/override.conf`.

This method ensures that your local modifications persist across package upgrades, as the original unit file (usually in `/usr/lib/systemd/system/`) remains untouched. After the drop-in file is saved, systemctl automatically reloads the systemd daemon configuration to apply the changes. If the unit is active, it will often prompt you to restart it. This command is essential for making persistent, upgrade-safe changes to unit behavior, such as altering execution commands, modifying dependencies, or setting resource limits.

Using `--full` to directly edit vendor unit files in `/etc/` can lead to conflicts during package upgrades, as the package manager might attempt to overwrite your modifications. The preferred and safer method is to use drop-ins without `--full`.

Changes made with `--runtime` are temporary and will not persist after a system reboot.

When overriding directives, especially lists like `ExecStart`, you might need to first clear the previous definition by assigning an empty value (e.g., `ExecStart=`) before providing new values.

When you use `systemctl edit <unit>.service` (without `--full`), systemd creates a directory `/etc/systemd/system/<unit>.service.d/` and a file named `override.conf` (by default) within it. This file is where your custom configurations reside. When the unit is loaded, systemd merges the original unit file's directives with those in your drop-in file(s). Directives in the drop-in take precedence, allowing you to selectively override or add configurations without altering the original package-provided unit file. This ensures your customizations are resilient to package updates and allows for easy rollback by simply deleting the drop-in file.

The `systemctl edit` command, along with the underlying drop-in snippet mechanism, was introduced in systemd to address the challenge of safely and persistently customizing unit files. Prior to its existence, users often resorted to manually copying unit files from `/usr/lib/` to `/etc/` and editing them, which was prone to errors and difficult to track. `systemctl edit` streamlines this process, providing a user-friendly and robust way to manage overrides, becoming a core part of systemd's administration toolkit around early systemd versions.

systemctl(1), systemd(1), systemd.unit(5), systemd.service(5), systemd-delta(1), journalctl(1)