==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

== Installation and upgrade of services ==

The /etc/sv/ directory contains the actual copy of each service that is
supervised by runit; to avoid to clutter /etc/sv/ with useless directories,
services are installed under /usr/share/runit/sv.

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 /etc/sv.
If a directory with the same name that contains local changes already exists
in /etc/sv/ the local copy is not overwritten and a warning is printed.
The cpsv(8) tool can be used to inspect the difference between a local service
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 /etc/sv/ thanks to a trigger that runs
' cpsv s' .

When this package is upgraded, old versions of services under /etc/sv/
are not automatically replaced by new versions in /usr/share/runit/sv/ and
a warning is printed: to inspect the difference and possibly overwrite the old
version in /etc/sv/ the cpsv(8) tool can be used like decribed above, or with
one invocation for all services (again, no backup is provided!)

  # cpsv -f s

== 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 /etc/sv/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 ander another init system services
copied into /etc/sv/ 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, 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 /etc/sv/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 /etc/sv/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 /etc/sv/dbus
   # update-service --remove /etc/sv/sddm
* 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.
