Install

Your Dockerfile should use CMD to run /usr/local/bin/boot-debian-base.

When running, use -t to enable the logging to docker logs

Environment Variables

This environment variable is available for your use:

DEBBASE_SYSLOG defaults to stdout, which redirects all syslog activityto the Docker infrastructure. If you instead set it to internal, it willuse the default Debian configuration of logging to /var/log within thecontainer. The configuration is applied at container start time byadjusting the /etc/syslog.conf symlink to point to either syslog.conf.internal orsyslog.conf.stdout. syslog.conf.internal is the default from the system.dpkg-divert is used to force all packages' attempts to write to /etc/syslog.confto instead write to /etc/syslog.conf.internal.

DEBBASE_TIMEZONE, if set, will configure the /etc/timezone and /etc/localtimefiles in the container to the appropriate timezone.

DEBBASE_SSH defaults to disabled. If you set to enabled, then the SSH serverwill be run.

Container initialization

Executables or scripts may be placed in /usr/local/preinit, which will be executedat container start time by run-parts prior to starting init. These cantherefore perform container startup steps. A script which needs to only runonce can delete itself after a successful run to prevent a future execution.

Orderly Shutdown

You can cause docker stop to invoke an orderly shutdown by running the containerlike this:

Within the container, you can call telinit 1 to cause the container to shutdown.

Advanted topic: Orderly Shutdown Mechanics

By default, docker stop sends the SIGTERM (and, later, SIGKILL) signal to PID1 (init) iniside a container. sysvinit does not act upon this signal.This will shut down a container, but it will not give your shutdown scriptsthe chance to run gracefully. In many situations, this is fine, but it maynot be so in all.

A workaround is, howerver, readily available, without modifying init. Theseimages are configured to perform a graceful shutdown upon receiving SIGPWR.

The process for this is... interesting, since we are unable to directlykill PID 1 inside a docker container. First, init calls /etc/init.d/powerfail.The powerfail script I install simply tells init to go to single-user mode.This causes it to perform an orderly shutdown of the daemons, and when it isdone, it invokes /sbin/sulogin. On an ordinary system, this prompts forthe root password for single-user mode. In this environment, we insteadsymlink /sbin/init to /bin/true, then tell init to re-exec itself. Thiscauses PID 1 to finally exit.

One of the preinit scripts makes sure that /sbin/init properly links to/sbin/init.real at boot time.

Configuration

Although the standard and security images run the SMTP and SSH servers,they do not expose these to the Internet by default. Both requiresite-specific configuration before they are actually useful.

Because the SMTP service is used inside containers, but the SSH servicegenerally is not, the SSH service is disabled by default.

Enabling or Disabling Services

You can enable or disable services using commands like this:

update-rc.d ssh disable update-rc.d ssh enable

Email

email is the main thing you'd need to configure. In the running system,dpkg-reconfigure -plow exim4-config will let you do this.

SSH

SSH host keys will be generated upon first run of a container, ifthey do not already exist. This implies every instantiationof a container containing SSH will have a new random host key.If you want to override this, you can of course supply your ownfiles in /etc/ssh or make it a volume.

Advanced topic: programs that depend on disabled scripts

There are a number of scripts in /etc/init.d that are normallypart of a Debian system initialization, but fail in a Docker environment.They do things like set up swap space, mount filesystems, etc.Docker images typically leave those scripts in place, but they arenever called because Docker systems typically don't run a real initlike these images do.

Although calling the scripts produces nothing worse than harmless errors, I havedisabled those scripts in these images in order to avoid putting uselesserror messages in people's log files. In some very rare circumstances,this may cause installation of additional packages to fail due toboot script dependency ordering not working right. (Again, this is veryrare).

I saw this happen once where a package had a long chain of dependenciesthat wound up pulling in cgmanager, which died in postinst complainingthat its init script required mountkernfs. I worked around this in myDockerfile like this:

Also, I have blocked systemd from accidentally being installed on the system.There are a few packages that pull in systemd shims and so forth, so ifyou get errors about systemd not installing, try addingrm /etc/apt/preferences.d/systemd to your Dockerfile.

Advanced Topic: Adding these enhancements to other images

Sometimes, it is desirable to not have to rebuild an image entirely.These images are also designed to make it easy to add thefunctionality to other images. You can do this by using the supportfor multiple FROM lines in a Dockerfile. For instance, here's asimple one I worked up:

It happens that home-assistant is based on a Python image which, inturn, is based on Debian jessie. There are just those four lines thatare needed: copying the /usr/local/preinit, bin, and debian-base-setupdirectories, and then the run-parts call. This effectively adds allthe features of debian-base-security to the home-assistant image.

This works because each image that is part of the chain leading up tosecurity (minimal, standard, and security) performs all of itsactivity from scripts it drops -- and leaves -- in/usr/local/debian-base-setup. Those scripts need nothing other thanthe files in the three directories referenced above. By adding thosethree directories and calling the scripts, it is easy to add thesefeatures to other images.

Copyright

Redistribution and use in source and binary forms, with or withoutmodification, are permitted provided that the following conditionsare met:

Redistributions of source code must retain the above copyrightnotice, this list of conditions and the following disclaimer.

Redistributions in binary form must reproduce the above copyrightnotice, this list of conditions and the following disclaimer in thedocumentation and/or other materials provided with the distribution.

Neither the name of the University nor the names of its contributorsmay be used to endorse or promote products derived from this softwarewithout specific prior written permission.

THIS SOFTWARE IS PROVIDED BY THE AUTHORS AND CONTRIBUTORS ``AS IS'' ANDANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THEIMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSEARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLEFOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIALDAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODSOR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICTLIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAYOUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OFSUCH DAMAGE.