S6-INSTANCE-CREATE(8)

✨ S6-INSTANCE-CREATE ✨

okay so this is s6-instance-create(8) from the System Manager's Manual, and bestie, it's literally the birth-certificate tool for instances. let's get into it 💅

---

🌸 NAME 🌸

s6-instance-create — create a brand-new instance of a currently supervised s6-instanced-service(7). that's it, that's the whole vibe. one job, iconic behavior 👑

---

🎀 SYNOPSIS 🎀

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

---

🦋 DESCRIPTION 🦋

so s6-instance-create expects a running, supervised s6-instanced-service(7) sitting in servicedir. this service typically got there by linking the result of an s6-instance-maker(8) invocation into an existing s6-scan-directory(7). ikyk how that pipeline goes ✨

then s6-instance-create creates a new instance of that service, named name. depending on which options you pass, it may start it immediately, or keep it down until a later s6-instance-control(8) invocation. your call, main character 🌈

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

and then it exits 0. slay.

ngl, s6-instance-create is giving 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. like adding a new member to the group chat and making sure they actually get the notifs 🫶

lowkey important: 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. both. no skipping 👀

okay listen, real talk: 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. compare that to s6-instance-control(8), which only has to send commands to already existing supervisors. so if you're gonna turn instances on and off on a regular basis, it is way more efficient to keep the instance existing and control it with s6-instance-control(8) than to repeatedly create and delete it. fr fr, don't do the expensive thing on a loop 💀

---

💖 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. this one's committed to the nap 😴
• -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. open invite, no bouncer 🎉
• -f — Force permissions. you should never need to use this option, it is only there for testing purposes. like, genuinely, hands off 🙈
• -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. no clock, no stress ⏰

---

⭐ EXIT STATUS ⭐

• 0 — Success. we ate. 🔥
• 99 — Timeout while waiting for the instance supervisor to start. 😭
• 100 — Wrong usage. bestie what did you type 💀
• 111 — System call failed. not our fault, the kernel said no 🫠

---

💜 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) — the whole friend group, go say hi 🌸

---

👑 AUTHORS 👑

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

---

okay bye bestie, go forth and create instances responsibly 🧚‍♀️💫 this page is from Debian, dated January 11, 2023 — thank you for coming to my Ted Talk, mwah 🍓