• Whenever we talk about some arbitrary "service" we will use the example name my_service. The common base directory for a service run through runit is then /etc/service/my_service/, e.g. /etc/service/spark-master holds the service which runs the spark-master.

Reference can be found here.

runit

a UNIX process no 1

runsv

starts and monitors a service and optionally an appendant log service

runsvdir

starts and monitors a collection of runsv(8) processes

sv

controls and manages services monitored by runsv(8)

svlogd

continuously reads log data from the service's stdin, optionally filters log messages, and writes the data to one or more automatically rotated logs.

chpst

runs a program with a changed process state

Processes/services are created as follows:

1. Create a directory under /etc/sv/, e.g. /etc/sv/my_service/, and create a symbolic link from this dir to /etc/service/my_service/.
   • Service directory must be in /etc/service/ for runsv to run it regularly and restart on shutdown, etc.
   • Any service directory added to /etc/service/ through creation or linking will be run by runsv within 5 seconds
   • In fact, normally services run by runsv would be located at /service/ but for some reason the image we use as a base in our docker setup uses /etc/service/ so we're going with that for now.
2. Create a run script, e.g. /etc/service/my_service/run
   • Simply a normal bash script or any executable
   • Make sure it doesn't daemonize (i.e. runs in the background)
   • Make sure it's executable (chmod is your friend)
   • (Optional) Create a finish script which will run, well, when the service finishes, ergo when run process exits.
     • If run or finish exists right away, runsv will wait for a bit before restarting the service
     • When run OR finish finishes, the service will be restarted
       • unless my_service/down file exists, in which case no restart will occur

     • Important: because runsv will stdout to the logging-daemons stdin, we need to pipe stderr to stdout in /etc/service/my_service/run to make sure we get all the output of the service.

       #!/bin/sh
       exec 2>&1
       exec /usr/sbin/my_service
       

3. (Optional) Create a logging directory, to which runsv will pipe the stderr of the service, e.g. /etc/service/my_service/log/
   • This directory follows almost all the same structure as the actual service dir,
     • Requires a run file which will receive the service's stderr on its stdin
     • Optionally can have a finish exec and so on
   • View logs and such using svlogd as mentioned above

   • A typical my_service/log/run will look something like this:

     #!/bin/sh
     exec svlogd -t /var/log/my_service/
     

     where the -t argument is simply to tell svlogd to add the timestamp at the beginning of each line.

4. Control the process using sv command

runsv service

The main thing is that runsv switches to the service directory and runs ./run. Further, it has a lot of conditional behavior: