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 and delete individual instances via the s6-instance-create and s6-instance-delete online tools, that work with active services.
Exit codes
- 0: success
- 100: wrong usage
- 111: system call failed
Options
- -c max : Plan for a maximum of max instances. Default is 500. You can't set it lower than 2 or higher than 90000. If your template service directory is logged, it's unadvisable to set this above the default.
- -r service[/logger[/pipeline]] : create s6-rc source definition directories. When this option is given, dir is not created as a service directory, but as a directory containing at least one service: dir/service. dir is suitable as a source argument to s6-rc-compile. If a logger part is given, then a second service, dir/logger, is also created, as a consumer for dir/service, and the -L option must also be used, to provide a directory to store the logs into. If the /pipeline part is also given, pipeline is used as a name for a bundle containing both service and logger. When the -r option is not given at all, dir is a regular service directory for direct inclusion (or linking) in a host scan directory, and if the -L option is given then the logger for the instance supervisor and all its instances is declared in dir/log.
- -u user : run the instance supervisor, and all of the instances, as user user. This option should only be used when the supervision tree that will host the instanced service is run as root. The default is that the service runs as the same user as the host supervision tree.
- -l loguser : run the logger of the instance supervisor, if any (see -L below) as user loguser. This option should only be used when the supervision tree that will host the instanced service is run as root. The default is that the logger runs as the same user as the host supervision tree.
- -L logdir : make the service logged via
s6-log, and ensure its log messages go into logdir.
Error messages from the instance supervisor as well as from every instance will
be logged to logdir. If this option is not given, these error messages
will fall through to the host supervision tree's catch-all logger, if any,
or standard error otherwise.
The options listed below are only used to configured the logger and are meaningless if -L is not given. - -t stamptype : how logs are timestamped in logdir. 0 means no timestamp, 1 means external TAI64N format, 2 means ISO 8601 format, and 3 means both. Default is 1.
- -n nfiles : maximum number of archive files in logdir. Default is 10.
- -s filesize : maximum size of the current file (and archive files) in logdir. Default is 1000000.
- -S maxsize : maximum total size of the archives in logdir. Default is 0, meaning no limits apart from those enforced by the -n and -s options.
- -P prefix : when logging to logdir, prefix logged lines with the prefix string. Default is no prefix.
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 all the instances and the supervision tree hosting them. If user and loguser are provided, it is recommended to make them distinct from each other.
Additionally, 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 example, 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
- s6-instance-maker makes use of the fact that execline scripts are much easier to generate programmatically and to harden than shell scripts, so it is only built if s6 is built with execline support - i.e. the --disable-execline switch has not been given to configure.
- If s6-instance-maker encounters failure (and exits 111), it does not clean up the directories it created. Make sure to always test s6-instance-maker's return code and clean up after it if needed.