openvpn.8

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

.TP
.B --tun-mtu n
Take the TUN device MTU to be
.B n
and derive the link MTU
from it (default=1500 for TAP devices).

See
.B --link-mtu
above more more information on MTU.
.TP
.B --tun-mtu-extra n
Assume that the TUN/TAP device might return as many as
.B n
bytes more than the
.B --tun-mtu
size on read.  This parameter defaults to 0, which is sufficient for
most TUN devices.  TAP devices may introduce additional overhead in excess
of the MTU size, and a setting of 32 is the default when TAP devices are used.
This parameter only controls internal OpenVPN buffer sizing,
so there is no transmission overhead associated with using a larger value.
.TP
.B --mtu-disc type
Should we do Path MTU discovery on TCP/UDP channel?  Only supported on OSes such
as Linux that supports the necessary system call to set.

.B 'no'
-- Never send DF (Don't Fragment) frames
.br
.B 'maybe'
-- Use per-route hints
.br
.B 'yes'
-- Always DF (Don't Fragment)
.br
.TP
.B --mtu-test
To empirically measure MTU on connection startup,
add the
.B --mtu-test
option to your configuration.
OpenVPN will send ping packets of various sizes
to the remote peer and measure the largest packets
which were successfully received.  The
.B --mtu-test
process normally takes about 3 minutes to complete.
.TP
.B --fragment max
Enable internal datagram fragmentation so
that no UDP datagrams are sent which
are larger than
.B max
bytes.

The
.B max
parameter is interpreted in the same way as the
.B --link-mtu
parameter, i.e. the UDP packet size after encapsulation
overhead has been added in, but not including
the UDP header itself.

The
.B --fragment
option only makes sense when you are using the UDP protocol
for OpenVPN peer-to-peer communication, i.e.
.B --proto udp.

.B --fragment
adds 4 bytes of overhead per datagram.

See the
.B --mssfix
option below for an important companion option to
.B --fragment.

It should also be noted that this option is not meant to replace
UDP fragmentation at the IP stack level.  It is only meant as a
last resort when path MTU discovery is broken.  Using this option
is less efficient than fixing path MTU discovery for your IP link and
using native IP fragmentation instead.

Having said that, there are circumstances where using OpenVPN's
internal fragmentation capability may be your only option, such
as tunneling a UDP multicast stream which requires fragmentation.
.TP
.B --mssfix max
Announce to TCP sessions running over the tunnel that they should limit
their send packet sizes such that after OpenVPN has encapsulated them,
the resulting UDP packet size that OpenVPN sends to its peer will not
exceed
.B max
bytes.

The
.B max
parameter is interpreted in the same way as the
.B --link-mtu
parameter, i.e. the UDP packet size after encapsulation
overhead has been added in, but not including
the UDP header itself.

The
.B --mssfix
option only makes sense when you are using the UDP protocol
for OpenVPN peer-to-peer communication, i.e.
.B --proto udp.

.B --mssfix
and
.B --fragment
can be ideally used together, where
.B --mssfix
will try to keep TCP from needing
packet fragmentation in the first place,
and if big packets come through anyhow
(from protocols other than TCP),
.B --fragment
will internally fragment them.

Both
.B --fragment
and
.B --mssfix
are designed to work around cases where Path MTU discovery
is broken on the network path between OpenVPN peers.

The usual symptom of such a breakdown is an OpenVPN
connection which successfully starts, but then stalls
during active usage.

If
.B --fragment
and
.B --mssfix
are used together,
.B --mssfix
will take its default
.B max
parameter from the
.B --fragment max
option.

Therefore, one could lower the maximum UDP packet size
to 1300 (a good first try for solving MTU-related
connection problems) with the following options:

.B --tun-mtu 1500 --fragment 1300 --mssfix
.TP
.B --sndbuf size
Set the TCP/UDP socket send buffer size.
Currently defaults to 65536 bytes.
.TP
.B --rcvbuf size
Set the TCP/UDP socket receive buffer size.
Currently defaults to 65536 bytes.
.TP
.B --txqueuelen n
(Linux only) Set the TX queue length on the tun/tap interface.
Currently defaults to 100.
.TP
.B --shaper n
Limit bandwidth of outgoing tunnel data to
.B n
bytes per second on the TCP/UDP port.
If you want to limit the bandwidth
in both directions, use this option on both peers.

OpenVPN uses the following algorithm to implement
traffic shaping: Given a shaper rate of
.I n
bytes per second, after a datagram write of
.I b
bytes is queued on the TCP/UDP port, wait a minimum of
.I (b / n)
seconds before queuing the next write.

It should be noted that OpenVPN supports multiple
tunnels between the same two peers, allowing you
to construct full-speed and reduced bandwidth tunnels
at the same time,
routing low-priority data such as off-site backups
over the reduced bandwidth tunnel, and other data
over the full-speed tunnel.

Also note that for low bandwidth tunnels
(under 1000 bytes per second), you should probably
use lower MTU values as well (see above), otherwise
the packet latency will grow so large as to trigger
timeouts in the TLS layer and TCP connections running
over the tunnel.

OpenVPN allows
.B n
to be between 100 bytes/sec and 100 Mbytes/sec.
.TP
.B --inactive n
Causes OpenVPN to exit after
.B n
seconds of inactivity on the TUN/TAP device.  The time length
of inactivity is measured since the last incoming tunnel packet.
.TP
.B --ping n
Ping remote over the TCP/UDP control channel
if no packets have been sent for at least
.B n
seconds (specify
.B --ping
on both peers to cause ping packets to be sent in both directions since
OpenVPN ping packets are not echoed like IP ping packets).
When used in one of OpenVPN's secure modes (where
.B --secret, --tls-server,
or
.B --tls-client
is specified), the ping packet
will be cryptographically secure.

This option has two intended uses:

(1) Compatibility
with stateful firewalls.  The periodic ping will ensure that
a stateful firewall rule which allows OpenVPN UDP packets to
pass will not time out.

(2) To provide a basis for the remote to test the existence
of its peer using the
.B --ping-exit
option.
.TP
.B --ping-exit n
Causes OpenVPN to exit after
.B n
seconds pass without reception of a ping
or other packet from remote.
This option can be combined with
.B --inactive, --ping,
and
.B --ping-exit
to create a two-tiered inactivity disconnect.

For example,

.B openvpn [options...] --inactive 3600 --ping 10 --ping-exit 60

when used on both peers will cause OpenVPN to exit within 60
seconds if its peer disconnects, but will exit after one
hour if no actual tunnel data is exchanged.
.TP
.B --ping-restart n
Similar to
.B --ping-exit,
but trigger a
.B SIGUSR1
restart after
.B n
seconds pass without reception of a ping
or other packet from remote.

This option is useful in cases
where the remote peer has a dynamic IP address and
a low-TTL DNS name is used to track the IP address using
a service such as
.I http://dyndns.org/
+ a dynamic DNS client such
as
.B ddclient.

If the peer cannot be reached, a restart will be triggered, causing
the hostname used with
.B --remote
to be re-resolved (if
.B --resolv-retry
is also specified).

See the signals section below for more information
on
.B SIGUSR1.

Note that the behavior of
.B SIGUSR1
can be modified by the
.B --persist-tun, --persist-key, --persist-local-ip,
and
.B --persist-remote-ip
options.

Also note that
.B --ping-exit
and
.B --ping-restart
are mutually exclusive and cannot be used together.
.TP
.B --ping-timer-rem
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).  The up script is useful for specifying route
commands which route IP traffic destined for
private subnets which exist at the other
end of the VPN connection into the tunnel.

