deb-systemd-invoke.

deb-systemd-invoke {start|stop|reload|restart} unitname...

start
    Starts the specified systemd unit(s).

stop
    Stops the specified systemd unit(s).

reload
    Reloads the configuration of the specified systemd unit(s).

restart
    Restarts the specified systemd unit(s).

unitname
    The name of the systemd unit (e.g., `my-service.service`) to operate on. Multiple unit names can be specified.

The `deb-systemd-invoke` command is a helper script primarily used within Debian package maintainer scripts. Its purpose is to reliably start, stop, reload, or restart systemd units (services, sockets, timers, etc.) during package installation, upgrade, or removal. This ensures that systemd units are properly managed during package management operations. It interacts with `systemctl` to perform the actual unit management actions, but handles edge cases and potential race conditions that might arise from running systemd commands within the context of a package manager like `apt`. The key benefit is preventing situations where package installation/removal becomes blocked or fails due to issues with systemd unit states.

By invoking systemd units via deb-systemd-invoke, maintainers can ensure that these units are started or stopped, or in general have their state changed at specific points in the lifecycle of a package that depends on them. This is a cleaner, more robust approach than attempting to directly manipulate systemd units within maintainer scripts without the appropriate checks and error handling, making package management more reliable.

This command is primarily intended for use within Debian package maintainer scripts. Using it directly outside of this context might have unintended consequences if not done carefully. The script relies on the systemd environment being correctly configured. It's also important to ensure that the specified unit names are valid systemd units.

To use `deb-systemd-invoke` within a maintainer script (e.g., `postinst`, `prerm`), simply call the command with the appropriate action (start, stop, reload, restart) and the unit name(s). Make sure the maintainer script has the proper permissions (e.g. calling `dpkg --configure --pending` as root will ensure that the `postinst` scripts are executed with root permissions).

While `deb-systemd-invoke` attempts to handle errors gracefully, it's still recommended to check the return code of the command in the maintainer script. A non-zero return code indicates that the operation failed.

The `deb-systemd-invoke` command was introduced to provide a standardized and reliable way to interact with systemd units within Debian package maintainer scripts. Before its introduction, maintainers often used ad-hoc methods to start, stop, or restart systemd units, which could lead to inconsistencies and problems during package management. It ensures consistent behavior and avoids common pitfalls. Its development was driven by the need to integrate systemd smoothly into Debian's package management ecosystem.

systemctl(1), systemd(1)