From 09750ce3525129a676dec4f579aea3ad2eca1b19 Mon Sep 17 00:00:00 2001 From: Laurent Bercot Date: Mon, 9 Jan 2023 11:09:14 +0000 Subject: Add instances implementation (still needs testing) Signed-off-by: Laurent Bercot --- doc/s6-instance-maker.html | 203 +++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 203 insertions(+) create mode 100644 doc/s6-instance-maker.html (limited to 'doc/s6-instance-maker.html') diff --git a/doc/s6-instance-maker.html b/doc/s6-instance-maker.html new file mode 100644 index 0000000..2eb0f4e --- /dev/null +++ b/doc/s6-instance-maker.html @@ -0,0 +1,203 @@ + + + + + + s6: the s6-instance-maker program + + + + + + +

+s6
+Software
+skarnet.org +

+ +

The s6-instance-maker program

+ +

+s6-instance-maker creates a service directory +implementing an instanced service. Give it a +templated service directory describing how to run an instance of a service, +and it will create a different service directory that can launch and +manage several instances; each of these instances will be running a +copy of the service directory you gave. +

+ +

+ Alternatively, s6-instance-maker can create source definition directories +for the s6-rc service manager. +

+ +

Interface

+ +
+     s6-instance-maker \
+       [ -c maxinstances ] \
+       [ -r service[/logger[/pipeline]] ] \
+       [ -u user ] \
+       [ -l loguser ] \
+       [ -L logdir ] \
+       [ -t stamptype ] \
+       [ -n nfiles ] \
+       [ -s filesize ] \
+       [ -S maxsize ] \
+       [ -P prefix ] \
+       template dir
+
+ +

+s6-instance-maker creates a service directory in dir. The +created service will be a supervisor for a set of instances (initially empty) +each running a copy of the service directory given in template. +

+ +

+s6-instance-maker is an offline tool: it is run before you need +instances. Once the created service directory is live, i.e. there is a +supervisor running on it, then you can create, delete, or control +individual instances via the +s6-instance-create, +s6-instance-delete and +s6-instance-control online +tools, that work with active services. +

+ +

Exit codes

+ + + +

Options

+ + + +

The templated service directory

+ +

+ template should be a directory that looks exactly like a service +directory. It will not be live, i.e. at no point will template +itself be supervised; instead, a copy of it is stored under dir +(and a copy of that copy will be used for every instance of the service). +You can safely move or delete template after running +s6-instance-maker. +

+ +

+ To differentiate between instances, the run and finish +script in template should take one additional argument (the +first argument for run and the third argument for finish). +This argument will be the name of the instance, as provided by the +s6-instance-create invocation. +

+ +

Logging

+ +

+ The service is logged: its stderr and stdout are piped to an +s6-log process running as loguser and +writing to the logdir directory. This logger is the catch-all logger +for the supervision tree owned by user; it is recommended to make +loguser distinct from user, and to have logdir +in a place that is not under the control of user. +If user wants to keep control of their logs, they can declare a +logger for each of their services. +

+ +

+ If template has a log subdirectory, then each instance +will have its own dedicated logger. The run and finish +scripts for the logger of an instance named name will be called +with an additional argument of name/log. They should +make use of this, to ensure loggers are properly differentiated between +instances: for instance, it is not possible to run several +s6-log processes on the same log directory, +so an instance logger script containing an invocation of s6-log on a fixed +logdir will fail as soon as there are 2 instances. +

+ +

Notes

+ + + + + -- cgit v1.2.3