sssctl

title: sssctl(8)

summary: SSSD control and status utility

text:
# sssctl(8)

## NAME
sssctl - SSSD control and status utility

## SYNOPSIS
sssctl COMMAND [options]

## DESCRIPTION
sssctl provides a simple and unified way to obtain information about SSSD status, such as active server, auto-discovered servers, domains and cached objects. In addition, it can manage SSSD data files for troubleshooting in such a way that is safe to manipulate while SSSD is running.

## AVAILABLE COMMANDS
To list all available commands run sssctl without any parameters. To print help for selected command run sssctl COMMAND --help.

## COMMON OPTIONS
Those options are available with all commands.

--debug LEVEL

SSSD supports two representations for specifying the debug level. The simplest is to specify a decimal value from 0-9, which represents enabling that level and all lower-level debug messages. The more comprehensive option is to specify a hexadecimal bitmask to enable or disable specific levels (such as if you wish to suppress a level). Currently supported debug levels:

0, 0x0010: Fatal failures. Anything that would prevent SSSD from starting up or causes it to cease running.

1, 0x0020: Critical failures. An error that doesn't kill SSSD, but one that indicates that at least one major feature is not going to work properly.

2, 0x0040: Serious failures. An error announcing that a particular request or operation has failed.

3, 0x0080: Minor failures. These are the errors that would percolate down to cause the operation failure of 2.

4, 0x0100: Configuration settings.

5, 0x0200: Function data.

6, 0x0400: Trace messages for operation functions.

7, 0x1000: Trace messages for internal control functions.

8, 0x2000: Contents of function-internal variables that may be interesting.

9, 0x4000: Extremely low-level tracing information.

10, 0x10000: Even more low-level libldb tracing information. Almost never really required.

To log required bitmask debug levels, simply add their numbers together as shown in following examples:

Example: To log fatal failures, critical failures, serious failures and function data use 0x0270.

Example: To log fatal failures, configuration settings, function data, trace messages for internal control functions use 0x1310.

Note: The bitmask format of debug levels was introduced in 1.7.0.

Default: 0x0070 (i.e. fatal, critical and serious failures; corresponds to setting 2 in decimal notation)

## SEE ALSO
sssd(8), sssd.conf(5), sssd-ldap(5), sssd-ldap-attributes(5), sssd-krb5(5), sssd-simple(5), sssd-ipa(5), sssd-ad(5), sssd-sudo(5), sssd-session-recording(5), sss_cache(8), sss_debuglevel(8), sss_obfuscate(8), sss_seed(8), sssd_krb5_locator_plugin(8), sss_ssh_authorizedkeys(8), sss_ssh_knownhostsproxy(8), sssd-ifp(5), pam_sss(8). sss_rpcidmapd(5)

## AUTHORS
The SSSD upstream - https://github.com/SSSD/sssd/


package: sssd-winbind-idmap

title: idmap_sss(8)

