s6.md: new article

articles/s6.md

@@ -0,0 +1,122 @@
+# s6
+s6 is a init system, process supervision and service manager suite written by Laurent Bercot aiming to be a solid
+alternative against [SystemD](systemd.md) on [Linux](linux.md) in just a fraction of soystemd code and complexity
+and with better reliability and security (Note that s6 is not Linux-only).
+
+The following cheatsheet is a WIP.
+
+## execline
+[execline](https://skarnet.org/software/execline/) is a scripting language meant to replace
+[shell script](shell_script.md) while being simpler than the latter, for writing service scripts.
+
+TODO
+
+## Services
+Different from other service supervision suites, s6 compiles its service definitions into
+a database file. This makes s6 more efficient than for example, [runit](runit),
+since it does not scan periodically for new services (runit's `runsvdir` [scans every 5 seconds](https://smarden.org/runit/runsvdir.8)).
+Instead, the database is updated and s6 is told to reload the database to include the
+new defined services.
+
+## Bundles
+A bundle is a collection of multiple services or even other bundles that may be started concurrently.
+For example, we can have an 'audio' bundle that includes Pipewire and Wireplumber. Then, by starting the
+'audio' bundle, both of these services will be started.
+
+### Controlling services (s6-rc)
+[Source](https://skarnet.org/software/s6-rc)
+s6-rc is the default service manager for the s6 supervision suite.
+
+s6-rc operates on a 'live' set of services. The location of this 'live' is configurable at compile time,
+therefore different distros may have a different path for it, but by default is `/run/s6-rc`.
+Alternatively, a different live set can be explicitly specified with the `-l` flag.
+
+#### Quick usage reference
+`s6-rc [start | stop] service_or_bundle`
+```sh
+s6-rc -u change foo # Starts service or bundle `foo`, including its dependencies.
+s6-rc -d change foo # Self explanatory
+s6-ec -D change foo # Forcedly stop a service
+s6-rc start foo     # Shorthands for the above commands
+s6-rc stop foo
+
+s6-rc -a list       # List all active services
+s6-rc -da list      # List all inactive services
+s6-rc -d listall bundle # List all atomic services and its dependencies from a bundle
+```
+
+### Creating services
+For this example, we're going to create a 
+#### Structure of a s6 service
+[Source](https://skarnet.org/software/s6/servicedir.html)
+```
+foo/
+  supervise/    # optional, s6-supervise will create it anyways
+  run           # (longruns only) executable file, this launches the service
+  finish        # (longruns only) optional, run then the service dies
+  up            # (oneshots only) executable, run when the service is started
+  down          # (oneshots only) executable, run when the service is stopped
+  type          # Used by s6-rc, declares the service type
+```
+
+#### Run file
+The most important file within the service directory, this is where we launch the service
+and do any previous setup that may be required for the service.
+
+Let's start with something simple:
+```execline
+fdmove -c 2 1           # Redirect stderr to stdout
+exec command args...    # Execute the service, with the provided arguments
+```
+
+```execline
+fdmove -c 2 1
+```
+First we make sure that the stderr output gets redirected to stdout. This will be useful
+if we want to setup a logging service for this service. You can leave it out if you don't care
+about logging. This is equivalent to `2>&1` in shell script.
+
+```execline
+exec command args...
+```
+Lastly, we finally launch the service `command` and we pass to it any arguments that it
+may need.
+
+Ensure it is executable:
+```sh
+chmod +x run
+```
+
+#### Type file
+A text file containing the service type, used by `s6-rc`.
+Possible values are `oneshot`, `longrun` or `bundle`.
+For this example, our service is a long-lived one, so we'll use the `longrun`.
+```
+longrun
+```
+
+#### Reloading the database
+s6, unlike other supervision systems like runit, does not check for new services unless told.
+This means we have to tell s6 about our new service:
+
+#### Logging
+TODO
+
+## For Linux distros with s6 as their init system
+### Power off / Rebooting
+[Source](https://skarnet.org/software/s6-linux-init/s6-linux-init-shutdown.html)
+
+```sh
+shutdown -Ph now        # Shuts down immediately
+shutdown -Ph +2         # Shuts down after 2 minutes
+shutdown -r now        # Reboots immediately
+
+shutdown -c             # Cancel a scheduled shutdown event (as long the shutdown sequence hasn't started yet)
+```
+The `-P` ensures that the machine is powered off. Note that it has to be used with either
+`-h` (halt) or `-r` (reboot).
+
+## Linux distributions offering s6
+- [Artix Linux](https://artixlinux.org)
+- [Gentoo](https://gentoo.org)
+- [Obarun](https://web.obarun.org/)