openvpn.8

一个开源的VPN原码

.\" Manual page for openvpn
.\" SH section heading
.\" SS subsection heading
.\" LP paragraph
.\" IP indented paragraph
.\" TP hanging label
openvpn
.TH openvpn 8 "20 October 2002"
.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\-\-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\-\-config\fR\ \fIfile\fR\ ]
[\ \fB\-\-local\fR\ \fIhost\fR\ ]
[\ \fB\-\-remote\fR\ \fIhost\fR\ ]
[\ \fB\-\-resolv\-retry\fR\ \fIn\fR\ ]
[\ \fB\-\-float\fR\ ]
[\ \fB\-\-ipchange\fR\ \fIcmd\fR\ ]
[\ \fB\-\-port\fR\ \fIport\fR\ ]
[\ \fB\-\-lport\fR\ \fIport\fR\ ]
[\ \fB\-\-rport\fR\ \fIport\fR\ ]
[\ \fB\-\-nobind\fR\ ]
[\ \fB\-\-dev\fR\ \fItunX\ |\ tapX\ |\ null\fR\ ]
[\ \fB\-\-tun\-ipv6\fR\ ]
[\ \fB\-\-dev\-type\fR\ \fIdevice\-type\fR\ ]
[\ \fB\-\-dev\-node\fR\ \fInode\fR\ ]
[\ \fB\-\-ifconfig\fR\ \fIl\ r\fR\ ]
[\ \fB\-\-udp\-mtu\fR\ \fIn\fR\ ]
[\ \fB\-\-tun\-mtu\fR\ \fIn\fR\ ]
[\ \fB\-\-shaper\fR\ \fIn\fR\ ]
[\ \fB\-\-inactive\fR\ \fIn\fR\ ]
[\ \fB\-\-ping\fR\ \fIn\fR\ ]
[\ \fB\-\-ping\-exit\fR\ \fIn\fR\ ]
[\ \fB\-\-ping\-restart\fR\ \fIn\fR\ ]
[\ \fB\-\-ping\-timer\-rem\fR\ ]
[\ \fB\-\-persist\-tun\fR\ ]
[\ \fB\-\-persist\-key\fR\ ]
[\ \fB\-\-persist\-local\-ip\fR\ ]
[\ \fB\-\-persist\-remote\-ip\fR\ ]
[\ \fB\-\-mlock\fR\ ]
[\ \fB\-\-up\fR\ \fIcmd\fR\ ]
[\ \fB\-\-down\fR\ \fIcmd\fR\ ]
[\ \fB\-\-user\fR\ \fIuser\fR\ ]
[\ \fB\-\-group\fR\ \fIgroup\fR\ ]
[\ \fB\-\-cd\fR\ \fIdir\fR\ ]
[\ \fB\-\-chroot\fR\ \fIdir\fR\ ]
[\ \fB\-\-daemon\fR\ ]
[\ \fB\-\-inetd\fR\ ]
[\ \fB\-\-writepid\fR\ \fIfile\fR\ ]
[\ \fB\-\-nice\fR\ \fIn\fR\ ]
[\ \fB\-\-nice\-work\fR\ \fIn\fR\ ]
[\ \fB\-\-verb\fR\ \fIn\fR\ ]
[\ \fB\-\-mute\fR\ \fIn\fR\ ]
[\ \fB\-\-gremlin\fR\ ]
[\ \fB\-\-comp\-lzo\fR\ ]
[\ \fB\-\-comp\-noadapt\fR\ ]
[\ \fB\-\-secret\fR\ \fIfile\fR\ ]
[\ \fB\-\-auth\fR\ \fIalg\fR\ ]
[\ \fB\-\-cipher\fR\ \fIalg\fR\ ]
[\ \fB\-\-keysize\fR\ \fIn\fR\ ]
[\ \fB\-\-no\-replay\fR\ ]
[\ \fB\-\-no\-iv\fR\ ]
[\ \fB\-\-tls\-server\fR\ ]
[\ \fB\-\-tls\-client\fR\ ]
[\ \fB\-\-ca\fR\ \fIfile\fR\ ]
[\ \fB\-\-dh\fR\ \fIfile\fR\ ]
[\ \fB\-\-cert\fR\ \fIfile\fR\ ]
[\ \fB\-\-key\fR\ \fIfile\fR\ ]
[\ \fB\-\-tls\-cipher\fR\ \fIl\fR\ ]
[\ \fB\-\-tls\-timeout\fR\ \fIn\fR\ ]
[\ \fB\-\-reneg\-bytes\fR\ \fIn\fR\ ]
[\ \fB\-\-reneg\-pkts\fR\ \fIn\fR\ ]
[\ \fB\-\-reneg\-sec\fR\ \fIn\fR\ ]
[\ \fB\-\-hand\-window\fR\ \fIn\fR\ ]
[\ \fB\-\-tran\-window\fR\ \fIn\fR\ ]
[\ \fB\-\-single\-session\fR\ ]
[\ \fB\-\-tls\-auth\fR\ \fIf\fR\ ]
[\ \fB\-\-askpass\fR\ ]
[\ \fB\-\-tls\-verify\fR\ \fIcmd\fR\ ]
[\ \fB\-\-disable\-occ\fR\ ]
.in -4
.ti +4
.hy
.SH DESCRIPTION
.LP
OpenVPN is a robust and highly configurable secure tunneling daemon which
tunnels IP networks over UDP.  OpenVPN provides a comprehensive suite of
security features including conventional encryption, public key encryption,
dynamic key exchange, perfect forward security,
and the choice of any cipher, key size, or HMAC digest (for packet
authentication) offered by the
.B OpenSSL
library.

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

