diff options
| -rw-r--r-- | doc/overview.html | 145 |
1 files changed, 71 insertions, 74 deletions
diff --git a/doc/overview.html b/doc/overview.html index 01ca88a..a871dc7 100644 --- a/doc/overview.html +++ b/doc/overview.html @@ -18,6 +18,49 @@ <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> @@ -57,8 +100,7 @@ capabilities, etc. </li> <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>: a set of directories, in a format understandable -by <a href="//skarnet.org/software/s6-rc/s6-rc-compile.html">s6-rc-compile</a>, +<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> @@ -66,11 +108,11 @@ daemons, one-shot scripts, and "bundles" aliasing to a group of these services. <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 made available in some pre-configured +directories should already be available in some pre-configured <a href="//skarnet.org/software/s6-rc/repodefs#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. But if you are installing s6-frontend manually, or are +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> @@ -106,14 +148,14 @@ administrators should do their local modifications in 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> And then you need the service definitions themselves. + <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. Alternatively, they -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 of software authors. </li> +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. </li> @@ -122,18 +164,18 @@ should be provided by the distribution in a specific package. </li> 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 since basic service -files are essential for people to use it, work is underway to write them; 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 + <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 and the s6-rc package comes with some <a href="https://git.skarnet.org/cgi-bin/cgit.cgi/s6-rc/tree/examples/source">example -service definitions</a>. </li> +service definitions</a> as well. </li> </ul> </li> </ul> </li> <li> Define a <a href="s6-frontend.conf.html">configuration file</a>, located at <tt>/etc/s6-frontend.conf</tt> unless you modified the default at -build time. If you go with all the defaults for all the packages in the s6 +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 @@ -142,7 +184,7 @@ store, you need to initialize the repository: 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 + <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 @@ -164,64 +206,20 @@ the way to reboot your system will be </ul> -<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 an intermediary between the stores and the live database: -offline sets. 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> - <li> To allow easy replacement of the current live database by a set that has been -worked 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. +management that is comparable to the one provided by OpenRC and should be +similar in everyday usage barring the following differences. </p> <p> - A fundamental difference between s6-frontend and OpenRC is that OpenRC always + 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. -</p> - -<p> - s6-frontend, on the other hand (and more accurately, this is the domain of +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> @@ -230,8 +228,8 @@ 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 the 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 +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> @@ -242,16 +240,15 @@ 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 +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> - These differences being given, s6-frontend should be very comparable to -OpenRC in its everyday usage. Here is a table showing some correspondences; -it is not meant to be exhaustive, but to show a representative enough sample -of the kind of commands that can be worked with. + 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> @@ -283,12 +280,12 @@ in which case it will give detailed information on its supervised instance. </td <tr> <td> <tt>rc-update add foobar</tt> </td> <td> <tt>s6 set enable foobar</tt> </td> - <td> See below. </td> + <td> Enable service <tt>foobar</tt> in the offline working set. </td> </tr> <tr> <td> <tt>rc-update del foobar</tt> </td> <td> <tt>s6 set disable foobar</tt> </td> - <td> See below. </td> + <td> Disable service <tt>foobar</tt> in the offline working set. </td> </tr> <tr> <td> <tt>rc-update show</tt> </td> |