openvpn.8

OpenVPN is a robust and highly flexible tunneling application that uses all of the encryption, authe

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 --up-delay
Delay TUN/TAP open and possible
.B --up
script execution
until after TCP/UDP connection establishment with peer.

In
.B --proto udp
mode, this option normally requires the use of
.B --ping
to allow connection initiation to be sensed in the absence
of tunnel data, since UDP is a "connectionless" protocol.

On Windows, this option will delay the TAP-Win32 media state
transitioning to "connected" until connection establishment,
i.e. the receipt of the first authenticated packet from the peer.
.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 and environmental
variables as the
.B --up
option above.
.TP
.B --up-restart
Enable the
.B --up
and
.B --down
scripts to be called for restarts as well as initial program start.
This option is described more fully above in the
.B --up
option documentation.
.TP
.B --setenv name value
Set a custom environmental variable
.B name=value
to pass to script.
.TP
.B --disable-occ
Don't output a warning message if option inconsistencies are detected between
peers.  An example of an option inconsistency would be where one peer uses
.B --dev tun
while the other peer uses
.B --dev tap.

Use of this option is discouraged, but is provided as
a temporary fix in situations where a recent version of OpenVPN must
connect to an old version.
.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 syslog redirection occurs immediately at the point
that
.B --daemon
is parsed on the command line even though
the daemonization point occurs later.  If one of the
.B --log
options is present, it will supercede syslog
redirection.

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 [wait|nowait] [progname]
Use this option when OpenVPN is being run from the inetd or
.BR xinetd(8)
server.

The
.B wait/nowait
option must match what is specified in the inetd/xinetd
config file.  The
.B nowait
mode can only be used with
.B --proto tcp-server.
The default is
.B wait.
The
.B nowait
mode can be used to instantiate the OpenVPN daemon as a classic TCP server,
where client connection requests are serviced on a single
port number.  For additional information on this kind of configuration,
see the OpenVPN FAQ:
.I http://openvpn.sourceforge.net/faq.html#oneport

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 in
.B wait
mode, each OpenVPN tunnel requires a separate TCP/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 --log file
Output logging messages to
.B file,
including output to stdout/stderr which
is generated by called scripts.
If
.B file
already exists it will be truncated.
This option takes effect
immediately when it is parsed in the command line
and will supercede syslog output if
.B --daemon
or
.B --inetd
is also specified.
This option is persistent over the entire course of
an OpenVPN instantiation and will not be reset by SIGHUP,
SIGUSR1, or
.B --ping-restart.

Note that on Windows, when OpenVPN is started as a service,
logging occurs by default without the need to specify
this option.
.TP
.B --log-append file
Append logging messages to
.B file.
If
.B file
does not exist, it will be created.
This option behaves exactly like
.B --log
except that it appends to rather
than truncating the log file.
.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 --
Output
.B R
and
.B W
characters to the console for each packet read and write, uppercase is
used for TCP/UDP packets and lowercase is used for TUN/TAP packets.
.br
.B 6 to 11 --
Show debug info of increasing verbosity (see errlevel.h for additional
information on debug levels).
.TP
.B --status file [n]
Write operational status to
.B file
every
.B n
seconds.

Status can also be written to the syslog by sending a
.B SIGUSR2
signal.
.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.
.SS Multi-Client Server options
Starting with OpenVPN 2.0, a multi-client UDP server mode
is supported, and can be enabled with the
.B --mode server
option.  In server mode, OpenVPN will listen on a single
UDP port for incoming client connections.  All client
connections will be routed through a single tun or tap
interface.  This mode is designed for scalability and should
be able to support hundreds or even thousands of clients
on sufficiently fast hardware.  SSL/TLS authentication must
be used in this mode.
.TP
.B --push "option"
Push a config file option back to the client for remote
execution.  Note that
.B
option
must be enclosed in double quotes ("").  The client must specify
.B --pull
in its config file.  The set of options which can be
pushed is limited by both feasibility and security.
Some options such as those which would execute scripts
are banned, since they would effectively allow a compromised
server to execute arbitrary code on the client.
Other options such as TLS or MTU parameters
cannot be pushed because the client needs to know
them before the connection to the server can be initiated.

This is a partial list of options which can currently be pushed:
.B --route, --route-gateway, --route-delay, --redirect-gateway,
.B --ip-win32, --dhcp-option,
.B --inactive, --ping, --ping-exit, --ping-restart,
.B --setenv
.TP
.B --push-reset
Don't inherit the global push list for a specific client instance.
Specify this option in a client-specific context such
as with a
.B --client-config-dir
configuration file.  This option will ignore
.B --push
options at the global config file level.
.TP
.B --pull
This option must be used on a client which is connecting
to a multi-client server.  It indicates to OpenVPN that it
should accept options pushed by the server, provided they
are part of the legal set of pushable options.
.TP
.B --ifconfig-pool start-IP end-IP
Set aside a pool of subnets to be
dynamically allocated to connecting clients.  For tun-style
tunnels, each client will be given a /30 subnet (for
interoperability with Windows clients).  For tap-style
tunnels, individual addresses will be allocated.
.TP
.B --ifconfig-push local remote-netmask
Push a tunnel ifconfig command to remote client,
overriding the --ifconfig-pool dynamic allocation.
Must be associated with a specific client instance,
which means that it must be specified either in a client
instance config file using
.B --client-config-dir
or dynamically generated using a
.B --client-connect
script.
.TP
.B --iroute network [netmask]
Generate an internal route to a specific
client. The
.B netmask
parameter, if omitted, defaults to 255.255.255.255.

This directive can be used to route a fixed subnet from
the server to a particular client, regardless