.\" Automatically generated by Pod::Man 4.14 (Pod::Simple 3.43)
.\"
.\" Standard preamble:
.\" ========================================================================
.de Sp \" Vertical space (when we can't use .PP)
.if t .sp .5v
.if n .sp
..
.de Vb \" Begin verbatim text
.ft CW
.nf
.ne \\$1
..
.de Ve \" End verbatim text
.ft R
.fi
..
.\" Set up some character translations and predefined strings.  \*(-- will
.\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
.\" double quote, and \*(R" will give a right double quote.  \*(C+ will
.\" give a nicer C++.  Capital omega is used to do unbreakable dashes and
.\" therefore won't be available.  \*(C` and \*(C' expand to `' in nroff,
.\" nothing in troff, for use with C<>.
.tr \(*W-
.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
.ie n \{\
.    ds -- \(*W-
.    ds PI pi
.    if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
.    if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\"  diablo 12 pitch
.    ds L" ""
.    ds R" ""
.    ds C` ""
.    ds C' ""
'br\}
.el\{\
.    ds -- \|\(em\|
.    ds PI \(*p
.    ds L" ``
.    ds R" ''
.    ds C`
.    ds C'
'br\}
.\"
.\" Escape single quotes in literal strings from groff's Unicode transform.
.ie \n(.g .ds Aq \(aq
.el       .ds Aq '
.\"
.\" If the F register is >0, we'll generate index entries on stderr for
.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
.\" entries marked with X<> in POD.  Of course, you'll have to process the
.\" output yourself in some meaningful fashion.
.\"
.\" Avoid warning from groff about undefined register 'F'.
.de IX
..
.nr rF 0
.if \n(.g .if rF .nr rF 1
.if (\n(rF:(\n(.g==0)) \{\
.    if \nF \{\
.        de IX
.        tm Index:\\$1\t\\n%\t"\\$2"
..
.        if !\nF==2 \{\
.            nr % 0
.            nr F 2
.        \}
.    \}
.\}
.rr rF
.\"
.\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2).
.\" Fear.  Run.  Save yourself.  No user-serviceable parts.
.    \" fudge factors for nroff and troff
.if n \{\
.    ds #H 0
.    ds #V .8m
.    ds #F .3m
.    ds #[ \f1
.    ds #] \fP
.\}
.if t \{\
.    ds #H ((1u-(\\\\n(.fu%2u))*.13m)
.    ds #V .6m
.    ds #F 0
.    ds #[ \&
.    ds #] \&
.\}
.    \" simple accents for nroff and troff
.if n \{\
.    ds ' \&
.    ds ` \&
.    ds ^ \&
.    ds , \&
.    ds ~ ~
.    ds /
.\}
.if t \{\
.    ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u"
.    ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u'
.    ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u'
.    ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u'
.    ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u'
.    ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u'
.\}
.    \" troff and (daisy-wheel) nroff accents
.ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V'
.ds 8 \h'\*(#H'\(*b\h'-\*(#H'
.ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#]
.ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H'
.ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u'
.ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#]
.ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#]
.ds ae a\h'-(\w'a'u*4/10)'e
.ds Ae A\h'-(\w'A'u*4/10)'E
.    \" corrections for vroff
.if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u'
.if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u'
.    \" for low resolution devices (crt and lpr)
.if \n(.H>23 .if \n(.V>19 \
\{\
.    ds : e
.    ds 8 ss
.    ds o a
.    ds d- d\h'-1'\(ga
.    ds D- D\h'-1'\(hy
.    ds th \o'bp'
.    ds Th \o'LP'
.    ds ae ae
.    ds Ae AE
.\}
.rm #[ #] #H #V #F C
.\" ========================================================================
.\"
.IX Title "DH_RUNIT 1"
.TH DH_RUNIT 1 "2023-06-15" "perl v5.36.0" "User Contributed Perl Documentation"
.\" For nroff, turn off justification.  Always turn off hyphenation; it makes
.\" way too many mistakes in technical documents.
.if n .ad l
.nh
.SH "NAME"
dh_runit \- install/enable runit runscripts
.SH "SYNOPSIS"
.IX Header "SYNOPSIS"
\&\fBdh_runit\fR [\fIdebhelper\ options\fR] [\fIpath\fR \fIoptions\fR] ...
.SH "DESCRIPTION"
.IX Header "DESCRIPTION"
\&\fBdh_runit\fR is a debhelper program that is responsible for
installing and enabling \fIrunit\fR runscripts. If a file named
\&\fIdebian/\fIpackage\fI.runit\fR exists, then it ensures appropriate actions
are performed based on its content.
.PP
For runit, each unit of supervision (or, simply speaking, program) is
represented by a directory under \fI/etc/sv\fR, containing at least a \fIrun\fR
executable file. Each enabled unit of supervision is represented by a
symbolic link under \fI/etc/services\fR (which itself is a symbolic link to
\&\fI/etc/runit/runsvdir/default\fR) pointing to some directory under
\&\fI/etc/sv\fR.
.PP
\&\fBdh_runit\fR reads arguments from the command line and
\&\fIdebian/\fIpackage\fI.runit\fR 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 \fI/etc/sv/*/run\fR as an executable file. If the first
argument names a directory, that directory is copied as a whole to
\&\fI/etc/sv\fR.
.PP
Options are comma separated, like mount options. Unrecognized options
are errors. The following options are recognized:
.IP "\fIdisable\fR" 4
.IX Item "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 manually by the system administrator or
automatically using \fBupdate\-service\fR\|(8).
.IP "\fIname\fR=preferred\-name" 4
.IX Item "name=preferred-name"
By default, the name of the directory under \fI/etc/sv\fR 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.
.IP "\fIlogscript\fR" 4
.IX Item "logscript"
Install a standard \fIlog/run\fR script that invokes \fBsvlogd\fR\|(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 \fI/log/run\fR script.
.IP "\fIonupgrade\fR=string" 4
.IX Item "onupgrade=string"
This option controls what to do during the upgrade of a service
when runit is \s-1PID 1\s0; 
it takes one of the following strings as argument:
.Sp
\&\fIrestart\fR
 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.
.Sp
\&\fIstop\fR
 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'.
.Sp
\&\fInostop\fR
 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 \fBinvoke-run\fR interpreter, provided by \fIrunit\fR
 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'.
.Sp
\&\fIreload\fR
 similar to nostop, but the service configuration is reloaded (\s-1HUP\s0) 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 \fBinvoke-run\fR interpreter, provided by \fIrunit\fR
 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).
.Sp
Please note that \fIonupgrade\fR 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.
.IP "\fInoscripts\fR" 4
.IX Item "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.
.IP "\fIusr\fR" 4
.IX Item "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 in mainly intended for a catch-all runscript package.
This option is experimental and it's use may produce a buggy package; the runit trigger
used in place of several dh/maintscripts actions is very new to Debian; also the
mechaninsm to automatically copy the service into /etc/sv/ is still under development.
.IP "\fIfinish\fR" 4
.IX Item "finish"
Install a standard finish file with the service; if there is already a finish file
inside the service directory, this option does nothing.
.IP "\fIbin\fR=/full/path/to/bin" 4
.IX Item "bin=/full/path/to/bin"
The full path to the binary that is exec'd run in the runscript should be provided.
When this option is used, additional metafiles are written inside the service
directory so that postinstall and prerem 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, postinst and prerm are skipped. This option is experimental.
.IP "\fIpresubj\fR" 4
.IX Item "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.
.IP "\fIdefaults\fR" 4
.IX Item "defaults"
If you don't need other options, specify this one.
.IP "\fIsince\fR" 4
.IX Item "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.
.IP "\fInoreplace\fR" 4
.IX Item "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.
.IP "\fInofinish\fR" 4
.IX Item "nofinish"
This option is deprecated, does nothing and it's scheduled for removal
with 3.0 release.
.SH "SUBSTITUTION VARIABLES"
.IX Header "SUBSTITUTION VARIABLES"
Packages using \fBdh_runit\fR do not depend on \fBrunit\fR but should include the
\&\fIrunit:Breaks\fR variable in their \fIBreaks\fR field in \fIdebian/control\fR
to ensure that no breakages are caused by a too-old version of \fBrunit\fR package.
.SH "EXAMPLES"
.IX Header "EXAMPLES"
This section contains several example \fI\fIpackage\fI.runit\fR snippets.
.PP
.Vb 3
\&  # In this case, a file is installed as a \*(Aqrun\*(Aq script. The directory
\&  # name under /etc/sv is derived from the file\*(Aqs 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\*(Aqs
\&  # 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
.Ve