====== Runit ======

===== Introduction =====

runit is a UNIX init scheme with service supervision. It is a cross-platform Unix init scheme with service supervision, a replacement for sysvinit, and other init schemes and supervision that are used with the traditional init. runit is compatible with djb's daemontools.

In Unix-based computer operating systems, init (short for initialization) is the first process started during booting of the computer system. Init is a daemon process that continues running until the system is shut down. Slackware comes with its own legacy init (/sbin/init) from the sysvinit package, that used to be included in almost all other major Linux distributions.

The init daemon (or its replacement) is characterised by Process ID 1 (PID 1).

To read on the benefits of runit, see here: http://smarden.org/runit/benefits.html

//* Unless otherwise stated, all commands in this article are to be run by root.//

===== Use runit with traditional init (sysvinit) =====

runit is not provided by Slackware, but a SlackBuild is maintained on https://slackbuilds.org/. It does not have any dependencies.

As we do not want yet to replace init with runit, run the slackbuild with CONFIG=no:

<code>
CONFIG=no ./runit.SlackBuild
</code>

Then install the resulting package and proceed as follows:

<code>
mkdir /etc/runit/ /service/
cp -a /usr/doc/runit-*/etc/2 /etc/runit/
/sbin/runsvdir-start &
</code>

==== Starting via rc.local ====

For a typical Slackware-stlyle service, you can edit ''/etc/rc.d/rc.local'' file

<code>
if [ -x /sbin/runsvdir-start ]; then
  /sbin/runsvdir-start &
fi
</code>

and then edit write ''/etc/rc.d/rc.local_shutdown''

<code>
#!/bin/sh
RUNIT=x$( /sbin/pidof runsvdir )
if [ "$RUNIT" !=  x ]; then
  kill $RUNIT
fi
</code>

Then give ''rc.local_shutdown'' executive permission:

<code>
chmod +x /etc/rc.d/rc.local_shutdown
</code>

and reboot

==== Starting via inittab (supervised) ====

Remove the entries in ''/etc/rc.d/rc.local'' and ''/etc/rc.d/rc.local_shutdown'' described above. 

Edit ''/etc/inittab''

<code>
cat >>/etc/inittab <<EOT
SV:123456:respawn:/sbin/runsvdir-start
EOT
</code>

and tell init to re-read its configuration, e.g.:

<code>
init q
</code>

or reboot 

===== How to replace init with runit =====

runit provides ''runit-init'' which can be used to boot up the system.

If you followed the previous chapter, then stop runsvdir and reverse all the changes that you made on your system.

So, remove the last line from ''/etc/inittab''

<code>
rm -rf /etc/runit /service
</code>

And reboot:

<code>
shutdown -r now
</code>

Also, it is best to re-build and re-install runit

This time, when running slackbuild, do pass not any value for CONFIG, or set it to yes:

<code>
unset CONFIG 
sh runit.SlackBuild
</code>

and upgrade with the resulting runit package.

Disable services that are already provided by the traditional init:

<code>
cd /service/
rm *
</code>

Create a new TTY service for runit:

