openvpn.8

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

.\"  OpenVPN -- An application to securely tunnel IP networks
.\"             over a single TCP/UDP port, with support for SSL/TLS-based
.\"             session authentication and key exchange,
.\"             packet encryption, packet authentication, and
.\"             packet compression.
.\"
.\"  Copyright (C) 2002-2004 James Yonan <[e-mail]>
.\"
.\"  This program is free software; you can redistribute it and/or modify
.\"  it under the terms of the GNU General Public License as published by
.\"  the Free Software Foundation; either version 2 of the License, or
.\"  (at your option) any later version.
.\"
.\"  This program is distributed in the hope that it will be useful,
.\"  but WITHOUT ANY WARRANTY; without even the implied warranty of
.\"  MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
.\"  GNU General Public License for more details.
.\"
.\"  You should have received a copy of the GNU General Public License
.\"  along with this program (see the file COPYING included with this
.\"  distribution); if not, write to the Free Software Foundation, Inc.,
.\"  59 Temple Place, Suite 330, Boston, MA  02111-1307  USA
.\"
.\" Manual page for openvpn
.\" SH section heading
.\" SS subsection heading
.\" LP paragraph
.\" IP indented paragraph
.\" TP hanging label
openvpn
.TH openvpn 8 "2 June 2004"
.SH NAME
openvpn \- secure IP tunnel daemon.
.SH SYNOPSIS
.LP
.nh
.in +4
.ti -4
.B openvpn
[\ \fB\-\-help\fR\ ]
.in -4
.ti +4
.hy

.nh
.in +4
.ti -4
.B openvpn
[\ \fB\-\-config\fR\ \fIfile\fR\ ]
.in -4
.ti +4
.hy

.nh
.in +4
.ti -4
.B openvpn
[\ \fB\-\-genkey\fR\ ]
[\ \fB\-\-secret\fR\ \fIfile\fR\ ]
.in -4
.ti +4
.hy

.nh
.in +4
.ti -4
.B openvpn
[\ \fB\-\-mktun\fR\ ]
[\ \fB\-\-rmtun\fR\ ]
[\ \fB\-\-dev\fR\ \fItunX\ |\ tapX\fR\ ]
[\ \fB\-\-dev\-type\fR\ \fIdevice\-type\fR\ ]
[\ \fB\-\-dev\-node\fR\ \fInode\fR\ ]
.in -4
.ti +4
.hy

.nh
.in +4
.ti -4
.B openvpn
[\ \fB\-\-test\-crypto\fR\ ]
[\ \fB\-\-secret\fR\ \fIfile\fR\ ]
[\ \fB\-\-auth\fR\ \fIalg\fR\ ]
[\ \fB\-\-cipher\fR\ \fIalg\fR\ ]
[\ \fB\-\-engine\fR\ ]
[\ \fB\-\-keysize\fR\ \fIn\fR\ ]
[\ \fB\-\-no\-replay\fR\ ]
[\ \fB\-\-no\-iv\fR\ ]
.in -4
.ti +4
.hy