For
.B --dev tun
execute as:

.B cmd tun_dev tun_mtu link_mtu ifconfig_local_ip ifconfig_remote_ip [ init | restart ]

For
.B --dev tap
execute as:

.B cmd tap_dev tap_mtu link_mtu ifconfig_local_ip ifconfig_netmask [ init | restart ]

See the "Environmental Variables" section below for
additional parameters passed as environmental variables.

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

Typically,
.B cmd
will run a script to add routes to the tunnel.

Normally the up script is called after the TUN/TAP device is opened.
In this context, the last command line parameter passed to the script
will be
.I init.
If the
.B --up-restart
option is also used, the up script will be called for restarts as
well.  A restart is considered to be a partial reinitialization
of OpenVPN where the TUN/TAP instance is preserved (the
.B --persist-tun
option will enable such preservation).  A restart
can be generated by a SIGUSR1 signal, a
.B --ping-restart
timeout, or a connection reset when the TCP protocol is enabled
with the
.B --proto
option.  If a restart occurs, and
.B --up-restart
has been specified, the up script will be called with
.I restart
as the last parameter.

The following standalone example shows how the
.B --up
script can be called in both an initialization and restart context.
(NOTE: for security reasons, don't run the following example unless UDP port
9999 is blocked by your firewall.  Also, the example will run indefinitely,
so you should abort with control-c).

.B openvpn --dev tun --port 9999 --verb 4 --ping-restart 10 --up 'echo up' --down 'echo down' --persist-tun --up-restart

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