s6
Software
skarnet.org

# 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.

## Exit codes

- 0: success
- 99: timeout while waiting for the instance supervisor to start
- 100: wrong usage
- 111: system call failed

## Options

- `-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.

## Notes

- 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.