summary: SSSD\*(Aqs idmap_sss Backend for Winbind

text:
# idmap_sss(8)

## NAME
idmap_sss - SSSD's idmap_sss Backend for Winbind

## DESCRIPTION
The idmap_sss module provides a way to call SSSD to map UIDs/GIDs and SIDs. No database is required in this case as the mapping is done by SSSD.

## IDMAP OPTIONS
range = low - high

Defines the available matching UID and GID range for which the backend is authoritative.

## EXAMPLES
This example shows how to configure idmap_sss as the default mapping module.

```
[global]
security = ads
workgroup = <AD-DOMAIN-SHORTNAME>
idmap config <AD-DOMAIN-SHORTNAME> : backend        = sss
idmap config <AD-DOMAIN-SHORTNAME> : range          = 200000-2147483647
idmap config * : backend        = tdb
idmap config * : range          = 100000-199999

```

Please replace <AD-DOMAIN-SHORTNAME> with the NetBIOS domain name of the AD domain. If multiple AD domains should be used each domain needs an idmap config line with backend = sss and a line with a suitable range.

Since Winbind requires a writeable default backend and idmap_sss is read-only the example includes backend = tdb as default.

## SEE ALSO
sssd(8), sssd.conf(5), sssd-ldap(5), sssd-ldap-attributes(5), sssd-krb5(5), sssd-simple(5), sssd-ipa(5), sssd-ad(5), sssd-sudo(5), sssd-session-recording(5), sss_cache(8), sss_debuglevel(8), sss_obfuscate(8), sss_seed(8), sssd_krb5_locator_plugin(8), sss_ssh_authorizedkeys(8), sss_ssh_knownhostsproxy(8), sssd-ifp(5), pam_sss(8). sss_rpcidmapd(5)

## AUTHORS
The SSSD upstream - https://github.com/SSSD/sssd/


sstpc

package: sstp-client

title: sstpc(8)

summary: SSTP Client

text:
# sstpc(8)

## NAME
sstpc - SSTP Client

## SYNOPSIS
sstpc [<sstp-options>] <hostname> [ppp-options] ...

## DESCRIPTION
sstpc establishes the client side of a Virtual Private Network (VPN) using the Secure Socket Tunneling Protocol (SSTP). Use this program to connect to an employer's SSTP based VPN when PPTP and L2TP is not working.

By default, sstpc establishes the SSTP call to the SSTP server, and then starts an instance of pppd to manage the data transfer. However, sstpc can also be run as a connection manager within pppd.

## OPTIONS
The first non-option argument on the sstpc command line must be the host name or IP address of the SSTP server.

All long options (starting with "--") are interpreted as sstpc options, and a fatal error occurs if an unrecognised option is used.

All command-line arguments which do not start with "-" are interpreted as ppp options, and passed as is to pppd unless --nolaunchpppd is given.

--ca-cert

Specify the CA certificate used to verify the server with

--ca-dir

Specify the directory of certificates that contains the CA certificate. If nothing is specified, the system's wide directory is used.

--cert-warn

Ignore certificate warnings like common name instead of terminating the connection.

--host

When connecting to an IP address, the host parameter will provide the hostname for http, proxy and tls-ext

--ipparam

This will help specify the callback socket that pppd will try to connect back to sstpc in order to communicate the MPPE keys as negotiated. The MPPE keys are required to authenticate against the server at the SSL layer. They can be zeroed if no MPPE is negotiated. The name is formed based on /tmp/sstpc-<ipparam>.

--nolaunchpppd

Do not launch pppd but use stdin as the network connection. Use this flag when including sstpc as a pppd connection process using the pty option. See EXAMPLES.

--password

Specify a password per command line instead of setting it up in a configuration file for pppd in /etc/ppp/peers.

--proxy

Connect to the SSTP server via a proxy on your network. The syntax is http://[<user>:<pass>@]<domain>:port.

--priv-user

Specify the privilege separation user to run sstpc

--priv-group

Specify the privilege separation group to run sstpc

--priv-dir

Specify the privilege separation directory for the chroot jail to run sstpc

--user

Specify the username to authenticate to the SSTP server instead of setting it up in a configuration file for pppd in /etc/ppp/peers.

--save-server-route

This will automatically add and remove a route to the SSTP server.

--uuid

Specify a UUID for the connection to simplify the server end debugging.

--tls-ext

This will enable TLS hostname extension.

### Troubleshooting
The following options are available to help troubleshoot sstpc

--log-level <level>

Set the debug level for debugging the sstpc process. Level can be a value between 0 and 4.

--log-syslog

Log messages to syslog (default).

--log-stderr

Log messages to error output

--log-stdout

Log messages to standard output

--log-fileno

Include file and line number with the log messages

--log-filter

Filter the logs by a particular set of files, e.g: sstp-packet,sstp-state

--log-ident

Specify the identity that will be used when writing logs to e.g. syslog

## EXAMPLES
Connection to a Microsoft Windows RAS Service using SSTP protocol

Setup the peer scripts in /etc/ppp/peers, you may start by cloning one of the scripts available in your docs directory, /usr/share/doc/sstp-client, or /usr/local/share/doc/sstp-client. The general content of this file will be close to the following:

\# Example Content of /etc/ppp/peers/sstp-test

remotename sstp-test

linkname sstp-test

ipparam sstp-test

pty "sstpc --ipparam sstp-test --nolaunchpppd sstp-test.yourdomain.com"

name eivnaes

plugin sstp-pppd-plugin.so

sstp-sock /var/run/sstpc/sstpc-sstp-test

usepeerdns

require-mppe

require-mschap-v2

refuse-eap

refuse-pap

refuse-chap

refuse-mschap

nobsdcomp

nodeflate

Note that the chap-secrets file used by pppd must include an entry for domain\\username. For the sstp-test example, the user eivnaes will have a equivalent entry in the /etc/ppp/chap-secrets file.

\# Secrets for authentication using CHAP

\# client server secret IP addresses

eivnaes * xxxxxx *

Starting the sstp-test using the pon script

sudo pon sstp-test

Invoking sstpc using the the call command

sstpc --ipparam sstp-test sstp-test.yourdomain.com call sstp-test-nopty

The sstp-test-nopty is a pppd script you need to create in /etc/ppp/peers, and you can clone the example sstp-test above; but you must omit the pty statement in the peers configuration.

## SEE ALSO
pppd(8)

## AUTHOR
This manual page was written by Eivind Naess <enaess@yahoo.com>


stalld

package: stalld

title: stalld(8)

summary: detect starving threads and boost them

text:
# stalld(8)

## NAME
stalld - detect starving threads and boost them

## SYNOPSIS
stalld [ -l ] [ -v ] [ -k ] [ -s ] [ -f ] [ -h ] [ -c cpu-list] [ -p time-in-ns ] [ -r time-in-ns ] [ -d time-in-sec ] [ -t time-in-sec ] [ -i regexes-of-thread-names ] [ -I regexes-of-process-names ] [ -R percentage ] [ -a cpu-list ]

## DESCRIPTION
stalld is a system daemon that monitors thread for the starvation condition. Starvation occurs when a thread sits on a cpu run-queue for longer than the starvation-threshold, meaning the thread has not been allowed to run for threshold seconds. The thread is boosted using the SCHED_DEADLINE policy and given a time period to run. Once it uses this boost period, the thread is returned to its original scheduling policy.

## OPTIONS
-t|--starving_threshold

how long (in seconds) a thread must starve before being boosted [60 s]

-p|--boost_period

SCHED_DEADLINE period in nanoseconds for a starving thread [1000000000 ns]

-r|--boost_runtime

SCHED_DEADLINE runtime in nanoseconds for a starving thread [20000 ns]

-d|--boost_duration

duration in seconds the starving thread will run [ 3 s]

-F|--force_fifo

force using SCHED_FIFO for boosting

-l|--log_only

only log information, do no boosting [false]

-v|--verbose

print action informtion to stdout [false]

-k|--log_kmsg

log information to the kernel buffer [false]

-s|--log_syslog

print information to syslog [true]

-f|--foreground

run in the foreground [false (true with -v)]

-P|--pidfile

write daemon pid to specified file [none]

-A|--aggressive_mode

dispatch one thread per cpu run-queue, even if thre are no starving threads (uses more power). [false]

-O|--power_mode

run as a single threaded program, it consumes less CPU, at the price of less precision/granularity. [false]

-M|--adaptive_mode

when a CPU shows threads starving for more than half of the starving_threshold time, dispatch a specialized thread to monitor it. [false]

-g|--granularity

set the granularity (in seconds) at which stalld checks for starving threads. The lower the value the more precise will be the detection, at the price of consuming more CPU time. [5 seconds]

-R|--reservation

set the percentage of CPU time reserved for stalld via SCHED_DEADLINE. In this way, stalld cannot starve due to high priority threads, also avoid indirect starvation via priority inversion. [not set]

-a|--affinity

set the stalld's affinity to the set of cpus in cpu-list.

-i|--ignore_threads

regexes (comma-separated) of thread names that must be ignored from being boosted

-I|--ignore_processes

regexes (comma-separated) of process names that must be ignored from being boosted

-b|--backend

selects the backend to search for starving tasks, options are: sched_debug || S: for sched/debug file (default option).

queue_track || Q: for tracking enqueue/dequeue of tasks in the runqueues.

-h|--help

print options

## FILES
/etc/systemd/stalld.conf

parameter file for systemd startup

/usr/lib/systemd/system/stalld.service

systemd unit file

/usr/bin/stalld

stalld executable

## BUGS
none

## AUTHOR
Daniel Bristot de Oliveira (bristot@redhat.com) Juri Lelli (juri.lelli@redhat.com)


state-change-notify

package: state-change-notify

title: state-change-notify(8)

text:
# state-change-notify(8)

## NAME
state-change-notify - system state transition notification service

## SYNOPSIS
state-change-notify HANDLER STATE

## DESCRIPTION
state-change-notify should be called when a system state transition is in progress. It is a wrapper script that performes the common procedures: determines the particular state change event and define message draft. It then calls the actual handler as follows:

```
/etc/state-change-notify/actions.d/<handler> STATE SUBJECT MESSAGE
```

In order to determine the actual system state systemctl(1) currently is used.

## CONFIGURATION
/etc/state-change-notify is the main configuration directory with (currently empty) main configuration file main.conf. There are also configuration files for the notification handlers, for instance, mail.conf (state-change-notify-mail(5)) for the E-Mail notification handler (such as state-change-notify-postfix(8)).

The handlers are placed in the actions.d directory. See the state-change-notify-mail(8) handler for example.

## ENVIRONMENT
Each notification handler is called with the following set of environment variables:

○

CONFIG -- the main configuration file, normally /etc/state-change-notify/main.conf;

○

CONFDIR -- the configuration directory path, normally /etc/state-change-notify;

○

ACTIONDIR -- the handlers directory path, normally /etc/state-change-notify/actions.d;

○

HANDLER -- the handler path: /etc/state-change-notify/actions.d/<handler>;

○

STATE -- the name of the event (´reboot´, ´shutdown´, etc.);

○

SUBJECT -- the draft message subject the handler can use as is for most of the cases;

○

MESSAGE -- the draft message body the handler can use as is for most of the cases.

## SEE ALSO
state-change-notify-postfix(8), state-change-notify-mail(8), state-change-notify-mail(5), systemd(8)


state-change-notify-mail

package: state-change-notify-mail

title: state-change-notify-mail(8)

text:
# state-change-notify-mail(8)

## NAME
state-change-notify-mail - system state transition email notification handler

## SYNOPSIS
/etc/state-change-notify/actions.d/mail STATE SUBJECT MESSAGE

## DESCRIPTION
The mail notification handler uses mail(1) command to send notifications about system state transitions by E-Mail.

## ENVIRONMENT
The handler depend on the following environment variables normally defined by state-change-notify(8) wrapper script:

○

CONFDIR -- the configuration directory path, normally /etc/state-change-notify.

## CONFIGURATION
The notification handler uses CONFGIR/mail.conf configuration file that is normally correspond to /etc/state-change-notify/mail.conf. The configuration parameters are described there in-place and also in state-change-notify-mail(5) manpage.

## SEE ALSO
state-change-notify(8), state-change-notify-mail(5), state-change-notify-postfix(8), mail(1)


state-change-notify-postfix

package: state-change-notify-postfix

title: state-change-notify-postfix(8)

text:
# state-change-notify-postfix(8)

## NAME
state-change-notify-postfix - system state transition email notification service which uses Postfix

## SYNOPSIS
state-change-notify-postfix.service

## DESCRIPTION
state-change-notify-postfix.service is a systemd(8) unit that reacts to system state changes such as initialization, reboot, sleep or shutdown. When such transition is in progress, network connectivity is present and the postfix.service is active the service invokes the mail handler (state-change-notify-mail(5)) to send notifications about the event.

## SEE ALSO
state-change-notify(8), state-change-notify-mail(8), state-change-notify-mail(5), systemd(8)


stmpclean

package: stmpclean

title: stmpclean(8)

text:
# stmpclean(8)

## NAME
stmpclean — remove old files from a world-writable directory

## SYNOPSIS
stmpclean

[-t<timespec>] [-v] dir1 [dir2 ...]

## DESCRIPTION
The stmpclean utility removes old files (and old empty directories) from the specified directory. It'll be typically used to clean directories such as ``/tmp'' where old files tend to accumulate.

The stmpclean utility never removes files or directories owned by root. It is a feature, not a bug. Great care is taken while descending into the directory, and the operation is secure. Anything that's not a directory, regular file, or symbolic link is also left alone (because programs like screen(1) create sockets and FIFOs under /tmp and expect them to be long-lived; we accomodate this practice). Unlike floating around Perl scripts that do the same task stmpclean never forks and consumes limited amount of memory (these Perl scripts easily turn into forking bombs when someone creates a lot a directories under ``/tmp''). If your system is attacked and the attacker creates an extremely deep file hierarchy, stmpclean won't add to the problem by crashing your system trying to remove it. But it won't help you in fighting the attack, either, because it descends only to a limited depth (currently, 30 levels). If stmpclean determines a race condition it'll log the situation (you can look for the word ``RACE'' in log files) and exit with a failure.

So, stmpclean will clean temporary directories for you fine when there are no attacks, and, when there is an attack, stmpclean won't make the situation worse (in particular, it cannot be tricked into removing files outside specified directories or consume unlimited amount of resources).

The following option is available:

-t<timespec>

The time specification that follows the -t flag specifies how old a file or a directory has to be before it will be removed. It can be a string like `1w' (one week) or `4d5h' (four days plus five hours) or `2m3s' (two minutes plus three seconds). The default is `3d' (three days).

-v

Be verbose: list each file deleted.

The stmpclean utility exits 0 on success, and >0 if an error occurs.

## EXAMPLES
The stmpclean utility will typically be run nightly from cron(8) as

stmpclean /tmp /var/tmp

In FreeBSD stmpclean invocation should be placed into the file /etc/periodic/daily/110.clean-tmps. In other versions of BSD it should go into the /etc/daily script. On LSB-compliant Linux distributions, the invocation of stmpclean may be placed in a script under /etc/cron.daily.

## SEE ALSO
cron(8)

## BUGS
When stmpclean scans a directory, access time of the directory changes and it looks new to stmpclean when it examines it later (if the directory became empty). Thus, removing a deep hierarchy can take some time. Notice that this only delays removal of some empty directories.


stow

package: stow

title: stow(8)

summary: manage farms of symbolic links

text:
# stow(8)

## NAME
stow - manage farms of symbolic links

## SYNOPSIS
stow [ options ] package ...

## DESCRIPTION
This manual page describes GNU Stow 2.4.1. This is not the definitive documentation for Stow; for that, see the accompanying info manual, e.g. by typing "info stow".

Stow is a symlink farm manager which takes distinct sets of software and/or data located in separate directories on the filesystem, and makes them all appear to be installed in a single directory tree.

Originally Stow was born to address the need to administer, upgrade, install, and remove files in independent software packages without confusing them with other files sharing the same file system space. For instance, many years ago it used to be common to compile programs such as Perl and Emacs from source. By using Stow, /usr/local/bin could contain symlinks to files within /usr/local/stow/emacs/bin, /usr/local/stow/perl/bin etc., and likewise recursively for any other subdirectories such as .../share, .../man, and so on.

While this is useful for keeping track of system-wide and per-user installations of software built from source, in more recent times software packages are often managed by more sophisticated package management software such as rpm, dpkg, and Nix / GNU Guix, or language-native package managers such as Ruby's gem, Python's pip, Javascript's npm, and so on.

However Stow is still used not only for software package management, but also for other purposes, such as facilitating a more controlled approach to management of configuration files in the user's home directory, especially when coupled with version control systems.

Stow was inspired by Carnegie Mellon's Depot program, but is substantially simpler and safer. Whereas Depot required database files to keep things in sync, Stow stores no extra state between runs, so there's no danger (as there was in Depot) of mangling directories when file hierarchies don't match the database. Also unlike Depot, Stow will never delete any files, directories, or links that appear in a Stow directory (e.g., /usr/local/stow/emacs), so it's always possible to rebuild the target tree (e.g., /usr/local).

Stow is implemented as a combination of a Perl script providing a CLI interface, and a backend Perl module which does most of the work.

## TERMINOLOGY
A "package" is a related collection of files and directories that you wish to administer as a unit -- e.g., Perl or Emacs -- and that needs to be installed in a particular directory structure -- e.g., with bin, lib, and man subdirectories.

A "target directory" is the root of a tree in which one or more packages wish to appear to be installed. A common, but by no means the only such location is /usr/local. The examples in this manual page will use /usr/local as the target directory.

A "stow directory" is the root of a tree containing separate packages in private subtrees. When Stow runs, it uses the current directory as the default stow directory. The examples in this manual page will use /usr/local/stow as the stow directory, so that individual packages will be, for example, /usr/local/stow/perl and /usr/local/stow/emacs.

An "installation image" is the layout of files and directories required by a package, relative to the target directory. Thus, the installation image for Perl includes: a bin directory containing perl and a2p (among others); an info directory containing Texinfo documentation; a lib/perl directory containing Perl libraries; and a man/man1 directory containing man pages.

A "package directory" is the root of a tree containing the installation image for a particular package. Each package directory must reside in a stow directory -- e.g., the package directory /usr/local/stow/perl must reside in the stow directory /usr/local/stow. The "name" of a package is the name of its directory within the stow directory -- e.g., perl.

Thus, the Perl executable might reside in /usr/local/stow/perl/bin/perl, where /usr/local is the target directory, /usr/local/stow is the stow directory, /usr/local/stow/perl is the package directory, and bin/perl within is part of the installation image.

A "symlink" is a symbolic link. A symlink can be "relative" or "absolute". An absolute symlink names a full path; that is, one starting from /. A relative symlink names a relative path; that is, one not starting from /. The target of a relative symlink is computed starting from the symlink's own directory. Stow only creates relative symlinks.

## OPTIONS
The stow directory is assumed to be the value of the "STOW_DIR" environment variable or if unset the current directory, and the target directory is assumed to be the parent of the current directory (so it is typical to execute stow from the directory /usr/local/stow). Each package given on the command line is the name of a package in the stow directory (e.g., perl). By default, they are installed into the target directory (but they can be deleted instead using "-D").

-n

--no

--simulate

Do not perform any operations that modify the filesystem; merely show what would happen.

-d DIR

--dir=DIR

Set the stow directory to "DIR" instead of the current directory. This also has the effect of making the default target directory be the parent of "DIR".

-t DIR

--target=DIR

Set the target directory to "DIR" instead of the parent of the stow directory.

-v

--verbose[=N]

Send verbose output to standard error describing what Stow is doing. Verbosity levels are from 0 to 5; 0 is the default. Using "-v" or "--verbose" increases the verbosity by one; using `--verbose=N' sets it to N.

-S

--stow

Stow the packages that follow this option into the target directory. This is the default action and so can be omitted if you are only stowing packages rather than performing a mixture of stow/delete/restow actions.

-D

--delete

Unstow the packages that follow this option from the target directory rather than installing them.

-R

--restow

Restow packages (first unstow, then stow again). This is useful for pruning obsolete symlinks from the target tree after updating the software in a package.

--adopt

Warning! This behaviour is specifically intended to alter the contents of your stow directory. If you do not want that, this option is not for you. When stowing, if a target is encountered which already exists but is a plain file (and hence not owned by any existing stow package), then normally Stow will register this as a conflict and refuse to proceed. This option changes that behaviour so that the file is moved to the same relative place within the package's installation image within the stow directory, and then stowing proceeds as before. So effectively, the file becomes adopted by the stow package, without its contents changing.

--no-folding

Disable folding of newly stowed directories when stowing, and refolding of newly foldable directories when unstowing.

--ignore=REGEX

Ignore files ending in this Perl regex.

--defer=REGEX

Don't stow files beginning with this Perl regex if the file is already stowed to another package.

--override=REGEX

Force stowing files beginning with this Perl regex if the file is already stowed to another package.

--dotfiles

Enable special handling for "dotfiles" (files or folders whose name begins with a period) in the package directory. If this option is enabled, Stow will add a preprocessing step for each file or folder whose name begins with "dot-", and replace the "dot-" prefix in the name by a period (.). This is useful when Stow is used to manage collections of dotfiles, to avoid having a package directory full of hidden files. For example, suppose we have a package containing two files, stow/dot-bashrc and stow/dot-emacs.d/init.el. With this option, Stow will create symlinks from .bashrc to stow/dot-bashrc and from .emacs.d/init.el to stow/dot-emacs.d/init.el. Any other files, whose name does not begin with "dot-", will be processed as usual.

-V

--version

Show Stow version number, and exit.

-h

--help

Show Stow command syntax, and exit.

## INSTALLING PACKAGES
The default action of Stow is to install a package. This means creating symlinks in the target tree that point into the package tree. Stow attempts to do this with as few symlinks as possible; in other words, if Stow can create a single symlink that points to an entire subtree within the package tree, it will choose to do that rather than create a directory in the target tree and populate it with symlinks.

For example, suppose that no packages have yet been installed in /usr/local; it's completely empty (except for the stow subdirectory, of course). Now suppose the Perl package is installed. Recall that it includes the following directories in its installation image: bin; info; lib/perl; man/man1. Rather than creating the directory /usr/local/bin and populating it with symlinks to ../stow/perl/bin/perl and ../stow/perl/bin/a2p (and so on), Stow will create a single symlink, /usr/local/bin, which points to stow/perl/bin. In this way, it still works to refer to /usr/local/bin/perl and /usr/local/bin/a2p, and fewer symlinks have been created. This is called "tree folding", since an entire subtree is "folded" into a single symlink.

To complete this example, Stow will also create the symlink /usr/local/info pointing to stow/perl/info; the symlink /usr/local/lib pointing to stow/perl/lib; and the symlink /usr/local/man pointing to stow/perl/man.

Now suppose that instead of installing the Perl package into an empty target tree, the target tree is not empty to begin with. Instead, it contains several files and directories installed under a different system-administration philosophy. In particular, /usr/local/bin already exists and is a directory, as are /usr/local/lib and /usr/local/man/man1. In this case, Stow will descend into /usr/local/bin and create symlinks to ../stow/perl/bin/perl and ../stow/perl/bin/a2p (etc.), and it will descend into /usr/local/lib and create the tree-folding symlink perl pointing to ../stow/perl/lib/perl, and so on. As a rule, Stow only descends as far as necessary into the target tree when it can create a tree-folding symlink.

The time often comes when a tree-folding symlink has to be undone because another package uses one or more of the folded subdirectories in its installation image. This operation is called "splitting open" a folded tree. It involves removing the original symlink from the target tree, creating a true directory in its place, and then populating the new directory with symlinks to the newly-installed package and to the old package that used the old symlink. For example, suppose that after installing Perl into an empty /usr/local, we wish to install Emacs. Emacs's installation image includes a bin directory containing the emacs and etags executables, among others. Stow must make these files appear to be installed in /usr/local/bin, but presently /usr/local/bin is a symlink to stow/perl/bin. Stow therefore takes the following steps: the symlink /usr/local/bin is deleted; the directory /usr/local/bin is created; links are made from /usr/local/bin to ../stow/emacs/bin/emacs and ../stow/emacs/bin/etags; and links are made from /usr/local/bin to ../stow/perl/bin/perl and ../stow/perl/bin/a2p.

When splitting open a folded tree, Stow makes sure that the symlink it is about to remove points inside a valid package in the current stow directory.

### Stow will never delete anything that it doesn't own.
Stow "owns" everything living in the target tree that points into a package in the stow directory. Anything Stow owns, it can recompute if lost. Note that by this definition, Stow doesn't "own" anything in the stow directory or in any of the packages.

If Stow needs to create a directory or a symlink in the target tree and it cannot because that name is already in use and is not owned by Stow, then a conflict has arisen. See the "Conflicts" section in the info manual.

## DELETING PACKAGES
When the "-D" option is given, the action of Stow is to delete a package from the target tree. Note that Stow will not delete anything it doesn't "own". Deleting a package does not mean removing it from the stow directory or discarding the package tree.

To delete a package, Stow recursively scans the target tree, skipping over the stow directory (since that is usually a subdirectory of the target tree) and any other stow directories it encounters (see "Multiple stow directories" in the info manual). Any symlink it finds that points into the package being deleted is removed. Any directory that contained only symlinks to the package being deleted is removed. Any directory that, after removing symlinks and empty subdirectories, contains only symlinks to a single other package, is considered to be a previously "folded" tree that was "split open." Stow will re-fold the tree by removing the symlinks to the surviving package, removing the directory, then linking the directory back to the surviving package.

## RESOURCE FILES
Stow searches for default command line options at .stowrc (current directory) and ~/.stowrc (home directory) in that order. If both locations are present, the files are effectively appended together.

The effect of options in the resource file is similar to simply prepending the options to the command line. For options that provide a single value, such as --target or --dir, the command line option will overwrite any options in the resource file. For options that can be given more than once, --ignore for example, command line options and resource options are appended together.

Environment variables and the tilde character (~) will be expanded for options that take a file path.

The options -D, -R, -S, and any packages listed in the resource file are ignored.

See the info manual for more information on how stow handles resource file.

## SEE ALSO
The full documentation for stow is maintained as a Texinfo manual. If the info and stow programs are properly installed at your site, the command

```
    info stow
```

should give you access to the complete manual.

## BUGS
Please report bugs in Stow using the Debian bug tracking system.

Currently known bugs include:

- The empty-directory problem. If package foo includes an empty directory -- say, foo/bar -- then if no other package has a bar subdirectory, everything's fine. If another stowed package quux, has a bar subdirectory, then when stowing, targetdir/bar will be "split open" and the contents of quux/bar will be individually stowed. So far, so good. But when unstowing quux, targetdir/bar will be removed, even though foo/bar needs it to remain. A workaround for this problem is to create a file in foo/bar as a placeholder. If you name that file .placeholder, it will be easy to find and remove such files when this bug is fixed.

- When using multiple stow directories (see "Multiple stow directories" in the info manual), Stow fails to "split open" tree-folding symlinks (see "Installing packages" in the info manual) that point into a stow directory which is not the one in use by the current Stow command. Before failing, it should search the target of the link to see whether any element of the path contains a .stow file. If it finds one, it can "learn" about the cooperating stow directory to short-circuit the .stow search the next time it encounters a tree-folding symlink.

## AUTHOR
This man page was originally constructed by Charles Briscoe-Smith from parts of Stow's info manual, and then converted to POD format by Adam Spiers. The info manual contains the following notice, which, as it says, applies to this manual page, too. The text of the section entitled "GNU General Public License" can be found in the file /usr/share/common-licenses/GPL on any Debian GNU/Linux system. If you don't have access to a Debian system, or the GPL is not there, write to the Free Software Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA, 02111-1307, USA.

## COPYRIGHT
Copyright (C) 1993, 1994, 1995, 1996 by Bob Glickstein <bobg+stow@zanshin.com>; 2000, 2001 by Guillaume Morin; 2007 by Kahlil Hodgson; 2011 by Adam Spiers; and others.

Permission is granted to make and distribute verbatim copies of this manual provided the copyright notice and this permission notice are preserved on all copies.

Permission is granted to copy and distribute modified versions of this manual under the conditions for verbatim copying, provided also that the section entitled "GNU General Public License" is included with the modified manual, and provided that the entire resulting derived work is distributed under the terms of a permission notice identical to this one.

Permission is granted to copy and distribute translations of this manual into another language, under the above conditions for modified versions, except that this permission notice may be stated in a translation approved by the Free Software Foundation.


strongswan

package: strongswan

title: strongswan(8)

summary: invoke IPsec utilities

text:
# strongswan(8)

## NAME
strongswan - invoke IPsec utilities

## SYNOPSIS
strongswan

command [arguments] [options]

## DESCRIPTION
The strongswan utility invokes any of several utilities involved in controlling and monitoring the IPsec encryption/authentication system, running the specified command with the specified arguments and options as if it had been invoked directly. This largely eliminates possible name collisions with other software, and also permits some centralized services.

All the commands described in this manual page are built-in and are used to control and monitor IPsec connections as well as the IKE daemon.

For other commands strongswan supplies the invoked command with a suitable PATH environment variable, and also provides the environment variables listed under ENVIRONMENT.

### CONTROL COMMANDS
start [starter options]

calls starter which in turn parses ipsec.conf and starts the IKE daemon charon.

update

sends a HUP signal to starter which in turn determines any changes in ipsec.conf and updates the configuration on the running IKE daemon charon.

reload

sends a USR1 signal to starter which in turn reloads the whole configuration of the running IKE daemon charon based on the actual ipsec.conf.

restart

is equivalent to stop followed by start after a guard of 2 seconds.

stop

terminates all IPsec connections and stops the IKE daemon charon by sending a TERM signal to starter.

up name

tells the IKE daemon to start up connection name.

down name

tells the IKE daemon to terminate connection name.

down name{n}

terminates IKEv1 Quick Mode and IKEv2 CHILD SA instance n of connection name.

down name{*}

terminates all IKEv1 Quick Mode and IKEv2 CHILD SA instances of connection name.

down name[n]

terminates IKE SA instance n of connection name.

down name[*]

terminates all IKE SA instances of connection name.

down-srcip <start> [<end>]

terminates all IKE SA instances with clients having virtual IPs in the range start-end.

route name

tells the IKE daemon to insert an IPsec policy in the kernel for connection name. The first payload packet matching the IPsec policy will automatically trigger an IKE connection setup.

unroute name

remove the IPsec policy in the kernel for connection name.

status [name]

returns concise status information either on connection name or if the argument is lacking, on all connections.

statusall [name]

returns detailed status information either on connection name or if the argument is lacking, on all connections.

### LIST COMMANDS
leases [<poolname> [<address>]]

returns the status of all or the selected IP address pool (or even a single virtual IP address).

listalgs

returns a list supported cryptographic algorithms usable for IKE, and their corresponding plugin.

listpubkeys [--utc]

returns a list of RSA public keys that were either loaded in raw key format or extracted from X.509 and|or OpenPGP certificates.

listcerts [--utc]

returns a list of X.509 and|or OpenPGP certificates that were either loaded locally by the IKE daemon or received via the IKE protocol.

listcacerts [--utc]

returns a list of X.509 Certification Authority (CA) certificates that were loaded locally by the IKE daemon from the /etc/strongswan/ipsec.d/cacerts/ directory or received via the IKE protocol.

listaacerts [--utc]

returns a list of X.509 Authorization Authority (AA) certificates that were loaded locally by the IKE daemon from the /etc/strongswan/ipsec.d/aacerts/ directory.

listocspcerts [--utc]

returns a list of X.509 OCSP Signer certificates that were either loaded locally by the IKE daemon from the /etc/strongswan/ipsec.d/ocspcerts/ directory or were sent by an OCSP server.

listacerts [--utc]

returns a list of X.509 Attribute certificates that were loaded locally by the IKE daemon from the /etc/strongswan/ipsec.d/acerts/ directory.

listgroups [--utc]

returns a list of groups that are used to define user authorization profiles.

listcainfos [--utc]

returns certification authority information (CRL distribution points, OCSP URIs, LDAP servers) that were defined by ca sections in ipsec.conf.

listcrls [--utc]

returns a list of Certificate Revocation Lists (CRLs) that were either loaded by the IKE daemon from the /etc/strongswan/ipsec.d/crls directory or fetched from an HTTP- or LDAP-based CRL distribution point.

listocsp [--utc]

returns revocation information fetched from OCSP servers.

listplugins

returns a list of all loaded plugin features.

listcounters [name]

returns a list of global or connection specific IKE counter values collected since daemon startup.

listall [--utc]

returns all information generated by the list commands above. Each list command can be called with the --utc option which displays all dates in UTC instead of local time.

### REREAD COMMANDS
rereadsecrets

flushes and rereads all secrets defined in ipsec.secrets.

rereadcacerts

removes previously loaded CA certificates, reads all certificate files contained in the /etc/strongswan/ipsec.d/cacerts directory and adds them to the list of Certification Authority (CA) certificates. This does not affect certificates explicitly defined in a ipsec.conf(5) ca section, which may be separately updated using the update command.

rereadaacerts

removes previously loaded AA certificates, reads all certificate files contained in the /etc/strongswan/ipsec.d/aacerts directory and adds them to the list of Authorization Authority (AA) certificates.

rereadocspcerts

reads all certificate files contained in the /etc/strongswan/ipsec.d/ocspcerts/ directory and adds them to the list of OCSP signer certificates.

rereadacerts

reads all certificate files contained in the /etc/strongswan/ipsec.d/acerts/ directory and adds them to the list of attribute certificates.

rereadcrls

reads all Certificate Revocation Lists (CRLs) contained in the /etc/strongswan/ipsec.d/crls/ directory and adds them to the list of CRLs.

rereadall

executes all reread commands listed above.

### RESET COMMANDS
resetcounters [name]

resets global or connection specific counters.

### PURGE COMMANDS
purgecerts

purges all cached certificates.

purgecrls

purges all cached CRLs.

purgeike

purges IKE SAs that don't have a Quick Mode or CHILD SA.

purgeocsp

purges all cached OCSP information records.

### INFO COMMANDS
--help

returns the usage information for the strongswan command.

--version

returns the version in the form of strongSwan U<strongSwan userland version>/K<kernel version>.

--versioncode

returns the version number in the form of U<strongSwan userland version>/K<kernel version>.

--copyright

returns the copyright information.

--directory

returns the LIBEXECDIR directory as defined by the configure options.

--confdir

returns the SYSCONFDIR directory as defined by the configure options.

--piddir

returns the PIDDIR directory as defined by the configure options.

## FILES
/usr/libexec/strongswan utilities directory

## ENVIRONMENT
When calling other commands the strongswan command supplies the following environment variables.

```
IPSEC_DIR               directory containing ipsec programs and utilities
IPSEC_BINDIR            directory containing pki command
IPSEC_SBINDIR           directory containing ipsec command
IPSEC_CONFDIR           directory containing configuration files
IPSEC_PIDDIR            directory containing PID/socket files
IPSEC_SCRIPT            name of the ipsec script
IPSEC_NAME              name of ipsec distribution
IPSEC_VERSION           version number of ipsec userland and kernel
IPSEC_STARTER_PID       PID file for ipsec starter
IPSEC_CHARON_PID        PID file for IKE keying daemon
```

## SEE ALSO
ipsec.conf(5), ipsec.secrets(5)

## HISTORY
Originally written for the FreeS/WAN project by Henry Spencer. Updated and extended for the strongSwan project <http://www.strongswan.org> by Tobias Brunner and Andreas Steffen.


title: strongswan_charon-cmd(8)

summary: Simple IKE client (IPsec VPN client)

text:
# strongswan_charon-cmd(8)

## NAME
charon-cmd - Simple IKE client (IPsec VPN client)

## SYNOPSIS
charon-cmd --host hostname --identity identity [ options ]

## DESCRIPTION
charon-cmd is a program for setting up IPsec VPN connections using the Internet Key Exchange protocol (IKE) in version 1 and 2. It supports a number of different road-warrior scenarios.

Like the IKE daemon charon, charon-cmd has to be run as root (or more specifically as a user with CAP_NET_ADMIN capability).

Of the following options at least --host and --identity are required. Depending on the selected authentication profile credentials also have to be provided with their respective options.

Many of the charon-specific configuration options in strongswan.conf also apply to charon-cmd. For instance, to configure customized logging to stdout the following snippet can be used:

```
	charon-cmd {
		filelog {
			stdout {
				default = 1
				ike = 2
				cfg = 2
			}
		}
	}
```

## OPTIONS
--help

Prints usage information and a short summary of the available options.

--version

Prints the strongSwan version.

--debug level

Sets the default log level (defaults to 1). level is a number between -1 and 4. Refer to strongswan.conf for options that allow a more fine-grained configuration of the logging output.

--host hostname

DNS name or IP address to connect to.

--identity identity

Identity the client uses for the IKE exchange.

--eap-identity identity

Identity the client uses for EAP authentication.

--xauth-username username

Username the client uses for XAuth authentication.

--remote-identity identity

Server identity to expect, defaults to hostname.

--cert path

Trusted certificate, either for authentication or trust chain validation. To provide more than one certificate multiple --cert options can be used.

--rsa path

RSA private key to use for authentication (if a password is required, it will be requested on demand). For other key types use --priv.

--priv path

Private key to use for authentication (if a password is required, it will be requested on demand).

--p12 path

PKCS#12 file with private key and certificates to use for authentication and trust chain validation (if a password is required it will be requested on demand).

--agent[=socket]

Use SSH agent for authentication. If socket is not specified it is read from the SSH_AUTH_SOCK environment variable.

--local-ts subnet

Additional traffic selector to propose for our side, the requested virtual IP address will always be proposed.

--remote-ts subnet

Traffic selector to propose for remote side, defaults to 0.0.0.0/0.

--ike-proposal proposal

IKE proposal to offer instead of default. For IKEv1, a single proposal consists of one encryption algorithm, an integrity/PRF algorithm and a DH group. IKEv2 can propose multiple algorithms of the same kind. To specify multiple proposals, repeat the option.

--esp-proposal proposal

ESP proposal to offer instead of default. For IKEv1, a single proposal consists of one encryption algorithm, an integrity algorithm and an optional DH group for Perfect Forward Secrecy rekeying. IKEv2 can propose multiple algorithms of the same kind. To specify multiple proposals, repeat the option.

--ah-proposal proposal

AH proposal to offer instead of ESP. For IKEv1, a single proposal consists of an integrity algorithm and an optional DH group for Perfect Forward Secrecy rekeying. IKEv2 can propose multiple algorithms of the same kind. To specify multiple proposals, repeat the option.

--profile name

Authentication profile to use, the list of supported profiles can be found in the Authentication Profiles sections below. Defaults to ikev2-pub if a private key was supplied, and to ikev2-eap otherwise.

### IKEv2 Authentication Profiles
ikev2-pub

IKEv2 with public key client and server authentication

ikev2-eap

IKEv2 with EAP client authentication and public key server authentication

ikev2-pub-eap

IKEv2 with public key and EAP client authentication (RFC 4739) and public key server authentication

### IKEv1 Authentication Profiles
The following authentication profiles use either Main Mode or Aggressive Mode, the latter is denoted with a -am suffix.

ikev1-pub, ikev1-pub-am

IKEv1 with public key client and server authentication

ikev1-xauth, ikev1-xauth-am

IKEv1 with public key client and server authentication, followed by client XAuth authentication

ikev1-xauth-psk, ikev1-xauth-psk-am

IKEv1 with pre-shared key (PSK) client and server authentication, followed by client XAuth authentication (INSECURE!)

ikev1-hybrid, ikev1-hybrid-am

IKEv1 with public key server authentication only, followed by client XAuth authentication

## SEE ALSO
strongswan.conf(5), ipsec(8)


title: strongswan_sec-updater(8)

text:
# strongswan_sec-updater(8)

## NAME
sec-updater - Extracts security update information of Linux distributions

## SYNOPSIS
sec-updater

[--debug level] [--quiet] [--security] --os string --arch string --uri uri --file filename

sec-updater

-h | --help

## DESCRIPTION
sec-updater extracts information about security updates and backports of Linux repositories (e.g. Debian or Ubuntu). This information is used to update the package version information stored in the strongTNC SQLite database. The "dbkg --compare-versions" command is used to determine which package versions are affected by a given security update.

## OPTIONS
-h, --help

Prints usage information and a short summary of the available commands.

-v, --debug level

Set debug level, default: 1.

-q, --quiet

Disable debug output to stderr.

-s, --security

Set when parsing a distributions file with security updates.

-o, --os string

Name of operating system (OS). eg. "Ubuntu 16.04".

-o, --arch string

Name of HW architecture. eg. "x86_64".

-o, --uri uri

URI where to download deb package from.

-f, --file filename

Linux package information file to parse.

## CONFIGURATION
The following parameters can be configured in strongswan.conf:

sec-updater {

database = sqlite:///etc/pts/config.db

swid_gen {

command = /usr/local/bin/swid_generator

tag_creator {

name = strongSwan Project

regid = strongswan.org

}

}

tnc_manage_command = /var/www/tnc/manage.py

tmp {

deb_file = /tmp/sec-updater.deb

tag_file = /tmp/sec-updater.tag

}

}

## SEE ALSO
strongswan.conf(5)


title: strongswan_sw-collector(8)

text:
# strongswan_sw-collector(8)

## NAME
sw-collector - Extracts software installation events from dpkg history log

## SYNOPSIS
sw-collector

[--debug level] [--quiet] [--count event-count]

sw-collector

[--debug level] [--quiet] [--installed|--removed] --list|--unregistered

sw-collector

[--debug level] [--quiet] [--installed|--removed] [--full] --generate

sw-collector

[--debug level] [--quiet] --migrate

sw-collector

[--debug level] [--quiet] --check

sw-collector

-h | --help

## DESCRIPTION
sw-collector extracts information about software package installation, update or removal events from the apt history log and stores the software events in an SQLite database. The retrieved history information is then merged and made consistent with the actual list of installed software packages obtained with dpkg-query.

## OPTIONS
-h, --help

Prints usage information and a short summary of the available commands.

-v, --debug level

Set debug level, default: 2.

-q, --quiet

Disable debug output to stderr.

-i, --installed

Apply command to installed software packages, only.

-r, --removed

Apply command to removed software packages, only.

-f, --full

Generate ISO 19770-2:2015 SWID tags with full file information (possible for installed software packages, only).

-l, --list

Lists all software packages stored in the collector database showing their installation status.

-u, --unregistered

Lists all software packages residing in the local collector database but for which no SWID tags exist yet in a central collector database reachable via a REST interface.

-g, --generate

Generates ISO 19770-2:2015 SWID tags for all software packages residing in the local collector database but for which no SWID tags exist in a central collector database reachable via a REST interface.

-m, --migrate

Can be used to migrate collector database versions. Currently all architecture suffixes are removed from dpkg package names.

-C, --check

Checks the integrity of the collector database against the actual list of installed packages obtained with dpkg-query.

## CONFIGURATION
The following parameters can be configured in strongswan.conf:

sw-collector {

database = sqlite:///etc/pts/collector.db

history = /var/log/apt/history.log

first_time = 2016-04-22T20:55:14Z

rest_api {

uri = https://admin-user:ietf99hackathon@tnc.strongswan.org/api/

timeout = 120

}

}

The parameters of the swid_generator used with the --generate command can be changed in the libimcv section of strongswan.conf:

libimcv {

swid_gen {

command = /usr/local/bin/swid_generator

tag_creator {

name = strongSwan Project

regid = strongswan.org

}

}

}

## FILES
@PKGDATADIR@/templates/database/sw-collector/sw_collector_tables.sql

## SEE ALSO
strongswan.conf(5)


title: strongswan_swanctl(8)

text:
# strongswan_swanctl(8)

## NAME
swanctl - strongSwan configuration, control and monitoring command line interface.

## SYNOPSIS
swanctl

command [option ...]

swanctl

-h | --help

## DESCRIPTION
swanctl is a cross-platform command line utility to configure, control and monitor the strongSwan IKE daemon. It is a replacement for the aging starter, ipsec and stroke tools.

swanctl uses a configuration file called swanctl.conf(5) to parse configurations and credentials. Private keys, certificates and other PKI related credentials are read from specific directories.

To communicate with the IKE daemon, swanctl uses the VICI protocol, the Versatile IKE Configuration Interface. This stable interface is usable by other tools and is often preferable than scripting swanctl and parsing its output.

## COMMANDS
-i, --initiate

initiate a connection

-t, --terminate

terminate a connection

-R, --rekey

rekey an SA

-d, --redirect

redirect an IKE_SA

-p, --install

install a trap or shunt policy

-u, --uninstall

uninstall a trap or shunt policy

-l, --list-sas

list currently active IKE_SAs

-P, --list-pols

list currently installed policies

-b, --load-authorities

(re-)load certification authorities information

-L, --list-conns

list loaded configurations

-B, --list-authorities

list loaded certification authorities information

-x, --list-certs

list stored certificates

-A, --list-pools

list loaded pool configurations

-g, --list-algs

list loaded algorithms and their implementation

-q, --load-all

(re-)load credentials, pools, authorities and connections

-c, --load-conns

(re-)load connection configuration

-s, --load-creds

(re-)load credentials

-a, --load-pools

(re-)load pool configuration

-T, --log

trace logging output

-S, --stats

show daemon infos and statistics

-f, --flush-certs

flush cached certificates

-r, --reload-settings

reload strongswan.conf(5) configuration

-v, --version

show daemon version information

-h, --help

show usage information

## SEE ALSO
swanctl.conf(5)


stunnel

title: stunnel(8)

summary: TLS offloading and load\-balancing proxy

text:
# stunnel(8)

## NAME
stunnel - TLS offloading and load-balancing proxy

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

## DESCRIPTION
The stunnel program is designed to work as TLS encryption wrapper between remote clients and local (inetd-startable) or remote servers. The concept is that having non-TLS aware daemons running on your system you can easily set them up to communicate with clients over secure TLS channels.

stunnel can be used to add TLS functionality to commonly used Inetd daemons like POP-2, POP-3, and IMAP servers, to standalone daemons like NNTP, SMTP and HTTP, 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 specified configuration file

-fd N (Unix only)

Read the config file from specified file descriptor

-help

Print stunnel help menu

-version

Print stunnel version and compile time defaults

-sockets

Print default socket options

-options

Print supported TLS options

-install (Windows NT and later only)

Install NT Service

-uninstall (Windows NT and later only)

Uninstall 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 NT Service

-reopen (Windows NT and later only)

Reopen the log file of the running NT Service

-exit (Win32 only)

Exit an already started stunnel

-quiet (Win32 only)

Don't display any message boxes

## 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 a start of a service definition.

An address parameter of an option 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).

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

