S6-INSTANCE-CREATE(8)

NAME
s6-instance-create - create a new instance of a currently supervised instanced service

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

DESCRIPTION
s6-instance-create expects a running, supervised s6-instanced-service(7) in servicedir. This service typically has been created by linking the result of an s6-instance-maker(8) invocation into an existing s6-scan-directory(7).

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

It waits for the new instance to be ready to take commands from s6-instance-control(8)

It exits 0.

s6-instance-create is similar to s6-svlink(8), 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(8) are relatively expensive operations, because they have to recursively copy or delete directories and use the s6-ftrigr(7) synchronization mechanism with the instance supervisor, compared to s6-instance-control(8) 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(8) than it is to repeatedly create and delete it.

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.

EXIT STATUS

0   Success.

99  Timeout while waiting for the instance supervisor to start.

100 Wrong usage.

111 System call failed.

SEE ALSO
s6-instanced-service(7), s6-instance-control(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)