diff options
Diffstat (limited to 'doc/s6-rc-update.html')
| -rw-r--r-- | doc/s6-rc-update.html | 215 |
1 files changed, 209 insertions, 6 deletions
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 @@ <p> s6-rc-update is an <em>online service database switcher</em>: 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. </p> <p> - 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. <h2> Interface </h2> +<pre> + s6-rc-update [ -n ] [ -v <em>verbosity</em> ] [ -t <em>timeout</em> ] [ -l <em>live</em> ] [ -f <em>convfile</em> ] <em>newdb</em> +</pre> + +<ul> + <li> s6-rc-update analyzes the current live state, the current compiled service +database, and the compiled service database contained at <em>newdb</em>. </li> + <li> Additionally, it can process an optional <em>conversion file</em> containing +instructions. </li> + <li> It computes the necessary service transitions to safely update the live +database. </li> + <li> It shuts down the necessary services. </li> + <li> It updates the live directory so that <em>newdb</em> becomes the +live compiled service database. </li> + <li> It starts up the necessary services. </li> +</ul> + +<h2> Exit codes </h2> + +<ul> + <li> 0: success </li> + <li> 1: failure to perform some state transitions </li> + <li> 2: timed out </li> + <li> 3: unknown service name in the conversion file </li> + <li> 4: invalid service database </li> + <li> 5: wrong service type in the conversion file </li> + <li> 6: duplicate service in the conversion file </li> + <li> 100: wrong usage </li> + <li> 111: system call failed </li> +</ul> + +<h2> Options </h2> + +<ul> + <li> <tt>-n</tt> : dry run. s6-rc-update will compute the service +transitions, and print the <a href="s6-rc.html">s6-rc</a> command lines +it would execute to perform those transitions. It will not actually +run them or modify the live database. </li> + <li> <tt>-v <em>verbosity</em></tt> : be more or less +verbose. Default is 1: warning and error messages will be printed to +stderr. 0 silences warnings. 2 adds a bit more information about +what s6-rc-update is doing. 3 or more is heavy debug output. </li> + <li> <tt>-t <em>timeout</em></tt> : if s6-rc-update cannot +perform its job within <em>timeout</em> milliseconds, it will exit. +The default is 0, meaning infinite (no timeout). Be aware that timing +out and exiting may leave the live database in an inconsistent state, +so use of this option is not recommended. </li> + <li> <tt>-l <em>live</em></tt> : look for the +live state in <em>live</em>. Default is <tt>/run/s6-rc</tt>. +The default can be changed at compile-time by giving the +<tt>--livedir=<em>live</em></tt> option to <tt>./configure</tt>. </li> + <li> <tt>-f <em>convfile</em></tt> : use the conversion +file located at <em>convfile</em>. Default is <tt>/dev/null</tt>, +meaning no special instructions. </li> +</ul> + +<h2> Transition details </h2> + +<p> + 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. +</p> + +<h3> Service identity </h3> + +<p> + 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. +</p> + +<p> + So, if there is an up oneshot named <tt>sshd</tt> in the old compiled, +and there is a longrun named <tt>sshd</tt> in the new compiled, then +s6-rc-update will decide that the new <tt>sshd</tt> longrun will replace +the old <tt>sshd</tt> oneshot. If the new compiled defines a <tt>sshd</tt> +bundle instead, then s6-rc-update will decide that the old <tt>sshd</tt> +oneshot will be replaced with the contents of the <tt>sshd</tt> bundle. +<p> + +<h3> Restarts </h3> + +<p> + 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: +</p> + +<ul> + <li> The service has disappeared in the new compiled. In this case, the +old service will simply be stopped. </li> + <li> The service has changed types: a oneshot becomes a longrun, a longrun +becomes a oneshot, or an atomic service becomes a bundle. In this case, the +old service will be stopped, then the new service will be started. </li> + <li> The service has a dependency to a service that must restart, or to an +old service that must stop, or to a new service that did not previously +exist or that was previously down. </li> + <li> There is an instruction to restart the service in the conversion file. </li> +</ul> + +<h3> Steps </h3> + +<p> + After it has decided what services it should restart, s6-rc-update will: +</p> + +<ul> + <li> Invoke <a href="s6-rc.html">s6-rc</a> to stop old services. </li> + <li> Update the live directory with the data from the new compiled. +This is the critical part; s6-rc should not be interrupted at this point. +It does its best to avoid risking leaving behind an inconsistent state, +but a 100% atomicity guarantee is impossible to achieve. </li> + <li> Adjust pipe names for the existing pipelines, if needed. </li> + <li> Exec into <a href="s6-rc.html">s6-rc</a> to start new services. </li> +</ul> + +<h2> The conversion file </h2> + <p> - 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: </p> +<ul> + <li> changing the name of a service </li> + <li> forcing a restart on a service </li> +</ul> + +<h3> Format </h3> + +<p> + 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. +</p> + +<p> + A line is lexed into words by the +<a href="http://skarnet.org/software/execline/execlineb.html">execlineb</a> +lexer, which means that words are normally separated by whitespace, but +can be quoted, that <tt>#</tt> comments are recognized, etc. +</p> + +<p> + 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. +</p> + +<h4> Renaming </h4> + +<p> + If the second word in the line is <tt>-></tt>, 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. +</p> + +<p> + Note that renaming a longrun without restarting it will keep the same +<a href="http://skarnet.org/software/s6/s6-supervise.html">s6-supervise</a> +process supervising the longrun: this process will appear in a +<tt>ps</tt> 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. +</p> + +<h4> Restarting </h4> + +<p> + If the word following either the old name, or a renaming instruction, is the +word <tt>restart</tt>, then the service will forced to restart. +</p> + +<h3> Examples </h3> + +<p> + Consider the following conversion file: +</p> + +<pre># Simple conversion file +mount-var -> mount-rwfs +httpd restart +sqld -> mysqld restart +</pre> + +<ul> + <li> It will rename <tt>mount-var</tt> to <tt>mount-rwfs</tt>, not restarting it +if <tt>mount-var</tt> in the old database and <tt>mount-rwfs</tt> in the new +database have the same type and do not depend on services that would force a +restart. </li> + <li> It will restart <tt>httpd</tt> </li> + <li> It will rename <tt>sqld</tt> to <tt>mysqld</tt> and make it restart. +</ul> + </body> </html> |