openvpn.8

OpenVPN -- A Secure tunneling daemon

Run the
.B --ping-exit
/
.B --ping-restart
timer only if we have a remote address.  Use this option if you are
starting the daemon in listen mode (i.e. without an explicit
.B --remote
peer), and you don't want to start clocking timeouts until a remote
peer connects.
.TP
.B --persist-tun
Don't close and reopen TUN/TAP device or run up/down scripts
across
.B SIGUSR1
or
.B --ping-restart
restarts.

.B SIGUSR1
is a restart signal similar to
.B SIGHUP,
but which offers finer-grained control over
reset options.
.TP
.B --persist-key
Don't re-read key files across
.B SIGUSR1
or
.B --ping-restart.

This option can be combined with
.B --user nobody
to allow restarts triggered by the
.B SIGUSR1
signal.
Normally if you drop root privileges in OpenVPN,
the daemon cannot be restarted since it will now be unable to re-read protected
key files.

This option solves the problem by persisting keys across
.B SIGUSR1
resets, so they don't need to be re-read.
.TP
.B --persist-local-ip
Preserve initially resolved local IP address and port number
across
.B SIGUSR1
or
.B --ping-restart
restarts.
.TP
.B --persist-remote-ip
Preserve most recently authenticated remote IP address and port number
across
.B SIGUSR1
or
.B --ping-restart
restarts.
.TP
.B --mlock
Disable paging by calling the POSIX mlockall function.
Requires that OpenVPN be initially run as root (though
OpenVPN can subsequently downgrade its UID using the
.B --user
option).

Using this option ensures that key material and tunnel
data are never written to disk due to virtual
memory paging operations which occur under most
modern operating systems.  It ensures that even if an
attacker was able to crack the box running OpenVPN, he
would not be able to scan the system swap file to
recover previously used
ephemeral keys, which are used for a period of time
governed by the
.B --reneg
options (see below), then are discarded.

The downside
of using
.B --mlock
is that it will reduce the amount of physical
memory available to other applications.
.TP
.B --up cmd
Shell command to run after successful TUN/TAP device open
(pre
.B --user
UID change).

Execute as:

.B cmd tun_tap_dev tun_mtu udp_mtu ifconfig_local_ip ifconfig_remote_ip

Note that
.B cmd
can be a shell command with multiple arguments, in which
case all OpenVPN-generated arguments will be appended
to
.B cmd
to build a command line which will be passed to the script.

Typically,
.B cmd
will run a script such as:

.B ifconfig $1 10.4.0.1 pointopoint 10.4.0.2 mtu $2

(Note: remove "pointopoint" from command line on OpenBSD).

Note that OpenVPN also provides the
.B --ifconfig
option to automatically ifconfig the TUN device,
eliminating the need to define an
.B --up
script, unless you also want to configure routes
in the
.B --up
script.

If
.B --ifconfig
is also specified, OpenVPN will pass the ifconfig local
and remote endpoints on the command line to the
.B --up
script so that they can be used to configure routes such as:

.B route add -net 10.0.0.0 netmask 255.255.255.0 gw $5
.TP
.B --down cmd
Shell command to run after TUN/TAP device close
(post
.B --user
UID change and/or
.B --chroot
).  Called with the same parameters as the
.B --up
option above.
.TP
.B --user user
Change the user ID of the OpenVPN process to
.B user
after initialization, dropping privileges in the process.
This option is useful to protect the system
in the event that some hostile party was able to gain control of
an OpenVPN session.  Though OpenVPN's security features make
this unlikely, it is provided as a second line of defense.

By setting
.B user
to
.I nobody
or somebody similarly unprivileged, the hostile party would be
limited in what damage they could cause.  Of course once
you take away privileges, you cannot return them
to an OpenVPN session.  This means, for example, that if
you want to reset an OpenVPN daemon with a
.B SIGUSR1
signal
(for example in response
to a DHCP reset), you should make use of one or more of the
.B --persist
options to ensure that OpenVPN doesn't need to execute any privileged
operations in order to restart (such as re-reading key files
or running
.BR ifconfig
on the TUN device).
.TP
.B --group group
Similar to the
.B --user
option,
this option changes the group ID of the OpenVPN process to
.B group
after initialization.
.TP
.B --cd dir
Change directory to
.B dir
prior to reading any files such as
configuration files, key files, scripts, etc.
.B dir
should be an absolute path, with a leading "/",
and without any references
to the current directory such as "." or "..".

This option is useful when you are running
OpenVPN in 
.B --daemon
mode, and you want to consolidate all of
your OpenVPN control files in one location.
.TP
.B --chroot dir
Chroot to
.B dir
after initialization.  
.B --chroot
essentially redefines
.B dir
as being the top
level directory tree (/).  OpenVPN will therefore
be unable to access any files outside this tree.
This can be desirable from a security standpoint.

Since the chroot operation is delayed until after
initialization, most OpenVPN options that reference
files will operate in a pre-chroot context.

In many cases, the
.B dir
parameter can point to an empty directory, however
complications can result when scripts or restarts
are executed after the chroot operation.
.TP
.B --daemon [progname]
Become a daemon after all initialization functions are completed.
This option will cause all message and error output to
be sent to the syslog file (such as /var/log/messages),
except for the output of shell scripts and
ifconfig commands,
which will go to /dev/null unless otherwise redirected.

The optional
.B progname
parameter will cause OpenVPN to report its program name
to the system logger as
.B progname.
This can be useful in linking OpenVPN messages
in the syslog file with specific tunnels.
When unspecified,
.B progname
defaults to "openvpn".

