s6
Software
skarnet.org

The s6-instance-maker program

s6-instance-maker creates a service directory implementing an instanced service. Give it a templated service directory describing how to run an instance of a service, and it will create a different service directory that can launch and manage several instances; each of these instances will be running a copy of the service directory you gave.

Alternatively, s6-instance-maker can create source definition directories for the s6-rc service manager.

Interface 

     s6-instance-maker \
       [ -c maxinstances ] \
       [ -r service[/logger[/pipeline]] ] \
       [ -u user ] \
       [ -l loguser ] \
       [ -L logdir ] \
       [ -t stamptype ] \
       [ -n nfiles ] \
       [ -s filesize ] \
       [ -S maxsize ] \
       [ -P prefix ] \
       template dir

s6-instance-maker creates a service directory in dir (which must not already exist). The created service will be a supervisor for a set of instances — initially empty — each running a copy of the service directory given in template.

s6-instance-maker is an offline tool: it is run before you need instances. Once the created service directory is live, i.e. there is a supervisor running on it, then you can create, delete, or control individual instances via the s6-instance-create, s6-instance-delete and s6-instance-control online tools, that work with active services.

Exit codes

Options

The templated service directory

template should be a directory that looks exactly like a service directory. It will not be live, i.e. at no point will template itself be supervised; instead, a copy of it is stored under dir (and a copy of that copy will be used for every instance of the service). You can safely move or delete template after running s6-instance-maker.

To differentiate between instances, the run and finish script in template should take one additional argument (the first argument for run and the third argument for finish). This argument will be the name of the instance, as provided by the s6-instance-create invocation.

Logging

The service is logged: its stderr and stdout are piped to an s6-log process running as loguser and writing to the logdir directory. This logger is the catch-all logger for the supervision tree owned by user; it is recommended to make loguser distinct from user, and to have logdir in a place that is not under the control of user. If user wants to keep control of their logs, they can declare a logger for each of their services.

If template has a log subdirectory, then each instance will have its own dedicated logger. The run and finish scripts for the logger of an instance named name will be called with an additional argument of name/log. They should make use of this, to ensure loggers are properly differentiated between instances: for instance, it is not possible to run several s6-log processes on the same log directory, so an instance logger script containing an invocation of s6-log on a fixed logdir will fail as soon as there are 2 instances.

Notes