From df591270aaedeed7dd91e3d6052e1d55a8712203 Mon Sep 17 00:00:00 2001 From: David Yozie Date: Wed, 14 Jun 2017 08:28:41 -0700 Subject: [PATCH] Removing unused stunnel reference doc --- .../admin_utilities/stunnel-ref.xml | 1291 ----------------- 1 file changed, 1291 deletions(-) delete mode 100644 gpdb-doc/dita/utility_guide/admin_utilities/stunnel-ref.xml diff --git a/gpdb-doc/dita/utility_guide/admin_utilities/stunnel-ref.xml b/gpdb-doc/dita/utility_guide/admin_utilities/stunnel-ref.xml deleted file mode 100644 index 4634d91eb0..0000000000 --- a/gpdb-doc/dita/utility_guide/admin_utilities/stunnel-ref.xml +++ /dev/null @@ -1,1291 +0,0 @@ - - - - - stunnel - -

The stunnel utility is an SSL encryption wrapper that runs between remote - clients and local (inetd-startable) or remote servers. You can use stunnel - to enable SSL for the PgBouncer connection pooler for Greenplum Database and PostgreSQL.

-
- Synopsis -
- -
- Unix: -
-
- stunnel [file] | -fd N | -help | -version | -sockets | -options -
- - -
- WIN32: -
-
- stunnel [ [ -install | -uninstall | -start | -stop | -reload | -reopen | -exit ] - [ -quiet] [ file] ] | -help | -version | -sockets | -options -
- -
-

stunnel returns zero on success, non-zero on error.

-
-
- Description -

stunnel can be used to add SSL functionality to commonly used - Inetd daemons like POP-2, POP-3, and IMAP servers, to standalone daemons like - NNTP, SMTP, HTTP, and PgBouncer, and in tunneling PPP over network sockets without changes - to the source code.

-

This product includes cryptographic software written by Eric Young - (eay@cryptsoft.com)

-
-
- Options -
- -
- file -
-
-

Use the specified configuration file

-
- - -
-fd N (Unix only)
-
-

Read the config file from specified file descriptor

-
- - -
-help
-
-

Display stunnel help

-
- - -
-version
-
-

Print stunnel version and compile time defaults

-
- - -
-sockets
-
-

Print default socket options

-
- - -
-options
-
-

Print supported SSL options

-
- - -
-install (Windows NT and later only)
-
-

Install stunnel as an NT Service

-
- - -
-uninstall (Windows NT and later only)
-
-

Uninstall stunnel NT Service

-
- - -
-start (Windows NT and later only)
-
-

Start NT Service

-
- - -
-stop (Windows NT and later only)
-
-

Stop NT Service

-
- - -
-reload (Windows NT and later only)
-
-

Reload the configuration file of the running Windows service

-
- - -
-reopen (Windows NT and later only)
-
-

Reopen the log file of the running Windows service

-
- - -
-exit (Win32 only)
-
-

Exit an already started stunnel

-
- - -
-quiet (Win32 only)
-
-

Don't display any message boxes

-
- -
-
- - - - Notes - -
- Restrictions -

stunnel cannot be used for the FTP daemon because of the nature of the - FTP protocol, which utilizes multiple ports for data transfers. There are SSL-enabled - versions of FTP and telnet daemons available.

-
-
- inetd Mode -

The most common use of stunnel is to listen on a network port and - establish communication with either a new port via the connect option, or a new program - via the exec option. However there is a special case when you wish to have some - other program accept incoming connections and launch stunnel, for example - with inetd, xinetd, or tcpserver.

-

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 stunnel Examples for example - configurations.

-
-
- Certificates -

Each SSL-enabled daemon needs to present a valid X.509 certificate to the peer. It also - needs a private key to decrypt the incoming data. The easiest way to obtain a certificate - and a key is to generate them with the free OpenSSL package. You can find more information - on certificate generation on pages listed below.

-

The order of contents of the .pem file is important. It should contain the - unencrypted private key first, then a signed certificate (not certificate request). There - should be empty lines after the certificate and the private key. Any plain text - certificate information appended on the top of generated certificate should be discarded. - The file should look like this:

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

stunnel needs to seed the PRNG (pseudo-random number generator) in order - for SSL to use good randomness. The following sources are loaded in order until sufficient - random data has been gathered:

-
    -
  • -

    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.

    -
    • -
-

With a recent (OpenSSL 0.9.5a or later) version of SSL it will stop loading random data - automatically when sufficient entropy has been gathered. With previous versions it will - continue to gather from all the above sources since no SSL function exists to tell when - enough data is available.

