This README describes the runit invoke-rc.d override.

==runit invoke-rc.d override==

The purpose of the override is to do actions like:
* block an invoke-rc.d action for a script name foo (for example because an
   equivalent runit service with dh-runit integration is found in the system)
* convert an invoke-rc.d action for a script name foo into an sv command (for
   example because an equivalent runit service without dh-runit integration is found)
* continue with an invoke-rc.d action for a script name foo, for example because
   the action is unknown to sv, or an equivalent runit service is not found.

The override establishes a default policy that is valid for all services, but it's
possible force a different policy for each single service by touching flagfiles with
appropriate names (see below); the override covers only invoke-rc.d invocations,
direct calls to sysvinit scripts in /etc/init.d/ are not covered as they are considered
in the domain of the sysadmin.
The invoke-rc.d override is always evaluated after the policy-rc.d override, so
if an action is denied by policy-rc.d the runit override becomes ineffective.
The override is effective only when runit is init (runit-init >=2.1.2-61 package is
required)

==default policy==

When invoke-rc.d is called (usually by maintscrips) for a certain script name 'foo'
with a certain action, the default policy, as in /etc/runit/override-sysv.d/runit-default,
works the following:

if a foo runit service is found (/etc/sv/foo or /usr/share/runit/sv.current/foo) in the system
but is not enabled, the invoke-rc.d action is blocked.
A foo runit service is considered enabled if /etc/service/foo symlink exists, and it's
considered disabled if no symlink or /etc/service/.foo symlink is found.

If an enabled runit service foo is found then if a dh-runit integration is detected the action
is blocked but if no dh-runit integration is found the action is forwarded to sv(8).
If the action is not supported by sv, then the sysvinit script will be called as fallback.

If no runit service foo is found then the policy is to run the sysvinit script (continuing
with invoke-rc.d).

==single service override==

The single service override works as following: for a 'foo' service, flagfiles are
tested in the following order:

if  /etc/runit/override-sysv.d/foo.block  is found, the invoke-rc.d call is blocked;

if  /etc/runit/override-sysv.d/foo.runit   is found, the invoke-rc.d action is forwarded
    to sv; if the action is unsupported by sv, the sysvinit script is used as fallback;
    if runit service 'foo' is not enabled the action is blocked (not forwarded to sysv)

if  /etc/runit/override-sysv.d/foo.sysv   is found, the action will be forwarded to the
    sysvinit script (by continuing with invoke-rc.d) regardless of the existence of a
    foo native runscript

flagfiles in the form of 'foo.pkgsysv', 'foo.pkgrunit' or  'foo.pkgblock' can be used by
runscript provided by packages and subjected to automatic removal: as such they
should not be used by the local admin.

==change the default policy==

When the default policy and the single service override are not flexible enough,
the runit-default script can be changed to achieve the desired result.

The runit-default script is called by invoke-rc.d script: the first argument is
the name of the sysvinit script and the second argument is the action to be performed
(for example start, stop, restart..); there can be a third argument which is a parameter to
be passed to the sysvinit script.
In order to continue with the sysvinit script, the runit-default script must return 104 as
exit code; any other ruturn code, included zero, will block the execution of the initscript.

To disable completely the runit override, the most efficient way is to do
# chmod -x /etc/runit/override-sysv.d/runit-default

== boot and shutdown tasks ==

*.block files can be used to prevent the execution of boot and shutdown scripts that
are run in stage 1 and stage 3;
*.block files are also effective in blocking execution of scripts run as oneshots by
'run_sysv_scripts' during stage 2;
*.sysv files are also effective in forcing 'run_sysv_scripts' to run a script regardless
the availability of an equivalent runscript in the system.
