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, a service directory 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 188.8.131.52, s6
provides a few tools to help users set up and manage dynamically
How to make a dynamically instanced service under s6
- Write a template for a service directory that would run under
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 program
with this template as first argument, and a path dir as second
argument. s6-instance-maker 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
scan directory. 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 process that will supervise all the
- Create and delete instances at will with the
s6-instance-delete programs; you
can list all the available instances with
These tools are online: they work with live service directories,
i.e. that are being supervised by s6-supervise.
- Instances are regular supervised processes. You can control individual
instances with s6-instance-control,
and check their status with
s6-instance-status. These tools
are online as well.
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
has two specific subdirectories in it: instance and instances. They
are initially empty, except that the template service directory is stored in
- When the service is active, there is an s6-svscan
process running on instance.
- s6-instance-create makes a copy of
instances/.template into instances/name, and
s6-svlinks instances/name to
instance. When it returns, there is an s6-supervise
process running on instance/name, and the instance may be up
or not depending on the given options.
- s6-instance-control is syntactic sugar
around s6-svc on instance/name.
- s6-instance-status is syntactic sugar
around s6-svstat on instance/name.
- s6-instance-delete is syntactic sugar
around s6-svunlink on instance/name.
- s6-instance-list is roughly equivalent
ls -1 instance .
- This implementation of dynamic instances may seem expensive: it
creates one s6-svscan process per
instanced service, and one s6-supervise
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.