S6-INSTANCED-SERVICE(7)

NAME
s6-instanced-service - dynamic instantiation

DESCRIPTION
An instanced service is a parameterized service that you want to run several copies of, with only the parameter changing. Each copy of the service is called an instance.

With s6, an s6-service-directory(7) can only handle one process at a time. So, if we want instanced services, there will have to be one service directory per instance, always.

Static instantiation means that the set of possible instances is finite and known in advance. With s6, it means that all the service directories for all possible instances are created, typically by a preprocessor, and instances are treated like regular services.

Dynamic instantiation means that instances are created on demand instead of preallocated. Starting with version 2.11.2.0, s6 provides a few tools to help users set up and manage dynamically instanced services.

  How to make a dynamically instanced service under s6

•   Write a template for a service directory that would run under s6-supervise(8). The run script should take the name of the instance as its first argument; the finish script, if present, should take the name of the instance as its third argument.

•   Call the s6-instance-maker(8) program with this template as first argument, and a path dir as second argument. s6-instance-maker(8) will create a service directory in dir. This is an offline tool: it does not interact with any currently active services or supervision trees.

•   Supervise dir by adding it to your regular s6-scan-directory(7). This will be your instanced service, but it's not running any instances yet. It is, instead, a nested supervision tree - the instanced service is an s6-svscan(8) process that will supervise all the instances.

•   Create and delete instances at will with the s6-instance-create(8) and s6-instance-delete(8) programs; you can list all the available instances with s6-instance-list(8). These tools are online: they work with live service directories, i.e. that are being supervised by s6-supervise(8).

•   Instances are regular supervised processes. You can control individual instances with s6-instance-control(8), and check their status with s6-instance-status(8). These tools are online as well.

  Internal workings
This section is not normative; users should not rely on it. It is only here for informational purposes.

•   The service directory created by s6-instance-maker(8) has three specifics subdirectories in it: instance and instances, which are initially empty, and template, storing the template service directory.

•   When the service is active, there is an s6-svscan(8) process running on instance.

•   s6-instance-create(8) makes a copy of template into instances/name, and s6-svlink(8) s instances/name to instance. When it returns, there is an s6-supervise(8) process running on instance/name, and the instance may be up or not depending on the given options.

•   s6-instance-control(8) is syntactic sugar around s6-svc(8) on instance/name.

•   s6-instance-status(8) is syntactic sugar around s6-svstat(8) on instance/name.

•   s6-instance-delete(8) is syntactic sugar around s6-svunlink(8) on instance/name.

•   s6-instance-list(8) is roughly equivalent to ‘ls -1 instance’.

  Notes
This implementation of dynamic instances may seem expensive: it creates one s6-svscan(8) process per instanced service, and one s6-supervise(8) process per instance. However, remember that these processes use very little private memory, so having additional copies of them is far less expensive than it looks. It's really a convenient way to implement the feature by reusing existing code.

SEE ALSO
s6-instance-control(8), s6-instance-create(8), s6-instance-delete(8), s6-instance-list(8), s6-instance-maker(8), s6-instance-status(8)

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