S6-INSTANCE-MAKER(8)

NAME
s6-instance-maker - create an s6-service-directory(7) implementing an s6-instanced-service(7)

SYNOPSIS
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

DESCRIPTION
Give s6-instance-maker 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[1].

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(8) and s6-instance-delete(8) online tools, that work with active services.

s6-instance-maker makes use of the fact that execline[2] 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.

  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(8) invocation.

  Logging
The service is logged: its stderr and stdout are piped to an s6-log(8) 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 instance, it is not possible to run several s6-log(8) processes on the same log directory, so an instance logger script containing an invocation of s6-log(8) on a fixed logdir will fail as soon as there are 2 instances.

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[1] 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[3]. 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 s6-scan-directory(7), 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(8), 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[4], 2 means ISO 8601 format[5], 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.

EXIT STATUS

0   Success.

100 Wrong usage.

111 System call failed.

SEE ALSO
s6-instanced-service(7), s6-instance-control(8), s6-instance-create(8), s6-instance-delete(8), s6-instance-list(8), s6-instance-status(8)

[1] https://skarnet.org/software/s6-rc/

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

[3] https://skarnet.org/software/s6-rc/s6-rc-compile.html

[4] https://cr.yp.to/libtai/tai64.html

[5] https://www.iso.org/iso/home/standards/iso8601.htm

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