summaryrefslogtreecommitdiff
path: root/doc/s6-rc-upgrade.html
blob: bdaa090400bef29fbde451b6d44936f8d17503f2 (plain)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
<html>
  <head>
    <meta name="viewport" content="width=device-width, initial-scale=1.0" />
    <meta http-equiv="Content-Type" content="text/html; charset=UTF-8" />
    <meta http-equiv="Content-Language" content="en" />
    <title>s6-rc: the s6-rc-update program</title>
    <meta name="Description" content="s6-rc: the s6-rc-update program" />
    <meta name="Keywords" content="s6-rc command rc update s6-rc-update init dependency state management services" />
    <!-- <link rel="stylesheet" type="text/css" href="http://skarnet.org/default.css" /> -->
  </head>
<body>

<p>
<a href="index.html">s6-rc</a><br />
<a href="http://skarnet.org/software/">Software</a><br />
<a href="http://skarnet.org/">skarnet.org</a>
</p>

<h1> The s6-rc-update program </h1>

<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.
</p>

<p>
 Live upgrading a service database is no small feat, 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
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.
</p>

<h2> Interface </h2>

<pre>
     s6-rc [ -v <em>verbosity</em> ] [ <em>servicenames...</em> ]
</pre>

<ul>
 <li> s6-rc expects to find a <em>compiled service database</em>
in <tt>/etc/s6-rc/compiled</tt> and a <em>live state</em> in
<tt>/s6/s6-rc</tt>. If it cannot find that data, it complains and
exits.
 <ul>
  <li> The <em>compiled service database</em> is built offline
via the <a href="s6-rc-compile.html">s6-rc-compile</a> tool. </li>
  <li> The <em>live state</em> should be initialized at boot time
via the <a href="s6-rc-init.html">s6-rc-init</a> tool. It is then
maintained by s6-rc itself. </li>
 </ul> </li>
 <li> The command line arguments <em>servicenames...</em> define a set
of selected services the user wants to act on. </li>
 <li> s6-rc computes the necessary transitions to bring the machine
to the desired state - by default a state where all the
services listed on the command line are up. If asked to, it performs
those transitions. </li>
 <li> s6-rc processes services as soon as they can be processed. It
will wait until a service is up to start a dependent service, but it
will start two independent services in parallel. </li>
 <li> If every state transition completes successfully, s6-rc exits 0. </li>
 <li> If a state transition fails, s6-rc will not perform the transitions
that depend on it. It will wait until all the other independent transitions
are done, then exit 1. </li>
</ul>

<h2> Options </h2>

<h3> s6-rc control </h3>

<ul>
 <li> <tt>-v&nbsp;<em>verbosity</em></tt>&nbsp;: be more or less
verbose. Default is 1: warning and error messages will be printed to
stderr. 0 silences warnings. 2 writes information messages whenever
s6-rc performs a transition. 3 or more is debug info. </li>
 <li> <tt>-n&nbsp;<em>dryruntimeout</em></tt>&nbsp;: dry run.
s6-rc will pretend to perform transitions, but will replace all its
program invocations by a call to
<a href="s6-rc-dryrun">s6-rc-dryrun</a>, which will do nothing but
print the command line s6-rc would have executed, then sleep for
<em>dryruntimeout</em> milliseconds before reporting success. </li>
 <li> <tt>-t&nbsp;<em>timeout</em></tt>&nbsp;: timeout. If s6-rc
isn't done after <em>timeout</em> milliseconds, it will exit, leaving
the live state as it is at exit time. It does not kill its children, so
a child may successfully complete afterwards and the live state will
not be updated; in that case, subsequent s6-rc invocations will notice
and correctly update it. </li>
 <li> <tt>-c&nbsp;<em>compiled</em></tt>&nbsp;: look for the
compiled service database in <em>compiled</em>. Default is
<tt>/etc/s6-rc/compiled</tt> </li>
 <li> <tt>-l&nbsp;<em>live</em></tt>&nbsp;: look for the
live state in <em>live</em>. Default is
<tt>/s6/s6-rc</tt> </li>
</ul>

<h3> Up or down </h3>

<ul>
 <li> <tt>-u</tt>&nbsp;: selected services are interpreted
as to be brought <em>up</em>. This is the default. </li>
 <li> <tt>-d</tt>&nbsp;: selected services are interpreted
as to be brought <em>down</em>. </li>
</ul>

<h3> Service selection </h3>

<ul>
 <li> <tt>-p</tt>&nbsp;: prune. The state will be brought to
<em>exactly</em> <em>servicenames...</em>, plus their dependencies, and
the other services will be brought down. With the <tt>-d</tt> option,
the meaning is reversed: the state will be brought to the maximum
possible set that does not include <em>servicenames...</em>. </li>
 <li> <tt>-a</tt>&nbsp;: all. Add the current set of active services to
the selected set. This is useful to ensure consistency of the machine
state, for instance, and also at shutdown time: <tt>s6-rc -da</tt>
will stop all the currently active services. </li>
</ul>

<h3> Actions </h3>

<ul>
 <li> <tt>-C</tt>&nbsp;: check. s6-rc will check the consistency of the
database, and exit with an error message if it finds errors. </li>
 <li> <tt>-L</tt>&nbsp;: list. s6-rc will resolve the given names, then
print the list of corresponding atomic services to stdout, without taking their
dependencies into account. It will print an empty line afterwards. </li>
 <li> <tt>-A</tt>&nbsp;: list all. s6-rc will print the list of selected
atomic services to stdout, after computing dependencies. Note that with
the <tt>-d</tt> option, it computes reverse dependencies instead. </li>
 <li> <tt>-S</tt>&nbsp;: state change. A state change will be performed
for the selected services.
This is the default if no other action option has been given. </li>
</ul>

<h2> Usage examples </h2>

<pre> s6-rc <em>myservicebundle</em> </pre>
<p>
 Brings up all the services represented by <em>myservicebundle</em>,
dependencies first.
</p>

<pre> s6-rc -Sad </pre>
<p>
 Brings down all the services in an orderly manner. This is typically
run at shutdown time.
</p>

<pre> s6-rc -Au <em>myservicebundle</em> </pre>
<p>
 Prints the names of all atomic services represented by
<em>myservicebundle</em>, as well as everything they depend on.
</p>

<pre> s6-rc -Ad <em>myservicebundle</em> </pre>
<p>
 Prints the names of all atomic services represented by
<em>myservicebundle</em>, as well as everything that depends on them.
</p>

<pre> s6-rc -pun0 <em>myservicebundle</em> </pre>
<p>
 Prints what s6-rc would do to bring the state to just
<em>myservicebundle</em> and its dependencies.
</p>


<h2> Internals </h2>

</body>
</html>