openvpn.8

OpenVPN -- A Secure tunneling daemon

every packet on the control channel is authenticated by an
HMAC signature and a unique ID for replay protection.
This signature will also help protect against DoS (Denial of Service) attacks.
An important rule of thumb in reducing vulnerability to DoS attacks is to
minimize the amount of resources a potential, but as yet unauthenticated,
client is able to consume.

.B --tls-auth
does this by signing every TLS control channel packet with an HMAC signature,
including packets which are sent before the TLS level has had a chance
to authenticate the peer.
The result is that packets without
the correct signature can be dropped immediately upon reception,
before they have a chance to consume additional system resources
such as by initiating a TLS handshake.
.B --tls-auth
can be strengthened by adding the
.B --replay-persist
option which will keep OpenVPN's replay protection state
in a file so that it is not lost across restarts.

It should be emphasized that this feature is optional and that the
passphrase file used with
.B --tls-auth
gives a peer nothing more than the power to initiate a TLS
handshake.  It is not used to encrypt or authenticate any tunnel data.
.TP
.B --askpass
Get PEM password from controlling tty before we daemonize.  For the extremely
security conscious, it is possible to protect your private key with
a password.  Of course this means that every time the OpenVPN
daemon is started you must be there to type the password.  The
.B --askpass
option allows you to start OpenVPN from the command line.  It will
query you for a password before it daemonizes.  To protect a private
key with a password you should omit the
.B -nodes
option when you use the
.B openssl
command line tool to manage certificates and private keys.
.TP
.B --tls-verify cmd
Execute shell command
.B cmd
to verify the X509 name of a
pending TLS connection that has otherwise passed all other
tests of certification.
.B cmd
should return 0 to allow the TLS handshake to proceed, or 1 to fail.
.B cmd
is executed as

.B cmd certificate_depth X509_NAME_oneline

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.

This feature is useful if the peer you want to trust has a certificate
which was signed by a certificate authority who also signed a zillion
other certificates.  In this case you want to be selective about which
peer certificate you accept.  This feature allows you to write a script
which will test the X509 name on a certificate and decide whether or
not it should be accepted.  For a simple perl script which will test
the common name field on the certificate, see the file
.B verify-cn
in the OpenVPN distribution.
.TP
.B --disable-occ
Disable options compatibility check between peers.  This is designed
to circumvent OpenVPN's normal options compatibility check in
TLS mode.  Use of this option is discouraged, but is provided as
a temporary fix in situations where a recent version of OpenVPN must
connect to an old version.
.SS SSL Library information:
.TP
.B --show-ciphers
Show all cipher algorithms to use with the
.B --cipher
option.
.TP
.B --show-digests
Show all message digest algorithms to use with the
.B --auth
option.
.TP
.B --show-tls
Show all TLS ciphers (TLS used only as a control channel).  The TLS
ciphers will be sorted from highest preference (most secure) to
lowest.
.SS Generate a random key:
Used only for non-TLS static key encryption mode.
.TP
.B --genkey
Generate a random key to be used as a shared secret,
for use with the
.B --secret
option.  This file must be shared with the
peer over a pre-existing secure channel such as
.BR scp (1)
.
.TP
.B --secret file
Write key to
.B file.
.SS TUN/TAP persistent tunnel config mode:
Available with linux 2.4.7+.  These options comprise a standalone mode
of OpenVPN which can be used to create and delete persistent tunnels.
.TP
.B --mktun
Create a persistent tunnel.  Normally TUN/TAP tunnels exist only for
the period of time that an application has them open.  This option
takes advantage of the TUN/TAP driver's ability to build persistent
tunnels that live through multiple instantiations of OpenVPN and die
only when they are deleted or the machine is rebooted.

One of the advantages of persistent tunnels is that they eliminate the
need for separate
.B --up
and
.B --down
scripts to run the appropriate
.BR ifconfig (8)
and
.BR route (8)
commands.  These commands can be placed in the the same shell script
which starts or terminates an OpenVPN session.

Another advantage is that open connections through the TUN/TAP-based tunnel
will not be reset if the OpenVPN peer restarts.  This can be useful to
provide uninterrupted connectivity through the tunnel in the event of a DHCP
reset of the peer's public IP address (see the
.B --ipchange
option above).

