From 047befef9b8ef074d34b05e294d753f6c2751987 Mon Sep 17 00:00:00 2001 From: Laurent Bercot Date: Wed, 23 Sep 2015 19:13:22 +0000 Subject: No need for -a in s6-rc -u invocation; remove -X from dryrun print --- doc/faq.html | 129 ++++++++++++++++++++++++++++++++++++++++++++++++++++------- 1 file changed, 114 insertions(+), 15 deletions(-) (limited to 'doc/faq.html') diff --git a/doc/faq.html b/doc/faq.html index 692c7f7..608c5e2 100644 --- a/doc/faq.html +++ b/doc/faq.html @@ -16,13 +16,62 @@ skarnet.org

-

s6-rc: FAQ

+

s6-rc: Frequently Asked Questions

+ +

Quick recipes

+ +

How do I...

+ +

list every active service ?

+ +
s6-rc -a list
+ +

list every service in the current live database, active or not ?

+ +
s6-rc -d list
+

or

+
s6-rc-db list services
+ +

bring up service foo ?

+ +
s6-rc -u change foo
+ +

bring down everything ?

+ +
s6-rc -da change
+ +

print the "up" script for oneshot service foo ?

+ +
s6-rc-db -u script foo | xargs -0 printf "%s "
+ +

see what pipeline longrun service foo is a part of ?

+ +
s6-rc-db pipeline foo
+ +

see the list of all services that depend on foo, +directly or indirectly ?

+ +
s6-rc-db -d all-dependencies foo
+ +

see what services will restart if I update my live service database to +newcompiled ?

+ +
s6-rc-update -n newcompiled
+ +

+ The first line is the s6-rc invocation that +will bring the old services down. The services that will stop are listed +after -- change. + The second line is the s6-rc invocation that +will bring the new services up. The services that will start are listed +after -- change. +

The s6-rc-compile source format

The source format for s6-rc-compile is not very convenient. -Why not put all the information for a service in a single file?

+Why not put all the information for a service in a single file ?

Because parsing sucks. Writing parsers is an annoying, ungrateful task, @@ -37,16 +86,17 @@ file.

Using the filesystem as a key-value store is a good technique to avoid parsing, and skarnet.org packages do it -everywhere: for instance, look at -s6-envdir. +everywhere: for instance, +s6-envdir +uses the file name as a key and the file contents as a value. The s6-rc-compile source format is just another instance of this technique.

- This format generally plays well with automated tools, be it for + The source format generally plays well with automated tools, be it for reading, as s6-rc-compile does, as for writing. -I fully expect the s6-rc-compile source format +I fully expect it to be used as the input (resp. the output) of some automated tools that would convert service definitions to (resp. from) another format, such as systemd @@ -55,17 +105,19 @@ s6-rc source format will make it easy on those tools.

- And if you love configuration files, don't mind writing a parser (which is + And if you love configuration files, are ok with writing a parser (which is indubitably easier to do in other languages than C), and want to write a program that takes a text file, parses it and outputs a service -definition directory, it should also be rather easy. +definition directory in the s6-rc-compile source format, it should also be +rather easy - please, feel free!

There are no "Provides:", no virtual services. What do I do -if I have several implementations for a service?

+if I have several implementations for a service ?

- Use bundles. Bundles are awesome. + Use bundles. Bundles are the solution to most of the questions in +the same vein.

@@ -84,7 +136,7 @@ will resolve to opensshd, and the compiled service database will consider opensshd to be the "real" service; but users will still be able to run s6-rc commands involving sshd. -And if users want to change the default to dropbear, just +And if you want to change the default to dropbear, just change the sshd/contents file to dropbear, recompile the database, and run s6-rc-update. @@ -113,7 +165,7 @@ one of them.

I have a collection of init scripts in another format, but don't want to wait until the whole collection is converted -before switching to s6-rc. Is there a smooth way in?

+before switching to s6-rc. Is there a smooth way in ?

Yes. @@ -163,7 +215,7 @@ you fix it.

There are no runlevels in s6-rc. I like runlevels.

- You have better than runlevels. You have bundles. + You have better than runlevels. You have bundles.

@@ -209,11 +261,57 @@ for. When in doubt, use bundles.

+

There are no intermediate states in s6-rc. There's just "up" +and "down", no "starting", no "failed", etc. Why ?

+ +

+ Because those intermediate states are unnecessary. +

+ +

+ From the machine's point of view, things are simple: a service is +either up or it's not. If a service fails to start, then it's still +down. Note that it is recommended to write atomic oneshots +for this very reason. +

+ +

+ Service managers that use intermediate states do so in order to keep +track of what they're doing and what they have done. But this +introduces needless complexity: the reality is that the service is +either up or down, it's either in the state you wanted it to be or +not. A model should not be more complex than the reality. +

+ +

+ s6-rc does not keep track of "failed" states: a service that fails +to start simply remains down, and +s6-rc exits 1 to report that something +went wrong. To know what services failed to start, compare the +result of s6-rc -a list against your expected machine state. +

+ +

+ The reason for this design is simple: if the +s6-rc process is killed in the middle of a transition +while a service state is "starting", what should the next invocation do? +This is unclear, and the intermediate state introduces ambiguity where +there should not be. Also, +if there is a "failed" service, what should the next invocation do? Try +and restart it, or not? This depends on what the user wants; this is +policy, not mechanism. Simply reporting the error while keeping the +state as "down" allows users to apply their chosen policies - see below. +

+ +

+ Keep it simple, stupid. +

+

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!

+provides a complete default set of scripts !

In the world of software development, it is important to distinguish @@ -248,7 +346,8 @@ distributors' job! 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. +requires adaptation and more work for the admin to use OpenRC outside of +that frame.

-- cgit v1.2.3