When openvpn is run with the
.B --daemon
option, it will try to delay daemonization until the majority of initialization
functions which are capable of generating fatal errors are complete.  This means
that initialization scripts can test the return status of the
openvpn command for a fairly reliable indication of whether the command
has correctly initialized and entered the packet forwarding event loop.

In OpenVPN, the vast majority of errors which occur after initialization are non-fatal.
.TP
.B --passtos
Set the TOS field of the tunnel packet to what the payload's TOS is.
.TP
.B --inetd [progname]
Use this option when OpenVPN is being run from the inetd or
.BR xinetd(8)
server.
This option precludes the use of
.B --daemon, --local,
or
.B --remote.
Note that this option causes message and error output to be handled in the same
way as the
.B --daemon
option.  The optional
.B progname
parameter is also handled exactly as in
.B --daemon.

Also note that each OpenVPN tunnel requires a separate UDP port and
a separate inetd or xinetd entry.  See the OpenVPN HOWTO for an example
on using OpenVPN with xinetd:
.I http://openvpn.sourceforge.net/howto.html
.TP
.B --writepid file
Write OpenVPN's main process ID to
.B file.
.TP
.B --nice n
Change process priority after initialization
(
.B n
greater than 0 is lower priority,
.B n
less than zero is higher priority).
.TP
.B --nice-work n
Change priority of background TLS work thread.  The TLS thread
feature is enabled when OpenVPN is built
with pthread support, and you are running OpenVPN
in TLS mode (i.e. with
.B --tls-client
or
.B --tls-server
specified).

Using a TLS thread offloads the CPU-intensive process of SSL/TLS-based
key exchange to a background thread so that it does not become
a latency bottleneck in the tunnel packet forwarding process.

The parameter
.B n
is interpreted exactly as with the
.B --nice
option above, but in relation to the work thread rather
than the main thread.
.TP
.B --verb n
Set output verbosity to
.B n
(default=1).  Each level shows all info from the previous levels.
Level 3 is recommended if you want a good summary
of what's happening without being swamped by output.

.B 0 --
no output except fatal errors
.br
.B 1 --
show startup information + connection initiated messages + non-fatal encryption & net errors
.br
.B 2 --
show SSL/TLS negotiations
.br
.B 3 --
show extra SSL/TLS info +
.B --gremlin
net outages + adaptive compression state changes (on or off)
.br
.B 4 --
show all parameter settings
.br
.B 5 to 11 --
show debug info of increasing verbosity (see errlevel.h for additional
information on debug levels)
.TP
.B --mute n
Log at most
.B n
consecutive messages in the same category.  This is useful to
limit repetitive logging of similar message types.
.TP
.B --gremlin
Simulate dropped & corrupted packets + network outages
(for debugging and testing only).  This is a
powerful tool for verifying the robustness of the OpenVPN protocol,
especially in TLS mode.  When used with TLS parameters that force
frequent key renegotiations such as
.B --reneg-sec 10,
this option will stress-test the ability of OpenVPN peers to recover
from errors and remain in sync.
Current parameter settings will cause
.B --gremlin
to drop 2% of packets and corrupt another 2%.  A packet corruption will
alter a random byte in the packet to a random value.  It might
also increase or decrease the size of the packet by one byte.
.B --gremlin
will also simulate network outages by going "down"
for a period of 10 to 60 seconds.
Between simulated outages, OpenVPN will
remain up for periods of 10 to 300 seconds.  To see gremlin
messages, set
.B --verb
to 3 or higher.  To change gremlin constants, consult the
file gremlin.c included in the OpenVPN source distribution.
.TP
.B --comp-lzo
Use fast LZO compression -- may add up to 1 byte per
packet for incompressible data.
.TP
.B --comp-noadapt
When used in conjunction with
.B --comp-lzo,
this option will disable OpenVPN's adaptive compression algorithm.
Normally, adaptive compression is enabled with
.B --comp-lzo.

Adaptive compression tries to optimize the case where you have
compression enabled, but you are sending predominantly uncompressible
(or pre-compressed) packets over the tunnel, such as an FTP or rsync transfer
of a large, compressed file.  With adaptive compression,
OpenVPN will periodically sample the compression process to measure its
efficiency.  If the data being sent over the tunnel is already compressed,
the compression efficiency will be very low, triggering openvpn to disable
compression for a period of time until the next re-sample test.
.B 
.SS Data Channel Encryption Options:
These options are meaningful for both Static & TLS-negotiated key modes
(must be compatible between peers).
.TP
.B --secret file
Enable Static Key encryption mode (non-TLS).
Use pre-shared secret file which was generated with
.B --genkey.
Static key encryption mode has certain advantages, the biggest
probably being the ease of configuration.  There are no certificates
or certificate authorities or complicated negotiation handshakes and protocols.
The only requirement is that you have a pre-existing secure channel with
your peer (such as
.B ssh
) to initially copy the key.  This requirement, along with the
fact that your key never changes unless you manually generate a new one,
makes it somewhat less secure than TLS mode (see below).  If an attacker
manages to steal your key, everything that was ever encrypted with
it is compromised.  Contrast that to the perfect forward security features of
TLS mode where even if an attacker was able to steal your private key,
he would gain no information to help him decrypt past sessions.

One interesting aspect of Static Key encryption mode is that
it is a handshake-free protocol 
without any distinguishing signature or feature
(such as a header or protocol handshake sequence) 
that would mark the ciphertext packets as being
generated by OpenVPN.  Anyone eavesdropping on the wire
would see nothing
but random-looking data.
.TP
.B --auth alg
Authenticate packets with an HMAC using message
digest algorithm
.B alg.
(The default is
.B SHA1
).
HMAC is a commonly used message authentication algorithm (MAC) that uses
a data string, a secure hash algorithm, and a key, to produce
a digital signature.  HMAC has the property that it is infeasible