s6: the s6-instance-create program

The s6-instance-create program

s6-instance-create creates a new instance of a currently supervised instanced service.

Interface

     s6-instance-create [ -d | -D ] [ -P ] [ -f ] [ -t timeout ] servicedir name

s6-instance-create expects a running, supervised instanced service in servicedir. This service typically has been created by linking the result of an s6-instance-maker invocation into an existing scan directory.
s6-instance-create creates a new instance of that service, named name. Depending on the given options, it may start it immediately, or keep it down until a later s6-instance-control invocation.
It waits for the new instance to be ready to take commands from s6-instance-control.
It exits 0.

-d : down. The instance supervisor will be started, but the instance itself will remain down. Any down file for the instance will be deleted. By default, if neither the -d nor -D options have been given, the supervisor auto-starts the instance as soon as it runs.
-D : down, and stay down. The instance supervisor will be started, but the instance itself will remain down. A down file will be created for the instance. By default, if neither the -d nor -D options have been given, the supervisor auto-starts the instance as soon as it runs.
-P : public. Everyone will be able to subscribe to the instance supervisor's notification. By default, only processes running with the same gid as the instanced service can subscribe to it.
-f : force permissions. You should never need to use this option, it is only there for testing purposes.
-t timeout : if the instance supervisor has not started after timeout milliseconds, s6-instance-create will print a message to stderr and exit 99. By default, timeout is 0, which means no time limit.

s6-instance-create is similar to s6-svlink, because it uses the same underlying library functions. Under the hood, an instance is a regular service running on a supervision tree that is specific to the instanced service, and s6-instance-create adds a service directory to that tree and ensures it gets supervised.
If the template for the service is logged, then s6-instance-create will wait until supervisors have been spawned for both the instance and its logger.
s6-instance-create and s6-instance-delete are relatively expensive operations, because they have to recursively copy or delete directories and use the synchronization mechanism with the instance supervisor, compared to s6-instance-control which only has to send commands to already existing supervisors. If you are going to turn instances on and off on a regular basis, it is more efficient to keep the instance existing and control it with s6-instance-control than it is to repeatedly create and delete it.