openvpn.8

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

.B --socks-proxy server [port]
Connect to remote host through a Socks5 proxy at address
.B server
and port
.B port
(default=1080).
.TP
.B --socks-proxy-retry
Retry indefinitely on Socks proxy errors.  If a Socks proxy error
occurs, simulate a SIGUSR1 reset.
.TP
.B --resolv-retry n
If hostname resolve fails for
.B --remote,
retry resolve for
.B n
seconds before failing (disabled by default).

Set
.B n
to "infinite" to retry indefinitely.
.TP
.B --float
Allow remote peer to change its IP address and/or port number, such as due to
DHCP (this is the default if
.B --remote
is not used).
.B --float
when specified with
.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

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 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
TCP/UDP port number for both local and remote.
.TP
.B --lport port
TCP/UDP port number for local (default=5000).
.TP
.B --rport port
TCP/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 a dynamic device.)

See examples section below
for an example on setting up a TUN device.

You must use either tun devices on both ends of the connection
or tap devices on both ends.  You cannot mix them, as they
represent different underlying protocols.

.B tun
devices encapsulate IPv4 while
.B tap
devices encapsulate ethernet 802.3.
.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.

On Windows systems, select the TAP-Win32 adapter which
is named
.B node
in the Network Connections Control Panel or the
raw GUID of the adapter enclosed by braces.
The
.B --show-adapters
option under Windows can also be used
to enumerate all available TAP-Win32
adapters and will show both the network
connections control panel name and the GUID for
each TAP-Win32 adapter.
.TP
.B --ifconfig l rn
Set TUN/TAP adapter parameters. 
.B l
is the IP address of the local VPN endpoint.
For TUN devices,
.B rn
is the IP address of the remote VPN endpoint.
For TAP devices,
.B rn
is the subnet mask of the virtual ethernet segment
which is being created or connected to.

For TUN devices, which facilitate virtual
point-to-point IP connections,
the proper usage of
.B --ifconfig
is to use two private IP addresses
which are not a member of any
existing subnet which is in use.
The IP addresses may be consecutive
and should have their order reversed
on the remote peer.  After the VPN
is established, by pinging
.B rn,
you will be pinging across the VPN.

For TAP devices, which provide
the ability to create virtual
ethernet segments,
.B --ifconfig
is used to set an IP address and
subnet mask just as a physical
ethernet adapter would be
similarly configured.  If you are
attempting to connect to a remote
ethernet bridge, the IP address
and subnet should be set to values
which would be valid on the
the bridged ethernet segment (note
also that DHCP can be used for the
same purpose).

This option, while primarily a proxy for the
.BR ifconfig (8)
command, is designed to simplify TUN/TAP
tunnel configuration by providing a
standard interface to the different
ifconfig implementations on different
platforms.

.B --ifconfig
parameters which are IP addresses can
also be specified as a DNS or /etc/hosts
file resolvable name.

For TAP devices,
.B --ifconfig
should not be used if the TAP interface will be
getting an IP address lease from a DHCP
server.
.TP
.B --ifconfig-noexec
Don't actually execute ifconfig/netsh commands, instead
pass
.B --ifconfig
parameters to scripts using environmental variables.
.TP
.B --ifconfig-nowarn
Don't output an options consistency check warning
if the
.B --ifconfig
option on this side of the
connection doesn't match the remote side.  This is useful
when you want to retain the overall benefits of the
options consistency check (also see
.B --disable-occ
option) while only disabling the ifconfig component of
the check.

For example,
if you have a configuration where the local host uses
.B --ifconfig
but the remote host does not, use
.B --ifconfig-nowarn
on the local host.
.TP
.B --route network [netmask] [gateway] [metric]
Add route to routing table after connection is established.
Multiple routes can be specified.  Routes will be
automatically torn down in reverse order prior to
tun/tap device close.

This option is intended as
a convenience proxy for the
.BR route (8)
shell command,
while at the same time providing portable semantics
across OpenVPN's platform space.

.B netmask
default -- 255.255.255.255

.B gateway
default -- taken from
.B --route-gateway
or the second parameter to
.B --ifconfig
when
.B --dev tun
is specified.

The default can be specified by leaving an option blank or setting
it to "default".

The
.B network
and
.B gateway
parameters can
also be specified as a DNS or /etc/hosts
file resolvable name, or as one of three special keywords:

.B vpn_gateway
-- The remote VPN endpoint address
(derived either from
.B --route-gateway
or the second parameter to
.B --ifconfig
when
.B --dev tun
is specified).

.B net_gateway
-- The pre-existing IP default gateway, read from the routing
table (Linux and Windows only).

.B remote_host
-- The
.B --remote
address, or the address of a connecting client if OpenVPN
is being run in server mode.
.TP
.B --route-gateway gw
Specify a default gateway
.B gw
for use with
.B --route.
.TP
.B --route-delay [n]
Delay
.B n
seconds (default=0) after connection
establishment, before adding routes. If
.B n
is 0, routes will be added immediately upon connection
establishment.  If
.B --route-delay
is omitted, routes will be added immediately after tun/tap device
open and
.B --up
script execution, before any
.B --user
or 
.B --group
privilege downgrade (or
.B --chroot
execution.)

This option is designed to be useful in scenarios where DHCP is
used to set
tap adapter addresses.  The delay will give the DHCP handshake
time to complete before routes are added.

A better solution would be to poll the virtual adapter, waiting
for its IP address to become defined, but unfortunately there
is no platform independent mechanism for doing this.
.TP
.B --route-up cmd
Execute shell command
.B cmd
after routes are added, subject to
.B --route-delay.

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.
.TP
.B --route-noexec
Don't add or remove routes automatically.  Instead pass routes to
.B --route-up
script using environmental variables.
.TP
.B --redirect-gateway ['local']
(Experimental) Automatically execute routing commands to cause all outgoing IP traffic
to be redirected over the VPN.  Currently implemented only on Linux and Windows.

This option performs three steps:

.B (1)
Create a static route for the
.B --remote
address which forwards to the pre-existing default gateway.
This is done so that
.B (3)
will not create a routing loop.

.B (2)
Delete the default gateway route.

.B (3)
Set the new default gateway to be the VPN endpoint address (derived either from
.B --route-gateway
or the second parameter to
.B --ifconfig
when
.B --dev tun
is specified).

Add
.B local
flag if both OpenVPN servers are directly connected via a common subnet,
such as with wireless.  The
.B local
flag will cause step
.B 1
above to be omitted.

When the tunnel is torn down, all of the above steps are reversed so
that the original default route is restored.
.TP
.B --link-mtu n
Take the link device MTU to be n and derive the TUN MTU
from it (default=1300 for TUN devices).  The
default 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 for TUN devices
over IPv4.

Fundamentally,
.B --link-mtu
sets an upper bound on the size of UDP packets which are sent
between OpenVPN peers.

Prior to OpenVPN 1.5, this option was named
.B --udp-mtu.
While deprecated, this name will still be supported
for compatibility.

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 link MTU should be set to a value between 1300 and 1500.
The optimal size for link MTU is the largest
MTU that can be handled by every router on the link path.
The link MTU value should be equal on both peers.

MTU problems often manifest themselves as connections which
hang during periods of active usage.  The
.B --fragment
and
.B --mssfix
options are provided as workarounds to such problems.
When using either of these options, it's best to
set
.B --tun-mtu
to 1500.

OpenVPN
adds a small amount of overhead to each tunnel packet before
it is forwarded from the TUN device over the secure link 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 link 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 link 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 link MTU values on the command line
to the script.