S6-INSTANCE-MAKER(8)

📦 version 2.15.1.0, in nixpkgs unstable

💅 s6-instance-maker — the manual, but make it make sense

okay so bestie, welcome to s6-instance-maker (that's section 8 of the System Manager's Manual, iykyk) — the offline little tool that takes one templated service directory and ✨slaps out✨ a whole service directory that can launch and manage several instances. Each instance runs a copy of the directory you handed it. Iconic behavior, honestly.

🌸 SYNOPSIS 🌸

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

💖 DESCRIPTION 💖

So here's the vibe: you give s6-instance-maker a templated service directory that describes how to run one instance of a service, and it creates a different service directory that can launch and manage several instances. Each of those instances is running a copy of the service directory you gave it. No cap. 🫶

Alternative route: s6-instance-maker can also create source definition directories for the s6-rc service manager[1]. Two paths, both slay.

s6-instance-maker creates a service directory in dir — and heads up, dir must not already exist, like, don't even try it. The created service is a supervisor for a set of instances (initially empty, as it should be 💅), each running a copy of the service directory given in template.

s6-instance-maker is an offline tool: you run it before you actually need instances. Once the created service directory is live — meaning there's a supervisor running on it — then you can create and delete individual instances with the online tools s6-instance-create(8) and s6-instance-delete(8), which are the ones that work with active services. Different eras, different tools, periodt.

s6-instance-maker makes use of the fact that execline[2] scripts are much easier to generate programmatically and to harden than shell scripts, so it is only built if s6 is built with execline support — i.e. the --disable-execline switch has not been given to configure. No execline, no maker, that's the rule 🎀

⚠️ Real talk: if s6-instance-maker encounters failure (and exits 111), it does not clean up the directories it created. So always check its return code and clean up after it if you need to. Not me being dramatic, that's just the actual behavior 😭

🦋 The templated service directory 🦋

template should be a directory that looks exactly like a service directory. It will not be live — 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. So yes, you can safely move or delete template after running s6-instance-maker. Girl math that actually works 💅

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. That argument will be the name of the instance, exactly as provided by the s6-instance-create(8) invocation. Cute, right? 🌸

🎀 Logging 🎀

The service is logged: its stderr and stdout are piped to an s6-log(8) process running as loguser and writing to the logdir directory. This logger is the catch-all logger for all the instances and the supervision tree hosting them. If user and loguser are both provided, it is recommended to make them distinct from each other. (Besties are great; sharing a UID is not 💀)

Additionally, if template has a log subdirectory, then each instance gets 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 actually use this, so loggers are properly differentiated between instances. Example of why: it is not possible to run several s6-log(8) processes on the same log directory, so an instance logger script containing an invocation of s6-log(8) on a fixed logdir will fail as soon as there are 2 instances. Two instances, one logdir, zero chill 🙈

✨ OPTIONS ✨

  • -c max — Plan for a maximum of max instances. Default is 500. You can't set it lower than 2 or higher than 90000. Also, if your template service directory is logged, it's unadvisable to set this above the default. Lowkey a warning, highkey a warning 💅
  • -r service[/logger[/pipeline]] — Create s6-rc[1] source definition directories. When this option is given, dir is not created as a service directory, but as a directory containing at least one service: dir/service. dir is suitable as a source argument to s6-rc-compile[3]. If a logger part is given, then a second service, dir/logger, is also created, as a consumer for dir/service, and the -L option must also be used, to provide a directory to store the logs into. If the /pipeline part is also given, pipeline is used as a name for a bundle containing both service and logger. When the -r option is not given at all, dir is a regular service directory for direct inclusion (or linking) in a host s6-scan-directory(7), and if the -L option is given then the logger for the instance supervisor and all its instances is declared in dir/log. Whew, that was a mouthful, but every word matters 🔥
  • -u user — Run the instance supervisor, and all of the instances, as user user. This option should only be used when the supervision tree that will host the instanced service is run as root. The default is that the service runs as the same user as the host supervision tree. Root-only vibes 🫶
  • -l loguser — Run the logger of the instance supervisor, if any (see -L below), as user loguser. This option should only be used when the supervision tree that will host the instanced service is run as root. The default is that the logger runs as the same user as the host supervision tree. Same root-only energy 💅
  • -L logdir — Make the service logged via s6-log(8), and ensure its log messages go into logdir. Error messages from the instance supervisor as well as from every instance will be logged to logdir. If this option is not given, those error messages fall through to the host supervision tree's catch-all logger, if any, or standard error otherwise. And ngl, the options listed below are only used to configure the logger and are meaningless if -L is not given. Like, they literally do nothing. Don't be that girl 😭
  • -t stamptype — How logs are timestamped in logdir. 0 means no timestamp, 1 means external TAI64N format[4], 2 means ISO 8601 format[5], and 3 means both. Default is 1. Pick your fighter ⭐
  • -n nfiles — Maximum number of archive files in logdir. Default is 10.
  • -s filesize — Maximum size of the current file (and archive files) in logdir. Default is 1000000.
  • -S maxsize — Maximum total size of the archives in logdir. Default is 0, meaning no limits apart from those enforced by the -n and -s options. Freedom 🌈
  • -P prefix — when logging to logdir, prefix logged lines with the prefix string. Default is no prefix. (note the lowercase "when" — we keep it real here 🍓)

👑 EXIT STATUS 👑

  • 0 — Success. Slay. 🎉
  • 100 — Wrong usage.
  • 111 — System call failed. (and remember, no cleanup on this one! 😭)

🧚 SEE ALSO 🧚

s6-instanced-service(7), s6-instance-control(8), s6-instance-create(8), s6-instance-delete(8), s6-instance-list(8), s6-instance-status(8)

💜 AUTHORS 💜

Laurent Bercot Alexis <flexibeast@gmail.com> (man page port)

and that's the whole page, bestie — brought to you by the Debian crew, dated January 15, 2023, for S6-INSTANCE-MAKER(8) 💅✨🎀

📦 where this page comes from