openvpn.8

OpenVPN -- A Secure tunneling daemon

.B --remote
allows an OpenVPN session to initially connect to a peer
at a known address, however if packets arrive from a new
address and pass all authentication tests, the new address
will take control of the session.  This is useful when
you are connecting to a peer which holds a dynamic address
such as a dial-in user or DHCP client.

Essentially,
.B --float
tells OpenVPN to accept authenticated packets
from any address, not only the address which was specified in the
.B --remote
option.
.TP
.B --ipchange cmd
Execute shell command
.B cmd
when our remote ip-address is initially authenticated or
changes.

Execute as:

.B cmd ip_address port_number

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.

If you are running in a dynamic IP address environment where
the IP addresses of either peer could change without notice,
you can use this script, for example, to edit the
.I /etc/hosts
file with the current address of the peer.  The script will
be run every time the remote peer changes its IP address.

Similarly if
.I our
IP address changes due to DHCP, we should configure
our IP address change script (see man page for
.BR dhcpcd (8)
) to deliver a
.B SIGHUP
or
.B SIGUSR1
signal to OpenVPN.  OpenVPN will then
reestablish a connection with its most recently authenticated
peer on its new IP address.
.TP
.B --port port
UDP port number for both local and remote.
.TP
.B --lport port
UDP port number for local (default=5000).
.TP
.B --rport port
UDP port number for remote (default=5000).
.TP
.B --nobind
Do not bind to local address and port.  The IP stack will allocate
a dynamic port for returning packets.  Since the value of the dynamic port
could not be known in advance by a peer, this option is only suitable for
peers which will be initiating connections by using the
.B --remote
option.
.TP
.B --dev tunX | tapX | null
TUN/TAP virtual network device (
.B X
can be omitted for dynamic device in
Linux 2.4.7+).  See examples section below
for an example on setting up a TUN device.
.TP
.B --dev-type device-type
Which device type are we using?
.B device-type
should be
.B tun
or
.B tap.
Use this option only if the TUN/TAP device used with
.B --dev
does not begin with
.B tun
or
.B tap.
.TP
.B --tun-ipv6
Build a tun link capable of forwarding IPv6 traffic.
Should be used in conjunction with
.B --dev tun
or
.B --dev tunX.
A warning will be displayed
if no specific IPv6 TUN support for your OS has been compiled into OpenVPN.
.TP
.B --dev-node node
Explicitly set the device node rather than using
/dev/net/tun, /dev/tun, /dev/tap, etc.  If OpenVPN
cannot figure out whether
.B node
is a TUN or TAP device based on the name, you should
also specify
.B --dev-type tun
or
.B --dev-type tap.
.TP
.B --ifconfig l r
Configure the TUN device to use IP address
.B l
as a local endpoint and
.B r
as a remote endpoint.
.B l
&
.B r
should be swapped on the other peer.
.B l
&
.B r
must be private
addresses outside of the subnets used by either peer.
This option implies
.B --udp-mtu 1300
if neither
.B --udp-mtu
or
.B --tun-mtu
is explicitly specified.

This option will
configure the tunnel endpoints using the
.BR ifconfig (8)
command, eliminating the need to have an
.B --up
script.  However, you will still need an
.B --up
script if you will be adding routes
to the tunnel.

The
.B --ifconfig
option can be used in conjunction with an
.B --up
script in which case the local and remote
endpoints will be passed as parameters to
the script.

In addition, the
.B --ifconfig
option will set the UDP MTU to 1300
and derive the tunnel MTU automatically.  You can
override the UDP MTU value of 1300 by using
the
.B --udp-mtu
option to explicitly specify a different value.

One of the nice features of the 
.B --ifconfig
option is that it knows how to run the
.BR ifconfig (8)
tool on each of the operating systems
which OpenVPN supports, allowing you
to specify the option consistently
across platforms, while OpenVPN deals
with formatting the appropriate
.BR ifconfig (8)
command for your platform.
.TP
.B --udp-mtu n
Take the UDP device MTU to be n and derive the TUN MTU
from it (default=1300 when the
.B --ifconfig
option is used).  This is a conservative value that was chosen
because it has a higher probability of working correctly.
However, for many
cases, using a value of 1472 will maximize performance.

This option should only be used for TUN style tunnels.  TAP tunnels
that are used for ethernet bridging should use the
.B --tun-mtu
parameter.

The MTU (Maximum Transmission Units) is
the maximum datagram size in bytes that can be sent unfragmented
over a particular network path.  OpenVPN requires that packets
on the control or data channels be sent unfragmented.

Typically, the UDP MTU should be set to a value between 1300 and 1500.
The optimal size for UDP MTU is the largest
MTU that can be handled by every router on the link path.
The UDP MTU value should be equal on both peers.

OpenVPN
adds a small amount of overhead to each tunnel packet before
it is forwarded from the TUN device over the secure UDP channel.
This overhead consists of data fields such as the HMAC signature,
packet ID, encryption block padding, etc.  Because of this overhead,
the TUN device MTU should be slightly smaller than the UDP device
MTU to make room for the extra bytes which OpenVPN adds to every
data channel packet.  OpenVPN allows you to explicitly specify either
the TUN MTU or the UDP MTU (but not both).  OpenVPN will then
compute the value you didn't specify based on the value you did.
OpenVPN will compute exactly how much overhead it will need to add
to each packet, based on the other options you specify.  If you
specify an
.B --up
script, OpenVPN will pass the TUN MTU and UDP MTU values on the command line
to the script.
.TP
.B --tun-mtu n
Take the TUN device MTU to be
.B n
and derive the UDP MTU
from it (default=1300).

See
.B --udp-mtu
above more more information on MTU.

Using the
.B --ifconfig
option is the recommended method of configuring
a TUN device MTU automatically.

However, for TUN devices which are used to bridge ethernet segments,
it is recommended that you set this parameter to 1500 and then also add
.B --tun-mtu-extra 64
to your command line or config file.
.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 64 would be a conservative choice for
TAP device usage.  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 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-dynamic [min] [max]
EXPERIMENTAL -- Enable internal datagram fragmentation so
that no UDP datagrams are sent which
are larger than
.B max
bytes.  Currently, dynamic MTU
sizing is not yet implemented, so
.B min
should equal
.B max.

Adds 4 bytes of overhead per datagram.

Since this option is currently experimental, you must rebuild
OpenVPN with the
.B --enable-mtu-dynamic
configure flag in order to have the capability of using
this option.

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 --shaper n
Limit bandwidth of outgoing tunnel data to
.B n
bytes per second on the 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 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 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).
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