When used in 
public key
encryption mode, OpenVPN utilizes the
.B TLS
protocol for peer authentication and dynamic key exchange.
TLS is the latest evolution of the SSL family of protocols developed
originally by Netscape for their first secure web browser.
TLS and its SSL predecessors
have seen widespread usage on the web for many years
and have been extensively analyzed for weaknesses.  As such,
I believe TLS is an excellent choice for the authentication and key exchange
mechanism of a VPN product.

In TLS mode, OpenVPN uses a dual control-channel/data-channel mode of operation.
The control channel runs a TLS session which is used to exchange randomly
generated cipher and HMAC keys.
Those keys are then used to encrypt and authenticate the data channel.
Both channels are multiplexed
over a single UDP port.  A reliability layer is placed over the control channel
since TLS expects a reliable connection.  The data channel is passed unmediated
over the UDP channel since the higher level protocols running over the tunnel
(such as TCP)
will expect such behaviour.  The control channel will trigger a new key
exchange handshake periodically, according to user-specified parameters.

OpenVPN's key exchange protocol has been designed for both security
and resilience to unreliable network conditions.  The protocol
has been rigorously stress-tested in situations that simulate highly unreliable
networks which drop packets, suffer intermittent losses of connectivity,
and even corrupt packet data.  No version of OpenVPN is released unless
it passes this test suite
(see the
.B --gremlin 
option below).

OpenVPN is designed to work with the
.B tun/tap driver
which supports both IP and Ethernet
tunneling.  OpenVPN supports both dynamic and persistent tun/tap tunnels.
OpenVPN can construct multiple tunnels to or from the same peer and
will peacefully co-exist with other applications which construct tun/tap tunnels.

OpenVPN supports building multiple tunnels between the same two peers, where
each tunnel has a different maximum bandwidth (see the
.B --shaper
option below).

OpenVPN is designed to work well on systems which have dynamically assigned IP
addresses such as dial-in or DHCP users.  OpenVPN has no problem remaining in sync
even if
.I both
peers possess dynamic IP addresses, as long as they don't change their IP addresses
simultaneously.