<code>
cd /etc/sv/
cp -ar agetty-tty1/ agetty-tty8/
sed -i 's/tty1/tty8/g' agetty-tty8/*
ln -s /etc/sv/agetty-tty8 /service
</code>

Start runit's stage 2 for testing:

<code>
/etc/runit/2 &
</code>

And check that the agetty is running, by logging in as an unprivileged user (not as root!)

<code>
CTRL+ALT+F8
</code>

If this has been successful, then reverse the last intervention:

<code>
kill $( pidof runsvdir )

rm /service/agetty-tty8
rm -rf /etc/sv/agetty-tty8
for N in {1..6}; do
  ln -s /etc/sv/agetty-tty${N} /service
done
</code>

Then, to boot in runit, reboot and enter ''init=/sbin/runit-init'' in the Lilo prompt. To do this, hit the tab key when you are presented with the Lilo menu as shown in Images 1 and 2 below.

{{:howtos:slackware_admin:lilo_tab.png?400|}}

//Image 1.: Hit the Tab key on the Lilo Menu before the counter times out.//

{{:howtos:slackware_admin:runit-init.png?400|}}

//Image 2: Add init=/sbin/runit-init in the OS Selection Prompt//

Confirm that runit has taken PID 1:

<code>
ps -o comm= -p 1
runit
</code>

If you do not have a multi boot system, you may append the init selection ''in /etc/lilo.conf''

For example:

<code>
append="vt.default_utf8=0 init=/sbin/runit-init"
</code>

Then run lilo:

<code>
lilo -v
</code>

Or just replace ''/sbin/init'' with ''/sbin/runit-init'' like this:

<code>
cp /sbin/init /sbin/init.sysv
cp /sbin/runit-init /sbin/init
</code>

However, with the last alternative, be warned that if you had booted with the original init, the system may refuse to reboot, therefore boot from runit-init first. 

==== Startup and Shutdown ====

The BSD style init scripts provided by Slackware are used to bring up the system.

Initially the single user script ''/etc/rc.d/rc.S'' runs. If set in the default runlevel 3, it follows it with ''/etc/rc.d/rc.M''. In runit the initialisation script is located in ''/etc/runit/1'' for all runlevels. By default ''/etc/runit/2'' is restricted to the TTY services. 

The script ''/etc/rc.d/rc.6'' is the rebooting script for the traditional init, while ''/etc/rc.d/rc.0'' (symlinked to the former) is the halting script. In runit, these scripts are called by ''/etc/runit/3''

Note that the shutdown command provided by sysvinit package will not work in runit. To reboot you enter

<code>
/sbin/runit-init 6
</code>

and to halt enter

<code>
/sbin/runit-init 0
</code>

A convenient script is provided with the configuration files which is placed in ''/usr/sbin/shutdown'' that determines whether the system has booted with the traditional init or runit and then calls the relevant command accordingly.

The ''halt'', ''reboot'' and ''poweroff'' commands provided by the sysvinit package would still work with runit.

Desktop Environments call ''/sbin/shutdown'' so they will not work until you move this file and symlink it to ''/usr/sbin/shutdown''

<code>
mv /sbin/shutdown /sbin/shutdown.sysv
ln -s /usr/sbin/shutdown /sbin/shutdown
</code>

However consider that shutdown would not work for the original init.

===== runsv =====

Although runit may replace init as the PID 1 daemon, there is not much benefit unless other services are migrated from Slackware's BSD style to runsv(8). While this is not a complicated task, some familiarisation with runit's characteristics is recommended and makes the task easier. This short example should help illustrate runsv to new users.

Make an arbitrary directory under ''/etc/sv/''

<code>
mkdir /etc/sv/example/
</code>

As a non-priviliged user (say user bob), create some directories:

<code>
mkdir -p /home/bob/runit/logs
</code>

Then edit a ''/home/bob/runit/service.sh'' script that simulates a (finicky) service in a convenient directory; say 

<code>
#!/bin/bash
echo "Started service..."
for i in {1..10}
do
  echo "Doing stuff..."
  sleep 1
done
echo "Oh no I crashed..." >&2
exit 1
</code>

Give it executable permission:

<code>
chmod +x /home/bob/runit/service.sh
</code>

Run it to check and appreciate its execution:

<code>
/home/bob/runit/service.sh
</code>

Log in back as root and edit a file called ''/etc/sv/example/run'' and give it executable permissions:

<code>
#!/bin/sh -e
exec 2>&1
exec chpst -u bob /home/bob/runit/service.sh
</code>

<code>
chmod +x /etc/sv/example/run
</code>

Note the exec in the last line, it tells the shell that interprets the script to replace itself with the service daemon

Naturally edit as necessary.

Create another directory:

<code>
mkdir /etc/sv/example/log/
</code>

and edit another file under it, also called ''/etc/sv/example/log/run''
 
<code>
#!/bin/sh
exec chpst -u bob svlogd -tt /home/bob/runit/logs
</code>

Give it executable permission:

<code>
chmod +x /etc/sv/example/log/run
</code>

Run the service to ensure that it works:

<code>
/etc/sv/example/run
</code>

Finally, we are ready to deploy the service. Create a symbolic link in ''/service'' to our staging location.

<code>
ln -s /etc/sv/example /service
</code>

Watch how your "service" works, crashes, but it is recovered by runit:

As your non-privilged user:

<code>
tail -f /home/bob/runit/logs/current 
</code>

Hit CTRL+C to exit.

Finally, login back as root and let bob take the ownership of the whole ''/etc/sv/example/'' directory:

<code>
chown -R bob.users /etc/sv/example/
</code>

Now bob can manage this service with the ''sv'' command. Note that in most cases, services should belong to root, and only to root.

=====  Managing Services with sv =====

To see the status of a supervised service use ''sv s <service_name>'', for example,

<code>
sv s example
</code>

returns

<code>
run: example: (pid 42) 1587s
</code>

To see the status of all services, use

<code>
sv s /service/*
</code>

==== Stop/Start/Restart ====

Start a service

<code>
sv u example
</code>

Stop a service

<code>
sv d example
</code>

Restart a service

<code>
sv t example
</code>

Each of these is a shortcut, for 'up', 'down', and 'terminate', respectively. Only the first letter of each word is recognised.

More verbose forms of the above:

<code>
sv start example

sv stop example

sv restart example
</code>

Each of these will also return the status of the service upon exit.

==== Enabling a service ====

Service directories are placed under ''/etc/sv/''. To enable a service in the current runlevel, create a symlink from it to ''/service''.

<code>
ln -s /etc/sv/example /service/
</code>

Once a service is linked it will always start on boot and restart if it stops (unless this is disabled).

==== Disabling a service ====

To disable a service in the current runlevel remove the symlink to its service directory from ''/service''.

<code>
rm /service/example
</code>

Removing the symlink will also stop the service.

Check out the sv man page to see additional options.

<code>
man sv
</code>

If you do not want a service to start upon bootup, or when enabled, just touch an empty file called ''down'' in the appropriate service directory.

<code>
touch /etc/sv/service/down
</code>

==== Dependencies ====

Dependencies of service are supported by starting the dependent run script as follows:

<code>
#!/bin/sh
sv start dependent-service || exit 1
.
.
exec ...
</code>

==== Runlevels ====

If you installed the slackbuild configuration files, you have two runlevels: default and single. The current runlevel is default. You can verify by looking under ''/etc/runit/runsvdir/,'' you will see that ''/etc/runit/runsvdir/current'' is a symbolic link ''/etc/runit/runsvdir/default/''.

Change runlevel to another runlevel; single:

<code>
runsvchdir single
</code>

You will see that ''/etc/runit/runsvdir/current'' is now symlinked to ''/etc/runit/runsvdir/single'' and ''/etc/runit/runsvdir/previous'' is symlinked to ''/etc/runsvdir/default''. If you reboot, you will boot again on the default runlevel as you have this entry in ''/etc/runit/2''

<code>
runsvchdir default >/dev/null
</code>

You can create any other runlevel and name them as you like. To start, you can copy an existing runlevel directory and modify as you wish. 

<code>
cp -ar /etc/runit/runsvdir/default /etc/runit/runsvdir/custom/
</code>

You can edit the runsvdir line of ''/etc/runit/2'' to your requirements.

===== Run scripts =====

Only one executable can be called for a service (the last line) and it must be called by the ''exec'' command. There are some generic runit run scripts on the Internet and on other Linux distributions. Also, other Slackers may post them on publicly available repositories. The author of this article has placed his here: https://gitlab.com/chrisabela/runit_scripts_for_slackware

Another set of installable run scripts are available at [[https://slackbuilds.org/repository/14.2/system/runit-services/|SBo]].

In direct contrast to Slackware's BSD style service scripts, runit run scripts must not must run in the foreground, otherwise runit would think that they have crashed and restart them.

For some services, this may not be possible, but there are workarounds. You can forcefully terminate them by ending the run script like this:

<code>
sv d service_name
</code>

Or you can use the ''pause'' command to keep the service alive. ''pause'' is a trivial command that will simply not exit, until it is killed (akin to tail -f /dev/null). A SlackBuild for ''pause'' is available at [[https://slackbuilds.org/repository/14.2/system/pause/|SBo]]. Then end the run script with:

<code>
exec chpst -b service_name pause
</code>

===== Migrating Services =====

It is suggested that services are migrated from stage 2 (which are still under the Slackware's BSD init scheme) to stage 3 carefully. Start from the bottom of ''/etc/rc.d/rc.M'' and work up. This means that you should start with any entries under ''/etc/rc.d/rc.local'' 

Then continue for ''/etc/rc.d/rc.S''

Proceed with other services to benefit's from runit features. Note that for some services, such as ''atd'' and ''crond'', you would need to edit ''/etc/rc.d/rc.M'' as they are hard-coded.

Let's take the popular ''NetworkManager'' service as an example. According to the permission of ''/etc/rc.d/rc.networkmanager'' this script is called by ''/etc/rc.d/rc.M'' The latter is called by ''/etc/runit/2'' (stage 2).

Stop the service:

<code>
/etc/rc.d/rc.networkmanager stop
</code>

Disable it:

<code>
chmod -x /etc/rc.d/rc.networkmanager
</code>

Create a suitable directory for runit

<code>
mkdir /etc/sv/networkmanager/
</code>

Write a runit run script: ''/etc/sv/networkmanager/run''

<code>
#!/bin/sh
prefix=/usr
exec_prefix=/usr
sbindir=${exec_prefix}/sbin
NETWORKMANAGER_BIN=${sbindir}/NetworkManager

export XDG_CACHE_HOME=/root/.cache 
exec $NETWORKMANAGER_BIN -n > /dev/null 2>&1
</code>

Symlink the ''/etc/sv/networkmanager'' directory to ''/service'' to enable under current runlevel and it will start in a few seconds:

<code>
ln -s /etc/sv/networkmanager /service
</code>

If run exits and ''/etc/sv/<service name>/finish'' exists (typically when the service is switched off), ''runsv'' runs ''finish'' if it has executable permission.

It is stuggested to let ''udev'' under runit's stage 2, but you can setup its monitoring for stage 3. 

===== Using runit-init with other init scripts =====

==== OpenRC ====

Here ''runit-init'' is used for booting, which then transfers control to the OpenRC for things like mounting the filesystem, loading modules, running udev, etc.

It requires a working OpenRC system. Check the [[howtos:general_admin:openrc]] page for instructions.
The level 1 runit service uses the OpenRC ''boot'' and ''sysinit'' runlevels.

The [[https://wiki.gentoo.org/wiki/Runit#Runit_as_the_init_system|gentoo wiki]] has more information, and [[https://gitlab.com/aadityabagga/runit-init-openrc|runit-init-openrc]] details how to install and set it up.

==== void-runit ====

Here the scripts provided by the [[https://github.com/void-linux/void-runit|void-runit]] project are used to mount the filesystem, load modules, etc.

Currently this is the most independent way to setup runit.

===== Sources =====

  - http://smarden.org/runit/
  - https://en.wikipedia.org/wiki/Init
  - https://voidlinux.org/usage/runit/
  - https://www.youtube.com/watch?v=jiBlIhFxNJo
  - http://kchard.github.io/runit-quickstart/
  - https://www.slackbook.org/beta/
  - https://gitlab.com/chrisabela/runit_scripts_for_slackware
  - https://github.com/aadityabagga/runit-services
  - https://wiki.gentoo.org/wiki/Runit
  - https://github.com/void-linux/void-runit

----

  * Written for Slackware 14.2 in December 2018
  * Originally written by [[wiki:user:chrisabela | Chris Abela]]
<!-- Please do not modify anything below, except adding new tags.-->
{{tag>init runit}}