One disadvantage of persistent tunnels is that it is harder to automatically
configure their MTU value (see
.B --udp-mtu
and
.B --tun-mtu
above).
.TP
.B --rmtun
Remove a persistent tunnel.
.TP
.B --dev tunX | tapX
TUN/TAP device
.SH SIGNALS
.TP
.B SIGHUP
Cause OpenVPN to close all TUN/TAP and
network connections,
restart, re-read the configuration file (if any),
and reopen TUN/TAP and network connections.
.TP
.B SIGUSR1
Like 
.B SIGHUP,
except don't re-read configuration file, and possibly don't close and reopen TUN/TAP
device, re-read key files, preserve local IP address/port, or preserve most recently authenticated
remote IP address/port based on
.B --persist-tun, --persist-key, --persist-local-ip,
and
.B --persist-remote-ip
options respectively (see above).

This signal may also be internally generated by a timeout condition, governed
by the
.B --ping-restart
option.

This signal, when combined with
.B --persist-remote-ip,
may be
sent when the underlying parameters of the host's network interface change
such as when the host is a DHCP client and is assigned a new IP address.
See
.B --ipchange
above for more information.
.TP
.B SIGUSR2
Causes OpenVPN to display its current statistics (to the syslog
file if
.B --daemon
is used, or stdout otherwise).
.TP
.B SIGINT, SIGTERM
Causes OpenVPN to exit gracefully.
.SH TUN/TAP DRIVER SETUP
If you are running Linux 2.4.7 or higher, you probably have the TUN/TAP driver
already installed.  If so, there are still a few things you need to do:

Make device:
.B mknod /dev/net/tun c 10 200

Load driver:
.B modprobe tun

If you have Linux 2.2 or earlier, you should obtain version 1.1 of the
TUN/TAP driver from
.I http://vtun.sourceforge.net/tun/
and follow the installation instructions.
.SH EXAMPLES
Prior to running these examples, you should have OpenVPN installed on two
machines with network connectivity between them.  If you have not
yet installed OpenVPN, consult the INSTALL file included in the OpenVPN
distribution.
.SS TUN/TAP Setup:
If you are using Linux 2.4 or higher,
make the tun device node and load the tun module:
.IP
.B mknod /dev/net/tun c 10 200
.LP
.IP
.B modprobe tun
.LP
If you installed from RPM, the
.B mknod
step may be omitted, because the RPM install does that for you.

If you have Linux 2.2, you should obtain version 1.1 of the
TUN/TAP driver from
.I http://vtun.sourceforge.net/tun/
and follow the installation instructions.

For other platforms, consult the INSTALL file at
.I http://openvpn.sourceforge.net/install.html
for more information.
.SS Firewall Setup:
If firewalls exist between
the two machines, they should be set to forward UDP port 5000
in both directions.  If you do not have control over the firewalls
between the two machines, you may still be able to use OpenVPN by adding
.B --ping 15
to each of the
.B openvpn
commands used below in the examples (this will cause each peer to send out
a UDP ping to its remote peer once every 15 seconds which will cause many
stateful firewalls to forward packets in both directions
without an explicit firewall rule).

If you are using a Linux iptables-based firewall, you may need to enter
the following command to allow incoming packets on the TUN device:
.IP
.B iptables -A INPUT -i tun+ -j ACCEPT
.LP
See the firewalls section below for more information on configuring firewalls
for use with OpenVPN.
.SS VPN Address Setup:
For purposes
of our example, our two machines will be called
.B may.kg
and
.B june.kg.
If you are constructing a VPN over the internet, then replace
.B may.kg
and
.B june.kg
with the internet hostname or IP address that each machine will use
to contact the other over the internet.

Now we will choose the tunnel endpoints.  Tunnel endpoints are
private IP addresses that only have meaning in the context of
the VPN.  Each machine will use the tunnel endpoint of the other
machine to access it over the VPN.  In our example,
the tunnel endpoint for may.kg
will be 10.4.0.1 and for june.kg, 10.4.0.2.

Once the VPN is established, you have essentially
created a secure alternate path between the two hosts
which is addressed by using the tunnel endpoints.  You can
control which network
traffic passes between the hosts 
(a) over the VPN or (b) independently of the VPN, by choosing whether to use
(a) the VPN endpoint address or (b) the public internet address,
to access the remote host. For example if you are on may.kg and you wish to connect to june.kg
via
.B ssh
without using the VPN (since
.B ssh
has its own built-in security) you would use the command
.B ssh june.kg.
However in the same scenario, you could also use the command
.B telnet 10.4.0.2
to create a telnet session with june.kg over the VPN, that would
use the VPN to secure the session rather than
.B ssh.

