S6-LINUX-INIT-QUICKSTART(7)

NAME
s6-linux-init-quickstart - quickstart and FAQ for s6-linux-init

DESCRIPTION

  Quickstart

1.  Install all the s6-linux-init dependencies:

    •   skalibs[1]

    •   execline[2]

    •   s6[3]

2.  Save and remove your old /etc/s6-linux-init directory, if you have one.

3.  Install the s6-linux-init package itself.

4.  Save your old /sbin/init, /sbin/telinit, /sbin/shutdown, /sbin/halt, /sbin/poweroff, and /sbin/reboot binaries.

5.  Make sure you have a /run directory.

6.  Edit the scripts in /etc/s6-linux-init/skel.

7.  Check that your devtmpfs is automounted by your kernel at boot time. If it is not, add the ‘-d /dev’ option to the s6-linux-init-maker(8) command line below.

8.  As root, run:

        rm -rf /tmp/blah
        s6-linux-init-maker -1 -G "/sbin/getty 38400 tty1" /tmp/blah
        rm -rf /etc/s6-linux-init/current
        mv /tmp/blah /etc/s6-linux-init/current
        cp -a /etc/s6-linux-init/current/bin/* /sbin/

9.  Reboot. Warning: use your old reboot command, that you saved, not the new one that has just been created by s6-linux-init-maker(8), because you're still running on your old init system and need to use a reboot command that matches it.

10. After the reboot: congratulations! your machine is now running an s6-based init system.

11. To shut the machine down, use /sbin/shutdown, /sbin/halt, /sbin/poweroff or /sbin/reboot as usual.

  FAQ

•   How do I convert a runit setup to an s6 one ?

    A runit[4] and an s6 setup are very similar. There are just three things you need to pay attention to:

    •   ‘runsv’ supports customized controls, whereas s6-supervise(8) does not. Fortunately, very few services use the customized control feature of runit; and s6 supports customizing the termination signal to a process via the down-signal file ( cf. s6-service-directory(7)), which can replace 99% of the legit uses of customized control. So, you should check your service directories for control/ subdirectories, and adapt them depending on how your service handles controls. If a service does not use customized controls, you don't need to make any change and the service will run under s6-supervise(8) as is.

    •   The interface of ‘svlogd’, runit's logger, is different from the interface of s6-log(8), s6's logger. Namely, ‘svlogd’ reads a config file in its log directory, while s6-log(8) reads its configuration on its command line. If you have logging services that use ‘svlogd’, you should read their configuration in their logdir, and translate it to the proper s6-log(8) invocation.

    •   And, finally, the init process. Understanding how s6-linux-init works may seem daunting, but using it really is a lot simpler than it looks.

    In a runit setup, you have the runit(8) program running as pid 1, and sequentially spawning /etc/runit/1, then /etc/runit/2 which contains the invocation of runsvdir(8), and finally /etc/runit/3 at shutdown time when runsvdir(8) is dead.

    In an s6 setup that you have booted via s6-linux-init, the scanner, s6-svscan(8) ( the equivalent of runsvdir(8)), runs as pid 1, very early, and remains there for the whole lifetime of the machine. At boot time, the /etc/s6-linux-init/current/scripts/rc.init script is run, with the supervision tree already in place; when it exits, the system is supposed to be in a fully-booted, stable state. At shutdown time ( on receipt of a shutdown command), the /etc/s6-linux-init/current/scripts/rc.shutdown script is run, with the supervision tree still in place; when it exits, the filesystems will be unmounted and the machine will be rebooted and/or stopped.

    So, the quickest way to port a runit setup to an s6-linux-init one is to:

    1.  Copy your /etc/runit/1 to /etc/s6-linux-init/current/scripts/rc.init. The only thing you should remove here is the creation of /run, because s6-linux-init(8) has already mounted a tmpfs on /run. But basically all the rest should stay.

    2.  Also copy the parts of /etc/runit/2, if any, that come before the runsvdir(8) invocation, to /etc/s6-linux-init/current/scripts/rc.init.

    3.  At the end of /etc/s6-linux-init/current/scripts/rc.init, symlink all your runit service directories to /run/service, and call ‘s6-svscanctl -a /run/service’. This will start and supervise all the services that you have symlinked, the way the original runsvdir(8) invocation would have.

    4.  Copy your /etc/runit/3 to /etc/s6-linux-init/current/scripts/rc.shutdown, removing the parts that unmount the filesystems and reboot the machine.

    Once you have done that, you have a literal translation of your runit system into an s6 system, and it should boot, and work, albeit in a non-idiomatic, unoptimized way. If you don't want to overwrite your /sbin/init binary, you can boot with ‘init=/etc/s6-linux-init/current/bin/init’ as a kernel command line argument to reach the s6-linux-init(8) entry point.

    Further work to make the setup prettier can include:

    •   Identifying daemons you run in /etc/s6-linux-init/current/scripts/rc.init and making them early services instead.

    •   Or, more idiomatically, analyze your whole boot sequence in /etc/s6-linux-init/current/scripts/rc.init and the daemons in your runit service directories, and convert the boot sequence so it can be handled by a service manager, for instance s6-rc.

    Colin Booth has a series of posts on Reddit[5] that go into more detail on how to use a Void Linux distribution, which natively uses runit, with the s6 ecosystem instead; there are step-by-step tutorials as well as turnkey solutions, and it is recommended reading even if you do not use Void.

SEE ALSO
s6-linux-init-echo(1), s6-linux-init-overview(7), s6-linux-init-why(7), s6-linux-init(8), s6-linux-init-hpr(8), s6-linux-init-logouthookd(8), s6-linux-init-maker(8), s6-linux-init-nuke(8), s6-linux-init-shutdown(8), s6-linux-init-shutdownd(8), s6-linux-init-telinit(8), s6-linux-init-umountall(8)

[1] https://skarnet.org/software/skalibs/

[2] https://skarnet.org/software/execline/

[3] https://skarnet.org/software/s6/

[4] http://smarden.org/runit/index.html

[5] https://www.reddit.com/r/voidlinux/comments/khn1jy/adventures_in_booting_void_on_s6/

This man page is ported from the authoritative documentation at: https://skarnet.org/software/s6-linux-init/quickstart.html

AUTHORS
Laurent Bercot Alexis <flexibeast@gmail.com> (man page port)