Stunnel Container Image

Description

Stunnel is an open source multi-platform application that provides a universal TLS/SSL tunneling service.

How to use this image

By default, the Stunnel container image launches stunnel using a minimal configuration file that specifies the following:

• run in foreground
• load further configuration files from /etc/stunnel/conf.d

Custom configuration files must be placed into the directory /etc/stunnel/conf.d.

The container entry point configures TLS/SSL automatically by setting the key and certificate to the values of the environment variables STUNNEL_KEY and STUNNEL_CERT. If one of the environment variables is unset, the entry point defaults to /etc/stunnel/stunnel.key for STUNNEL_KEY and /etc/stunnel/stunnel.pem for STUNNEL_CERT.

The entry point can set up a single service via environment variables, so that the user doesn't have to write and mount their own configuration file. This can be specified via the environment variables STUNNEL_SERVICE_NAME, STUNNEL_ACCEPT, STUNNEL_CONNECT, and STUNNEL_CLIENT:

• STUNNEL_SERVICE_NAME: name or otherwise unique identifier of the service (used for documentation purposes only)

• STUNNEL_ACCEPT: address on which new connections should be accepted. It can be either a hostname and port number or just a port number (in which case, localhost is assumed)

• STUNNEL_CONNECT: address on which the unencrypted service is listening and to which stunnel connects. It can be either a hostname and port number or just a port number (in which case, localhost is assumed)

• STUNNEL_CLIENT: sets the client mode (accepts yes or no). Defaults to no, which means stunnel operates in server mode (accepts encrypted connections and forwards them unencrypted). When set to yes, stunnel operates in client mode (accepts unencrypted connections and forwards them encrypted)

For example, to create an SSL endpoint for a Web server listening on port 8000 on localhost, run the following command:

podman run --rm -d \
    -p 8443:8443 \
    -e STUNNEL_SERVICE_NAME=webserver \
    -e STUNNEL_ACCEPT=0.0.0.0:8443 \
    -e STUNNEL_CONNECT=0.0.0.0:8000 \
    -v=path/to/server.pem:/etc/stunnel/stunnel.pem:Z \
    -v=path/to/server.crt:/etc/stunnel/stunnel.crt:Z \
    registry.opensuse.org/opensuse/stunnel:5

Logging

Stunnel supports eight log levels, from 0 (emergency) to 7 (debug) with 5 (notice) as the default. The log level can be configured via the environment variable STUNNEL_DEBUG using either the number or the log level name. For the supported logging levels, refer to the upstream documentation.

Pitfalls

The Stunnel container image is configured to launch stunnel as the stunnel user. But by default, files mounted into a running container belong to the root user. Set the file permissions of mounted files accordingly, so that non-owners and non-group members can read them.

Stunnel's inetd mode is not supported in the container image, and it does not ship a package manager for installing any services.

Licensing

SPDX-License-Identifier: MIT

This documentation and the build recipe are licensed as MIT. The container itself contains various software components under various open source licenses listed in the associated Software Bill of Materials (SBOM).

This image is based on openSUSE Tumbleweed.