==Runit services collection==

This package provides a collection of runit services to have them run under
runit service supervision when runit is init (runit-init package) or when it's
available as supervision suite under another init system (runit-run package).

Index:
* Installation and upgrade of services
* Enable or disable a service
* Automatic restart of services during upgrades
* Error during purge of this package
* Initscripts oneshots (boot / shutdown)
* Package-port scripts (testing)

== Installation and upgrade of services ==

Each symlink in /etc/service/ is a service under runit supervision; the service directory
where services are actually installed can be either /usr/share/runit/sv.current
or in /etc/sv/ ; in the context of this package, the latter is reserved for (supposedly
modified) local copies of services.
When this package is installed, for each runit service in /usr/share/runit/sv/
if a sysv or systemd service with the same name exists in the system, then
the runit service is copied into /usr/share/runit/sv.current.
The cpsv(8) tool can be used to inspect the difference between a local service
(in /etc/sv/) and the one provided by the runit-services package, for example

  $ cpsv d cron

if desired, the local copy can be overwritten with the cpsv tool
(carefull, no backup is provided!)

  # cpsv -f a cron

Each time a package that ships a systemd or sysv service file is installed,
if a runit service with the same name exists under /usr/share/runit/sv/
then it is automatically copied into /usr/share/runit/sv.current thanks to a
trigger that runs

' cpsv s' .

When this package is upgraded, old versions of services under
/usr/share/runit/sv.current are overwritten with new ones; services in /etc/sv/
are never overwritten this way.
The cpsv(8) tool can be used like described above to inspect the difference
and possibly overwrite the old version in /etc/sv/.

== Enable or disable a service ==

During installation, when runit is init, services are automatically enabled
and started. Each Sysv running instance, if any, is automatically replaced
by the native runit one.
The only exception is a bunch of services (dbus, elogind and login managers
like slim lightdm sddm and the like) that will crush the graphic session when
restarted: those services are enabled but the running sysv instance, if any,
is not replaced. The replace happens automatically the next time the system
is rebooted.
The status of all services supervised by runit can be checked with

  # sv s /etc/service/*

To disable and stop a service that is automatically enabled the admin can use
the update-service(8) tool, for example

  # update-service --remove cron

will disable the cron service and make sure that it is not automatically enabled
by this package.

When runit is used as a supervision suite under another init system services
copied into /usr/share/runit/sv.current are not automatically enabled: to start a
service under runit supervision control, first stop the service (if it's already running
under another init system), then tell runit about the new service it should supervise.

Here's an example on how to do so with the cron service.

(1) Stop the service through the original init script or with systemctl

    (1a) systems with runit or SysV as init
     (if the runscript use the invoke-run interpreter this step can be skipped)

        # /etc/init.d/cron stop

    (1b) systems with systemd as init

        # systemctl stop cron
        # systemctl disable cron
        # systemctl mask cron

(2) tell runit about the new service

        # update-service --add /etc/sv/cron

The service will be picked up and started by runit within the next five
seconds, and automatically started on system boot.
Check the status of the cron service using the sv program

 # sv status cron
    run: cron: (pid 18851) 4s; run: log: (pid 18850) 4s

See the sv(8) man page for details on how to control and signal the
service.  See the documentation of the runit package on how service
supervision generally works.

 $ man sv
 $ w3m /usr/share/doc/runit/html/index.html

To switch a service back from runit service supervision to the init
script or systemd service, first tell runit to no longer supervise the service,
then re-enable the service through your init system.
E.g. for the cron service.

(1) tell runit to remove the cron service from service supervision

        # update-service --remove cron

(2) re-enable the service through the init script or with systemctl

    (2a) systems with runit or SysV as init

        # /etc/init.d/cron start

    (2b) systems with systemd as init

        # systemctl unmask cron
        # systemctl enable cron
        # systemctl start cron

== Automatic restart of services during upgrades ==

