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
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
|
<html>
<head>
<meta name="viewport" content="width=device-width, initial-scale=1.0" />
<meta name="color-scheme" content="dark light" />
<meta http-equiv="Content-Type" content="text/html; charset=UTF-8" />
<meta http-equiv="Content-Language" content="en" />
<title>s6-frontend: overview</title>
<meta name="Description" content="s6-frontend: overview" />
<meta name="Keywords" content="s6 ecosystem supervision service manager user interface init skarnet.org skarnet software overview" />
<link rel="stylesheet" type="text/css" href="//skarnet.org/default.css" />
</head>
<body>
<p>
<a href="index.html">s6-frontend</a><br />
<a href="//skarnet.org/software/">Software</a><br />
<a href="//skarnet.org/">skarnet.org</a>
</p>
<h1> s6-frontend: an overview </h1>
<h2 id="concepts"> Concepts </h2>
<p>
s6-frontend does not come with any innovating concepts — it's just a series
of user-friendly wrappers around various commands in the s6 ecosystem, hiding
the details of various options and installation directories. For instance:
</p>
<ul>
<li> Instead of running <tt>s6-svc -r /run/service/foobar</tt>, you run
<tt>s6 process restart foobar</tt> </li>
<li> Instead of running <tt>s6-rc -d change foobar</tt>, you run
<tt>s6 live stop foobar</tt> </li>
<li> Instead of running <tt>s6-rc-init /run/service && s6-rc change default</tt>
at boot time, you run <tt>s6 system boot</tt> </li>
</ul>
<p>
The most innovating change comes from the
<a href="//skarnet.org/software/s6-rc/repodefs.html">repo</a> commands, in the
version of <a href="//skarnet.org/software/s6-rc/">s6-rc</a> that is released at the
same time as the first release of s6-frontend. The goals of the <em>repo</em> commands, which
are wrapped by the <a href="s6_repository.html"><tt>s6 repository</tt></a> and
<a href="s6_set.html"><tt>s6 set</tt></a> commands, are:
</p>
<ul>
<li> To provide a framework for distributions and system administrators to organize their
text-format source definition directories, by defining places where service definitions
should be stored </li>
<li> To allow local administrators to tailor what services they want to see in
their live database, by providing intermediaries between the service stores and
the live database called offline sets.
<ul>
<li> With <a href="s6_set.html#mask"><tt>s6 set mask</tt></a>, an administrator
can make it so a service, though defined in a store, will not appear in the service
database at all. <em>Unmasked</em> services appear in the live database, but are only started
at boot time when they are <em>enabled</em> (or <em>essential</em>, but that property
is best set in the service definition itself and never overridden). </li>
</ul></li>
<li> To allow easy replacement of the current live database by a set that has been
worked on. </li>
</ul>
<h2 id="contents"> Contents of the s6-frontend package </h2>
<p>
The <tt>s6-frontend</tt> package does not itself contain much. The only binary
that users will interact with directly is the
<a href="s6.html"><tt>s6</tt></a> binary, which is a wrapper around the
<a href="s6-frontend.html"><tt>s6-frontend</tt></a> binary (which users
should not have to call directly), which is itself a wrapper around
various commands of the s6 ecosystem that users also need to have
installed in order for s6-frontend to work. That means:
</p>
<ul>
<li> <a href="//skarnet.org/software/s6/">s6</a>, the <em>package</em>,
not the <em>command</em>: a process supervisor. Yes, the
<a href="s6.html"><tt>s6</tt></a> binary is provided by the s6-frontend
package (this package) and not the s6 package. Because the "s6" name,
which was originally meant for "the supervision system", evolved to mean
"the skarnet.org ecosystem of programs", and <tt>s6</tt> was the natural
name to use for a command interfacing with all of it. </li>
<li> <a href="//skarnet.org/software/s6-rc/">s6-rc</a>: a service manager
working on top of the s6 process supervisor. </li>
<li> optionally, <a href="//skarnet.org/software/s6-linux-init/">s6-linux-init</a>:
a set of programs to make a Linux system <em>boot</em> and use
<a href="//skarnet.org/software/s6/s6-svscan.html">s6-svscan</a>, the cornerstone
of the s6 process supervisor, as pid 1. This makes s6 a full init system, by
eliminating the need to pair s6 with something like busybox init, sysvinit,
openrc-init or systemd, which provide a pid 1. </li>
<li> Future packages may be added to the ecosystem to add functionality,
for instance: a package with turnkey essential service definitions that downstream
can use, a package to handle namespaces and cgroups, a package to handle
capabilities, etc. </li>
</ul>
<h2 id="installation"> Installing s6-frontend </h2>
<p>
In addition to the s6-frontend package and its dependencies, in order to
make use of the <a href="s6.html"><tt>s6</tt></a> command, you will need
<em>service definitions</em> in the <a href="//skarnet.org/software/s6-rc/s6-rc-compile.html#source">s6-rc source format</a>
describing various services that can run on a machine — long-running
daemons, one-shot scripts, and "bundles" aliasing to a group of these services.
</p>
<p>
If you are running s6-frontend from a distribution, the packages that provide
these services should already have them defined, and the service definition
directories should already be available in some pre-configured
<a href="//skarnet.org/software/s6-rc/repodefs.html#store">stores</a>. Your
distribution should also have pre-installed everything you need in order
for you to be able to use the <a href="s6.html"><tt>s6</tt></a> command to
control the system. However, if you are installing s6-frontend manually, or are
the person <em>building</em> the distribution, here is what you need to do:
</p>
<ul>
<li> Define one or more places where your service directories will
be hosted: it's the equivalent of <tt>/etc/init.d</tt> for OpenRC or sysv-rc,
the place where they store their scripts; or the equivalent of the places where
systemd looks for its unit files, namely:
<tt>/etc/systemd/system.control</tt>,
<tt>/run/systemd/system.control</tt>,
<tt>/run/systemd/transient</tt>,
<tt>/run/systemd/generator.early</tt>,
<tt>/etc/systemd/system</tt>,
<tt>/etc/systemd/system.attached</tt>,
<tt>/run/systemd/system</tt>,
<tt>/run/systemd/system.attached</tt>,
<tt>/run/systemd/generator</tt>,
<tt>/usr/local/lib/systemd/system</tt>,
<tt>/usr/lib/systemd/system</tt>, and
<tt>/run/systemd/generator.late</tt>.
<ul>
<li> Yes, we think systemd <em>might</em> be overdoing it just a little.
But who are we to criticize if it works for them? 🤭 </li>
<li> We recommend having <em>two or three</em> stores: one for packages
installed by the package manager, one for local modifications, and possibly
one that is managed by the distribution outside of any package. The default
<em>store list</em> for s6-frontend is
<tt>/usr/share/s6/sources:/etc/s6/sources</tt>,
which means that the package manager should install service definition
directories in <tt>/usr/share/s6/sources</tt>, and that
administrators should do their local modifications in
<tt>/etc/s6/sources</tt>. You can modify this store list
at build time with the <tt>--storelist</tt> configure option, or after
installation in the s6-frontend configuration file, see below. </li>
</ul> </li>
<li> Then you need the service definitions themselves.
<ul>
<li> Service definitions for a given daemon such as e.g. sshd should
be written by the distribution that packages sshd and provided by the
package manager when it installs sshd. (The definitions could be provided by
the sshd upstream, but service definitions are <em>policy</em> not
<em>mechanism</em> and we think policy is the realm of distributions, not
software authors.) </li>
<li> Essential services, i.e. how to boot a machine and bring it to
the state where it can accept logins and run services provided by packages,
should be provided by the distribution in a specific package.
<ul>
<li> systemd comes with a big list of unit files: it provides some policy
itself. </li>
<li> OpenRC also comes with a set of basic services: it provides some policy
itself as well. </li>
<li> s6-frontend <em>does not</em> provides policy, but work is underway to
write these since basic service files are essential for people to use it. When
complete they will be provided in a separate package. In the meantime, you can
find service definitions contributed by the community pretty much everywhere
s6-rc is used. The s6-rc package comes with some example service definitions
as well; if you want to try out s6-frontend outside of a real installation,
we recommend downloading the
<a href="https://git.skarnet.org/cgi-bin/cgit.cgi/s6-rc/tree/examples/demo">
demo stores</a> and put them in your storelist. </li>
</ul> </li>
</ul> </li>
<li> Define a <a href="s6.conf.html">configuration file</a>,
located at <tt>/etc/s6.conf</tt> unless you modified the default at
build time. If you have gone with all the defaults for all the packages in the s6
ecosystem, the configuration file can basically be empty; but you will probably
at least want to define the <tt>storelist</tt> variable. </li>
<li> Once your configuration file is ready, and all your services are in the
store, you need to initialize the repository:
<a href="s6_repository.html#init"><tt>s6 repository init</tt></a>. This command
will create the repository and make a reference database with all the services
in your stores. If it succeeds, congratulations! Your stores are <em>consistent</em>,
i.e. they define a full set of services that can be used by the s6-rc service manager. </li>
<li> Check that the default states of the service are what you want with
<a href="s6_set.html#status"><tt>s6 set status</tt></a>. If they're not, make the
changes you need with various <a href="s6_set.html#enable"><tt>s6 set</tt></a> commands. </li>
<li> Once you're happy with the set, commit your changes with
<a href="s6_set.html#commit"><tt>s6 set commit</tt></a>. This will make an s6-rc
compiled service database. </li>
<li> Install this service database as the one that will be run at boot time.
This is done by <a href="s6_live.html#install"><tt>s6 live install --init</tt></a>.
Note that the <tt>--init</tt> option should only be given for this first installation
when the machine isn't managed by s6-rc yet. </li>
<li> Make sure your init system will actually boot the service database you have
just installed. The command that should be run at boot time is:
<a href="s6_system.html#boot"><tt>s6 system boot</tt></a>. Check the link to see
how to configure your init system to run it. </li>
<li> If everything is ready, reboot the machine. Congratulations! It is now
running under a full s6 init system. </li>
<li> If you are using <a href="//skarnet.org/software/s6-linux-init/">s6-linux-init</a>,
the way to reboot your system will be
<a href="s6_system.html#reboot"><tt>s6 system reboot</tt></a> from now on. </li>
</ul>
<h2 id="openrc"> Comparison with OpenRC </h2>
<p>
One of the design goals of s6-frontend is to provide a user interface to service
management that is comparable to the one provided by OpenRC and should be
similar in everyday usage barring the following differences.
</p>
<p>
The fundamental difference between s6-frontend and OpenRC is that OpenRC always
works on <em>live services</em>, the ones that are currently running on the
user's machine. It only has one <em>live database</em>, comprising several
"runlevels" (sets of services meant to be run together), and manages its
dependency tree dynamically. On the other hand, s6-frontend (and, more accurately,
the <a href="//skarnet.org/software/s6-rc/">s6-rc</a> service manager and its
<a href="//skarnet.org/software/s6-rc/repodefs.html">repo</a> commands),
separates the notion of <em>live database</em> and of <em>working set</em>
entirely. A <em>working set</em> is worked on <em>offline</em>, without
impacting the current machine state. You can <em>start</em> and <em>stop</em>
live services, but you can only <em>enable</em> or <em>disable</em>
— or <em>mask</em> — services on a working set. Enabling a
service means that <em>next time you boot on the service database you are
working on</em>, that service will be automatically started. <br />
Once you have worked on a set of services you can replace the live
database with it; the old live database disappears entirely, and your
working set (well, a copy of it) is now <em>live</em>.
</p>
<p>
A corollary of that is that s6-frontend does not have runlevels. It does
not need them. The <em>default bundle</em> specifies what services should
be started at boot; other bundles (in the sense of s6-rc) can be defined
in the stores, and the user can start and stop them at will, as well as
start and stop individual services, dependencies notwithstanding. By
default all the services are accessible in the live database but the
user can choose to exclude certain services by <em>masking them</em> in
a working set and then installing that set.
</p>
<p>
The following table shows some equivalencies between s6-frontend and OpenRC;
it is not meant to be exhaustive but to show a representative enough sample of
the kind of commands that can be worked with.
</p>
<table>
<thead>
<tr>
<th> OpenRC command </th>
<th> s6-frontend equivalent </th>
<th> Notes </th>
</tr>
</thead>
<tbody>
<tr>
<td> <tt>rc-service foobar start</tt> </td>
<td> <tt>s6 live start foobar</tt> or <tt>s6 start foobar</tt> </td>
<td> Starts a service in the live database. <tt>s6 start foobar</tt>
is a shortcut. </td>
</tr>
<tr>
<td> <tt>rc-service foobar status</tt> </td>
<td> <tt>s6 live status foobar</tt> or <tt>s6 process status foobar</tt> </td>
<td> <tt>s6 process status foobar</tt> only works if foobar is a longrun,
in which case it will give detailed information on its supervised instance. </td>
</tr>
<tr>
<td> <tt>rc-status default</tt> </td>
<td> <tt>s6 live status</tt> or <tt>s6 set status</tt> </td>
<td> <tt>s6 live status</tt> shows the status of the current live database,
<tt>s6 set status</tt> the status of the <tt>current</tt> offline working set. </td>
</tr>
<tr>
<td> <tt>rc-update add foobar</tt> </td>
<td> <tt>s6 set enable foobar</tt> or <tt>s6 enable foobar</tt> </td>
<td> Enable service <tt>foobar</tt> in the <tt>current</tt> offline working set.
<tt>s6 enable foobar</tt> is a shortcut. </td>
</tr>
<tr>
<td> <tt>rc-update del foobar</tt> </td>
<td> <tt>s6 set disable foobar</tt> or <tt>s6 disable foobar</tt> </td>
<td> Disable service <tt>foobar</tt> in the <tt>current</tt> offline working set.
<tt>s6 disable foobar</tt> is a shortcut. </td>
</tr>
<tr>
<td> <tt>rc-update show</tt> </td>
<td> <tt>s6 set status</tt> </td>
<td> Shows the enabled, disabled and masked services, but to make the
changes effective, the user needs to run <tt>s6 set commit</tt> then
<tt>s6 live install</tt>. </td>
</tr>
<tr>
<td> <tt>openrc sysinit && openrc boot && openrc default</tt> </td>
<td> <tt>s6 system boot</tt> </td>
<td> The <tt>sysinit</tt> and <tt>boot</tt> runlevels in OpenRC are only distinct
for historical reasons. s6-frontend does not make the distinction, all the services it
starts at boot time are in the <em>default bundle</em>. </td>
</tr>
<tr>
<td> <tt>reboot</tt> </td>
<td> <tt>reboot</tt> or <tt>s6 system reboot</tt> </td>
<td> Just like OpenRC's <tt>reboot</tt> command will only work if the system
is using <tt>openrc-init</tt>, <tt>s6 system reboot</tt> command will only work
if the system is using <a href="//skarnet.org/software/s6-linux-init/">s6-linux-init</a>. </td>
</tr>
</tbody>
</table>
</body>
</html>
|
