Provided by: dh-runit_2.16.3ubuntu1_all 
NAME
dh_runit - install/enable runit runscripts
SYNOPSIS
dh_runit [debhelper options] [path options] ...
DESCRIPTION
dh_runit is a debhelper program that is responsible for installing and enabling runit runscripts. If a
file named debian/package.runit exists, then it ensures appropriate actions are performed based on its
content.
For runit, each unit of supervision (or, simply speaking, program) is represented by a directory under
/etc/sv, containing at least a run executable file. Each enabled unit of supervision is represented by a
symbolic link under /etc/services (which itself is a symbolic link to /etc/runit/runsvdir/default)
pointing to some directory under /etc/sv.
dh_runit reads arguments from the command line and debian/package.runit in pairs, with the first item
being the path to a file or directory and the second being a set of options. If the first argument names
a file, it is treated as a 'run' script to be installed at /etc/sv/*/run as an executable file. If the
first argument names a directory, that directory is copied as a whole to /etc/sv.
Options are comma separated, like mount options. Unrecognized options are errors. The following options
are recognized:
disable
Install the runscript but do not enable it by default. This means that the corresponding service
will not be started. The service can be enabled by the system administrator manually or with
update-service(8).
name=preferred-name
By default, the name of the directory under /etc/sv for a given runscript is the basename of the path
argument naming it. This option allows overriding that default with an explicitly chosen directory
name.
logscript
Install a standard log/run script that invokes svlogd(8) with the rights of the dedicated user.
Specifying this option produces an error if the path argument names a directory that already contains
a /log/run script.
onupgrade=string
This option controls the debhelper action performed during the upgrade of the service, when runit is
PID 1, and it takes one of the following strings as argument:
restart
restart the service in postinstall, after all files of the package are
unpacked and the upgrade is complete. This is the same as dh_installinit
or dh_installsystemd ' --restart-after-upgrade '.
This is the implicit default if the 'onupgrade' option is not set.
stop
stop the service in prerm and start again in postinst. This option is useful
if the daemon get confused by the package being upgraded while it's still
running. This is the same as dh_installinit or dh_installsystemd
'--no-restart-after-upgrade'.
nostop
do not stop service on upgrade. This has the side-effect of not restarting the
service as a part of the upgrade. Use this option when the service does not
support being restarted while it's running. Display managers (xdm, slim, ...)
are example of non-restartible services.
When this option is set the invoke-run interpreter, provided by runit
package, will refrain from automatically replace the sysvinit-managed
instance of the service with a runit-managed instance (replacement requires manual
intervention or a system restart).
This is the same as dh_installinit or dh_installsystemd '--no-stop-on-upgrade'.
reload
similar to nostop, but the service configuration is reloaded (HUP) during the upgrade.
This might be useful in cases (like dbus) where the service does not support restarting
on upgrade and where reloading the config instead of restarting makes sense.
When this option is set the invoke-run interpreter, provided by runit
package, will refrain to automatically replace the sysvinit-managed
instance of the service with a runit-managed instance (replacement requires manual
intervention or a system restart).
The onupgrade option does not control whether the service will be started after the first install of
the package; by default the service is always started if it's enabled (and stopped before removal).
To not start the service after the first install you should use the 'disable' option. The upgrade
action usually happens in postinst, however if the bin option is used, the action is performed at the
end of the upgrade process, with a noawait trigger on runit's package side.
noscripts
With this option dh-runit will not add its snippets to maintscripts; actions like enable or disable,
start, stop, restart and purge the service need manual editing of maintaner scripts.
usr With this option dh-runit will install the service directory under /usr/share/runit/sv/ instead of
the default /etc/sv/. It must be used together with the 'bin' option or dh-runit will exit with an
error. This option is experimental, is mainly intended for a catch-all runscript package and may
produce a buggy package (that fails the piuparts purge test).
finish
Install a standard finish file with the service; if there is already a finish file inside the service
directory, this option does nothing.
bin=/full/path/to/bin
The full path to the binary that is exec'd in the runscript should be provided. When this option is
used, additional metafiles are written inside the service directory so that postinstall and prerm
actions that are usually performed inside maintainer scripts are performed with a trigger on runit
package side. When this option is used, only the postrm snippet that handles purge action is written
while postinst and prerm snippets are skipped. Additionally, all instances (if any) of '##bin##' in
the runscript are automatically replaced with the path provided with this option; this is done so
that the path of the bin can be maintained only in the control file. This option is experimental.
presubj
Include presubj file for reportbug into generate package. This file contains note that suggest
including runit maintainers into copy of bug reports, related to runit integration. If the package
already include it's own presubj file, that file takes precedence over runit presubj file. This may
make life of package maintainer who uses another init system easier.
defaults
If you don't need other options, specify this one.
since
Since dh-runit 2.8.15 this option is no longer needed and is deprecated. It's retained only for
backward compatibility with packages that still use it (see #942323). It's scheduled for removal with
3.0 release.
noreplace
Since dh-runit 2.9.0 this option is deprecated and it's retained only for backward compatibility and
it's scheduled for removal with 3.0 release. You can use onupgrade=nostop instead.
nofinish
This option is deprecated, does nothing and it's scheduled for removal with 3.0 release.
SUBSTITUTION VARIABLES
Packages using dh_runit do not depend on runit but should include the runit:Breaks variable in their
Breaks field in debian/control to ensure that no breakages are caused by a too-old version of runit
package.
EXAMPLES
This section contains several example package.runit snippets.
# In this case, a file is installed as a 'run' script. The directory
# name under /etc/sv is derived from the file's basename (/etc/sv/script).
path/to/file/to/be/installed/as/run/script defaults
# Similar, but installs a directory as a whole. It is the package's
# responsibility to ensure this directory contains everything required.
path/to/directory defaults
# Similar, but without creating a symlink under /etc/service.
path/to/directory disable
# Explicitly specifying a name to use for the directory under /etc/sv.
# A standard log/run script will be created.
path/to/directory name=my-preferred-name,logscript
perl v5.38.2 2024-07-15 DH_RUNIT(1)