From 716dde0b12532bb814c3cc8fedd99b8d16b3cf07 Mon Sep 17 00:00:00 2001 From: Laurent Bercot Date: Fri, 11 Sep 2015 17:04:18 +0000 Subject: s6-rc-update doc, bugfix --- doc/s6-rc-compile.html | 12 ++- doc/s6-rc-update.html | 215 +++++++++++++++++++++++++++++++++++++++++++++++-- 2 files changed, 220 insertions(+), 7 deletions(-) (limited to 'doc') diff --git a/doc/s6-rc-compile.html b/doc/s6-rc-compile.html index 0c1afc1..8e4b279 100644 --- a/doc/s6-rc-compile.html +++ b/doc/s6-rc-compile.html @@ -86,6 +86,16 @@ to operate the database. If neither option is used, then root (and only root) is implicitly allowed.

+

+ It is important to only use the -u or -g +options when the user owning the supervision tree is not root. The +internal s6-rc mechanisms allow uids and gids specified by those +options to run any program as the user owning the supervision tree; +if that user is root, this becomes an easy avenue for unwanted +privilege gain. Only specify users that have the right to operate +the supervision tree! +

+

Source format

@@ -363,7 +373,7 @@ Linux system running skarnet.org packages; of course, only the service definition set has been kept, and private information has been removed, so it won't work out-of-the-box without the proper specific files, -notably configuration in /etc/ - but nevertheless, you can browse the +notably configuration in /etc - but nevertheless, you can browse the source and understand what it does, and adapt it to your own needs. It will compile as is with s6-rc-compile, and you can examine the diff --git a/doc/s6-rc-update.html b/doc/s6-rc-update.html index fda6885..ac8377a 100644 --- a/doc/s6-rc-update.html +++ b/doc/s6-rc-update.html @@ -21,13 +21,14 @@

s6-rc-update is an online service database switcher: it will replace your compiled service database with another -one, and adjust the live state accordingly. +one, and adjust the live state accordingly. This allows you to +change your set of services without having to reboot.

- Live upgrading a service database is no small feat, and no + Live upgrading a service database is not easy, and no fully automated system can get it right in all cases. -s6-rc-update will do its best on its own, but it lets you +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 @@ -36,11 +37,213 @@ situations it really cannot solve.

Interface

+
+     s6-rc-update [ -n ] [ -v verbosity ] [ -t timeout ] [ -l live ] [ -f convfile ] newdb
+
+ + + +

Exit codes

+ + + +

Options

+ + + +

Transition details

+ +

+ s6-rc-update's job is to ensure consistency of the live state across +a change of compiled service database. To do so, it must make sure +that the services that are up at the time of its invocation are still +up after its invocation; but service definitions in the new compiled +may be different from those in the old one; in particular, dependencies +may change, or a service can change types - a oneshot can become +a longrun and vice-versa, and an atomic service can even become a +bundle. +

+ +

Service identity

+ +

+ s6-rc-update examines atomic services, as defined in the old compiled, +that are up at invocation time, and computes what is necessary for the +"same" service, as defined in the new compiled, to be up. Barring +conversion file instructions, the service is "the same" if it has the +same name in the new compiled, no matter its type. +

+ +

+ So, if there is an up oneshot named sshd in the old compiled, +and there is a longrun named sshd in the new compiled, then +s6-rc-update will decide that the new sshd longrun will replace +the old sshd oneshot. If the new compiled defines a sshd +bundle instead, then s6-rc-update will decide that the old sshd +oneshot will be replaced with the contents of the sshd bundle. +

+ +

Restarts

+ +

+ s6-rc-update tries to avoid needlessly restarting services. For instance, +running it with a new compiled that is an exact copy of +the old compiled should not cause any restarts. s6-rc-update will flag a +service to be restarted in the following cases: +

+ + + +

Steps

+ +

+ After it has decided what services it should restart, s6-rc-update will: +

+ + + +

The conversion file

+

- To be written. s6-rc-update is currently the missing piece in the -s6-rc suite, which is the reason why s6-rc has not been officially released -yet. :-) + The conversion file is used to give s6-rc-update instructions when the +change of databases is not entirely straightforward. Currently, it +supports the following features:

+ + +

Format

+ +

+ The conversion file is a sequence of lines; each line is parsed +independently, there's no carrying of information from one line to +the next. +

+ +

+ A line is lexed into words by the +execlineb +lexer, which means that words are normally separated by whitespace, but +can be quoted, that # comments are recognized, etc. +

+ +

+ The first word in a line must be the name of an "old" atomic service, i.e. +an atomic service contained in the current live database. The remaining +words in the line are instructions telling s6-rc-update how to convert +that service. +

+ +

Renaming

+ +

+ If the second word in the line is ->, then the third word in the +line must be the new name of the service in the new database: s6-rc-update +will then rename it. It is possible +to rename an atomic service to another atomic service or a bundle, but no +matter whether a service is renamed or not, changing its type will force a +restart. +

+ +

+ Note that renaming a longrun without restarting it will keep the same +s6-supervise +process supervising the longrun: this process will appear in a +ps output as supervising the old name. This is only cosmetic and +will have no impact on the service; nevertheless, if you wish to avoid that, +simply force a restart on every service you rename. +

+ +

Restarting

+ +

+ If the word following either the old name, or a renaming instruction, is the +word restart, then the service will forced to restart. +

+ +

Examples

+ +

+ Consider the following conversion file: +

+ +
# Simple conversion file
+mount-var -> mount-rwfs
+httpd restart
+sqld -> mysqld restart
+
+ + + -- cgit v1.2.3