9.3.3. Interfacing with init systems

Maintainer scripts for packages including init scripts must use update-rc.d as described below to interact with the service manager for requests such as enabling or disabling services. They should use invoke-rc.d as described below to invoke init scripts for requests such as starting and stopping service.

Directly managing the /etc/rc?.d links and directly invoking the /etc/init.d/ init scripts should be done only by packages providing the init script subsystem (such as init-system-helpers).

9.3.3.1. Managing the links

The program update-rc.d is provided for package maintainers to arrange for the proper creation and removal of /etc/rcn.d symbolic links, or their functional equivalent if another method is being used. It is intended for use in package maintainer scripts.

You must not include any /etc/rcn.d symbolic links in the actual archive or manually create or remove the symbolic links in maintainer scripts; you must use the update-rc.d program instead. (The former will fail if an alternative method of maintaining runlevel information is being used.) You must not include the /etc/rcn.d directories themselves in the archive either. (Only the sysvinit package may do so.)

To get the default behavior for your package, put in your postinst script:

update-rc.d package defaults

and in your postrm:

if [ "$1" = purge ]; then
    update-rc.d package remove
fi

The default behaviour is to enable autostarting your package’s daemon. The local administrator can override this using the command update-rc.d package disable. If, however, the daemon should not be autostarted unless the local administrator has explicitly requested this, instead add to your postinst script:

update-rc.d package defaults-disabled

and add a dependency on init-system-helpers (>= 1.50), which introduced the defaults-disabled option. Then the local administrator can enable autostarting the daemon using the command update-rc.d package enable.

An older practice, which should not be used, was to include a line like DISABLED=yes in the package’s /etc/default file. The package’s init script would not start the service until the local system administrator changed this to DISABLED=no, or similar. The problem with this approach was that it hides from the init system whether or not the daemon should actually be started, which leads to inconsistent and confusing behavior: service <package> start may return success but not start the service; services with a dependency on this service will be started even though the service isn’t running; and init system status commands may incorrectly claim that the service was started.

Note that if your package changes runlevels or priority, you may have to remove and recreate the links, since otherwise the old links may persist. Refer to the documentation of update-rc.d.

For more information about using update-rc.d, please consult its man page, update-rc.d(8).

It is easiest for packages not to call update-rc.d directly, but instead use debhelper programs that add the required update-rc.d calls automatically. See dh_installinit, dh_installsystemd, etc.

9.3.3.2. Running init scripts

The program invoke-rc.d is provided to make it easier for package maintainers to properly invoke an init script, obeying runlevel and other locally-defined constraints that might limit a package’s right to start, stop and otherwise manage services. This program may be used by maintainers in their packages’ scripts.

The package maintainer scripts must use invoke-rc.d to invoke the /etc/init.d/* init scripts or equivalent instead of calling them directly.

By default, invoke-rc.d will pass any action requests (start, stop, reload, restart…) to the /etc/init.d script, filtering out requests to start or restart a service out of its intended runlevels.

Most packages will simply use:

invoke-rc.d package action

in their postinst and prerm scripts.

A package should register its init script services using update-rc.d before it tries to invoke them using invoke-rc.d. Invocation of unregistered services may fail.

For more information about using invoke-rc.d, please consult its man page, invoke-rc.d(8).

It is easiest for packages not to call invoke-rc.d directly, but instead use debhelper programs that add the required invoke-rc.d calls automatically. See dh_installinit, dh_installsystemd, etc.