OpenVPN is primarily a peer-to-peer application though it supports some
client/server modes such as the ability to designate a peer as
either a TLS server or client, or the ability to instantiate an OpenVPN peer without
an explicit remote peer address.

OpenVPN never uses more than a single UDP port to communicate with its peer.  OpenVPN
doesn't use the
.B GRE
protocol which can be a benefit for users running on networks that
discriminate against VPN users by blocking the GRE protocol.

OpenVPN is highly efficient while giving users flexibility in choosing
tradeoffs between efficiency and security.  All security options
which add packet overhead can be enabled or disabled with
command line options.

OpenVPN's build system is based on
.B automake
and
.B autoconf
and offers
several build options.  It can be built standalone, in which
case it will only offer non-encrypted UDP tunnels; it can be built
with the
.B LZO
real-time compression library; it can be built with the
OpenSSL crypto library which will give support for static private key encryption;
it can be built with the OpenSSL SSL library which will give full support
for certificates and TLS-based dynamic key exchange; and it can be built
with pthread support for improved latency in SSL/TLS mode.  For more information, consult
the
.B INSTALL
file included in the OpenVPN distribution.

OpenVPN aims to offer many of the key features of IPSec but
with a very lightweight footprint.
.SH OPTIONS
.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 can be used to denote comments.

Configuration files can be nested.

For examples of configuration files,
see the OpenVPN HOWTO at
.I http://openvpn.sourceforge.net/howto.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:
It should be noted that OpenVPN is a peer-to-peer application.  Each peer establishes
a symmetrical UDP link with its partner.  If an OpenVPN session is started without
an explicitly specified remote peer, OpenVPN will
wait until it receives an authenticated
packet from any IP address, in which case it will take this address as its peer.

One of the ramifications of this behaviour is that either
OpenVPN peer can be halted and restarted, and link will immediately resume.

OpenVPN also provides a session-usurp feature:
once a new session is authenticated it will
usurp an old session.  This is useful for dial-in users.
If your modem disconnects, and you
must reconnect to your ISP from a different IP address,
you will immediately be able to reconnect
to your remote OpenVPN peer and take control of the session.
An OpenVPN peer will not ignore an authenticated connection request,
even if it is busy trying to communicate with
an old IP address that just got disconnected.  There is one exception
to this behavior: the
.B --single-session
option will disable the session-usurp feature in TLS mode.  The option
does not apply in static-key mode, as it is a stateless protocol without
any notion of a session.

An OpenVPN peer will try to stay connected indefinitely, even under conditions of
high network error frequency, until it receives a SIGINT or SIGTERM signal,
or a time-out condition.
A major design goal of OpenVPN is that it should be as responsive, in terms of both normal
operations and error recovery, as the underlying IP layer that it is tunneling over.
That means that if the IP layer goes down for 5 minutes, when it comes back up,
tunnel traffic will immediately resume even if the outage interfered with
a dynamic key exchange which was scheduled during that time.
Because OpenVPN runs in a single-process, single-thread mode, and exclusively uses
non-blocked I/O, it is fairly immune to the problem of hung or unresponsive processes.

Another ramification of being a peer-to-peer application is
that OpenVPN will not dynamically
fork to accept new clients. 
If you have three clients who need to securely connect to a machine,
you should run 3 instantiations of OpenVPN on that machine,
each on a different UDP port
number.  This has certain advantages, among them being the
independence of each OpenVPN session.
If you need to bring one session down it won't
interfere with the others.  If you have tens
or hundreds of clients who want to connect to a
secure network, then you may want to consider
a more scalable solution such as IPSec.  OpenVPN is designed for
small networks but with
strong security requirements.  That being said however,
there's no reason why OpenVPN couldn't
scale to many users with the right underlying administration infrastructure.
.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
Remote host name or IP address.  If 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).
.TP
.B --resolv-retry n
If hostname resolve fails for
.B --local
or
.B --remote,
retry resolve for
.B n
seconds before failing (disabled by default).
.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: