Content-type: text/html; charset=UTF-8
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
<HTML><HEAD><TITLE>Man page of openvpn</TITLE>
</HEAD><BODY>
<H1>openvpn</H1>
Section: Maintenance Commands (8)<BR>Updated: 28 February 2018<BR><A HREF="#index">Index</A>
<A HREF="/cgi-bin/man/man2html">Return to Main Contents</A><HR>
<A NAME="lbAB"> </A>
<H2>NAME</H2>
openvpn - secure IP tunnel daemon.
<A NAME="lbAC"> </A>
<H2>SYNOPSIS</H2>
<B>
openvpn [ options ... ]
</B>
<A NAME="lbAD"> </A>
<H2>INTRODUCTION</H2>
<P>
OpenVPN is an open source VPN daemon by James Yonan.
Because OpenVPN tries to
be a universal VPN tool offering a great deal of flexibility,
there are a lot of options on this manual page.
If you're new to OpenVPN, you might want to skip ahead to the
examples section where you will see how to construct simple
VPNs on the command line without even needing a configuration file.
<P>
Also note that there's more documentation and examples on
the OpenVPN web site:
<I><A HREF="http://openvpn.net/">http://openvpn.net/</A></I>
<P>
And if you would like to see a shorter version of this manual,
see the openvpn usage message which can be obtained by
running
<B>openvpn</B>
without any parameters.
<A NAME="lbAE"> </A>
<H2>DESCRIPTION</H2>
<P>
OpenVPN is a robust and highly flexible VPN daemon.
OpenVPN supports SSL/TLS security, ethernet bridging,
TCP or UDP tunnel transport through proxies or NAT,
support for dynamic IP addresses and DHCP,
scalability to hundreds or thousands of users,
and portability to most major OS platforms.
<P>
OpenVPN is tightly bound to the OpenSSL library, and derives much
of its crypto capabilities from it.
<P>
OpenVPN supports
conventional encryption
using a pre-shared secret key
<B>(Static Key mode)</B>
or
public key security
<B>(SSL/TLS mode)</B>
using client & server certificates.
OpenVPN also
supports non-encrypted TCP/UDP tunnels.
<P>
OpenVPN is designed to work with the
<B>TUN/TAP</B>
virtual networking interface that exists on most platforms.
<P>
Overall, OpenVPN aims to offer many of the key features of IPSec but
with a relatively lightweight footprint.
<A NAME="lbAF"> </A>
<H2>OPTIONS</H2>
OpenVPN allows any option to be placed either on the command line
or in a configuration file. Though all command line options are preceded
by a double-leading-dash ("--"), this prefix can be removed when
an option is placed in a configuration file.
<DL COMPACT>
<DT><B>--help</B>
<DD>
Show options.
<DT><B>--config file</B>
<DD>
Load additional config options from
<B>file</B>
where each line corresponds to one command line option,
but with the leading '--' removed.
<P>
If
<B>--config file</B>
is the only option to the openvpn command,
the
<B>--config</B>
can be removed, and the command can be given as
<B>openvpn file</B>
<P>
Note that
configuration files can be nested to a reasonable depth.
<P>
Double quotation or single quotation characters ("", '')
can be used to enclose single parameters containing whitespace,
and "#" or ";" characters in the first column
can be used to denote comments.
<P>
Note that OpenVPN 2.0 and higher performs backslash-based shell
escaping for characters not in single quotations,
so the following mappings should be observed:
<P>
<PRE>
<B>\\ Maps to a single backslash character (\).
\" Pass a literal doublequote character ("), don't
interpret it as enclosing a parameter.
\[SPACE] Pass a literal space or tab character, don't
interpret it as a parameter delimiter.
</B></PRE>
<P>
For example on Windows, use double backslashes to
represent pathnames:
<P>
<PRE>
<B>secret "c:\\OpenVPN\\secret.key"
</B></PRE>
<P>
For examples of configuration files,
see
<I><A HREF="http://openvpn.net/examples.html">http://openvpn.net/examples.html</A></I>
<P>
Here is an example configuration file:
<P>
<PRE>
<B>#
# Sample OpenVPN configuration file for
# using a pre-shared static key.
#
# '#' or ';' may be used to delimit comments.
# Use a dynamic tun device.
dev tun
# Our remote peer
remote mypeer.mydomain
# 10.1.0.1 is our local VPN endpoint
# 10.1.0.2 is our remote VPN endpoint
ifconfig 10.1.0.1 10.1.0.2
# Our pre-shared static key
secret static.key
</B></PRE>
</DL>
<A NAME="lbAG"> </A>
<H3>Tunnel Options:</H3>
<DL COMPACT>
<DT><B>--mode m</B>
<DD>
Set OpenVPN major mode. By default, OpenVPN runs in
point-to-point mode ("p2p"). OpenVPN 2.0 introduces
a new mode ("server") which implements a multi-client
server capability.
<DT><B>--local host</B>
<DD>
Local host name or IP address for bind.
If specified, OpenVPN will bind to this address only.
If unspecified, OpenVPN will bind to all interfaces.
<DT><B>--remote host [port] [proto]</B>
<DD>
Remote host name or IP address. On the client, multiple
<B>--remote</B>
options may be specified for redundancy, each referring
to a different OpenVPN server. Specifying multiple
<B>--remote</B>
options for this purpose is a special case of the more
general connection-profile feature. See the
<B><connection></B>
documentation below.
<P>
The OpenVPN client will try to connect to a server at
<B>host:port</B>
in the order specified by the list of
<B>--remote</B>
options.
<P>
<B>proto</B>
indicates the protocol to use when connecting with the
remote, and may be "tcp" or "udp".
<P>
For forcing IPv4 or IPv6 connection suffix tcp or udp
with 4/6 like udp4/udp6/tcp4/tcp6.
<P>
The client will move on to the next host in the list,
in the event of connection failure.
Note that at any given time, the OpenVPN client
will at most be connected to
one server.
<P>
Note that since UDP is connectionless, connection failure
is defined by the
<B>--ping</B>
and
<B>--ping-restart</B>
options.
<P>
Note the following corner case: If you use multiple
<B>--remote</B>
options, AND you are dropping root privileges on
the client with
<B>--user</B>
and/or
<B>--group,</B>
AND the client is running a non-Windows OS, if the client needs
to switch to a different server, and that server pushes
back different TUN/TAP or route settings, the client may lack
the necessary privileges to close and reopen the TUN/TAP interface.
This could cause the client to exit with a fatal error.
<P>
If
<B>--remote</B>
is unspecified, OpenVPN will listen
for packets from any IP address, but will not act on those packets unless
they pass all authentication tests. This requirement for authentication
is binding on all potential peers, even those from known and supposedly
trusted IP addresses (it is very easy to forge a source IP address on
a UDP packet).
<P>
When used in TCP mode,
<B>--remote</B>
will act as a filter, rejecting connections from any host which does
not match
<B>host.</B>
<P>
If
<B>host</B>
is a DNS name which resolves to multiple IP addresses,
OpenVPN will try them in the order that the system getaddrinfo()
presents them, so priorization and DNS randomization is done
by the system library. Unless an IP version is forced by the
protocol specification (4/6 suffix), OpenVPN will try both IPv4
and IPv6 addresses, in the order getaddrinfo() returns them.
<DT><B>--remote-random-hostname</B>
<DD>
Prepend a random string (6 bytes, 12 hex characters) to hostname to prevent
DNS caching. For example, "foo.bar.gov" would be modified to
"<random-chars>.foo.bar.gov".
<DT><B><connection></B>
<DD>
Define a client connection
profile. Client connection profiles are groups of OpenVPN options that
describe how to connect to a given OpenVPN server. Client connection
profiles are specified within an OpenVPN configuration file, and
each profile is bracketed by
<B><connection></B>
and
<B></connection>.</B>
<P>
An OpenVPN client will try each connection profile sequentially
until it achieves a successful connection.
<P>
<B>--remote-random</B>
can be used to initially "scramble" the connection
list.
<P>
Here is an example of connection profile usage:
<P>
<PRE>
<B>client
dev tun
<connection>
remote 198.19.34.56 1194 udp
</connection>
<connection>
remote 198.19.34.56 443 tcp
</connection>
<connection>
remote 198.19.34.56 443 tcp
http-proxy 192.168.0.8 8080
</connection>
<connection>
remote 198.19.36.99 443 tcp
http-proxy 192.168.0.8 8080
</connection>
persist-key
persist-tun
pkcs12 client.p12
remote-cert-tls server
verb 3
</B></PRE>
<P>
First we try to connect to a server at 198.19.34.56:1194 using UDP.
If that fails, we then try to connect to 198.19.34.56:443 using TCP.
If that also fails, then try connecting through an HTTP proxy at
192.168.0.8:8080 to 198.19.34.56:443 using TCP. Finally, try to
connect through the same proxy to a server at 198.19.36.99:443
using TCP.
<P>
The following OpenVPN options may be used inside of
a
<B><connection></B>
block:
<P>
<B>bind,</B>
<B>connect-retry,</B>
<B>connect-retry-max,</B>
<B>connect-timeout,</B>
<B>explicit-exit-notify,</B>
<B>float,</B>
<B>fragment,</B>
<B>http-proxy,</B>
<B>http-proxy-option,</B>
<B>link-mtu,</B>
<B>local,</B>
<B>lport,</B>
<B>mssfix,</B>
<B>mtu-disc,</B>
<B>nobind,</B>
<B>port,</B>
<B>proto,</B>
<B>remote,</B>
<B>rport,</B>
<B>socks-proxy,</B>
<B>tun-mtu and</B>
<B>tun-mtu-extra.</B>
<P>
A defaulting mechanism exists for specifying options to apply to
all
<B><connection></B>
profiles. If any of the above options (with the exception of
<B>remote</B>
) appear outside of a
<B><connection></B>
block, but in a configuration file which has one or more
<B><connection></B>
blocks, the option setting will be used as a default for
<B><connection></B>
blocks which follow it in the configuration file.
<P>
For example, suppose the
<B>nobind</B>
option were placed in the sample configuration file above, near
the top of the file, before the first
<B><connection></B>
block. The effect would be as if
<B>nobind</B>
were declared in all
<B><connection></B>
blocks below it.
<DT><B>--proto-force p</B>
<DD>
When iterating through connection profiles,
only consider profiles using protocol
<B>p</B>
('tcp'|'udp').
<DT><B>--remote-random</B>
<DD>
When multiple
<B>--remote</B>
address/ports are specified, or if connection profiles are being
used, initially randomize the order of the list
as a kind of basic load-balancing measure.
<DT><B>--proto p</B>
<DD>
Use protocol
<B>p</B>
for communicating with remote host.
<B>p</B>
can be
<B>udp,</B>
<B>tcp-client,</B>
or
<B>tcp-server.</B>
<P>
The default protocol is
<B>udp</B>
when
<B>--proto</B>
is not specified.
<P>
For UDP operation,
<B>--proto udp</B>
should be specified on both peers.
<P>
For TCP operation, one peer must use
<B>--proto tcp-server</B>
and the other must use
<B>--proto tcp-client.</B>
A peer started with
<B>tcp-server</B>
will wait indefinitely for an incoming connection. A peer
started with
<B>tcp-client</B>
will attempt to connect, and if that fails, will sleep for 5
seconds (adjustable via the
<B>--connect-retry</B>
option) and try again infinite or up to N retries (adjustable via the
<B>--connect-retry-max</B>
option). Both TCP client and server will simulate
a SIGUSR1 restart signal if either side resets the connection.
<P>
OpenVPN is designed to operate optimally over UDP, but TCP capability is provided
for situations where UDP cannot be used.
In comparison with UDP, TCP will usually be
somewhat less efficient and less robust when used over unreliable or congested
networks.
<P>
This article outlines some of problems with tunneling IP over TCP:
<P>
<I><A HREF="http://sites.inka.de/sites/bigred/devel/tcp-tcp.html">http://sites.inka.de/sites/bigred/devel/tcp-tcp.html</A></I>
<P>
There are certain cases, however, where using TCP may be advantageous from
a security and robustness perspective, such as tunneling non-IP or
application-level UDP protocols, or tunneling protocols which don't
possess a built-in reliability layer.
<DT><B>--connect-retry n [max]</B>
<DD>
Wait
<B>n</B>
seconds between connection attempts (default=5). Repeated reconnection
attempts are slowed down after 5 retries per remote by doubling the wait
time after each unsuccessful attempt. The optional argument
<B>max</B>
specifies the maximum value of wait time in seconds at which it gets
capped (default=300).
<DT><B>--connect-retry-max n</B>
<DD>
<B>n</B>
specifies the number of times each
<B>--remote</B>
or
<B><connection></B>
entry is tried. Specifying
<B>n</B>
as one would try each entry exactly once. A successful connection
resets the counter. (default=unlimited).
<DT><B>--show-proxy-settings</B>
<DD>
Show sensed HTTP or SOCKS proxy settings. Currently, only Windows clients
support this option.
<DT><B>--http-proxy server port [authfile|'auto'|'auto-nct'] [auth-method]</B>
<DD>
Connect to remote host through an HTTP proxy at address
<B>server</B>
and port
<B>port.</B>
If HTTP Proxy-Authenticate is required,
<B>authfile</B>
is a file containing a username and password on 2 lines, or
"stdin" to prompt from console. Its content can also be specified
in the config file with the
<B>--http-proxy-user-pass</B>
option. (See section on inline files)
<P>
<B>auth-method</B>
should be one of "none", "basic", or "ntlm".
<P>
HTTP Digest authentication is supported as well, but only via
the
<B>auto</B>
or
<B>auto-nct</B>
flags (below).
<P>
The
<B>auto</B>
flag causes OpenVPN to automatically determine the
<B>auth-method</B>
and query stdin or the management interface for
username/password credentials, if required. This flag
exists on OpenVPN 2.1 or higher.
<P>
The
<B>auto-nct</B>
flag (no clear-text auth) instructs OpenVPN to automatically
determine the authentication method, but to reject weak
authentication protocols such as HTTP Basic Authentication.
<DT><B>--http-proxy-option type [parm]</B>
<DD>
Set extended HTTP proxy options.
Repeat to set multiple options.
<P>
<B>VERSION version --</B>
Set HTTP version number to
<B>version</B>
(default=1.0).
<P>
<B>AGENT user-agent --</B>
Set HTTP "User-Agent" string to
<B>user-agent.</B>
<P>
<B>CUSTOM-HEADER name content --</B>
Adds the custom Header with
<B>name</B>
as name and
<B>content</B>
as the content of the custom HTTP header.
<DT><B>--socks-proxy server [port] [authfile]</B>
<DD>
Connect to remote host through a Socks5 proxy at address
<B>server</B>
and port
<B>port</B>
(default=1080).
<B>authfile</B>
(optional) is a file containing a username and password on 2 lines, or
"stdin" to prompt from console.
<DT><B>--resolv-retry n</B>
<DD>
If hostname resolve fails for
<B>--remote,</B>
retry resolve for
<B>n</B>
seconds before failing.
<P>
Set
<B>n</B>
to "infinite" to retry indefinitely.
<P>
By default,
<B>--resolv-retry infinite</B>
is enabled. You can disable by setting n=0.
<DT><B>--float</B>
<DD>
Allow remote peer to change its IP address and/or port number, such as due to
DHCP (this is the default if
<B>--remote</B>
is not used).
<B>--float</B>
when specified with
<B>--remote</B>
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.
<P>
Essentially,
<B>--float</B>
tells OpenVPN to accept authenticated packets
from any address, not only the address which was specified in the
<B>--remote</B>
option.
<DT><B>--ipchange cmd</B>
<DD>
Run command
<B>cmd</B>
when our remote ip-address is initially authenticated or
changes.
<P>
<B>cmd</B>
consists of a path to script (or executable program), optionally
followed by arguments. The path and arguments may be single- or double-quoted
and/or escaped using a backslash, and should be separated by one or more spaces.
<P>
When
<B>cmd</B>
is executed two arguments are appended after any arguments specified in
<B>cmd</B>
, as follows:
<P>
<B>cmd ip_address port_number</B>
<P>
Don't use
<B>--ipchange</B>
in
<B>--mode server</B>
mode. Use a
<B>--client-connect</B>
script instead.
<P>
See