summaryrefslogtreecommitdiff
path: root/doc/s6-rc-init.html
blob: f3a7bb13988f5530849ccaa97b5401e5a4d1506e (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
<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-init program</title>
    <meta name="Description" content="s6-rc: the s6-rc-init program" />
    <meta name="Keywords" content="s6-rc command s6-rc-init rc init dependency state management services" />
    <!-- <link rel="stylesheet" type="text/css" href="//skarnet.org/default.css" /> -->
  </head>
<body>

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

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

<p>
 s6-rc-init is an initialization tool for the s6-rc
system. It must be run as root, at boot time, prior to any
invocation of the
<a href="s6-rc.html">s6-rc</a> binary.
</p>

<h2> Interface </h2>

<pre>
     s6-rc-init [ -c <em>compiled</em> ] [ -l <em>live</em> ] [ -t <em>timeout</em> ] [ -b ] <em>scandir</em>
</pre>

<ul>
 <li> <em>compiled</em> (if the <tt>-d</tt> option hasn't been given),
<em>live</em> and <em>scandir</em> must be absolute paths. </li>
 <li> s6-rc-init expects to find a <em>compiled service database</em>
in <em>compiled</em>. It expects to be able to create a directory
named <em>live</em>. It also expects that an instance of
<a href="//skarnet.org/software/s6/s6-svscan.html">s6-svscan</a>
is running on <em>scandir</em>. </li>
 <li> s6-rc-init initializes the live state in <em>live</em>. It
declares <em>compiled</em> as the current service database and
sets the state as "all services down". </li>
 <li> It then copies verbatim all
the service directories declared by <em>compiled</em> into a
subdirectory of <em>live</em>, adds <tt>./down</tt> files to the live copies
and links those live copies into <em>scandir</em>. It then triggers
<a href="//skarnet.org/software/s6/s6-svscan.html">s6-svscan</a>,
which will pick up the new service directories and start
<a href="//skarnet.org/software/s6/s6-supervise.html">s6-supervise</a>
processes on them - but the service themselves will not be started
right away, because of the <tt>./down</tt> files. </li>
 <li> s6-rc-init waits for all s6-supervise processes to be
operational, then exits 0. </li>
</ul>

<h2> Options </h2>

<ul>
 <li> <tt>-t&nbsp;<em>timeout</em></tt>&nbsp;: if all
s6-supervise processes are not up and running after <em>timeout</em>
milliseconds, s6-rc-init will complain and exit 111. This is a
safety feature so s6-rc-init doesn't hang indefinitely on a
nonworking installation; normally this initialization should not take
more than a few milliseconds. </li>
 <li> <tt>-c&nbsp;<em>compiled</em></tt>&nbsp;: declare <em>compiled</em>
as the current compiled service database for the upcoming live state.
Default is <tt>/etc/s6-rc/compiled</tt>. </li>
 <li> <tt>-l&nbsp;<em>live</em></tt>&nbsp;: Store the live state into
the <em>live</em> directory, which should not exist prior to running
s6-rc-init, but should be under a writable filesystem - likely a RAM
filesystem. 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>-b</tt>&nbsp;: blocking lock. If the database is currently
being used by another program, s6-rc-init will wait until that
other program has released its lock on the database, then proceed.
By default, s6-rc-init fails with an error message if the database
is currently in use. </li>
 <li><tt>-d</tt>&nbsp;: dereference <em>compiled</em>. Fully resolve
the <em>compiled</em> path before declaring it as the current
compiled service database for the upcoming live state. This allows
<em>compiled</em> to be a symlink that can be updated later without
impacting the current live state. Using this flag in your init scripts'
<tt>s6-rc-init</tt> invocation means that it's possible to boot on a
compiled service database whose validity has not previously been
guaranteed by a successful <a href="s6-rc-update.html">s6-rc-update</a>
invocation: you should know what you are doing. </li>
</ul>

<h2> Typical usage </h2>

<p>
 Administrators should invoke <tt>s6-rc-init</tt> once, in their
early boot scripts, after s6-svscan is functional and ready to
supervise longrun services (and after its catch-all logger, if
any, has started), but before any
other initialization. (The rest of the initialization can be
written as a set of s6-rc services, and performed by just one
invocation of the <a href="s6-rc.html">s6-rc change</a> command.)
</p>

<p>
 For instance, when using an init created by
<a href="//skarnet.org/software/s6-linux-init/">s6-linux-init</a>,
<tt>s6-rc-init</tt> should be the first command in the
<em>stage2</em> (by default <tt>/etc/rc.init</tt>) script.
</p>

<h2> Notes </h2>

<ul>
 <li> The directory created by s6-rc-init will actually be called
<em>live</em><tt>:initial</tt>, and <em>live</em> will be a symbolic
link to that directory. Users should ignore this, and always refer
to the live directory as <em>live</em> in their future
<a href="s6-rc.html">s6-rc</a> or <a href="s6-rc-update.html">s6-rc-update</a>
invocations. The reason for this behaviour is that
<a href="s6-rc-update.html">s6-rc-update</a> creates another,
similarly named, directory (<em>live</em><tt>:<em>suffix</em></tt>)
and updates the live state by atomically changing the target of the
<em>live</em> symlink - so <em>live</em> will not change names, whereas
the real directory may.) </li>
 <li> Similarly, it is recommended that administrators store their
compiled service databases into some versioned directory, and that
<em>compiled</em> be a symbolic link to the database currently in
use. This will make it easier to create new compiled databases and
switch them with <a href="s6-rc-update.html">s6-rc-update</a>
without having to change the s6-rc-init invocation in boot scripts. </li>
 <li> After s6-rc-init runs, <em>compiled</em> has become the
"live compiled database", and must not be tampered with or deleted.
The only way to free it for deletion is to replace it with another
database, via a call to <a href="s6-rc-update.html">s6-rc-update</a>. </li>
</ul>

</body>
</html>