.nh
.in +4
.ti -4
.B openvpn
[\ \fB\-\-askpass\fR\ ]
[\ \fB\-\-auth\fR\ \fIalg\fR\ ]
[\ \fB\-\-bcast\-buffers\fR\ \fIn\fR\ ]
[\ \fB\-\-ca\fR\ \fIfile\fR\ ]
[\ \fB\-\-cd\fR\ \fIdir\fR\ ]
[\ \fB\-\-cert\fR\ \fIfile\fR\ ]
[\ \fB\-\-chroot\fR\ \fIdir\fR\ ]
[\ \fB\-\-cipher\fR\ \fIalg\fR\ ]
[\ \fB\-\-client\-config\-dir\fR\ \fIdir\fR\ ]
[\ \fB\-\-client\-connect\fR\ \fIscript\fR\ ]
[\ \fB\-\-client\-connect\fR\ ]
[\ \fB\-\-client\-disconnect\fR\ ]
[\ \fB\-\-client\-disconnect\fR\ ]
[\ \fB\-\-client\-to\-client\fR\ ]
[\ \fB\-\-comp\-lzo\fR\ ]
[\ \fB\-\-comp\-noadapt\fR\ ]
[\ \fB\-\-config\fR\ \fIfile\fR\ ]
[\ \fB\-\-connect\-freq\fR\ \fIn\ sec\fR\ ]
[\ \fB\-\-connect\-retry\fR\ \fIn\fR\ ]
[\ \fB\-\-crl\-verify\fR\ \fIcrl\fR\ ]
[\ \fB\-\-daemon\fR\ \fI[progname]\fR\ ]
[\ \fB\-\-dev\-node\fR\ \fInode\fR\ ]
[\ \fB\-\-dev\-type\fR\ \fIdevice\-type\fR\ ]
[\ \fB\-\-dev\fR\ \fItunX\ |\ tapX\ |\ null\fR\ ]
[\ \fB\-\-dev\fR\ \fItunX\ |\ tapX\fR\ ]
[\ \fB\-\-dh\fR\ \fIfile\fR\ ]
[\ \fB\-\-dhcp\-option\fR\ \fItype\ [parm]\fR\ ]
[\ \fB\-\-disable\-occ\fR\ ]
[\ \fB\-\-down\fR\ \fIcmd\fR\ ]
[\ \fB\-\-down\fR\ ]
[\ \fB\-\-engine\fR\ ]
[\ \fB\-\-float\fR\ ]
[\ \fB\-\-fragment\fR\ \fImax\fR\ ]
[\ \fB\-\-genkey\fR\ ]
[\ \fB\-\-gremlin\fR\ ]
[\ \fB\-\-group\fR\ \fIgroup\fR\ ]
[\ \fB\-\-hand\-window\fR\ \fIn\fR\ ]
[\ \fB\-\-hash\-size\fR\ \fIr\ v\fR\ ]
[\ \fB\-\-help\fR\ ]
[\ \fB\-\-http\-proxy\-retry\fR\ ]
[\ \fB\-\-http\-proxy\fR\ \fIserver\ port\ [authfile]\fR\ ]
[\ \fB\-\-ifconfig\-noexec\fR\ ]
[\ \fB\-\-ifconfig\-nowarn\fR\ ]
[\ \fB\-\-ifconfig\-pool\fR\ \fIstart\-IP\ end\-IP\fR\ ]
[\ \fB\-\-ifconfig\-push\fR\ \fIlocal\ remote\-netmask\fR\ ]
[\ \fB\-\-ifconfig\fR\ \fIl\ rn\fR\ ]
[\ \fB\-\-inactive\fR\ \fIn\fR\ ]
[\ \fB\-\-inetd\fR\ \fI[wait|nowait]\ [progname]\fR\ ]
[\ \fB\-\-ip\-win32\fR\ \fImethod\fR\ ]
[\ \fB\-\-ipchange\fR\ \fIcmd\fR\ ]
[\ \fB\-\-ipchange\fR\ ]
[\ \fB\-\-iroute\fR\ \fInetwork\ [netmask]\fR\ ]
[\ \fB\-\-key\-method\fR\ \fIm\fR\ ]
[\ \fB\-\-key\fR\ \fIfile\fR\ ]
[\ \fB\-\-keysize\fR\ \fIn\fR\ ]
[\ \fB\-\-learn\-address\fR\ \fIcmd\fR\ ]
[\ \fB\-\-link\-mtu\fR\ \fIn\fR\ ]
[\ \fB\-\-local\fR\ \fIhost\fR\ ]
[\ \fB\-\-log\-append\fR\ \fIfile\fR\ ]
[\ \fB\-\-log\fR\ \fIfile\fR\ ]
[\ \fB\-\-lport\fR\ \fIport\fR\ ]
[\ \fB\-\-mktun\fR\ ]
[\ \fB\-\-mlock\fR\ ]
[\ \fB\-\-mode\fR\ \fIm\fR\ ]
[\ \fB\-\-mssfix\fR\ \fImax\fR\ ]
[\ \fB\-\-mtu\-disc\fR\ \fItype\fR\ ]
[\ \fB\-\-mtu\-test\fR\ ]
[\ \fB\-\-mute\fR\ \fIn\fR\ ]
[\ \fB\-\-nice\-work\fR\ \fIn\fR\ ]
[\ \fB\-\-nice\fR\ \fIn\fR\ ]
[\ \fB\-\-no\-iv\fR\ ]
[\ \fB\-\-no\-replay\fR\ ]
[\ \fB\-\-nobind\fR\ ]
[\ \fB\-\-passtos\fR\ ]
[\ \fB\-\-pause\-exit\fR\ ]
[\ \fB\-\-persist\-key\fR\ ]
[\ \fB\-\-persist\-local\-ip\fR\ ]
[\ \fB\-\-persist\-remote\-ip\fR\ ]
[\ \fB\-\-persist\-tun\fR\ ]
[\ \fB\-\-ping\-exit\fR\ \fIn\fR\ ]
[\ \fB\-\-ping\-restart\fR\ \fIn\fR\ ]
[\ \fB\-\-ping\-timer\-rem\fR\ ]
[\ \fB\-\-ping\fR\ \fIn\fR\ ]
[\ \fB\-\-port\fR\ \fIport\fR\ ]
[\ \fB\-\-proto\fR\ \fIp\fR\ ]
[\ \fB\-\-pull\fR\ ]
[\ \fB\-\-push\-reset\fR\ ]
[\ \fB\-\-push\fR\ \fI"option"\fR\ ]
[\ \fB\-\-rcvbuf\fR\ \fIsize\fR\ ]
[\ \fB\-\-redirect\-gateway\fR\ \fI['local']\fR\ ]
[\ \fB\-\-remote\-random\fR\ ]
[\ \fB\-\-remote\fR\ \fIhost\ [port]\fR\ ]
[\ \fB\-\-reneg\-bytes\fR\ \fIn\fR\ ]
[\ \fB\-\-reneg\-pkts\fR\ \fIn\fR\ ]
[\ \fB\-\-reneg\-sec\fR\ \fIn\fR\ ]
[\ \fB\-\-replay\-persist\fR\ \fIfile\fR\ ]
[\ \fB\-\-replay\-window\fR\ \fIn\ [t]\fR\ ]
[\ \fB\-\-resolv\-retry\fR\ \fIn\fR\ ]
[\ \fB\-\-rmtun\fR\ ]
[\ \fB\-\-route\-delay\fR\ \fI[n]\fR\ ]
[\ \fB\-\-route\-gateway\fR\ \fIgw\fR\ ]
[\ \fB\-\-route\-noexec\fR\ ]
[\ \fB\-\-route\-up\fR\ \fIcmd\fR\ ]
[\ \fB\-\-route\-up\fR\ ]
[\ \fB\-\-route\fR\ \fInetwork\ [netmask]\ [gateway]\ [metric]\fR\ ]
[\ \fB\-\-rport\fR\ \fIport\fR\ ]
[\ \fB\-\-service\fR\ \fIexit\-event\ [0|1]\fR\ ]
[\ \fB\-\-secret\fR\ \fIfile\ [direction]\fR\ ]
[\ \fB\-\-secret\fR\ \fIfile\fR\ ]
[\ \fB\-\-setenv\fR\ \fIname\ value\fR\ ]
[\ \fB\-\-shaper\fR\ \fIn\fR\ ]
[\ \fB\-\-show\-adapters\fR\ ]
[\ \fB\-\-show\-ciphers\fR\ ]
[\ \fB\-\-show\-digests\fR\ ]
[\ \fB\-\-show\-tls\fR\ ]
[\ \fB\-\-show\-valid\-subnets\fR\ ]
[\ \fB\-\-single\-session\fR\ ]
[\ \fB\-\-sndbuf\fR\ \fIsize\fR\ ]
[\ \fB\-\-socks\-proxy\-retry\fR\ ]
[\ \fB\-\-socks\-proxy\fR\ \fIserver\ [port]\fR\ ]
[\ \fB\-\-status\fR\ \fIfile\ [n]\fR\ ]
[\ \fB\-\-tap\-sleep\fR\ \fIn\fR\ ]
[\ \fB\-\-test\-crypto\fR\ ]
[\ \fB\-\-tls\-auth\fR\ \fIfile\ [direction]\fR\ ]
[\ \fB\-\-tls\-cipher\fR\ \fIl\fR\ ]
[\ \fB\-\-tls\-client\fR\ ]
[\ \fB\-\-tls\-remote\fR\ \fIx509name\fR\ ]
[\ \fB\-\-tls\-server\fR\ ]
[\ \fB\-\-tls\-timeout\fR\ \fIn\fR\ ]
[\ \fB\-\-tls\-verify\fR\ \fIcmd\fR\ ]
[\ \fB\-\-tls\-verify\fR\ ]
[\ \fB\-\-tmp\-dir\fR\ \fIdir\fR\ ]
[\ \fB\-\-tran\-window\fR\ \fIn\fR\ ]
[\ \fB\-\-tun\-ipv6\fR\ ]
[\ \fB\-\-tun\-mtu\-extra\fR\ \fIn\fR\ ]
[\ \fB\-\-tun\-mtu\fR\ \fIn\fR\ ]
[\ \fB\-\-txqueuelen\fR\ \fIn\fR\ ]
[\ \fB\-\-up\-delay\fR\ ]
[\ \fB\-\-up\-restart\fR\ ]
[\ \fB\-\-up\fR\ \fIcmd\fR\ ]
[\ \fB\-\-up\fR\ ]
[\ \fB\-\-user\fR\ \fIuser\fR\ ]
[\ \fB\-\-verb\fR\ \fIn\fR\ ]
[\ \fB\-\-writepid\fR\ \fIfile\fR\ ]
.in -4
.ti +4
.hy
.SH DESCRIPTION
.LP
OpenVPN is a robust and highly configurable VPN (Virtual Private Network)
daemon which can be used to securely link two or more private networks
using an encrypted tunnel over the Internet. OpenVPN's principal strengths
include wide cross-platform portability, excellent stability,
support for dynamic IP addresses and NAT, adaptive link compression,
single TCP/UDP port usage, a modular design that offloads most crypto
tasks to the OpenSSL library, and relatively easy installation that in
most cases doesn't require a special kernel module.

