访问官网
Github
文档Table of Contents
- Quickstart
- Compatibility with v2
- Goals
- Features
- The Docker Way?
- Init stages
- Installation
- Usage
- Using
CMD - Writing a service script
- Setting the exit code of the container to the exit code of your main service
- Fixing ownership and permissions
- Executing initialization and finalization tasks
- Writing an optional finish script
- Logging
- Dropping privileges
- Read-only Root Filesystem
- Container environment
- Customizing s6-overlay's behaviour
- syslog
- Using
- Performance
- Verifying Downloads
- Notes
- Releases
- Contributing
- Building the overlay yourself
- Upgrade notes
s6-overlay 
s6-overlay is an easy-to-install (just extract a tarball or two!) set of scripts and utilities allowing you to use existing Docker images while using s6 as a pid 1 for your container and process supervisor for your services.
Quickstart
Build the following Dockerfile and try it out:
# Use your favorite image
FROM ubuntu
ARG S6_OVERLAY_VERSION=3.2.0.0
RUN apt-get update && apt-get install -y nginx xz-utils
RUN echo "daemon off;" >> /etc/nginx/nginx.conf
CMD ["/usr/sbin/nginx"]
ADD https://github.com/just-containers/s6-overlay/releases/download/v${S6_OVERLAY_VERSION}/s6-overlay-noarch.tar.xz /tmp
RUN tar -C / -Jxpf /tmp/s6-overlay-noarch.tar.xz
ADD https://github.com/just-containers/s6-overlay/releases/download/v${S6_OVERLAY_VERSION}/s6-overlay-x86_64.tar.xz /tmp
RUN tar -C / -Jxpf /tmp/s6-overlay-x86_64.tar.xz
ENTRYPOINT ["/init"]
docker-host $ docker build -t demo .
docker-host $ docker run --name s6demo -d -p 80:80 demo
docker-host $ docker top s6demo acxf
PID TTY STAT TIME COMMAND
11735 ? Ss 0:00 \_ s6-svscan
11772 ? S 0:00 \_ s6-supervise
11773 ? Ss 0:00 | \_ s6-linux-init-s
11771 ? Ss 0:00 \_ rc.init
11812 ? S 0:00 | \_ nginx
11814 ? S 0:00 | \_ nginx
11816 ? S 0:00 | \_ nginx
11813 ? S 0:00 | \_ nginx
11815 ? S 0:00 | \_ nginx
11779 ? S 0:00 \_ s6-supervise
11785 ? Ss 0:00 | \_ s6-ipcserverd
11778 ? S 0:00 \_ s6-supervise
docker-host $ curl --head http://127.0.0.1/
HTTP/1.1 200 OK
Server: nginx/1.18.0 (Ubuntu)
Date: Mon, 17 Jan 2022 13:33:58 GMT
Content-Type: text/html
Content-Length: 612
Last-Modified: Mon, 17 Jan 2022 13:32:11 GMT
Connection: keep-alive
ETag: "61e56fdb-264"
Accept-Ranges: bytes
Compatibility with v2
If you're migrating from a previous version of s6-overlay (v2) to the new version (v3), you may need to make some changes to your services or the way you use s6-overlay in order for everything to work smoothly. This document tries to be accurate on how v3 works, but we have a separate page listing the main differences, and things you're likely to notice. Please read it if you're in this situation!
Goals
The project has the following goals:
- Be usable on top of any Docker image
- Make it easy to create new images, that will operate like any other images
- Provide users with a turnkey s6 installation that will give them a stable pid 1, a fast and orderly init sequence and shutdown sequence, and the power of process supervision and automatically rotated logs.
Features
- A simple init process which allows the end-user to execute tasks like initialization (
cont-init.d), finalization (cont-finish.d) and their own services with dependencies between them - The s6-overlay provides proper
PID 1functionality- You'll never have zombie processes hanging around in your container, they will be properly cleaned up.
- Multiple processes in a single container
- Able to operate in "The Docker Way"
- Usable with all base images - Ubuntu, CentOS, Fedora, Alpine, Busybox...
- Distributed as a small number of .tar.xz files depending on what exact functionality you need - to keep your image's number of layers small.
- A whole set of utilities included in
s6ands6-portable-utils. They include handy and composable utilities which make our lives much, much easier. - Log rotating out-of-the-box through
logutil-servicewhich usess6-logunder the hood. - Some support for Docker's
USERdirective, to run your whole process tree as a specific user. Not compatible with all features, details in the notes section.
The Docker Way?
One of the oft-repeated Docker mantras is "one process per container", but we disagree. There's nothing inherently bad about running multiple processes in a container. The more abstract "one thing per container" is our policy - a container should do one thing, such as "run a chat service" or "run gitlab." This may involve multiple processes, which is fine.
The other reason image authors shy away from process supervisors is they believe a process supervisor must restart failed services, meaning the Docker container will never die.
This does effectively break the Docker ecosystem - most images run one process that will exit when there's an error. By exiting on error, you allow the system administrator to handle failures however they prefer. If your image will never exit, you now need some alternative method of error recovery and failure notification.
Our policy is that if "the thing" fails, then the container should fail, too.
We do this by determining which processes can restart, and which should bring down
the container. For example, if cron or syslog fails, your container can most
likely restart it without any ill effects, but if ejabberd fails, the container
should exit so the system administrator can take action.
Our interpretation of "The Docker Way" is thus:
- Containers should do one thing
- Containers should stop when that thing stops
and our init system is designed to do exactly that. Your images will behave like other Docker images and fit in with the existing ecosystem of images.
See "Writing an optional finish script" under the Usage section for details on stopping "the thing."
Init stages
Our overlay init is a properly customized one to run appropriately in containerized environments. This section briefly explains how stages work but if you want to know how a complete init system should work, you can read this article: How to run s6-svscan as process 1
- stage 1: Its purpose is to set up the image to execute the supervision tree which will handle all the auxiliary services, and to launch stage 2. Stage 1 is where all the black magic happens, all the container setup details that we handle for you so that you don't have to care about them.
- stage 2: This is where most of the end-user provided files are meant to be executed:
- Execute legacy oneshot user scripts contained in
/etc/cont-init.d. - Run user s6-rc services declared in
/etc/s6-overlay/s6-rc.d, following dependencies - Copy legacy longrun user services (
/etc/services.d) to a temporary directory and have s6 start (and supervise) them.
- Execute legacy oneshot user scripts contained in
- stage 3: This is the shutdown stage. When the container is supposed to exit, it will:
- Send a TERM signal to all legacy longrun services and, if required, wait for them to exit.
- Bring down user s6-rc services in an orderly fashion.
- Run any finalization scripts contained in
/etc/cont-finish.d. - Send all remaining processes a
TERMsignal. There should not be any remaining processes anyway. - Sleep for a small grace time, to allow stray processes to exit cleanly.
- Send all processes a
KILLsignal. Then the container exits.
Installation
s6-overlay comes as a set of tarballs that you can extract onto your image. The tarballs you need are a function of the image you use; most people will need the first two, and the other ones are extras you can use at your convenience.
s6-overlay-noarch.tar.xz: this tarball contains the scripts implementing the overlay. We call it "noarch" because it is architecture- independent: it only contains scripts and other text files. Everyone who wants to run s6-overlay needs to extract this tarball.s6-overlay-x86_64.tar.xz: replacex86_64with your system's architecture. This tarball contains all the necessary binaries from the s6 ecosystem, all linked statically and out of the way of your image's binaries. Unless you know for sure that your image already comes with all the packages providing the binaries used in the overlay, you need to extract this tarball.s6-overlay-symlinks-noarch.tar.xz: this tarball contains symlinks to the s6-overlay scripts so they are accessible via/usr/bin. It is normally not needed, all the scripts are accessible via the PATH environment variable, but if you have old user scripts containing shebangs such as#!/usr/bin/with-contenv, installing these symlinks will make them work.s6-overlay-symlinks-arch.tar.xz: this tarball contains symlinks to the binaries from the s6 ecosystem provided by the second tarball, to make them accessible via/usr/bin. It is normally not needed, but if you have old user scripts containing shebangs such as#!/usr/bin/execlineb, installing these symlinks will make them work.syslogd-overlay-noarch.tar.xz: this tarball contains definitions for asyslogdservice. If you are running daemons that cannot log to stderr to take advantage of the s6 logging infrastructure, but hardcode the use of the oldsyslog()mechanism, you can extract this tarball, and your container will run a lightweight emulation of asyslogddaemon, so your syslog logs will be caught and stored to disk.
To install those tarballs, add lines to your Dockerfile that correspond to the functionality you want to install. For instance, most people would use the following:
ADD https://github.com/just-containers/s6-overlay/releases/download/v${S6_OVERLAY_VERSION}/s6-overlay-noarch.tar.xz /tmp
RUN tar -C / -Jxpf /tmp/s6-overlay-noarch.tar.xz
ADD https://github.com/just-containers/s6-overlay/releases/download/v${S6_OVERLAY_VERSION}/s6-overlay-x86_64.tar.xz /tmp
RUN tar -C / -Jxpf /tmp/s6-overlay-x86_64.tar.xz
Make sure to preserve file permissions when extracting (i.e. to use the
-p option to tar.)
Usage
The project is distributed as a set of standard .tar.xz files, which you extract at the root of your image.
(You need the xz-utils package for tar to understand .tar.xz files; it is available
in every distribution, but not always in the default container images, so you may need
to apt install xz-utils or apk add xz, or equivalent, before you can
expand the archives.)
Afterwards, set your ENTRYPOINT to /init.
Right now, we recommend using Docker's ADD directive instead of running wget or curl
in a RUN directive - Docker is able to handle the https URL when you use ADD, whereas
your base image might not be able to use https, or might not even have wget or curl
installed at all.
From there, you have a couple of options:
- If you want the container to exit when your program exits: run the program as your image's
CMD. - If you want the container to run until told to exit, and your program to be supervised by s6: write a service script for your program.
Using CMD
Using CMD is a convenient way to take advantage of the overlay. Your CMD can be given at
build time in the Dockerfile, or at run time on the command line, either way is fine. It will
be run as a normal process in the environment set up by s6; when it fails or exits, the
container will shut down cleanly and exit. You can run interactive programs in this manner:
only the CMD will receive your interactive command, the support processes will be unimpacted.
For example:
FROM busybox
ADD https://github.com/just-containers/s6-overlay/releases/download/v${S6_OVERLAY_VERSION}/s6-overlay-noarch.tar.xz /tmp
RUN tar -C / -Jxpf /tmp/s6-overlay-noarch.tar.xz
ADD https://github.com/just-containers/s6-overlay/releases/download/v${S6_OVERLAY_VERSION}/s6-overlay-x86_64.tar.xz /tmp
RUN tar -C / -Jxpf /tmp/s6-overlay-x86_64.tar.xz
ENTRYPOINT ["/init"]
docker-host $ docker build -t s6demo .
docker-host $ docker run -ti s6demo /bin/sh
/package/admin/s6-overlay/libexec/preinit: notice: /var/run is not a symlink to /run, fixing it
s6-rc: info: service s6rc-oneshot-runner: starting
s6-rc: info: service s6rc-oneshot-runner successfully started
s6-rc: info: service fix-attrs: starting
s6-rc: info: service fix-attrs successfully started
s6-rc: info: service legacy-cont-init: starting
s6-rc: info: service legacy-cont-init successfully started
s6-rc: info: service legacy-services: starting
s6-rc: info: service legacy-services successfully started
/ # ps
PID USER TIME COMMAND
1 root 0:00 /package/admin/s6/command/s6-svscan -d4 -- /run/service
17 root 0:00 {rc.init} /bin/sh -e /run/s6/basedir/scripts/rc.init top /bin/sh
18 root 0:00 s6-supervise s6-linux-init-shutdownd
20 root 0:00 /package/admin/s6-linux-init/command/s6-linux-init-shutdownd -c /run/s6/basedir -g 3000 -C -B
24 root 0:00 s6-supervise s6rc-fdholder
25 root 0:00 s6-supervise s6rc-oneshot-runner
31 root 0:00 /package/admin/s6/command/s6-ipcserverd -1 -- /package/admin/s6/command/s6-ipcserver-access -v0 -E -l0 -i data/rules -- /packa
58 root 0:00 /bin/sh
66 root 0:00 ps
/ # exit
s6-rc: info: service legacy-services: stopping
s6-rc: info: service legacy-services successfully stopped
s6-rc: info: service legacy-cont-init: stopping
s6-rc: info: service legacy-cont-init successfully stopped
s6-rc: info: service fix-attrs: stopping
s6-rc: info: service fix-attrs successfully stopped
s6-rc: info: service s6rc-oneshot-runner: stopping
s6-rc: info: service s6rc-oneshot-runner successfully stopped
docker-host $
