From d71f18b44e4168e2d942b503110af5b5314364b5 Mon Sep 17 00:00:00 2001 From: Laurent Bercot Date: Thu, 9 Oct 2025 17:14:12 +0000 Subject: Move all string comparison operations into skalibs --- doc/repodefs.html | 149 +++++++++++++++++++++++++++++++++++------------------- 1 file changed, 98 insertions(+), 51 deletions(-) (limited to 'doc') diff --git a/doc/repodefs.html b/doc/repodefs.html index ff2bd32..be3351c 100644 --- a/doc/repodefs.html +++ b/doc/repodefs.html @@ -51,46 +51,24 @@ simply because they manage a repository of services.

Definitions

-
-

Repository

+
+

Store

- An s6-rc repository is a place in the filesystem where the -repo commands perform their work and store their data. It -is made of hierarchies of symlinks (lots and lots of symlinks), that -ultimately point to source definition directories in the -stores, as well as several compiled databases: -the reference database, and the compiled databases -made of the sets you have -committed, including the one you will eventually -install. + Store: place where service definitions are stored

-

- A repository is where offline work on -services happens. It must be located on a read-write filesystem, but -that filesystem does not need to be accessible during the early boot. -The default repository is located in /var/lib/s6-rc/repository -(configurable at build-time). Other repositories can be created and -used at will, typically by non-root users who want to manage their own -sets of services. -

- -
-

Store

-
-

A service store is a place in the filesystem where source definition directories are written by the package manager or the user, where you can find the real contents of the services (instead of just symlinks), as in, source definition directories that are processed by s6-rc-compile. -A repository will typically link to several stores: one provided by -the package manager, and one — or more — provided locally -by the admin. No s6-rc command will ever write to a store, but most -repo commands read from all the stores. +A repository will typically link to several +stores: one provided by the package manager, and one — or more +— provided locally by the admin. No s6-rc command will ever +write to a store, but most repo commands read from all the stores.

@@ -102,21 +80,64 @@ place to host local service definition directories managed by an administrator could be /etc/s6-rc/sources.

+ +
+

Repository

+
+ +

+ Repository: place in the filesystem where the repo commands work, +write their data, maintain the dependency graph of all the services +in the stores, etc. +

+ +

+ The s6-rc repository is the central concept of the repo +commands: it's the place in the filesystem where these commands perform +their work and store their data. It is made of hierarchies of symlinks +(lots and lots of symlinks), that ultimately point to source definition +directories in the stores, as well as several +compiled databases: the reference database, and the +compiled databases made of the sets the user has +committed, including the one the user will eventually +install. +

+ +

+ The repository is where offline work on +services happens. It must be located on a read-write filesystem, but +that filesystem does not need to be accessible during the early boot. +By default, the repository is located in /var/lib/s6-rc/repository; +it is configurable at s6-rc build time. +

+ +

+ The repository is generally unique for a system. However, it is possible +to create and use repositories in non-default locations; that is, for +instance, what non-root users would do in order to manage their own sets +of services. +

+

Reference database

- When a repository is created or updated, the list of all services + Reference database: the dependency graph between all the services +in all the stores used by the repository. +

+ +

+ When the repository is created or updated, the list of all services defined in all the stores used by this repository is analyzed, and all these services are automatically compiled into a reference database, stored in the repository. The reference database is never meant to be installed or go live in any way; its purpose is mainly to give repo commands access to the full dependency -graph of all the services in the store. Additionally, compiling this -reference database ensures that the whole set of services defined -in all the used stores is consistent: if not, the initialization fails, -so the problem is reported as early as possible. +graph of all the services in the stores. Additionally, compiling this +reference database ensures that the whole set of services defined by +the unions of all the stores is consistent: if not, the initialization +fails, so the problem is reported as early as possible.

@@ -124,13 +145,19 @@ so the problem is reported as early as possible.

- Inside a repository, a set is the fundamental unit of operation, -and what users will interact the most with. A set is a map associating -each service contained in the reference database + Set: a set of services with all the states the user wants them +to be in at boot time: unavailable in the database, available but not +automatically started, started at boot time. +

+ +

+ Inside the repository, a set is the fundamental unit of operation, +and what users will interact the most with. A set contains all the +services defined in the reference database (so, each service listed in all the stores used by the -repository) to a given state that the user wants this service in when -booting the system. This target state is also called a -sub, because target states are implemented by +repository) and associates, to each service, a given state that the user +wants this service to be in when the system boots. This target state is also +called a sub, because target states are implemented by subdirectories of the directory holding a set.

@@ -146,6 +173,10 @@ can commit the set, then install it

Subs

+

+ Sub: the state the user wants a service to reach at boot time. +

+

A sub is the target state for every service in a set. At all times, each service is in one and only one sub. The list of subs the service can be in @@ -156,26 +187,30 @@ is the following:

  • masked: when the set is committed, masked services will not be included in the compiled set database. They will be completely absent; if the set database is installed, s6-rc will not know them. -A service in another sub cannot depend on a masked service.
    • -
  • disabled, aka unmasked, aka active (yes, the -naming may seem inconsistent, but bear with me): these services will appear in -the compiled set database, and be startable by s6-rc if -the database is installed. However, they will not be included in the default -bundle, i.e. they will not be automatically started at boot time.
    • +A service in another sub cannot depend on a masked service. Users typically mask +services that are included in a store but are superfluous to them, services they +just do not want to interact with. +
  • disabled: these services will appear in the compiled set database, +and will be startable by s6-rc if the database is installed. +However, they will not be included in the default bundle, i.e. they will not be +automatically started at boot time. Other names for disabled are: +inactive, unmasked, latent, usable. (Tooling +will likely report these services as latent or usable.)
  • enabled: these services will appear in the compiled set database, -and in the default bundle. They will be started at boot time.
    • +and in the default bundle, which means they will be started at boot time. +Other names for enabled are: active.
  • essential, aka always: these services have been marked as essential in their source definition directories, so they will always be enabled. They cannot be disabled or masked. They cannot depend on non-essential services. This sub is typically used by early boot services that should always -be run.
    • +run.

    Working on a set basically means moving services from one of these subs to -another, mostly choosing what services you will enable or disable, and sometimes -masking services you don't want to see at all. And once you are happy with a set, -you can commit it. +another, mostly choosing what services to enable or disable, and sometimes +masking services the user does not want to see at all. Once the user is happy +with a set, they should commit it.

    @@ -211,12 +246,14 @@ the new live database. according to distribution policy.
  • The installer also sets a default live service database up.
    • +
  • Whenever distribution policies change, for instance when declaring an additional local store:
    • +
  • Whenever service files change, typically when the package manager installs/updates/deletes packages that provide daemons, or admins modify services in local stores: @@ -230,6 +267,15 @@ repository in sync with the stores.
    • database is also kept in sync with the machine state. (Failure to do so may prevent the machine from booting next time.) + +
  • Whenever the admin wants to modify the current, live, +machine state, by starting, stopping or restarting services: +
      +
    • They use the original s6-rc change command, +which operates on the live database. No repo command is involved +here.
      • +
    • +
  • Whenever the admin wants to customize their startup process:
    • They can create new sets (with default subs coming from policy that's @@ -242,6 +288,7 @@ or delete sets with s6-rc-set-delete.
    • They install the set with s6-rc-set-install. This action potentially modifies the current state of the machine!
    • +
  • At boot time:
    • The system boots on the installed live database. None of the repo -- cgit v1.3.1