Setting up a supervised service

Whenever you want to run a program permanently you maybe want to "supervise" it. [http://cr.yp.to Dan J. Bernstein] created the "daemontools" package, which contains supervise, [http://smarden.org/pape Gerrit Pape] has created runit, a GPL'd substitute.

You tell supervise to supervise a certain program, by

  1. creating a directory for program
  2. putting a script named run into this directory. run must launch program
  3. optionally create a log subdirectory to set up a supervised log-service for /program/
  4. create a symbolic link /service/program which points to the directory with the run-script If a supervised program ends, it will be re-lauched by supervise within five seconds, so your services never die forever.

It is easy to know if a services is running, and it is easy to restart a service.

This document tells you how to set up a supervised service in Debian GNU/Linux.

Required Packages

apt-get install runit

Read the html documentation of runit at file:///usr/share/doc/runit/index.html, especially the collection of runscripts at: file:///usr/share/doc/runit/runscripts.html may be useful.

Log User

I recommend strongly to create a user who will own the logs of your services. The securest practice is to create an individual log-user for each service, however it is better to have at least a separate user for all the supervised logs (and maybe others).

adduser --gecos "Log - User" --ingroup adm \
        --home /var/log --no-create-home \
        --disabled-login --disabled-password \

Create a supervised directory

The supervised directories are usually created in /etc with the name of the program to supervise.

# mkdir /etc/program
# cd /etc/program

the run script usually starts with:

exec 2>&1
exec ... program

the exec 2>&1 joins standard error and standard output of the supervised program, so they go both to the log.

When you launch the program it is wise to exec it, instead of run it as a sub-process, so you spare memory by re-using the shell from the first line of the file.

Don't forget to

# chmod +x run

it has to be executable, of course, and you can test it with:

# ./run

It should not go into the background, and it should be stoppable with Ctrl+C.

Setting up a log service

From within the /etc/program directory we do:

# mkdir log
# cd log

and create a run script with the following contents:

exec chpst -u log svlogd -t ./main

then we create the log directory following Debian standards and link it to main:

# mkdir /var/log/program
# chown log:adm /var/log/program
# chmod u=rwx,g=rxs,o-rwx /var/log/program
# ln -s /var/log/program main

of course you chmod +x'ed run and test it the same way like in the service directory.

Starting it all up

 # cd ..
 # ln -s `pwd` /service
... and repeating several times 
 # svstat . log

will show us, if everything is running fine.

In case the services won't start up, but the log services does, you can follow the log with:

# tail -F /var/log/progam/current

Removing a Service

# cd /service/program
# rm /service/program
# svc -dx . log