-

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.

-

The file specified with the RNDfile flag should contain random data—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.

- 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 -

stunnel 4.40 and later contains hardcoded 2048-bit DH parameters. - Starting with stunnel 5.18, these hardcoded DH parameters are replaced - every 24 hours with autogenerated temporary DH parameters. DH parameter generation may - take several minutes.

-

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

- openssl dhparam 2048 >> stunnel.pem -
- - - - stunnel Configuration File - -

The default stunnel configuration file is - /usr/local/etc/stunnel/stunnel.conf. When you install stunnel a - sample configuration file is created at - /usr/local/etc/stunnel/stunnel.conf-sample. You can copy and then - edit this file to create a configuration file.

-

Each line of the configuration file can be either:

-
    -
  • An empty line (ignored).
    • -
  • A comment starting with ';' (ignored).
    • -
  • An option_name = option_value pair.
    • -
  • -

    '[service_name]' indicating the start of a service definition.

    -
    • -
-

An address parameter may be either:

-
    -
  • -

    A port number.

    -
    • -
  • -

    A colon-separated pair of IP address (either IPv4, IPv6, or domain name) and port - number.

    -
    • -
  • -

    A Unix socket path (Unix only).

    -
    • -
-
- stunnel Configuration Options -

The configuration file may contain the following 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.:

-
    -
  • -

    Delayed resolver typically needs /etc/nsswitch.conf and - /etc/resolv.conf.

    -
    • -
  • -

    Local time in log files needs /etc/timezone.

    -
    • -
  • -

    Some other functions may need devices, for example, - /dev/zero or /dev/null.

    -
    • -
-
- - -
compression = deflate | zlib
-
Selects the compression algorithm. - Default: no compression. - deflate is the standard compression method as described in RFC - 1951. - zlib compression of OpenSSL 0.9.8 or above is not backward - compatible with OpenSSL 0.9.7. -
- - -
debug = [FACILITY.]LEVEL
-
-

The 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 are shown. Use - debug = debug or debug = 7 for the most 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)
-
-

The path to the Entropy Gathering Daemon socket.

-

The Entropy Gathering Daemon socket is used to feed the OpenSSL random number - generator. (Available only if compiled with OpenSSL 0.9.5a or higher.)

-
- - -
engine = auto | ENGINE_ID
-
-

Selects the hardware engine.

-

Default: software-only cryptography

-

Here is an example of advanced engine configuration to read the private key from an - OpenSC engine.

- engine=dynamic - engineCtrl=SO_PATH:/usr/lib/opensc/engine_pkcs11.so - engineCtrl=ID:pkcs11 - engineCtrl=LIST_ADD:1 - engineCtrl=LOAD - engineCtrl=MODULE_PATH:/usr/lib/pkcs11/opensc-pkcs11.so - engineCtrl=INIT - - [service] - engineNum=1 - key=id_45 -
- - -
engineCtrl = COMMAND[:PARAMETER]
-
-

Control hardware engine.

-

Special commands LOAD and INIT can be used to - load and initialize the engine cryptogaphic module.

-
- - -
engineDefault = TASK_LIST
-
-

Set OpenSSL tasks delegated to the current engine.

-

The parameter value is a comma-separated list of tasks 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 | no (Unix only)
-
-

Enable or disable foreground mode.

-

Stay in foreground (do not fork) and log to stderr instead of via syslog (unless - output is specified).

-

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.

-

Selects whether the log file (specified with the output option) is appended - or overwritten when it is opened or re-opened.

-

Default: append

-
- - -
output = FILE
-
-

Append log messages to a file.

-

The /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)
-
-

The location of the pid file.

-

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

-

pid path is relative to the chroot directory if specified.

-
- - -
RNDbytes = BYTES
-
-

The number of bytes of data to read from random seed files. With SSL versions less - than 0.9.5a, this also determines how many bytes of data are considered sufficient - to seed the PRNG (pseudo-random number generator). More recent OpenSSL versions have - a built-in function to determine when sufficient randomness is available.

-
- - -
RNDfile = FILE
-
-

The path to the file with random seed data.

-

The SSL library uses 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)
-
-

The 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

-
- - -
setgid = GROUP (Unix only)
-
-

setgid() to the specified group in daemon mode and clear all other groups.

-
- - -
setuid = USER (Unix only)
-
-

setuid() to the specified user in daemon mode.

-
- - -
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 -
- - -
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 -

Each configuration section begins with a service name in square brackets. The service - name is used for libwrap (TCP Wrappers) access control and lets you distinguish - stunnel services in your log files.

-

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.