OpenVPN is tightly bound to the OpenSSL library, and derives much
of its crypto capabilities from it.

OpenVPN supports
conventional encryption
using a pre-shared secret key
.B (Static Key mode)
or
public key security
.B (SSL/TLS mode)
using client & server certificates.
OpenVPN also
supports non-encrypted TCP/UDP tunnels.  

OpenVPN is designed to work with the
.B TUN/TAP
virtual networking interface that exists on most platforms.

Overall, OpenVPN aims to offer many of the key features of IPSec but
with a relatively lightweight footprint.
.SH OPTIONS
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.
.TP
.B --help
Show options.
.TP
.B --config file
Load additional config options from
.B file
where each line corresponds to one command line option,
but with the leading '--' removed.

Double quotation characters ("") can be used
to enclose single parameters containing whitespace,
and "#" or ";" characters in the first column
can be used to denote comments.

Configuration files can be nested to a reasonable depth.

For examples of configuration files,
see
.I http://openvpn.sourceforge.net/examples.html

Here is an example configuration file:
.RS
.ft 3
.nf
.sp
#
# 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
.ft
.LP
.RE
.fi
.SS Tunnel Options:
.TP
.B --mode m
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.
.TP
.B --local host
Local host name or IP address.
If specified, OpenVPN will bind to this address only.
If unspecified, OpenVPN will bind to all interfaces.
.TP
.B --remote host [port]
Remote host name or IP address.  Multiple
.B --remote
options may be specified for a client which
is connecting to a multi-client UDP server.
OpenVPN will try each
.B host:port
in the order specified,
moving on to the next host in the event of connection failure.
Note that since UDP is connectionless, connection failure
is defined by the
.B --ping
and
.B --ping-restart
options.