- 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, e.g. /dev/zero or /dev/null.

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.

The debug = debug (or the equivalent <debug = 7>) level produces for the most verbose log output. This logging level is only meant to be understood by stunnel developers, and not by users. Please either use the debug level when requested to do so by an stunnel developer, or when you intend to get confused.

The default logging level is notice (5).

The syslog 'authpriv' facility 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
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 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

```

CAengine = ENGINE-SPECIFIC_CA_CERTIFICATE_IDENTIFIER

load a trusted CA certificate from an engine The loaded CA certificates will be used with the verifyChain and verifyPeer options.

Multiple CAengine options are allowed in a single service section.

Currently supported engines: pkcs11, cng.

CApath = CA_DIRECTORY

load trusted CA certificates from a directory The loaded CA certificates will be used with the verifyChain and 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 or later.

CApath path is relative to the chroot directory if specified.

CAfile = CA_FILE

load trusted CA certificates from a file The loaded CA certificates will 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

verify the email address of the end-entity (leaf) peer certificate subject Certificates are accepted if no subject checks were specified, or the email address of the end-entity (leaf) peer certificate matches any of the email addresses specified with checkEmail.

Multiple checkEmail options are allowed in a single service section.

This option requires OpenSSL 1.0.2 or later.

checkHost = HOST

verify the host of the end-entity (leaf) peer certificate subject Certificates are accepted if no subject checks were specified, or the host name of the end-entity (leaf) peer certificate matches any of the hosts specified with checkHost.

Multiple checkHost options are allowed in a single service section.

This option requires OpenSSL 1.0.2 or later.

checkIP = IP

verify the IP address of the end-entity (leaf) peer certificate subject Certificates are accepted if no subject checks were specified, or the IP address of the end-entity (leaf) peer certificate matches any of the IP addresses specified with checkIP.

Multiple checkIP options are allowed in a single service section.

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:

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.

process

The operating system process identifier (PID) may be useful in the inetd mode.

default: sequential

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.

rr

round robin - fair load distribution

prio

priority - use the order specified in config file

default: prio

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 the end-entity (leaf) peer 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.

OCSPrequire = yes | no

require a conclusive OCSP response Disable this option to allow a connection even though no conclusive OCSP response was retrieved from stapling and a direct request to the OCSP responder.

default: yes

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:

cifs

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

capwin

http://www.capwin.org/ application support

capwinctrl

http://www.capwin.org/ application support This protocol is only supported in client mode.

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

ldap

Based on RFC 2830 - Lightweight Directory Access Protocol (v3): Extension for Transport Layer Security

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 http://www.postgresql.org/docs/8.3/static/protocol-flow.html#AEN73982

pop3

Based on RFC 2449 - POP3 Extension Mechanism

proxy

Passing of the original client IP address with HAProxy PROXY protocol version 1 https://www.haproxy.org/download/1.8/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 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 = 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 | DELAY

reconnect a connect+exec section after it was disconnected The DELAY value specifies the number of milliseconds before retrying. "retry = yes" has the same effect as "retry = 1000".

default: no

securityLevel = LEVEL

set the security level The meaning of each level is described below:

level 0

Everything is permitted.

level 1

The security level corresponds to a minimum of 80 bits of security. Any parameters offering below 80 bits of security are excluded. As a result RSA, DSA and DH keys shorter than 1024 bits and ECC keys shorter than 160 bits are prohibited. All export cipher suites are prohibited since they all offer less than 80 bits of security. SSL version 2 is prohibited. Any cipher suite using MD5 for the MAC is also prohibited.

level 2

Security level set to 112 bits of security. As a result RSA, DSA and DH keys shorter than 2048 bits and ECC keys shorter than 224 bits are prohibited. In addition to the level 1 exclusions any cipher suite using RC4 is also prohibited. SSL version 3 is also not allowed. Compression is disabled.

level 3

Security level set to 128 bits of security. As a result RSA, DSA and DH keys shorter than 3072 bits and ECC keys shorter than 256 bits are prohibited. In addition to the level 2 exclusions cipher suites not offering forward secrecy are prohibited. TLS versions below 1.1 are not permitted. Session tickets are disabled.

level 4

Security level set to 192 bits of security. As a result RSA, DSA and DH keys shorter than 7680 bits and ECC keys shorter than 384 bits are prohibited. Cipher suites using SHA1 for the MAC are prohibited. TLS versions below 1.2 are not permitted.

level 5

Security level set to 256 bits of security. As a result RSA, DSA and DH keys shorter than 15360 bits and ECC keys shorter than 512 bits are prohibited.

default: 2

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

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 secondary service (a name-based virtual server) for Server Name Indication TLS extension (RFC 3546). SERVICE_NAME specifies the primary 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 secondary services are normally specified for a single primary service. The sni option can also be specified more than once within a single secondary service.

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

The connect option of the secondary 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 primary service name after TCP connection is accepted, and with the secondary 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 a remote host

TIMEOUTidle = SECONDS

time to keep an idle connection

TIMEOUTocsp = SECONDS

time to wait to connect an OCSP responder

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

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

```

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

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. _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 This option is obsolete and should be replaced with the verifyChain and verifyPeer options.

level 0

Request and ignore the peer certificate chain.

level 1

Verify the peer certificate chain if present.

level 2

Verify the peer certificate chain.

level 3

Verify the peer certificate chain and the end-entity (leaf) peer certificate against a locally installed certificate.

level 4

Ignore the peer certificate chain and only verify the end-entity (leaf) peer certificate against a locally installed certificate.

default

No verify.

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 end-entity (leaf) peer certificate The end-entity (leaf) peer certificate needs to be stored either in the file specified with CAfile, or in the directory specified with CApath.

default: no

## RETURN VALUE
stunnel returns zero on success, non-zero on error.

## SIGNALS
The following signals can be used to control stunnel in 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.

SIGUSR2

Log the list of active connections.

SIGTERM, SIGQUIT, SIGINT

Shut stunnel down.

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

## EXAMPLES
In order to provide TLS 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
```

In order to let your local e-mail client connect to a TLS-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
```

If you want to provide tunneling to your pppd daemon on port 2020, use something like:

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

If you want to use stunnel in inetd mode to launch your imapd process, you'd use this stunnel.conf. Note there must be no [service_name] section.

```
    exec = /usr/sbin/imapd
    execArgs = imapd
```

To setup SOCKS VPN configure the following client service:

```
    [socks_client]
    client = yes
    accept = 127.0.0.1:1080
    connect = vpn_server:9080
    verifyPeer = yes
    CAfile = stunnel.pem
```

The corresponding configuration on the vpn_server host:

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

Now test your configuration on the client machine with:

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

An example server mode SNI configuration:

```
    [virtual]
    ; primary service
    accept = 443
    cert =  default.pem
    connect = default.internal.mydomain.com:8080
    [sni1]
    ; secondary service 1
    sni = virtual:server1.mydomain.com
    cert = server1.pem
    connect = server1.internal.mydomain.com:8081
    [sni2]
    ; secondary service 2
    sni = virtual:server2.mydomain.com
    cert = server2.pem
    connect = server2.internal.mydomain.com:8082
    verifyPeer = yes
    CAfile = server2-allowed-clients.pem
```

An example of advanced engine configuration allows for authentication with private keys stored in the Windows certificate store (Windows only). With the CAPI engine you don't need to manually select the client key to use. The client key is automatically selected based on the list of CAs trusted by the server.

```
    engine = capi
    [service]
    engineId = capi
    client = yes
    accept = 127.0.0.1:8080
    connect = example.com:8443
```

An example of advanced engine configuration to use the certificate and the corresponding private key from a pkcs11 engine:

```
    engine = pkcs11
    engineCtrl = MODULE_PATH:opensc-pkcs11.so
    engineCtrl = PIN:123456
    [service]
    engineId = pkcs11
    client = yes
    accept = 127.0.0.1:8080
    connect = example.com:843
    cert = pkcs11:token=MyToken;object=MyCert
    key = pkcs11:token=MyToken;object=MyKey
```

An example of advanced engine configuration to use the certificate and the corresponding private key from a SoftHSM token:

```
    engine = pkcs11
    engineCtrl = MODULE_PATH:softhsm2.dll
    engineCtrl = PIN:12345
    [service]
    engineId = pkcs11
    client = yes
    accept = 127.0.0.1:8080
    connect = example.com:843
    cert = pkcs11:token=MyToken;object=KeyCert
```

## 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 available TLS-enabled versions of FTP and telnet daemons, however.

### 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/bin/stunnel stunnel /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
Each TLS-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 certificates generation on pages listed below.

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
stunnel needs to seed the PRNG (pseudo-random number generator) in order for TLS 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.

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

## FILES
/etc/stunnel/stunnel.conf

stunnel configuration file

## BUGS
The execArgs option and the Win32 command line do not support quoting.

## SEE ALSO
tcpd(8)

access control facility for internet services

inetd(8)

internet 'super-server'

http://www.stunnel.org/

stunnel homepage

http://www.openssl.org/

OpenSSL project website

## AUTHOR
Michał Trojnara

<Michal.Trojnara@stunnel.org>