-
- -
accept = [HOST:]PORT
-
-

Accept connections on specified address.

-

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

-

To listen on all IPv6 addresses use:

- accept = :::PORT -
- - -
CApath = DIRECTORY
-
-

The Certificate Authority directory.

-

This is the directory where stunnel looks for certificates when - using the verify option. 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 certificate.

-

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 = CERT_FILE
-
-

The Certificate Authority file.

-

This file contains multiple CA certificates, used with the verify - option.

-
- - -
cert = PEM_FILE
-
-

The certificate chain PEM file name.

-

The certificates must be in PEM format, and must be from the actual server/client - certificate to the self-signed root CA certificate.

-

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

-
- - -
checkEmail = EMAIL
-
-

The email address of the peer certificate subject.

-

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

-
- - -
checkHost = HOST
-
-

The host of the peer certificate subject.

-

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

-
- - -
checkIP = IP
-
-

IP address of the peer certificate subject.

-

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

-
- - -
ciphers = CIPHER_LIST
-
-

Specifies the permitted SSL ciphers.

-

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

-
- - -
client = yes | no
-
-

Client mode (remote service uses SSL).

-

Default: no (server mode)

-
- - -
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 selected using a round-robin - algorithm.

-
- - -
CRLpath = DIRECTORY
-
-

Certificate Revocation Lists directory.

-

This is the directory in which stunnel looks for CRLs when using - the verify option. 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 = CERT_FILE
-
-

Certificate Revocation Lists file.

-

This file contains multiple CRLs, used with the verify option.

-
- - -
curve = NID
-
-

Specify ECDH curve name.

-

To get a list of supported curves use:

- openssl ecparam -list_curves -

Default: prime256v1

-
- - -
logId = TYPE
-
-

The connection identifier type.

-

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

-

Currently supported types:

-
    -
  • - sequential -

    The numeric sequential identifier is only unique within a single instance of - stunnel, but very compact. It is most useful for manual log - analysis.

    -
    • -
  • - unique -

    This alphanumeric identifier is globally unique, but longer than the sequential - number. It is most useful for automated log analysis.

    -
    • -
  • - thread -

    The operating system thread identifier is neither unique (even within a single - instance of stunnel) nor short. It is most useful for debugging - software or configuration issues.

    -
    • -
-

Default: sequential

-
- - -
debug = LEVEL
-
-

The 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. Use - debug = debug or debug = 7 for greatest - debugging output. The default is notice (5).

-
- - -
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.

-

The executable 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 ...
-
-

The 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.

-
    -
  • rr (round robin) - fair load distribution
    • -
  • prio (priority) - use the order specified in the config file
    • -
-

Default: rr

-
- - -
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.

-
- - -
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 to protect the keyfile:

- chmod 600 keyfile -

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.

-
- - -
sni = SERVICE:SERVER_PATTERN (server - mode)
-
-

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

-

service 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, for example, - *.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 and the master service cannot 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 the TLS - handshake.

-

Libwrap checks (Unix only) are performed twice: with the master service name after - the 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 (client mode)
-
-

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

-

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

-
- - -
OCSP = URL
-
-

Select OCSP server 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
-
-

Specifies an OCSP server flag.

-

Several OCSPflag can be used to specify multiple flags.

-

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

-
- - -
options = SSL_OPTIONS
-
-

Specify OpenSSL library options.

-

The parameter is the OpenSSL option name as described in the - SSL_CTX_set_options(3ssl) manual, but without the 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 options 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 SSL implementation, the - following option can be used:

- options = DONT_INSERT_EMPTY_FRAGMENTS -

Default:

- options = NO_SSLv2 - options = NO_SSLv3 -
- - -
protocol = PROTO
-
-

application protocol to negotiate SSL

-

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

-

Currently supported protocols:

-
    -
  • - cifs -

    Proprietary (undocummented) extension of CIFS protocol implemented in Samba. - Support for this extension was dropped in Samba 3.0.0.

    -
    • -
  • - connect -

    Based on RFC 2817 - Upgrading to TLS Within HTTP/1.1, section 5.2 - - Requesting a Tunnel with CONNECT.

    -

    This protocol is only supported in client mode.

    -
    • -
  • - imap -

    Based on RFC 2595 - Using TLS with IMAP, POP3 and ACAP.

    -
    • -
  • - nntp -

    Based on RFC 4642 - Using Transport Layer Security (TLS) with Network News - Transfer Protocol (NNTP).

    -

    This protocol is only supported in client mode.

    -
    • -
  • - pgsql -

    Based on - https://www.postgresql.org/docs/8.3/static/protocol-flow.html#AEN73982.

    -
    • -
  • - pop3 -

    Based on RFC 2449 - POP3 Extension Mechanism.

    -
    • -
  • - proxy -

    Haproxy client IP address - http://haproxy.1wt.eu/download/1.5/doc/proxy-protocol.txt.

    -
    • -
  • - smtp -

    Based on RFC 2487 - SMTP Service Extension for Secure SMTP over TLS

    -
    • -
  • - socks -

    SOCKS versions 4, 4a, and 5 are supported. The SOCKS protocol itself is - encapsulated within SSL/TLS encryption layer to protect the final destination - address.

    -

    - http://www.openssh.com/txt/socks4.protocol -

    -

    - http://www.openssh.com/txt/socks4a.protocol -

    -

    The BIND command of the SOCKS protocol is not supported. The USERID parameter - is ignored.

    -

    See Examples section for sample configuration files for VPN based on SOCKS - encryption.

    -
    • -
-
- - -
protocolAuthentication = basic | ntlm
-
-

The authentication type for protocol negotiations.

-

Currently the authentication type only applies to the connect protocol.

-

Default: basic

-
- - -
protocolHost = HOST:PORT
-
-

The destination address for protocol negotiations.

-

protocolHost specifies the final SSL server to be connected to by the proxy, - and not the proxy server directly connected by stunnel. The proxy - server should be specified with the connect option.

-

Currently, the protocol destination address only applies to the connect - protocol.

-
- - -
protocolPassword = PASSWORD
-
-

Password for protocol negotiations.

-
- - -
protocolUsername = USERNAME
-
-

Username for protocol negotiations.

-
- - -
PSKidentity = IDENTITY
-
-

The 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
-
-

A file with PSK identities and corresponding keys.

-

Each line of the file is in the following format:

- IDENTITY:KEY -

The key is required to be at least 20 characters long. The file should not be - world-readable nor world-writable.

-
- - -
pty = yes | no (Unix only)
-
-

Allocate a pseudoterminal for the exec option.

-
- - -
redirect = [HOST:]PORT
-
-

Redirect SSL 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 SSL renegotiation.

-

Applications of the SSL 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. Note that - disabling SSL 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 is disconnected.

-

Default: no

-
- - -
sessionCacheSize = NUM_ENTRIES
-
-

The session cache size.

-

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

-

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

-
- - -
sessionCacheTimeout = TIMEOUT
-
-

The session cache timeout.

-

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

-
- - -
sessiond = HOST:PORT
-
-

The address of the sessiond SSL cache server.

-
- - -
sslVersion = SSL_VERSION
-
-

Selects the SSL protocol version.

-

Allowed values: all, SSLv2, - SSLv3, TLSv1, TLSv1.1, - TLSv1.2

-
- - -
stack = BYTES (except for FORK model)
-
-

The thread stack size.

-
- - -
TIMEOUTbusy = SECONDS
-
-

The time to wait for expected data.

-
- - -
TIMEOUTclose = SECONDS
-
-

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

-
- - -
TIMEOUTconnect = SECONDS
-
-

The time to wait to connect to a remote host.

-
- - -
TIMEOUTidle = SECONDS
-
-

The time to keep an idle connection.

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

Enables transparent proxy support on selected platforms.

-

Supported values:

-
    -
  • - none -

    Disable transparent proxy support. This is the default.

    -
    • -
  • - source -

    Re-write the address to appear as if a wrapped daemon is connecting from the - SSL client machine instead of the machine running stunnel.

    -

    This option is currently available in:

    -
      -
    • Remote mode (connect option) on Linux >=2.6.28

      This - configuration requires stunnel to be executed as root and - without the setuid option.

      This configuration requires the - following setup for iptables and routing (possibly in - /etc/rc.local or equivalent - file):

      iptables -t mangle -N DIVERT - iptables -t mangle -A PREROUTING -p tcp -m socket -j DIVERT - iptables -t mangle -A DIVERT -j MARK --set-mark 1 - iptables -t mangle -A DIVERT -j ACCEPT - ip rule add fwmark 1 lookup 100 - ip route add local 0.0.0.0/0 dev lo table 100 - echo 0 >/proc/sys/net/ipv4/conf/lo/rp_filter
      • -
    • Remote mode (connect option) on Linux 2.2.x

      This - configuration requires the kernel to be compiled with the transparent - proxy option. Connected service must be installed on a separate host. - Routing towards the clients has to go through the stunnel - box.

      stunnel must also to be executed as root and - without the setuid option.

      • -
    • Remote mode (connect option) on FreeBSD >=8.0

      This - configuration requires additional firewall and routing setup. - stunnel must also to be executed as root and without the - setuid option.

      • -
    • Local mode (exec option)

      This configuration works by pre-loading - the libstunnel.so shared library. The _RLD_LIST - environment variable is used on Tru64, and LD_PRELOAD - variable on other platforms.

      • -
    -
    • -
  • - destination -

    The original destination is used instead of the connect option.

    -

    A service section for transparent destination may look like this:

    - [transparent] - client=yes - accept=<stunnel_port> - transparent=destination -

    This configuration requires iptables setup to work, possibly in - /etc/rc.local or equivalent file.

    -

    For a connect target installed on the same host:

    - /sbin/iptables -t nat -I OUTPUT -p tcp --dport <redirected_port> \ - -m ! --uid-owner <stunnel_user_id> \ - -j DNAT --to-destination <local_ip>:<stunnel_port> -

    For a connect target installed on a remote host:

    - /sbin/iptables -I INPUT -i eth0 -p tcp --dport <stunnel_port> -j ACCEPT \ - /sbin/iptables -t nat -I PREROUTING -p tcp --dport <redirected_port> \ - -i eth0 -j DNAT --to-destination <local_ip>:<stunnel_port> -

    The transparent destination option is currently only supported on Linux.

    -
    • -
  • - both -

    Use both source and destination transparent proxy.

    -
    • -
-

Two legacy options are also supported for backward compatibility:

-
    -
  • - yes -

    This option has been renamed to source.

    -
    • -
  • - no -

    This option has been renamed to none.

    -
    • -
-
- - -
verify = LEVEL
-
-

Verify the peer certificate.

-
    -
  • - level 0 -

    Request and ignore the peer certificate.

    -
    • -
  • - level 1 -

    Verify the peer certificate if present.

    -
    • -
  • - level 2 -

    Verify the peer certificate.

    -
    • -
  • - level 3 -

    Verify the peer with locally installed certificate.

    -
    • -
  • - level 4 -

    Ignore the CA chain and only verify the peer certificate.

    -
    • -
  • - default -

    No verify.

    -
    • -
-

This option was solely designed for access control and not for authorization. - Specifically for level 2, every non-revoked certificate is accepted regardless of - its Common Name. For this reason a dedicated CA should be used with level 2, and not - a generic CA commonly used for Web servers. Level 3 is preferred for point-to-point - connections.

-
- -
-
- - - - Signals - -

The following signals can be used to control stunnel in a Unix - environment:

-
- -
SIGHUP
-
-

Force a reload of the configuration file.

-

Some global options will not be reloaded:

-
    -
  • chroot
    • -
  • foreground
    • -
  • pid
    • -
  • setgid
    • -
  • setuid
    • -
-

The use of the setuid option will also prevent stunnel from binding - to privileged (<1024) ports during configuration reloading.

-

When the chroot option is used, stunnel will look for all its files - (including the configuration file, certificates, the log file and the pid file) within - the chroot jail.

-
- - -
SIGUSR1
-
-

Close and reopen the stunnel log file. This function can be used for - log rotation.

-
- - -
SIGTERM, SIGQUIT, SIGINT
-
-

Shut stunnel down.

-
- -
-

The result of sending any other signals to the server is undefined.

- - - - stunnel Examples - -

To provide SSL encapsulation to your local imapd service, use:

- [imapd] - accept = 993 - exec = /usr/sbin/imapd - execArgs = imapd -

or in remote mode:

- [imapd] - accept = 993 - connect = 143 -

To allow your local e-mail client to connect to an SSL-enabled imapd service on - another server, configure the e-mail client to connect to localhost on port 119 and use:

- [imap] - client = yes - accept = 143 - connect = servername:993 -

To provide tunneling to your pppd daemon on port 2020, use a service like the - following:

- [vpn] - accept = 2020 - exec = /usr/sbin/pppd - execArgs = pppd local - pty = yes -

To use stunnel in inetd mode to launch your imapd process, use this - stunnel.conf. Note there must be no [service_name] section.

- exec = /usr/sbin/imapd - execArgs = imapd -

To set up SOCKS VPN, configure the following client service:

- [socks_client] - client = yes - accept = 127.0.0.1:1080 - connect = vpn_server:9080 - verify = 4 - CAfile = stunnel.pem -

The corresponding configuration on the vpn_server host:

- [socks_server] - protocol = socks - accept = 9080 - cert = stunnel.pem - key = stunnel.key -

Test your configuration on the client machine with:

- curl --socks4a localhost http://www.example.com/ - - - -- GitLab