If
.B --remote
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).

When used in TCP mode, 
.B --remote
will act as a filter, rejecting connections from any host which does
not match
.B host.

If
.B host
resolves to multiple IP addresses, one will be randomly
chosen, providing a sort of basic load-balancing and
failover capability.
.TP
.B --remote-random
When multiple
.B --remote
address/ports are specified, initially randomize the order of the list
as a kind of basic load-balancing measure.
.TP
.B --proto p
Use protocol
.B p
for communicating with remote host.
.B p
can be
.B udp,
.B tcp-client,
or
.B tcp-server.

The default protocol is
.B udp
when
.B --proto
is not specified.

For UDP operation,
.B --proto udp
should be specified on both peers.

For TCP operation, one peer must use
.B --proto tcp-server
and the other must use
.B --proto tcp-client.
A peer started with
.B tcp-server
will wait indefinitely for an incoming connection.  A peer
started with
.B tcp-client
will attempt to connect, and if that fails, will sleep for 5
seconds (adjustable via the
.B --connect-retry
option) and try again.  Both TCP client and server will simulate
a SIGUSR1 restart signal if either side resets the connection.

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.

This article outlines some of problems with tunneling IP over TCP:

.I http://sites.inka.de/sites/bigred/devel/tcp-tcp.html

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.
.TP
.B --connect-retry n
For
.B --proto tcp-client,
take
.B n
as the
number of seconds to wait
between connection retries (default=5).
.TP
.B --http-proxy server port [authfile]
Connect to remote host through an HTTP proxy at address
.B server
and port
.B port.
If HTTP Proxy-Authenticate is required,
.B authfile
is a file containing a username and password on 2 lines.
.TP
.B --http-proxy-retry
Retry indefinitely on HTTP proxy errors.  If an HTTP proxy error
occurs, simulate a SIGUSR1 reset.
.TP