GLOBAL OPTIONS

chroot = DIRECTORY (Unix only)

directory to chroot stunnel process

chroot keeps stunnel in a chrooted jail. CApath, CRLpath, pid and exec are located inside the jail and the patches have to be relative to the directory specified with chroot.

Several functions of the operating system also need their files to be located within the chroot jail, e.g.:

compression = deflate | zlib

select data compression algorithm

default: no compression

Deflate is the standard compression method as described in RFC 1951.

debug = [FACILITY.]LEVEL

debugging level

Level is one of the syslog level names or numbers emerg (0), alert (1), crit (2), err (3), warning (4), notice (5), info (6), or debug (7). All logs for the specified level and all levels numerically less than it will be shown. Use debug = debug or debug = 7 for greatest debugging output. The default is notice (5).

The syslog facility 'daemon' will be used unless a facility name is supplied. (Facilities are not supported on Win32.)

Case is ignored for both facilities and levels.

EGD = EGD_PATH (Unix only)

path to Entropy Gathering Daemon socket

Entropy Gathering Daemon socket to use to feed the OpenSSL random number generator.

engine = auto | ENGINE_ID

select hardware or software cryptographic engine

default: software-only cryptography

See Examples section for an engine configuration to use the certificate and the corresponding private key from a cryptographic device.

engineCtrl = COMMAND[:PARAMETER]

control hardware engine

engineDefault = TASK_LIST

set OpenSSL tasks delegated to the current engine

The parameter specifies a comma-separated list of task to be delegated to the current engine.

The following tasks may be available, if supported by the engine: ALL, RSA, DSA, ECDH, ECDSA, DH, RAND, CIPHERS, DIGESTS, PKEY, PKEY_CRYPTO, PKEY_ASN1.

fips = yes | no

enable or disable FIPS 140-2 mode.

This option allows you to disable entering FIPS mode if stunnel was compiled with FIPS 140-2 support.

default: no (since version 5.00)

foreground = yes | quiet | no (Unix only)

foreground mode