Services shipped by this package are automatically restarted when
the package that ships the corresponding binary is upgraded,  thanks to
a trigger.
The trigger watches for the path of the binary, so the restart happens
regardless of the existance of a corresponding sysv or systemd service
with the same name in the system.
Older version of this document mentioned a sysv compatibility layer and
suggested to divert the init script and replace it with a symlink to sv; this
approach is no longer necessary and discouraged, as it confuses insserv
and doesn't work when the sysv script is missing or removed from a package.

== Error during purge of this package ==

Before removing this package, it is a good idea to switch any service provided
by this package back from runit service supervision to the init script or systemd
service, as described in the bottom part of the "Enable or disable a service" of
this document.
Attempting to purge this package while certain services are still active will
fail with an error such as (example for dbus)

        "error: failed to purge dbus : still running
         please disable dbus manually from a getty first with
         update-service --remove dbus
         then run 'dpkg -P runit-services' "

This is because an unconditional removal of certain services may crash
the graphic session on which the purge is performed.
Example of such services are dbus, sddm, lightdm, slim (and any other
login managers). If you run into the error above, the following procedure
should work:

* take note of the list of services that are blocking the purge process
  (they are printed in the error message); for this example dbus and sddm
  are used
* if a graphic session is open, save all your work there and logout
* press Ctrl+Alt+F2 to go to a virtual terminal, and login as root there
* disable services that are blocking the purge
   # update-service --remove sddm
   # update-service --remove dbus
* try to purge again with
   # dpkg -P runit-services

At this point you probably also want to replace runit instances with sysv
or systemd instances:
  for runit-init or sysvinit users
    # /etc/init.d/dbus start
    # /etc/init.d/sddm start
  for systemd users
    # systemctl unmask dbus sddm
    # systemctl enable dbus sddm
    # systemctl start dbus sddm

press exit to logout from the virtual terminal;
press Ctrl+Alt+F7 to access a graphic login;
a reboot is recommended anyway.

== Initscripts oneshots (boot / shutdown) ==

This package also ships oneshot translations of Debian/Genuen initscripts
boot and shutdown tasks (hostname.sh, mountkernfs.sh, checkroot.sh,
umountfs, halt, and so on).

They are regular runit service directories under /usr/share/runit/sv/, but
each contains an empty "down" file so runsv does not start them when
runsvdir comes up. Invoke them explicitly:

  # sv once hostname.sh
  # sv once checkroot.sh

OpenRC-style dependencies between these oneshots are expressed as nested
calls: for example checkroot.sh runs "sv once hostname.sh" and
"sv once mountdevsubfs.sh" before its own work.

Scripts that had a meaningful OpenRC stop() action ship a companion
oneshot named "*-stop" (urandom-stop, hwclock.sh-stop, brightness-stop,
rc.local-stop). Call those during shutdown, e.g.:

  # sv once urandom-stop
  # sv once umountnfs.sh
  # sv once sendsigs
  # sv once umountfs
  # sv once umountroot
  # sv once halt

These oneshots source helpers from /lib/init/ (provided by initscripts /
sysvinit-utils). They are not wired into stage 1/3 automatically; other
services or a custom /etc/runit/1|/etc/runit/3 should call "sv once" as
needed.

== Package-port scripts (testing) ==

Additional runscripts for packages that do not yet ship dh-runit of their
own. They live here while behaviour is validated; later they can move into
the corresponding source packages.

Daemons follow the usual invoke-run / foreground pattern (for example
dhcpcd -B, syslog-ng -F, rsync --daemon --no-detach). Several are installed
disabled by default (dhcpcd, eudev, rsync, spice-vdagentd, watchdog) because
they need local config or hardware.

eudev and vdev both provide device management: enable only one of them.

vdev also needs the oneshots vdev-modprobe.sh (before the daemon) and
vdev-settle-sync.sh (after vdev + networking); stop with
vdev-settle-sync.sh-stop.

Extra oneshots (fake-hwclock, cryptdisks*, networking, opensysusers, procps,
console-setup, alsa-utils, …) use an empty "down" file and are started with
"sv once <name>"; companions named "*-stop" cover shutdown actions.
