S6-SCAN-DIRECTORY(7)

📦 version 2.15.1.0, in nixpkgs unstable

💅 S6-SCAN-DIRECTORY(7) — scan directory energy, explained 💅

okay so this is S6-SCAN-DIRECTORY(7) from the Miscellaneous Information Manual, and we are gonna make the scan directory situation make sense, bestie. no cap. 🫶

🌸 NAME 🌸

s6-scan-directory — a directory containing a list of service directories, or symbolic links pointing to service directories. that's the whole little icon of it. ✨

✨ DESCRIPTION ✨

A scan directory represents a list of services that are supposed to be supervised. Running s6-svscan(8) on this scan directory launches a supervision tree: every service listed in the scan directory will be supervised. literally the main character move. 👑

There is normally only one scan directory per system, although nothing prevents a system administrator from having more. daemontools[1] traditionally uses /service, and runit[2] traditionally uses /etc/service. s6 does not care where your scan directory is, but I would advise /service for compatibility with daemontools. Depending on your installation, /service could be a symbolic link and point to a place either in a RAM filesystem or in /var. iykyk. 💖

🛠️ Where and how to build a scan directory 🛠️

Opinions and practices differ. and honestly? valid.

It is generally accepted that the place where you store all your service directories (your “service repository”) should not be used as a scan directory — for a simple reason: you might want to have service directories for more services than what you want to start at any given time. In other words, your scan directory will be a subset of your service repository, so you cannot just run s6-svscan(8) on every service you have a service directory for. So, the first thing is to separate your service repository, which is just a storage place for all the services you might want to manage someday, and your scan directory, which is a directory representing all the services that you are currently managing. separation is self-care, periodt. 🦋

🗂️ SERVICE REPOSITORY 🗂️

Where to store your service repository is purely a matter of personal preference. You just have to be aware that s6-supervise(8) needs writable supervise and event subdirectories in a service directory it monitors. noted, bestie. ✨

📁 SCAN DIRECTORY 📁

Where and how to build your scan directory depends heavily on your boot system — and on your personal preference too.

Standard daemontools[1] and runit[2] installations like to have a fixed scan directory containing symlinks to service directories located in the service repository. In other words, the service repository contains the real working copies of the service directories. This works, as long as:

  • It is possible to create writable supervise and event subdirectories in every managed service directory. This can be achieved for instance via symlinks, or by having the service repository stored on a writable filesystem.
  • The scan program (s6-svscan(8), svscan, runsvdir(8) ...) is started late enough for all the necessary filesystems to be mounted.

ngl, my own recommendation would be to have working copies of the service directories entirely separate from the service repository. The service repository can be safely stored on the root filesystem, and the needed directories copied to a RAM filesystem at boot time. The scan directory can be either the place where the working copies are written, or another directory containing symlinks to those working copies. (The latter is useful if you are using the -t option to s6-svscan(8) with a nonzero argument: copying a directory is not atomic, but making a symlink is, so there is no risk of your scanner finding a directory while it is being copied — which could result in s6-supervise(8) getting the wrong information and not managing the service properly.) this is the good stuff, fr fr. 🔥

An example:

  • Have your service repository in /img/services, i.e. have service directories in /img/services/ftpd, /img/services/httpd, /img/services/sshd, etc.
  • When booting, make /tmp a RAM filesystem, and create the directories /tmp/services and /tmp/service.
  • Have s6-svscan(8) run on /tmp/service, as early as possible in your boot sequence. This is possible whether you want to run s6-svscan(8) as process 1[3] or not[4].
  • During the boot sequence, populate /tmp/services with copies of the service directories you need: for instance,
cp -a /img/services/sshd /tmp/services/sshd
cp -a /img/services/ftpd /tmp/services/ftpd
etc.
  • When you are ready to start a service, make a symlink in the /tmp/service scan directory pointing to the working copy of the s6-service-directory(7) you need in /tmp/services, then notify s6-svscan(8). For instance, to start ftpd and httpd together:
ln -s ../services/ftpd /tmp/service
ln -s ../services/httpd /tmp/service
s6-svscanctl -a /tmp/service

iconic boot sequence behavior, honestly. 💅

👀 SEE ALSO 👀

This man page is ported from the authoritative documentation at: https://skarnet.org/software/s6/scandir.html slay for documentation preservation. 🎀

💖 AUTHORS 💖

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

okay that's the whole page, bestie! 💖 this cutie came from Debian, dated September 29, 2021, and it's the S6-SCAN-DIRECTORY(7) manual page. bye bestie! 🫶🌸

📦 where this page comes from