Stay in foreground (don't fork).

With the yes parameter it also logs to stderr in addition to the destinations specified with syslog and output.

default: background in daemon mode

iconActive = ICON_FILE (GUI only)

GUI icon to be displayed when there are established connections

On Windows platform the parameter should be an .ico file containing a 16x16 pixel image.

iconError = ICON_FILE (GUI only)

GUI icon to be displayed when no valid configuration is loaded

On Windows platform the parameter should be an .ico file containing a 16x16 pixel image.

iconIdle = ICON_FILE (GUI only)

GUI icon to be displayed when there are no established connections

On Windows platform the parameter should be an .ico file containing a 16x16 pixel image.

log = append | overwrite

log file handling

This option allows you to choose whether the log file (specified with the output option) is appended or overwritten when opened or re-opened.

default: append

output = FILE

append log messages to a file

/dev/stdout device can be used to send log messages to the standard output (for example to log them with daemontools splogger).

pid = FILE (Unix only)

pid file location

If the argument is empty, then no pid file will be created.

pid path is relative to the chroot directory if specified.

RNDbytes = BYTES

bytes to read from random seed files

RNDfile = FILE

path to file with random seed data

The OpenSSL library will use data from this file first to seed the random number generator.

RNDoverwrite = yes | no

overwrite the random seed files with new random data

default: yes

service = SERVICE (Unix only)

stunnel service name

The specified service name is used for syslog and as the inetd mode service name for TCP Wrappers. While this option can technically be specified in the service sections, it is only useful in global options.

default: stunnel

syslog = yes | no (Unix only)

enable logging via syslog

default: yes

taskbar = yes | no (WIN32 only)

enable the taskbar icon

default: yes

SERVICE-LEVEL OPTIONS

Note that if you wish to run stunnel in inetd mode (where it is provided a network socket by a server such as inetd, xinetd, or tcpserver) then you should read the section entitled INETD MODE below.

accept = [HOST:]PORT

accept connections on specified address

If no host specified, defaults to all IPv4 addresses for the local host.

To listen on all IPv6 addresses use:

    accept = :::PORT
    

CApath = DIRECTORY

Certificate Authority directory

This is the directory in which stunnel will look for certificates when using the verifyChain or verifyPeer options. Note that the certificates in this directory should be named XXXXXXXX.0 where XXXXXXXX is the hash value of the DER encoded subject of the cert.

The hash algorithm has been changed in OpenSSL 1.0.0. It is required to c_rehash the directory on upgrade from OpenSSL 0.x.x to OpenSSL 1.x.x.

CApath path is relative to the chroot directory if specified.

CAfile = CA_FILE

Certificate Authority file

This file contains multiple CA certificates, to be used with the verifyChain and verifyPeer options.

cert = CERT_FILE

certificate chain file name

The parameter specifies the file containing certificates used by stunnel to authenticate itself against the remote client or server. The file should contain the whole certificate chain starting from the actual server/client certificate, and ending with the self-signed root CA certificate. The file must be either in PEM or P12 format.

A certificate chain is required in server mode, and optional in client mode.

This parameter is also used as the certificate identifier when a hardware engine is enabled.

checkEmail = EMAIL

email address of the peer certificate subject

Multiple checkEmail options are allowed in a single service section. Certificates are accepted if no subject checks were specified, or the email address of the peer certificate matches any of the email addresses specified with checkEmail.

This option requires OpenSSL 1.0.2 or later.

checkHost = HOST

host of the peer certificate subject

Multiple checkHost options are allowed in a single service section. Certificates are accepted if no subject checks were specified, or the host name of the peer certificate matches any of the hosts specified with checkHost.

This option requires OpenSSL 1.0.2 or later.

checkIP = IP

IP address of the peer certificate subject

Multiple checkIP options are allowed in a single service section. Certificates are accepted if no subject checks were specified, or the IP address of the peer certificate matches any of the IP addresses specified with checkIP.

This option requires OpenSSL 1.0.2 or later.

ciphers = CIPHER_LIST

select permitted TLS ciphers (TLSv1.2 and below)

This option does not impact TLSv1.3 ciphersuites.

A colon-delimited list of the ciphers to allow in the TLS connection, for example DES-CBC3-SHA:IDEA-CBC-MD5.

ciphersuites = CIPHERSUITES_LIST

select permitted TLSv1.3 ciphersuites

A colon-delimited list of TLSv1.3 ciphersuites names in order of preference.

This option requires OpenSSL 1.1.1 or later.

default: TLS_CHACHA20_POLY1305_SHA256:TLS_AES_256_GCM_SHA384:TLS_AES_128_GCM_SHA256

client = yes | no

client mode (remote service uses TLS)

default: no (server mode)

config = COMMAND[:PARAMETER]

OpenSSL configuration command

The OpenSSL configuration command is executed with the specified parameter. This allows any configuration commands to be invoked from the stunnel configuration file. Supported commands are described on the SSL_CONF_cmd(3ssl) manual page.

Several config lines can be used to specify multiple configuration commands.

Use curves option instead of enabling config = Curves:list_curves to support elliptic curves.

This option requires OpenSSL 1.0.2 or later.

connect = [HOST:]PORT

connect to a remote address

If no host is specified, the host defaults to localhost.

Multiple connect options are allowed in a single service section.

If host resolves to multiple addresses and/or if multiple connect options are specified, then the remote address is chosen using a round-robin algorithm.

CRLpath = DIRECTORY

Certificate Revocation Lists directory

This is the directory in which stunnel will look for CRLs when using the verifyChain and verifyPeer options. Note that the CRLs in this directory should be named XXXXXXXX.r0 where XXXXXXXX is the hash value of the CRL.

The hash algorithm has been changed in OpenSSL 1.0.0. It is required to c_rehash the directory on upgrade from OpenSSL 0.x.x to OpenSSL 1.x.x.

CRLpath path is relative to the chroot directory if specified.

CRLfile = CRL_FILE

Certificate Revocation Lists file

This file contains multiple CRLs, used with the verifyChain and verifyPeer options.

curves = list

ECDH curves separated with ':'

Only a single curve name is allowed for OpenSSL older than 1.1.1.

To get a list of supported curves use:

    openssl ecparam -list_curves
    

default:

    X25519:P-256:X448:P-521:P-384 (OpenSSL 1.1.1 or later)

    prime256v1 (OpenSSL older than 1.1.1)
    

logId = TYPE

connection identifier type

This identifier allows you to distinguish log entries generated for each of the connections.

Currently supported types:

debug = LEVEL

debugging level

Level is a one of the syslog level names or numbers emerg (0), alert (1), crit (2), err (3), warning (4), notice (5), info (6), or debug (7). All logs for the specified level and all levels numerically less than it will be shown. The default is notice (5).

While the debug = debug or debug = 7 level generates the most verbose output, it is only intended to be used by stunnel developers. Please only use this value if you are a developer, or you intend to send your logs to our technical support. Otherwise, the generated logs will be confusing.

delay = yes | no

delay DNS lookup for the connect option

This option is useful for dynamic DNS, or when DNS is not available during stunnel startup (road warrior VPN, dial-up configurations).

Delayed resolver mode is automatically engaged when stunnel fails to resolve on startup any of the connect targets for a service.

Delayed resolver inflicts failover = prio.

default: no

engineId = ENGINE_ID

select engine ID for the service

engineNum = ENGINE_NUMBER

select engine number for the service

The engines are numbered starting from 1.

exec = EXECUTABLE_PATH

execute a local inetd-type program

exec path is relative to the chroot directory if specified.

The following environmental variables are set on Unix platforms: REMOTE_HOST, REMOTE_PORT, SSL_CLIENT_DN, SSL_CLIENT_I_DN.

execArgs = $0 $1 $2 ...

arguments for exec including the program name ($0)

Quoting is currently not supported. Arguments are separated with an arbitrary amount of whitespace.

failover = rr | prio

Failover strategy for multiple "connect" targets.

ident = USERNAME

use IDENT (RFC 1413) username checking

include = DIRECTORY

include all configuration file parts located in DIRECTORY

The files are included in the ascending alphabetical order of their names. The recommended filename convention is

for global options:

        00-global.conf
    

for local service-level options:

        01-service.conf

        02-service.conf
    

key = KEY_FILE

private key for the certificate specified with cert option

A private key is needed to authenticate the certificate owner. Since this file should be kept secret it should only be readable by its owner. On Unix systems you can use the following command:

    chmod 600 keyfile
    

This parameter is also used as the private key identifier when a hardware engine is enabled.

default: the value of the cert option

libwrap = yes | no

Enable or disable the use of /etc/hosts.allow and /etc/hosts.deny.

default: no (since version 5.00)

local = HOST

By default, the IP address of the outgoing interface is used as the source for remote connections. Use this option to bind a static local IP address instead.

OCSP = URL

select OCSP responder for certificate verification

OCSPaia = yes | no

validate certificates with their AIA OCSP responders

This option enables stunnel to validate certificates with the list of OCSP responder URLs retrieved from their AIA (Authority Information Access) extension.

OCSPflag = OCSP_FLAG

specify OCSP responder flag

Several OCSPflag can be used to specify multiple flags.

currently supported flags: NOCERTS, NOINTERN, NOSIGS, NOCHAIN, NOVERIFY, NOEXPLICIT, NOCASIGN, NODELEGATED, NOCHECKS, TRUSTOTHER, RESPID_KEY, NOTIME

OCSPnonce = yes | no

send and verify the OCSP nonce extension

This option protects the OCSP protocol against replay attacks. Due to its computational overhead, the nonce extension is usually only supported on internal (e.g. corporate) responders, and not on public OCSP responders.

options = SSL_OPTIONS

OpenSSL library options

The parameter is the OpenSSL option name as described in the SSL_CTX_set_options(3ssl) manual, but without SSL_OP_ prefix. stunnel -options lists the options found to be allowed in the current combination of stunnel and the OpenSSL library used to build it.

Several option lines can be used to specify multiple options. An option name can be prepended with a dash ("-") to disable the option.

For example, for compatibility with the erroneous Eudora TLS implementation, the following option can be used:

    options = DONT_INSERT_EMPTY_FRAGMENTS
    

default:

    options = NO_SSLv2
    options = NO_SSLv3
    

Use sslVersionMax or sslVersionMin option instead of disabling specific TLS protocol versions when compiled with OpenSSL 1.1.0 or later.

protocol = PROTO

application protocol to negotiate TLS

This option enables initial, protocol-specific negotiation of the TLS encryption. The protocol option should not be used with TLS encryption on a separate port.

Currently supported protocols:

protocolAuthentication = AUTHENTICATION

authentication type for the protocol negotiations

Currently, this option is only supported in the client-side 'connect' and 'smtp' protocols.

Supported authentication types for the 'connect' protocol are 'basic' or 'ntlm'. The default 'connect' authentication type is 'basic'.

Supported authentication types for the 'smtp' protocol are 'plain' or 'login'. The default 'smtp' authentication type is 'plain'.

protocolDomain = DOMAIN

domain for the protocol negotiations

Currently, this option is only supported in the client-side 'connect' protocol.

protocolHeader = HEADER

header for the protocol negotiations

Currently, this option is only supported in the client-side 'connect' protocol.

protocolHost = ADDRESS

host address for the protocol negotiations

For the 'connect' protocol negotiations, protocolHost specifies HOST:PORT of the final TLS server to be connected to by the proxy. The proxy server directly connected by stunnel must be specified with the connect option.

For the 'smtp' protocol negotiations, protocolHost controls the client SMTP HELO/EHLO value.

protocolPassword = PASSWORD

password for the protocol negotiations

Currently, this option is only supported in the client-side 'connect' and 'smtp' protocols.

protocolUsername = USERNAME

username for the protocol negotiations

Currently, this option is only supported in the client-side 'connect' and 'smtp' protocols.

PSKidentity = IDENTITY

PSK identity for the PSK client

PSKidentity can be used on stunnel clients to select the PSK identity used for authentication. This option is ignored in server sections.

default: the first identity specified in the PSKsecrets file.

PSKsecrets = FILE

file with PSK identities and corresponding keys

Each line of the file in the following format:

    IDENTITY:KEY
    

Hexadecimal keys are automatically converted to binary form. Keys are required to be at least 16 bytes long, which implies at least 32 characters for hexadecimal keys. The file should neither be world-readable nor world-writable.

pty = yes | no (Unix only)

allocate a pseudoterminal for 'exec' option

redirect = [HOST:]PORT

redirect TLS client connections on certificate-based authentication failures

This option only works in server mode. Some protocol negotiations are also incompatible with the redirect option.

renegotiation = yes | no

support TLS renegotiation

Applications of the TLS renegotiation include some authentication scenarios, or re-keying long lasting connections.

On the other hand this feature can facilitate a trivial CPU-exhaustion DoS attack:

http://vincent.bernat.im/en/blog/2011-ssl-dos-mitigation.html

Please note that disabling TLS renegotiation does not fully mitigate this issue.

default: yes (if supported by OpenSSL)

reset = yes | no

attempt to use the TCP RST flag to indicate an error

This option is not supported on some platforms.

default: yes

retry = yes | no

reconnect a connect+exec section after it was disconnected

default: no

securityLevel = LEVEL

set the security level

The meaning of each level is described below:

requireCert = yes | no

require a client certificate for verifyChain or verifyPeer

With requireCert set to no, the stunnel server accepts client connections that did not present a certificate.

Both verifyChain = yes and verifyPeer = yes imply requireCert = yes.

default: no

setgid = GROUP (Unix only)

Unix group id

As a global option: setgid() to the specified group in daemon mode and clear all other groups.

As a service-level option: set the group of the Unix socket specified with "accept".

setuid = USER (Unix only)

Unix user id

As a global option: setuid() to the specified user in daemon mode.

As a service-level option: set the owner of the Unix socket specified with "accept".

sessionCacheSize = NUM_ENTRIES

session cache size

sessionCacheSize specifies the maximum number of the internal session cache entries.

The value of 0 can be used for unlimited size. It is not recommended for production use due to the risk of a memory exhaustion DoS attack.

sessionCacheTimeout = TIMEOUT

session cache timeout

This is the number of seconds to keep cached TLS sessions.

sessionResume = yes | no

allow or disallow session resumption

default: yes

sessiond = HOST:PORT

address of sessiond TLS cache server

sni = SERVICE_NAME:SERVER_NAME_PATTERN (server mode)

Use the service as a slave service (a name-based virtual server) for Server Name Indication TLS extension (RFC 3546).

SERVICE_NAME specifies the master service that accepts client connections with the accept option. SERVER_NAME_PATTERN specifies the host name to be redirected. The pattern may start with the '*' character, e.g. '*.example.com'. Multiple slave services are normally specified for a single master service. The sni option can also be specified more than once within a single slave service.

This service, as well as the master service, may not be configured in client mode.

The connect option of the slave service is ignored when the protocol option is specified, as protocol connects to the remote host before TLS handshake.

Libwrap checks (Unix only) are performed twice: with the master service name after TCP connection is accepted, and with the slave service name during the TLS handshake.

The sni option is only available when compiled with OpenSSL 1.0.0 and later.

sni = SERVER_NAME (client mode)

Use the parameter as the value of TLS Server Name Indication (RFC 3546) extension.

Empty SERVER_NAME disables sending the SNI extension.

The sni option is only available when compiled with OpenSSL 1.0.0 and later.

socket = a|l|r:OPTION=VALUE[:VALUE]

Set an option on the accept/local/remote socket

The values for the linger option are l_onof:l_linger. The values for the time are tv_sec:tv_usec.

Examples:

    socket = l:SO_LINGER=1:60
        set one minute timeout for closing local socket
    socket = r:SO_OOBINLINE=yes
        place out-of-band data directly into the
        receive data stream for remote sockets
    socket = a:SO_REUSEADDR=no
        disable address reuse (enabled by default)
    socket = a:SO_BINDTODEVICE=lo
        only accept connections on loopback interface
    

sslVersion = SSL_VERSION

select the TLS protocol version

Supported versions: all, SSLv2, SSLv3, TLSv1, TLSv1.1, TLSv1.2, TLSv1.3

Availability of specific protocols depends on the linked OpenSSL library. Older versions of OpenSSL do not support TLSv1.1, TLSv1.2 and TLSv1.3. Newer versions of OpenSSL do not support SSLv2.

Obsolete SSLv2 and SSLv3 are currently disabled by default.

Setting the option

    sslVersion = SSL_VERSION
    

is equivalent to options

    sslVersionMax = SSL_VERSION
    sslVersionMin = SSL_VERSION
    

when compiled with OpenSSL 1.1.0 and later.

sslVersionMax = SSL_VERSION

maximum supported protocol versions

Supported versions: all, SSLv3, TLSv1, TLSv1.1, TLSv1.2, TLSv1.3

all enable protocol versions up to the highest version supported by the linked OpenSSL library.

Availability of specific protocols depends on the linked OpenSSL library.

The sslVersionMax option is only available when compiled with OpenSSL 1.1.0 and later.

default: all

sslVersionMin = SSL_VERSION

minimum supported protocol versions

Supported versions: all, SSLv3, TLSv1, TLSv1.1, TLSv1.2, TLSv1.3

all enable protocol versions down to the lowest version supported by the linked OpenSSL library.

Availability of specific protocols depends on the linked OpenSSL library.

The sslVersionMin option is only available when compiled with OpenSSL 1.1.0 and later.

default: TLSv1

stack = BYTES (except for FORK model)

CPU stack size of created threads

Excessive thread stack size increases virtual memory usage. Insufficient thread stack size may cause application crashes.

default: 65536 bytes (sufficient for all platforms we tested)

ticketKeySecret = SECRET

hexadecimal symmetric key used for session ticket confidentiality protection

Session tickets defined in RFC 5077 provide an enhanced session resumption capability, where the server-side caching is not required to maintain per session state.

Combining ticketKeySecret and ticketMacSecret options allow to resume a negotiated session on other cluster nodes, or to resume a negotiated session after server restart.

The key is required to be either 16 or 32 bytes long, which implies exactly 32 or 64 hexadecimal digits. Colons may optionally be used between two-character hexadecimal bytes.

This option only works in server mode.

The ticketKeySecret option is only available when compiled with OpenSSL 1.0.0 and later.

Disabling NO_TICKET option is required for the ticket support in OpenSSL older than 1.1.1, but note that this option is incompatible with the redirect option.

ticketMacSecret = SECRET

hexadecimal symmetric key used for session ticket integrity protection

The key is required to be either 16 or 32 bytes long, which implies exactly 32 or 64 hexadecimal digits. Colons may optionally be used between two-character hexadecimal bytes.

This option only works in server mode.

The ticketMacSecret option is only available when compiled with OpenSSL 1.0.0 and later.

TIMEOUTbusy = SECONDS

time to wait for expected data

TIMEOUTclose = SECONDS

time to wait for close_notify (set to 0 for buggy MSIE)

TIMEOUTconnect = SECONDS

time to wait to connect to a remote host

TIMEOUTidle = SECONDS

time to keep an idle connection

transparent = none | source | destination | both (Unix only)

enable transparent proxy support on selected platforms

Supported values:

verify = LEVEL

verify the peer certificate

This option is obsolete and should be replaced with the verifyChain and verifyPeer options.

verifyChain = yes | no

verify the peer certificate chain starting from the root CA

For server certificate verification it is essential to also require a specific certificate with checkHost or checkIP.

The self-signed root CA certificate needs to be stored either in the file specified with CAfile, or in the directory specified with CApath.

default: no

verifyPeer = yes | no

verify the peer certificate

The peer certificate needs to be stored either in the file specified with CAfile, or in the directory specified with CApath.

default: no

RESTRICTIONS

INETD MODE

For example, if you have the following line in inetd.conf:

    imaps stream tcp nowait root /usr/local/bin/stunnel stunnel /usr/local/etc/stunnel/imaps.conf

In these cases, the inetd-style program is responsible for binding a network socket (imaps above) and handing it to stunnel when a connection is received. Thus you do not want stunnel to have any accept option. All the Service Level Options should be placed in the global options section, and no [service_name] section will be present. See the EXAMPLES section for example configurations.

CERTIFICATES

The .pem file should contain the unencrypted private key and a signed certificate (not certificate request). So the file should look like this:

    -----BEGIN RSA PRIVATE KEY-----
    [encoded key]
    -----END RSA PRIVATE KEY-----
    -----BEGIN CERTIFICATE-----
    [encoded certificate]
    -----END CERTIFICATE-----

RANDOMNESS

• The file specified with the RNDfile flag.
• The file specified by the RANDFILE environment variable, if set.
• The file .rnd in your home directory, if RANDFILE not set.
• The file specified with '--with-random' at compile time.
• The contents of the screen if running on Windows.
• The egd socket specified with the EGD flag.
• The egd socket specified with '--with-egd-sock' at compile time.
• The /dev/urandom device.

Note that on Windows machines that do not have console user interaction (mouse movements, creating windows, etc.) the screen contents are not variable enough to be sufficient, and you should provide a random file for use with the RNDfile flag.

Note that the file specified with the RNDfile flag should contain random data -- that means it should contain different information each time stunnel is run. This is handled automatically unless the RNDoverwrite flag is used. If you wish to update this file manually, the openssl rand command in recent versions of OpenSSL, would be useful.

Important note: If /dev/urandom is available, OpenSSL often seeds the PRNG with it while checking the random state. On systems with /dev/urandom OpenSSL is likely to use it even though it is listed at the very bottom of the list above. This is the behaviour of OpenSSL and not stunnel.

DH PARAMETERS

Alternatively, it is possible to specify static DH parameters in the certificate file, which disables generating temporary DH parameters:

    openssl dhparam 2048 >> stunnel.pem