From 0de8d41258ed37745cdebc8844b0e4145b2da255 Mon Sep 17 00:00:00 2001 From: Colin Booth Date: Thu, 22 Jan 2026 22:18:42 +0000 Subject: overview.html: reorder sections to have a better conceptual flow note: expects an id in s6-rc-compile.html for the source format. --- doc/overview.html | 145 ++++++++++++++++++++++++++---------------------------- 1 file changed, 71 insertions(+), 74 deletions(-) (limited to 'doc') 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 @@

s6-frontend: an overview

+

Concepts

+ +

+ 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: +

+ + + +

+ The most innovating change comes from the +repo commands, in the +version of s6-rc that is released at the +same time as the first release of s6-frontend. The goals of the repo commands, which +are wrapped by the s6 repository and +s6 set commands, are: +

+ +

Contents of the s6-frontend package

@@ -57,8 +100,7 @@ capabilities, etc.

In addition to the s6-frontend package and its dependencies, in order to make use of the s6 command, you will need -service definitions: a set of directories, in a format understandable -by s6-rc-compile, +service definitions in the s6-rc source format describing various services that can run on a machine — long-running daemons, one-shot scripts, and "bundles" aliasing to a group of these services.

@@ -66,11 +108,11 @@ daemons, one-shot scripts, and "bundles" aliasing to a group of these services.

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 stores. Your distribution should also have pre-installed everything you need in order for you to be able to use the s6 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 building the distribution, here is what you need to do:

@@ -106,14 +148,14 @@ administrators should do their local modifications in at build time with the --storelist configure option, or after installation in the s6-frontend configuration file, see below. -
  • And then you need the service definitions themselves. +
  • Then you need the service definitions themselves.
  • Define a configuration file, located at /etc/s6-frontend.conf 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 storelist variable.
  • 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 consistent, i.e. they define a full set of services that can be used by the s6-rc service manager.
    • -
  • Check that the default states of the service are what you want, with +
  • Check that the default states of the service are what you want with s6 set status. If they're not, make the changes you need with various s6 set commands.
  • Once you're happy with the set, commit your changes with @@ -164,64 +206,20 @@ the way to reboot your system will be -

    Concepts

    - -

    - 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: -

    - - - -

    - The most innovating change comes from the -repo commands, in the -version of s6-rc that is released at the -same time as the first release of s6-frontend. The goals of the repo commands, which -are wrapped by the s6 repository and -s6 set commands, are: -

    - - -

    Comparison with OpenRC

    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.

    - 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 live services, the ones that are currently running on the user's machine. It only has one live database, comprising several "runlevels" (sets of services meant to be run together), and manages its -dependency tree dynamically. -

    - -

    - 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 s6-rc service manager and its repo commands), separates the notion of live database and of working set @@ -230,8 +228,8 @@ impacting the current machine state. You can start and stop live services, but you can only enable or disable — or mask — services on the working set. Enabling a service means that next time you boot on the service database you are -working on, that service will be automatically started.
    - Once you have worked on a set of services, you can replace the live +working on, that service will be automatically started.
    + 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 live.

    @@ -242,16 +240,15 @@ not need them. The default bundle 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 masking them in a working set and then installing that set.

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

    @@ -283,12 +280,12 @@ in which case it will give detailed information on its supervised instance. - + - + -- cgit v1.3.1
    rc-update add foobar s6 set enable foobar See below. Enable service foobar in the offline working set.
    rc-update del foobar s6 set disable foobar See below. Disable service foobar in the offline working set.
    rc-update show