From 776c6ad7c4e24bdb5e039c088703f1fee9a2cfd8 Mon Sep 17 00:00:00 2001 From: Laurent Bercot Date: Wed, 23 Sep 2015 03:37:07 +0000 Subject: Some documentation updates --- doc/faq.html | 51 ++++++++++++++++++++++++++++++++++++++++++++++++--- doc/s6-rc-update.html | 14 +++++++++++--- doc/s6-rc.html | 9 +++++---- 3 files changed, 64 insertions(+), 10 deletions(-) diff --git a/doc/faq.html b/doc/faq.html index 2fe7acd..692c7f7 100644 --- a/doc/faq.html +++ b/doc/faq.html @@ -25,10 +25,13 @@ Why not put all the information for a service in a single file?

- Because parsing sucks. Writing parsers is an annoying, ungrateful task; -and automatic parser generators produce big and inefficient code. For + Because parsing sucks. Writing parsers is an annoying, ungrateful task, +with significant risks of bugs and security holes; +and automatic parser generators produce big and inefficient code - and +they are not immune to bugs or security holes either. For security, efficiency and maintainability reasons, I prefer to focus my -efforts on code that actually does stuff, not parsing code. +efforts on code that actually does stuff, not code that parses a text +file.

@@ -206,5 +209,47 @@ for. When in doubt, use bundles.

+

Mechanism vs. policy

+ +

s6-rc feels bare: there are tools, but no wrappers, no pre-packaged +scripts to boot my machines, no default runlevels. By comparison, OpenRC +provides a complete default set of scripts!

+ +

+ In the world of software development, it is important to distinguish +mechanism from policy. Mechanism is "how do I perform +the job", and should, theoretically, be addressed by software authors. +Policy is "what are the details of the job I perform, where should I +put my files, what conventions do I use", and should, theoretically, be +addressed by Unix distributions. +

+ +

+ Like the rest of skarnet.org +software, s6-rc aims to provide mechanism, not policy: +it is OS-agnostic and distribution-agnostic. Providing boot scripts, +or anything of this kind, would go against this principle; it is +possible that a policy defined by software conflicts with a +policy defined by a distribution, for instance the provided boot +scripts do not match the distribution's needs, and so the distributors +have to patch the software! +

+ +

+ The s6-rc tools only provide mechanism, so they can be used as is by +individual users, or by a distribution. They do not need to be patched. +It is up to distributions to provide their own policy surrounding those +tools, including complete service databases. It is literally the +distributors' job! +

+ +

+ OpenRC is a different case, because it was developed by and +for a Linux distribution, so with that in mind, the OpenRC +developers did not have to think much about separating mechanism from policy. +It works very well for Gentoo and Gentoo-derived distributions; but it +requires more work to use OpenRC outside of that frame. +

+ diff --git a/doc/s6-rc-update.html b/doc/s6-rc-update.html index fc049b4..1e56ba2 100644 --- a/doc/s6-rc-update.html +++ b/doc/s6-rc-update.html @@ -32,7 +32,7 @@ s6-rc-update will do its best on its own, but it lets the user give it instructions to handle difficult cases; and rather than implement doubtful heuristics, it will fail with an error message in -situations it really cannot solve. +situations it cannot solve.

Interface

@@ -254,13 +254,21 @@ be the same argument that was given to the booted. In other words: it should be the name of the symbolic link pointing to the real directory containing the live information, not the name of the real directory. -
  • The old compiled service database is left unchanged, and the new compiled +
  • If a longrun service is renamed from oldname to newname, +but not restarted, the +s6-supervise +process in charge of it will still show up in the process list as +s6-supervise oldname. This is purely cosmetic. To make +s6-supervise pick up the new name, make sure to restart the service when +invoking s6-rc-update.
    • +
  • After a s6-rc-update invocation, the old compiled service database +is left unchanged where it was, and the new compiled service database is used in-place. If the machine is rebooted, the s6-rc-init invocation will still boot on the old compiled unless more work is performed. It is recommended to keep a current symbolic link to the current compiled, to always s6-rc-init on current, and to -make current point to the new compiled right after a s6-rc-update +make current a link to the new compiled right after a s6-rc-update invocation.
    • diff --git a/doc/s6-rc.html b/doc/s6-rc.html index 5cdf720..8eb0753 100644 --- a/doc/s6-rc.html +++ b/doc/s6-rc.html @@ -223,10 +223,11 @@ it will exit 1.

    Longrun transitions

    - Transitions for longrun services are simple: s6-rc removes or create -a down file, then sends a command + Transitions for longrun services are simple: s6-rc removes or creates +a ./down file in the live service directory for the longrun +service, then sends a command to the supervision tree to start or stop the service. (A service that -is considered down by s6-rc will have a down file in its live service +is considered down by s6-rc will have a ./down file in its live service directory; a service that is considered up by s6-rc will not.) The transition is considered successful as soon as the daemon dies (for down transitions), or becomes up and @@ -236,7 +237,7 @@ readiness notification, the s6-svc command that is invoked by s6-rc will print a warning message, and the transition will be considered successful as soon as the daemon -is up, i.e. as soon as the run script is executed by +is up, i.e. as soon as the ./run script is executed by s6-supervise.

    -- cgit v1.2.3