You can use any address you wish for the
tunnel endpoints
but make sure that they are private addresses
(such as those that begin with 10 or 192.168) and that they are
not part of any existing subnet on the networks of
either peer.  If you use an address that is part of
your local subnet for either of the tunnel endpoints,
you will get a weird feedback loop.
.SS Example 1: A simple tunnel without security
.LP
On may:
.IP
.B openvpn --remote june.kg --dev tun1 --ifconfig 10.4.0.1 10.4.0.2 --verb 9
.LP
On june:
.IP
.B openvpn --remote may.kg --dev tun1 --ifconfig 10.4.0.2 10.4.0.1 --verb 9
.LP
Now verify the tunnel is working by pinging across the tunnel.
.LP
On may:
.IP
.B ping 10.4.0.2
.LP
On june:
.IP
.B ping 10.4.0.1
.LP
The
.B --verb 9
option will produce verbose output, similar to the
.BR tcpdump (8)
program.  Omit the
.B --verb 9
option to have OpenVPN run quietly.
.SS Example 2: A tunnel with static-key security (i.e. using a pre-shared secret)
First build a static key on may.
.IP
.B openvpn --genkey --secret key
.LP
This command will build a random key file called
.B key
(in ascii format).
Now copy
.B key
to june over a secure medium such as by
using the
.BR scp (1)
program.
.LP
On may:
.IP
.B openvpn --remote june.kg --dev tun1 --ifconfig 10.4.0.1 10.4.0.2 --verb 5 --secret key
.LP
On june:
.IP
.B openvpn --remote may.kg --dev tun1 --ifconfig 10.4.0.2 10.4.0.1 --verb 5 --secret key
.LP
Now verify the tunnel is working by pinging across the tunnel.
.LP
On may:
.IP
.B ping 10.4.0.2
.LP
On june:
.IP
.B ping 10.4.0.1
.SS Example 3: A tunnel with full TLS-based security
For this test, we will designate
.B may
as the TLS client and
.B june
as the TLS server.
.I Note that client or server designation only has meaning for the TLS subsystem.  It has no bearing on OpenVPN's peer-to-peer, UDP-based communication model.

First, build a separate certificate/key pair
for both may and june (see above where
.B --cert
is discussed for more info).  Then construct
Diffie Hellman parameters (see above where
.B --dh
is discussed for more info).  You can also use the
included test files client.crt, client.key,
server.crt, server.key and tmp-ca.crt.
The .crt files are certificates/public-keys, the .key
files are private keys, and tmp-ca.crt is a certification
authority who has signed both
client.crt and server.crt.  For Diffie Hellman
parameters you can use the included file dh1024.pem.
.I Note that all client, server, and certificate authority certificates and keys included in the OpenVPN distribution are totally insecure and should be used for testing only.
.LP
On may:
.IP
.B openvpn --remote june.kg --dev tun1 --ifconfig 10.4.0.1 10.4.0.2 --tls-client --ca tmp-ca.crt --cert client.crt --key client.key --reneg-sec 60 --verb 5
.LP
On june:
.IP
.B openvpn --remote may.kg --dev tun1 --ifconfig 10.4.0.2 10.4.0.1 --tls-server --dh dh1024.pem --ca tmp-ca.crt --cert server.crt --key server.key --reneg-sec 60 --verb 5
.LP
Now verify the tunnel is working by pinging across the tunnel.
.LP
On may:
.IP
.B ping 10.4.0.2
.LP
On june:
.IP
.B ping 10.4.0.1
.LP
Notice the
.B --reneg-sec 60
option we used above.  That tells OpenVPN to renegotiate
the data channel keys every minute.
Since we used
.B --verb 5
above, you will see status information on each new key negotiation.

For production operations, a key renegotiation interval of 60 seconds
is probably too frequent.  Omit the
.B --reneg-sec 60
option to use OpenVPN's default key renegotiation interval of one hour.
.SS Routing:
Assuming you can ping across the tunnel,
the next step is to route a real subnet over
the secure tunnel.  Suppose that may and j