Repository files navigation

s6rc-overlay is a collection of statically-compiled binairies and scripts aimedat easing the building of containers with complex setup.

It is heavily inspired bys6-overlay but usesskarnet's s6-rc for controlling setupand service dependencies.

The reading ofs6 ands6-rc overview dans documentation ishighly advised.

You can use one of thedocker images.

Or include it in your Dockerfile, like this:

ENV S6RC_VERSION 0.0.1ADD https://github.com/Adirelle/s6rc-overlay/releases/download/v${S6RC_VERSION}/s6rc-overlay-v${S6RC_VERSION}-amd64.tar.bz2 /tmp/s6rc-overlay.tar.bz2RUN tar xfa /tmp/s6rc-overlay.tar.bz2 -C / \&&  rm /tmp/s6rc-overlay.tar.bz2ENTRYPOINT ["/sbin/container-init"]

1. When starting, s6rc-overlay entrypoint extracts its configuration variablesfrom the environment, backup the other variables, as well as the current userand working directory, then clear all variables and gain root privileges.

2. It removes everything in both/tmp and/run and installs its workingdirectory in/run/s6-rc.

3. If there is no precompiled service database, it compiles one from/etc/services.d.

4. It tries to bring up the targetservice, which should depends on the actual services to start.

5. Once all the services are started:

   1. If command line has been given, it restores the initial environment(user, working directory, variables) and executes it.

   2. Else it waits forever until some signal is received.

6. s6rc-overlay regains the control as root, then tries to bring down theservices.

7. It sends a SIGTERM signal to all remaining processes and waits 2 seconds.

8. Finally it returns the exit code of the commmand, or 0 if they was none.

When the starting user is not root, s6rc-overlay creates a safe environment forroot: it clears all environment variables, redefines PATH and imports theconfiguration variables from the starting environment.

Said otherwise, root default environment does not contains that environmentvariables passed at launch, and the starting user does not have access toconfiguration variables.

All services are run in the root environment, i.e. as root with almost novariables. If they need variables from the starting environment, youcan use thewith-contenv helper (see below).

You can provide a precompiled service database in/etc/s6-rc/compiled or lets6rc-overlay compile it from service definitions in/etc/services.d. See thes6-rc-compile documentation aboutthe format of service definitions.

s6rc-overlay comes with the following default services. They are defined in the/etc/services.d directory and can be configured using environment variables.

Note: in case you provided precompiled service database, these serviceswould not be available.

Recursively removes files and directories.

The targets are defined by a colon-separated list of glob patterns inREMOVE_PATHS.

UnsetsREMOVE_PATHS once done.

Recursively gives write permissions on a set of directories and files to a user. Createsdirectory for targets that do not exist.

The user is defined by theWRITABLE_USER and the files/directories by a colon-separatedlist inWRITABLE_PATHS.

Runs afterremove-paths and unsets the variables once done.

Note: it usessetfacl, so this command has to been available.

A simple bundle that referenceswritable-paths. It can be used as asynchronisation point before launching longruns. You can add other services towait to with a single command:

echo my_other_service >> /etc/s6-rc/source/init/contents

This service is dynamically added by s6rc-overlay on compilation. It is asimple bundle that lists every services in/etc/services.d to ensure they areall started.

s6-notice message prog...

Printsmessage in green and executes intoprog.

s6-logcmd prog...

Printsprog in yellow and executes it. Standard and error outputs are coloredin white and red, respectively. The final status is shown as 'Success' in greenif it is 0, or as 'Failed (actual value)' in red in case of failure.

All outputs are prefixed withNN> where NN is a sequential number. This helpsidentifying entangled outputs from parallel tasks.

with-contenv [ -a | [-c] [-e] [-w] [-u] ] prog...

Executesprog with all or parts of the starting environment, depending on theoptions.

• -a is an alias for-cewu.

• -c clears the environment. It is intended to be used with-e.

• -e imports all variables from the starting environment.

• -w changes the working directory to the starting one.

• -u runs progs as the starting user.

He is a list of environment variables that alters s6rc-overlay behavior:

• S6_VERBOSITY: the verbosity of various s6-rc commands. Defaults to 1.

• S6_TARGET: the service to bring up at startup. Defaults toservices. If empty or set tonone, services will not be started.

• S6_USER: if defined, execute the command as the indicated user. Take an single user name or user id. Can be used with Docker when you cannot use the --user switchs.

• S6_INIT_TIMEOUT: the initialisation timeout (see s6-rc-init), inmilliseconds. Defauts to 500ms.

• S6_START_TIMEOUT: the service start timeout, in milliseconds. Defauts to 2minutes.

• S6_STOP_TIMEOUT: the service stop timeout, in milliseconds. Defauts to 5s.

• S6_SERVICES_DIR: the path to the service definitions. Defaults to/etc/services.d.

• S6_CONF_DIR: the path to the initial configuration of s6rc-overlay. Defaultsto/etc/s6-rc.

• S6_RUN_DIR: the path to the working directory of s6rc-overlay. Defaults to/run/s6-rc.

s6rc-overlay usessu-exec : it is required for privilege escalation in thecontainer during startup, but it can also be exploited by malicious code.

• skarnet's tools, as statically-linked binaries fromjust-containers/skaware:
  • scripting language:execline
  • POSIX-compliant tools, well-suited for execline scripts:s6-portable-utils,
  • supervision suite:s6,
  • service manager:s6-rc,
• su-exec, compiled using the product ofmusl-cross-make.

s6rc-overlay scripts are released under theMIT license.