OPENVPN - 2 - BRIDGED VPN - SSL CERTS - CLIENT 2 SITE
######################################################
######################################################
OPENVPN BRIDGE VPN WITH SSL/TLS PKI SECURITY
############################################
############################################
Setting up a OpenVPN configuration from a Debian Server to a Debian Client. The Server is behind a firewall which has a port forward of port 50006 UDP to port 50006 UDP on the server, which gives it that needed UDP port. Note its better to use UDP for vpns as TCP over TCP tends to not work that well.
Also as a sidenote you will see port 50006 udp which is portforwarded at server www.server.com to the debian linux server behind the router (the router being the stronghold for www.server.com). You will also see port 50005 which is the tcp for ssh to access the client, so to clarify on my client network, www.client.com, there is a portforward setup on the router there that forward port 50005 tcp to 22 tcp on the debian client machine there.
TOPOLOGY:
<DEBIAN SERVER 172.18.10.21 /24>-[LAN 172.18.10.x]-[ROUTER www.server.com]========[internet========[ROUTER www.client.com]-[LAN 10.11.12.x]-<DEBIAN CLIENT 10.11.12.55 /24>
Note the debian server is actually sits on a vm which comes into play later on, the client is also a vm but that doesnt matter.
INSTALLATION:
###############
First before continuing install the following software on the server and the client, and make sure you have a putty/shell open for the server and client for easy navigation and inputing of commands.
ON SERVER:
apt-get install bridge-utils
apt-get install openvpn
apt-get install openssl
ON CLIENT:
apt-get install openvpn
apt-get install openssl
ON SERVER WE NEED TO MAKE THE BRIDGE START AND BRIDGE STOP SCRIPTS
###################################################################
cd /etc/openvpn
touch start.sh; chmod +x start.sh;
touch stop.sh; chmod +x stop.sh;
MY /etc/openvpn/start.sh
=========================
#!/bin/bash
br="br0" # Define Bridge Interface
tap="tap0" # Define list of TAP example tap="tap0 tap1 tap2"
eth="eth0"
# * CHANGE FROM HERE DOWN
eth_ip="172.18.10.21"
eth_netmask="255.255.255.0"
eth_broadcast="172.18.10.255"
eth_gw="172.18.10.2"
# * CHANGE FROM HERE UP AND NOTHING BELOW
for t in $tap; do
openvpn --mktun --dev $t
done
brctl addbr $br
brctl addif $br $eth
for t in $tap; do
brctl addif $br $t
done
for t in $tap; do
ifconfig $t 0.0.0.0 promisc up
done
ifconfig $eth 0.0.0.0 promisc up
ifconfig $br $eth_ip netmask $eth_netmask broadcast $eth_broadcast
route add default gw $eth_gw $br
echo "* Bridge STARTED `date`" >> /var/log/syslog
MY /etc/openvpn/stop.sh
========================
#!/bin/bash
br="br0"
tap="tap0"
# * CHANGE FROM HERE DOWN
eth="eth0"
eth_ip="172.18.10.21"
eth_netmask="255.255.255.0"
eth_broadcast="172.18.10.255"
eth_gw="172.18.10.2"
# * CHANGE FROM HERE UP AND NOTHING BELOW
ifconfig $br down
brctl delbr $br
for t in $tap; do
openvpn --rmtun --dev $t
done
ifconfig eth0 -promisc
ifconfig $eth $eth_ip netmask $eth_netmask broadcast $eth_broadcast
route add default gw $eth_gw $eth
echo "* Bridge STOPPED `date`" >> /var/log/syslog
TEST THE BRIDGE
===============
The bridge should be able to get started and start a ping, you might get disconnected for a second
./start.sh; ping 8.8.8.8
./stop.sh; ping 8.8.8.8
You should be able to do the above all day long, note its okay if there is a delay after you start the bridge with start.sh and the pings comeing through, sometimes it took me 10 seconds, and sometimes its instant
Note when you start the bridge on the server your ifconfig should look like this:
./start.sh
ifconfig
And when you stop the bridge on the server your ifconfig should look like this:
./stop.sh
ifconfig
OUTPUT:
br0 Link encap:Ethernet HWaddr 00:50:56:aa:cc:44
inet addr:172.18.10.21 Bcast:172.18.10.255 Mask:255.255.255.0
inet6 addr: fe80::250:56ff:feaa:cc44/64 Scope:Link
UP BROADCAST RUNNING MULTICAST MTU:1500 Metric:1
RX packets:226268724 errors:0 dropped:40 overruns:0 frame:0
TX packets:72419607 errors:0 dropped:0 overruns:0 carrier:0
collisions:0 txqueuelen:0
RX bytes:128122219579 (119.3 GiB) TX bytes:38122071147 (35.5 GiB)
eth0 Link encap:Ethernet HWaddr 00:50:56:aa:cc:44
inet6 addr: fe80::250:56ff:feaa:cc44/64 Scope:Link
UP BROADCAST RUNNING PROMISC MULTICAST MTU:1500 Metric:1
RX packets:4785785867 errors:0 dropped:624 overruns:0 frame:0
TX packets:911487819 errors:0 dropped:0 overruns:0 carrier:0
collisions:0 txqueuelen:1000
RX bytes:3251376854369 (2.9 TiB) TX bytes:967950374803 (901.4 GiB)
lo Link encap:Local Loopback
inet addr:127.0.0.1 Mask:255.0.0.0
inet6 addr: ::1/128 Scope:Host
UP LOOPBACK RUNNING MTU:16436 Metric:1
RX packets:6 errors:0 dropped:0 overruns:0 frame:0
TX packets:6 errors:0 dropped:0 overruns:0 carrier:0
collisions:0 txqueuelen:0
RX bytes:408 (408.0 B) TX bytes:408 (408.0 B)
tap0 Link encap:Ethernet HWaddr a6:0a:c1:be:20:e5
inet6 addr: fe80::a40a:c1ff:febe:20e5/64 Scope:Link
UP BROADCAST RUNNING PROMISC MULTICAST MTU:1500 Metric:1
RX packets:14557 errors:0 dropped:0 overruns:0 frame:0
TX packets:69436125 errors:0 dropped:140650466 overruns:0 carrier:0
collisions:0 txqueuelen:100
RX bytes:1047354 (1022.8 KiB) TX bytes:32999262636 (30.7 GiB)
Before continuing start the bridge
./start.sh
ifconfig
OUTPUT:
eth0 Link encap:Ethernet HWaddr 00:50:56:aa:cc:44
inet addr:172.18.10.21 Bcast:172.18.10.255 Mask:255.255.255.0
inet6 addr: fe80::250:56ff:feaa:cc44/64 Scope:Link
UP BROADCAST RUNNING MULTICAST MTU:1500 Metric:1
RX packets:4786738468 errors:0 dropped:624 overruns:0 frame:0
TX packets:911566372 errors:0 dropped:0 overruns:0 carrier:0
collisions:0 txqueuelen:1000
RX bytes:3251996200507 (2.9 TiB) TX bytes:967991077500 (901.5 GiB)
lo Link encap:Local Loopback
inet addr:127.0.0.1 Mask:255.0.0.0
inet6 addr: ::1/128 Scope:Host
UP LOOPBACK RUNNING MTU:16436 Metric:1
RX packets:6 errors:0 dropped:0 overruns:0 frame:0
TX packets:6 errors:0 dropped:0 overruns:0 carrier:0
collisions:0 txqueuelen:0
RX bytes:408 (408.0 B) TX bytes:408 (408.0 B)
OTHER CONFIGS:
1. If your server is on an ESXi Server make sure to allow that NIC to have Promiscous mode enabled, for more on that look below
If you are setting up the server as a virtual machine, in a ESXi server there is a nasty little gotcha on the network card settings that needs to be changed. The setting is in the VMWare ESX Management Client, then in Networking/Properties/Choose The VLAN your server is using/Edit/Security/Promiscous Mode/Check the box and choose Enable. Otherwise the bridge wont work because the ESX is preventing it from going into promiscous mode.
vSphere 5.0 -> Home -> Inventory -> Hosts and Clusters -> select HOST 172.18.10.100 where the Server is -> Configuration Tab -> Networking -> select Properties for vSwitch that has your machine VSWITCH2 PHYSICAL ADDRESS vmnic4 -> From List select vSwitch and hit edit (((notice there are 2 enteries a vSwitch - which has a summary in the tree of "120 Ports" and a Network "Lab 1 Network", editing the vSwitch affects the Network called "Lab 1 Network" - which has the summary in the tree of "Virtual Machine Port Group"))) -> Security Tab -> Promiscous Mode -> Change to Accept from Reject (((There shouldnt be a checkbox you have to check to change this, unless you selected the Network/"Virtual Machine Port Group" instead of the correct selection which is the vSwitch)))
2. If you have firewall rules setup with IPTABLES other then allow all then allow the correct packets to passthrough
Note with no iptables rules, or just the default Allow All, everything should work:
iptables -S
-P INPUT ACCEPT
-P FORWARD ACCEPT
-P OUTPUT ACCEPT
iptables -L
Chain INPUT (policy ACCEPT)
target prot opt source destination
Chain FORWARD (policy ACCEPT)
target prot opt source destination
Chain OUTPUT (policy ACCEPT)
target prot opt source destination
But if you have more vigourous security make sure you run these commands to allow br0 and tap0 to communicate:
iptables -A INPUT -i tap0 -j ACCEPT
iptables -A INPUT -i br0 -j ACCEPT
iptables -A FORWARD -i br0 -j ACCEPT
I dont think applies here but maybe this might help, so your troubleshooting you can put this in:
echo 1 > /proc/sys/net/ipv4/ip_forward
For me it worked with that on "echo 1" and off "echo 0"
OPENVPN CONFIGURATION ON THE SERVER
###################################
HOW 2 GEN SSL KEYS
===================
First move the appropriate template over:
cd /etc/openvpn
cp /usr/share/doc/openvpn/examples/easy-rsa/2.0/ . -R
cd /etc/openvpn/2.0
Empty the file because we will use my template below:
:>vars
Edit the vars file, and paste the vars template I have below into it, just change the section that says you need to change:
nano vars
Run the vars file:
source vars
Prepare to generate the keys:
./clean-all
*** IMPORTANT ***
NOTE WHEN GENERATING THESE KEYS MOST OF THE ANSWERS SUFFICE A SIMPLE enter KEY PRESS, PUT THE LAST 2 QUESTIONS REQUIRE A y OR n FOR yes OR no: MAKE SURE TO PUT y FOR yes
THE QUESTIONS ARE:
Sign the certificate? [y/n]:y
1 out of 1 certificate requests certified, commit? [y/n]y
*** END OF IMPORTANT ***
Build the keys:
./build-ca
./build-key-server server
./build-key client
./build-dh
Note for additional clients just rerun the ./build-key client and change client to name of the client for example ./build-key bob, afterwards client config changes would have to reflect that change (but thats only 2 lines to change in the client openvpn.conf which you will see later on in this article)
Lets copy the needed server keys from where they are at now: /etc/openvpn/2.0/keys to: /etc/openvpn - note that the /etc/openvpn/2.0/keys directory is new - it was generated with the above scripts:
cd /etc/openvpn/2.0/keys
cp ca.key ca.crt server.crt server.key dh2048.pem /etc/openvpn
NOTE: Note in my case it was dh2048.pem in your case it could be dh1024.pem, it depends on if you changed the key strength in the vars file, I didnt so its 2048 for me.
So now you should have 5 files in /etc/openvpn: ca.key ca.crt server.crt server.key dh2048.pem, confirm that:
ls -lisah /etc/openvpn
SERVER /etc/openvpn/openvpn.conf:
====================================
port 50006
proto udp
dev tap0
server-bridge 172.18.10.21 255.255.255.0 172.18.10.150 172.18.10.170
keepalive 10 120
persist-key
persist-tun
ca ca.crt
cert server.crt
key server.key
dh dh2048.pem
cipher AES-128-CBC
auth MD5
status openvpn-status.log
verb 5
START VPN ON SERVER:
====================
service openvpn start
If you need to stop the vpn:
service openvpn stop
If you experience issues check out the /etc/openvpn-status.log and also the syslog /var/log/syslog towards the bottom and start googling.
FROM SERVER COPY THE CLIENT KEYS TO CLIENT
===========================================
The client needs the following files:
1. ca.crt (he doesnt need the ca.key thats for the server only, or actually for the root authority only, but since we are the root authority in these examples withour self generated keys, then the server is the only one that should have the ca.key)
2. client.crt
3. client.key
Note no need to copy the dh2048.pem file, the diffiehelman is also kept on the server
So from the server you can copy the 3 files with cat & ssh like this.
First go to the folder where all the keys are at - remember we only put the server important keys directly on /etc/openvpn:
cd /etc/openvpn/2.0/keys
cat ca.crt | ssh www.client.com -p 50005 "cat - > /etc/openvpn/ca.crt"
cat client.crt | ssh www.client.com -p 50005 "cat - > /etc/openvpn/client.crt"
cat client.key | ssh www.client.com -p 50005 "cat - > /etc/openvpn/client.key"
It will ask for the password on each ssh command and also note that the client needs to have the /etc/openvpn folder there for it to copy those files (that folder gets automatically made when you install openvpn with apt-get install openvpn).
OPENVPN CONFIGURATION ON THE CLIENT
###################################
Now on your client we just make this file.
CLIENT /etc/openvpn/openvpn.conf:
====================================
client
remote www.server.com
port 50006
proto udp
dev tap0
persist-key
persist-tun
pull
ca ca.crt
cert client.crt
key client.key
cipher AES-128-CBC
auth MD5
verb 5
START VPN ON CLIENT:
====================
service openvpn start
If you need to stop the vpn:
service openvpn stop
If you experience issues check out the /etc/openvpn-status.log and also the syslog /var/log/syslog towards the bottom and start googling.
TESTS
######
Try pinging the server first 172.18.10.21 then beyond it, everything should work if not. Google :-)
FOR THE FUTURE:
###############
In the future to properly start the server:
/etc/openvpn/start.sh
service openvpn start
To properly stop the server
service openvpn stop
/etc/openvpn/stop.sh
It would be nice to make that all automated, and we can, I just didnt include it in this article... Maybe I will as an update later on.
VARS - used when making the keys
##################################
# MODIFIED FROM:https://github.com/OpenVPN/easy-rsa/blob/master/easy-rsa/2.0/vars
# easy-rsa parameter settings
# NOTE: If you installed from an RPM,
# don't edit this file in place in
# /usr/share/openvpn/easy-rsa --
# instead, you should copy the whole
# easy-rsa directory to another location
# (such as /etc/openvpn) so that your
# edits will not be wiped out by a future
# OpenVPN package upgrade.
# This variable should point to
# the top level of the easy-rsa
# tree.
export EASY_RSA="/etc/openvpn/2.0"
#
# This variable should point to
# the requested executables
#
export OPENSSL="openssl"
export PKCS11TOOL="pkcs11-tool"
export GREP="grep"
# This variable should point to
# the openssl.cnf file included
# with easy-rsa.
export KEY_CONFIG=`$EASY_RSA/whichopensslcnf $EASY_RSA`
# Edit this variable to point to
# your soon-to-be-created key
# directory.
#
# WARNING: clean-all will do
# a rm -rf on this directory
# so make sure you define
# it correctly!
export KEY_DIR="$EASY_RSA/keys"
# Issue rm -rf warning
echo NOTE: If you run ./clean-all, I will be doing a rm -rf on $KEY_DIR
# PKCS11 fixes
export PKCS11_MODULE_PATH="dummy"
export PKCS11_PIN="dummy"
# Increase this to 2048 if you
# are paranoid. This will slow
# down TLS negotiation performance
# as well as the one-time DH parms
# generation process.
export KEY_SIZE=2048
# In how many days should the root CA key expire?
export CA_EXPIRE=3650
# In how many days should certificates expire?
export KEY_EXPIRE=3650
# These are the default values for fields
# which will be placed in the certificate.
# Don't leave any of these fields blank.
#
# ****** CHANGE FROM HERE DOWN ******
#
export KEY_COUNTRY="US"
export KEY_PROVINCE="CA"
export KEY_CITY="SanJose"
export KEY_ORG="SERVAWE"
export KEY_EMAIL="thisawesome@gmail.com"
export KEY_OU="SERVAWELAB"
# X509 Subject Field
export KEY_NAME="SERVAWE"
#
# ****** CHANGE FROM HERE UP ******
#
# PKCS11 Smart Card
# export PKCS11_MODULE_PATH="/usr/lib/changeme.so"
# export PKCS11_PIN=1234
# If you'd like to sign all keys with the same Common Name, uncomment the KEY_CN export below
# You will also need to make sure your OpenVPN server config has the duplicate-cn option set
# export KEY_CN="CommonName"
EXTRA EXTRA
###########
Some good reading:
==================
http://coderazzi.net/howto/openwrt/tl841n/openvpn-bridge.htm
http://openvpn.net/index.php/open-source/documentation/miscellaneous/76-ethernet-bridging.html
Another persons start and stop bridge scripts:
===============================================
START BRIDGE:
stop
ifconfig tap0 &> /dev/null || sleep 1
ifconfig tap0 &> /dev/null || sleep 1
ifconfig tap0 &> /dev/null || sleep 1
fconfig tap0 &> /dev/null || sleep 1
ifconfig tap0 &> /dev/null || sleep 1
brctl addbr br0
brctl addif br0 tap0
brctl addif br0 eth1.2
ifconfig br0 up
STOP BRIDGE:
ifconfig br0 &> /dev/null || return
ifconfig br0 down
rctl delbr br0
Some thoughs on the firewall:
==============================
For me this worked:
# iptables -S
default:
-P INPUT ACCEPT
-P FORWARD ACCEPT
-P OUTPUT ACCEPT
But it recommended this:
-A INPUT -i tap0 -j ACCEPT
-A INPUT -i br0 -j ACCEPT
-A FORWARD -i br0 -j ACCEPT
However I also thought this might be needed:
-A FORWARD -i tap0 -j ACCEPT
-A FORWARD -i eth0 -j ACCEPT
Remember to do this:
echo 1 > /proc/sys/net/ipv4/ip_forward
What does that do?
The '1' in "/proc/sys/net/ipv4/ip_forward" enables IP forwarding.
A '0' signifies IP forwarding is disabled.
Before you issue the echo... command, try
cat /proc/sys/net/ipv4/ip_forward
and you will see a '0'.
You can add
echo "1" > /proc/sys/net/ipv4/ip_forward
to one of your startup files if you need this enabled all the time.
Add to the end of /etc/rc.d/rc.local.
There is no portforwarding here so I believe this is more for the topic of routed openvpn. Because after all with extra routes inplace on the server and the lan machines in the servers network you can have the client be able to access all of the servers network with a routed openvpn setup
DHCP?
======
So the server-bridge command takes care of it, but if you want more options or have another dhcp server thats also possible. Here is an exerpt from the web.
A: want to set up an ethernet bridge on the 192.168.1.0/24 subnet. existing DHCP.
Q: I want to set up an ethernet bridge on the 192.168.1.0/24 subnet. How do I configure OpenVPN so that it will cooperate with the existing DHCP server on the LAN?
There are two ways to do this.
Using the server-bridge directive is the easiest. First, set aside an address pool in your 192.168.1.0/24 subnet for use by OpenVPN clients. This range must be separate from the DHCP server range used on the subnet. Suppose you want OpenVPN to use192.168.1.200 to 192.168.1.254 for allocation to connecting clients, and that the gateway for the LAN is 192.168.1.1. Then the appropriateserver-bridge directive would be:
server-bridge 192.168.1.1 255.255.255.0 192.168.1.200 192.168.1.254
In the second method, the OpenVPN clients get their IP address lease from the DHCP server which is serving the LAN. For this configuration, you don't need a server-bridge directive, just something like:
mode server
dev tap0 # must be bridged with LAN ethernet interface
[SSL/TLS parms]
[keepalive parms]
The clients will negotiate a DHCP lease through the tunnel, meaning that both VPN clients and local machines will receive their IP addresses from the DHCP server address pool. The one complexity about this configuration is that you need to modify your DHCP server configuration to differentiate between local clients and VPN clients. The reason for this is that you must not pass out a default gateway to VPN clients. See the Win32 install notes for an example.
SIDE NOTE: STATIC KEY BRIDGE DOESNT WORK WITH SERVER-BRIDGE COMMAND
===================================================================
So originally I tried to do this but the syslog told me server-bridge and static key dont work well, so I moved on to making a TLS bridge config.
But here are my notes for the none working OPENVPN BRIDGED with STATIC KEY
With only a few changes like removing the server-bridge part this could possibly work.
Perhaps in a future update Ill include a way to setup Openvpn with bridge with a static key.
TO MAKE KEY:
openvpn --genkey --secret static.key
SERVER FILES:
/etc/openvpn/static.key
/etc/openvpn/openvpn.conf
SERVER OPENVPN.CONF - /etc/openvpn/openvpn.conf:
port 50006
proto udp
dev tap0
# ifconfig 10.99.99.1 10.99.99.2
server-bridge 10.11.12.55 255.255.255.0 10.11.12.70 10.11.12.80
keepalive 10 120
persist-key
persist-tun
verb 5
CLIENT FILES:
/etc/openvpn/static.key
/etc/openvpn/openvpn.conf
CLIENT OPENVPN.CONF - /etc/openvpn/openvpn.con:
remote www.server.com
proto udp
port 50006
dev tap
pull
# ifconfig 10.99.99.2 10.99.99.1
secret static.key
A COPY OF THE ENTIRE OPEN VPN MAN PAGE:
========================================
Sign in Follow us
Home VPN Service
Your Private Tunnel to the Internet
VPN Solution
Overview
Software Packages
Virtual Appliances
Cloud Machines
Purchase License
My Licenses
Pricing
Documentation
Quick Start Guide
HOWTO
Videos
Admin Guide
Data Sheet
FAQ
Advantages
Community
Overview
Downloads
Source Code
Documentation
HOWTO
Security Overview
Examples
Graphical User Interface
Manuals
Change Log
Installation Notes
Release Notes
Miscellaneous
Non-English
File Signatures
Articles
FAQ
Books
Wiki/Tracker
Forums
Contributing
Downloads
Access Server Downloads
Community Downloads
Community
Overview
Downloads
Source Code
Documentation
HOWTO
Security Overview
Examples
Graphical User Interface
Manuals
Change Log
Installation Notes
Release Notes
Miscellaneous
Non-English
File Signatures
Articles
FAQ
Books
Wiki/Tracker
Forums
Contributing
OpenVPN 2.0.x
NAME
openvpn - secure IP tunnel daemon. f
SYNOPSIS
openvpn [ --help ]
openvpn [ --config file ]
openvpn [ --genkey ] [ --secret file ]
openvpn [ --mktun ] [ --rmtun ] [ --dev tunX | tapX ] [ --dev-type device-type ] [ --dev-node node ]
openvpn [ --test-crypto ] [ --secret file ] [ --auth alg ] [ --cipher alg ] [ --engine ] [ --keysize n ] [ --no-replay ] [ --no-iv ]
openvpn [ --askpass [file] ] [ --auth-nocache ] [ --auth-retry type ] [ --auth-user-pass-verify script ] [ --auth-user-pass up ] [ --auth alg ] [ --bcast-buffers n ] [ --ca file ] [ --ccd-exclusive ] [ --cd dir ] [ --cert file ] [ --chroot dir ] [ --cipher alg ] [ --client-cert-not-required ] [ --client-config-dir dir ] [ --client-connect script ] [ --client-disconnect ] [ --client-to-client ] [ --client ] [ --comp-lzo ] [ --comp-noadapt ] [ --config file ] [ --connect-freq n sec ] [ --connect-retry n ] [ --crl-verify crl ] [ --cryptoapicert select-string ] [ --daemon [progname] ] [ --dev-node node ] [ --dev-type device-type ] [ --dev tunX | tapX | null ] [ --dev tunX | tapX ] [ --dh file ] [ --dhcp-option type [parm] ] [ --dhcp-release ] [ --dhcp-renew ] [ --disable-occ ] [ --disable ] [ --down-pre ] [ --down cmd ] [ --duplicate-cn ] [ --echo [parms...] ] [ --engine [engine-name] ] [ --explicit-exit-notify [n] ] [ --fast-io ] [ --float ] [ --fragment max ] [ --genkey ] [ --group group ] [ --hand-window n ] [ --hash-size r v ] [ --help ] [ --http-proxy-option type [parm] ] [ --http-proxy-retry ] [ --http-proxy-timeout n ] [ --http-proxy server port [authfile] [auth-method] ] [ --ifconfig-noexec ] [ --ifconfig-nowarn ] [ --ifconfig-pool-linear ] [ --ifconfig-pool-persist file [seconds] ] [ --ifconfig-pool start-IP end-IP [netmask] ] [ --ifconfig-push local remote-netmask ] [ --ifconfig l rn ] [ --inactive n ] [ --inetd [wait|nowait] [progname] ] [ --ip-win32 method ] [ --ipchange cmd ] [ --iroute network [netmask] ] [ --keepalive n m ] [ --key-method m ] [ --key file ] [ --keysize n ] [ --learn-address cmd ] [ --link-mtu n ] [ --local host ] [ --log-append file ] [ --log file ] [ --suppress-timestamps ] [ --lport port ] [ --management-hold ] [ --management-log-cache n ] [ --management-query-passwords ] [ --management IP port [pw-file] ] [ --max-clients n ] [ --max-routes-per-client n ] [ --mktun ] [ --mlock ] [ --mode m ] [ --mssfix max ] [ --mtu-disc type ] [ --mtu-test ] [ --mute-replay-warnings ] [ --mute n ] [ --nice n ] [ --no-iv ] [ --no-replay ] [ --nobind ] [ --ns-cert-type client|server ] [ --passtos ] [ --pause-exit ] [ --persist-key ] [ --persist-local-ip ] [ --persist-remote-ip ] [ --persist-tun ] [ --ping-exit n ] [ --ping-restart n ] [ --ping-timer-rem ] [ --ping n ] [ --pkcs12 file ] [ --plugin module-pathname init-string ] [ --port port ] [ --proto p ] [ --pull ] [ --push-reset ] [ --push "option" ] [ --rcvbuf size ] [ --redirect-gateway ["local"] ["def1"] ] [ --remap-usr1 signal ] [ --remote-random ] [ --remote host [port] ] [ --reneg-bytes n ] [ --reneg-pkts n ] [ --reneg-sec n ] [ --replay-persist file ] [ --replay-window n [t] ] [ --resolv-retry n ] [ --rmtun ] [ --route-delay [n] [w] ] [ --route-gateway gw ] [ --route-method m ] [ --route-noexec ] [ --route-up cmd ] [ --route network [netmask] [gateway] [metric] ] [ --rport port ] [ --secret file [direction] ] [ --secret file ] [ --server-bridge gateway netmask pool-start-IP pool-end-IP ] [ --server network netmask ] [ --service exit-event [0|1] ] [ --setenv name value ] [ --shaper n ] [ --show-adapters ] [ --show-ciphers ] [ --show-digests ] [ --show-engines ] [ --show-net-up ] [ --show-net ] [ --show-tls ] [ --show-valid-subnets ] [ --single-session ] [ --sndbuf size ] [ --socks-proxy-retry ] [ --socks-proxy server [port] ] [ --status file [n] ] [ --status-version n ] [ --syslog [progname] ] [ --tap-sleep n ] [ --tcp-queue-limit n ] [ --test-crypto ] [ --tls-auth file [direction] ] [ --tls-cipher l ] [ --tls-client ] [ --tls-exit ] [ --tls-remote x509name ] [ --tls-server ] [ --tls-timeout n ] [ --tls-verify cmd ] [ --tmp-dir dir ] [ --tran-window n ] [ --tun-ipv6 ] [ --tun-mtu-extra n ] [ --tun-mtu n ] [ --txqueuelen n ] [ --up-delay ] [ --up-restart ] [ --up cmd ] [ --user user ] [ --username-as-common-name ] [ --verb n ] [ --writepid file ]
INTRODUCTION
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.
Also note that there's more documentation and examples on the OpenVPN web site: http://openvpn.net/
And if you would like to see a shorter version of this manual, see the openvpn usage message which can be obtained by running openvpn without any parameters.
DESCRIPTION
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.
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 (Static Key mode) or public key security (SSL/TLS mode) using client & server certificates. OpenVPN also supports non-encrypted TCP/UDP tunnels.
OpenVPN is designed to work with the 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.
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.
--help
Show options.
--config file
Load additional config options from file where each line corresponds to one command line option, but with the leading '--' removed.
If --config file is the only option to the openvpn command, the --config can be removed, and the command can be given as openvpn file
Note that configuration files can be nested to a reasonable depth.
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.
Note that OpenVPN 2.0 and higher performs backslash-based shell escaping, so the following mappings should be observed:
\\ 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.
For example on Windows, use double backslashes to represent pathnames:
secret "c:\\OpenVPN\\secret.key"
For examples of configuration files, see http://openvpn.net/examples.html
Here is an example configuration file:
#
# 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
Tunnel Options:
--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.
--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.
--remote host [port]
Remote host name or IP address. On the client, multiple --remote options may be specified for redundancy, each referring to a different OpenVPN server.
The OpenVPN client will try to connect to a server at host:port in the order specified by the list of --remote options.
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.
Note that since UDP is connectionless, connection failure is defined by the --ping and --ping-restart options.
Note the following corner case: If you use multiple --remote options, AND you are dropping root privileges on the client with --user and/or --group, 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.
If --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, --remote will act as a filter, rejecting connections from any host which does not match host.
If host is a DNS name which resolves to multiple IP addresses, one will be randomly chosen, providing a sort of basic load-balancing and failover capability.
--remote-random
When multiple --remote address/ports are specified, initially randomize the order of the list as a kind of basic load-balancing measure.
--proto p
Use protocol p for communicating with remote host. p can be udp, tcp-client, or tcp-server.
The default protocol is udp when --proto is not specified.
For UDP operation, --proto udp should be specified on both peers.
For TCP operation, one peer must use --proto tcp-server and the other must use --proto tcp-client. A peer started with tcp-server will wait indefinitely for an incoming connection. A peer started with tcp-client will attempt to connect, and if that fails, will sleep for 5 seconds (adjustable via the --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:
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.
--connect-retry n
For --proto tcp-client, take n as the number of seconds to wait between connection retries (default=5).
--http-proxy server port [authfile] [auth-method]
Connect to remote host through an HTTP proxy at address server and port port. If HTTP Proxy-Authenticate is required, authfile is a file containing a username and password on 2 lines, or "stdin" to prompt from console.
auth-method should be one of "none", "basic", or "ntlm".
--http-proxy-retry
Retry indefinitely on HTTP proxy errors. If an HTTP proxy error occurs, simulate a SIGUSR1 reset.
--http-proxy-timeout n
Set proxy timeout to n seconds, default=5.
--http-proxy-option type [parm]
Set extended HTTP proxy options. Repeat to set multiple options.
VERSION version -- Set HTTP version number to version (default=1.0).
AGENT user-agent -- Set HTTP "User-Agent" string to user-agent.
--socks-proxy server [port]
Connect to remote host through a Socks5 proxy at address server and port port (default=1080).
--socks-proxy-retry
Retry indefinitely on Socks proxy errors. If a Socks proxy error occurs, simulate a SIGUSR1 reset.
--resolv-retry n
If hostname resolve fails for --remote, retry resolve for n seconds before failing.
Set n to "infinite" to retry indefinitely.
By default, --resolv-retry infinite is enabled. You can disable by setting n=0.
--float
Allow remote peer to change its IP address and/or port number, such as due to DHCP (this is the default if --remote is not used). --float when specified with --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, --float tells OpenVPN to accept authenticated packets from any address, not only the address which was specified in the --remote option.
--ipchange cmd
Execute shell command cmd when our remote ip-address is initially authenticated or changes.
Execute as:
cmd ip_address port_number
Don't use --ipchange in --mode server mode. Use a --client-connect script instead.
See the "Environmental Variables" section below for additional parameters passed as environmental variables.
Note that cmd can be a shell command with multiple arguments, in which case all OpenVPN-generated arguments will be appended to 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 /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 our IP address changes due to DHCP, we should configure our IP address change script (see man page for dhcpcd(8) ) to deliver a SIGHUP or SIGUSR1 signal to OpenVPN. OpenVPN will then reestablish a connection with its most recently authenticated peer on its new IP address.
--port port
TCP/UDP port number for both local and remote. The current default of 1194 represents the official IANA port number assignment for OpenVPN and has been used since version 2.0-beta17. Previous versions used port 5000 as the default.
--lport port
TCP/UDP port number for local.
--rport port
TCP/UDP port number for remote.
--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 --remote option.
--dev tunX | tapX | null
TUN/TAP virtual network device ( 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.
tun devices encapsulate IPv4 while tap devices encapsulate ethernet 802.3.
--dev-type device-type
Which device type are we using? device-type should be tun or tap. Use this option only if the TUN/TAP device used with --dev does not begin with tun or tap.
--tun-ipv6
Build a tun link capable of forwarding IPv6 traffic. Should be used in conjunction with --dev tun or --dev tunX. A warning will be displayed if no specific IPv6 TUN support for your OS has been compiled into OpenVPN.
--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 node is a TUN or TAP device based on the name, you should also specify --dev-type tun or --dev-type tap.
On Windows systems, select the TAP-Win32 adapter which is named node in the Network Connections Control Panel or the raw GUID of the adapter enclosed by braces. The --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.
--ifconfig l rn
Set TUN/TAP adapter parameters. l is the IP address of the local VPN endpoint. For TUN devices, rn is the IP address of the remote VPN endpoint. For TAP devices, 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 --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 rn, you will be pinging across the VPN.
For TAP devices, which provide the ability to create virtual ethernet segments, --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 ifconfig(8) command, is designed to simplify TUN/TAP tunnel configuration by providing a standard interface to the different ifconfig implementations on different platforms.
--ifconfig parameters which are IP addresses can also be specified as a DNS or /etc/hosts file resolvable name.
For TAP devices, --ifconfig should not be used if the TAP interface will be getting an IP address lease from a DHCP server.
--ifconfig-noexec
Don't actually execute ifconfig/netsh commands, instead pass --ifconfig parameters to scripts using environmental variables.
--ifconfig-nowarn
Don't output an options consistency check warning if the --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 --disable-occ option) while only disabling the ifconfig component of the check.
For example, if you have a configuration where the local host uses --ifconfig but the remote host does not, use --ifconfig-nowarn on the local host.
This option will also silence warnings about potential address conflicts which occasionally annoy more experienced users by triggering "false positive" warnings.
--route network/IP [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 route(8) shell command, while at the same time providing portable semantics across OpenVPN's platform space.
netmask default -- 255.255.255.255
gateway default -- taken from --route-gateway or the second parameter to --ifconfig when --dev tun is specified.
The default can be specified by leaving an option blank or setting it to "default".
The network and gateway parameters can also be specified as a DNS or /etc/hosts file resolvable name, or as one of three special keywords:
vpn_gateway -- The remote VPN endpoint address (derived either from --route-gateway or the second parameter to --ifconfig when --dev tun is specified).
net_gateway -- The pre-existing IP default gateway, read from the routing table (not supported on all OSes).
remote_host -- The --remote address if OpenVPN is being run in client mode, and is undefined in server mode.
--route-gateway gw
Specify a default gateway gw for use with --route.
--route-delay [n] [w]
Delay n seconds (default=0) after connection establishment, before adding routes. If n is 0, routes will be added immediately upon connection establishment. If --route-delay is omitted, routes will be added immediately after TUN/TAP device open and --up script execution, before any --user or --group privilege downgrade (or --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.
On Windows, --route-delay tries to be more intelligent by waiting w seconds (w=30 by default) for the TAP-Win32 adapter to come up before adding routes.
--route-up cmd
Execute shell command cmd after routes are added, subject to --route-delay.
See the "Environmental Variables" section below for additional parameters passed as environmental variables.
Note that cmd can be a shell command with multiple arguments.
--route-noexec
Don't add or remove routes automatically. Instead pass routes to --route-up script using environmental variables.
--redirect-gateway [local] [def1]
(Experimental) Automatically execute routing commands to cause all outgoing IP traffic to be redirected over the VPN.
This option performs three steps:
(1) Create a static route for the --remote address which forwards to the pre-existing default gateway. This is done so that (3) will not create a routing loop.
(2) Delete the default gateway route.
(3) Set the new default gateway to be the VPN endpoint address (derived either from --route-gateway or the second parameter to --ifconfig when --dev tun is specified).
When the tunnel is torn down, all of the above steps are reversed so that the original default route is restored.
Add the local flag if both OpenVPN servers are directly connected via a common subnet, such as with wireless. The local flag will cause step 1 above to be omitted.
Add the def1 flag to override the default gateway by using 0.0.0.0/1 and 128.0.0.0/1 rather than 0.0.0.0/0. This has the benefit of overriding but not wiping out the original default gateway.
Using the def1 flag is highly recommended, and is currently planned to become the default by OpenVPN 2.1.
--link-mtu n
Sets an upper bound on the size of UDP packets which are sent between OpenVPN peers. It's best not to set this parameter unless you know what you're doing.
--tun-mtu n
Take the TUN device MTU to be n and derive the link MTU from it (default=1500). In most cases, you will probably want to leave this parameter set to its default value.
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.
MTU problems often manifest themselves as connections which hang during periods of active usage.
It's best to use the --fragment and/or --mssfix options to deal with MTU sizing issues.
--tun-mtu-extra n
Assume that the TUN/TAP device might return as many as n bytes more than the --tun-mtu size on read. This parameter defaults to 0, which is sufficient for most TUN devices. TAP devices may introduce additional overhead in excess of the MTU size, and a setting of 32 is the default when TAP devices are used. This parameter only controls internal OpenVPN buffer sizing, so there is no transmission overhead associated with using a larger value.
--mtu-disc type
Should we do Path MTU discovery on TCP/UDP channel? Only supported on OSes such as Linux that supports the necessary system call to set.
'no' -- Never send DF (Don't Fragment) frames
'maybe' -- Use per-route hints
'yes' -- Always DF (Don't Fragment)
--mtu-test
To empirically measure MTU on connection startup, add the --mtu-test option to your configuration. OpenVPN will send ping packets of various sizes to the remote peer and measure the largest packets which were successfully received. The --mtu-test process normally takes about 3 minutes to complete.
--fragment max
Enable internal datagram fragmentation so that no UDP datagrams are sent which are larger than max bytes.
The max parameter is interpreted in the same way as the --link-mtu parameter, i.e. the UDP packet size after encapsulation overhead has been added in, but not including the UDP header itself.
The --fragment option only makes sense when you are using the UDP protocol ( --proto udp ).
--fragment adds 4 bytes of overhead per datagram.
See the --mssfix option below for an important related option to --fragment.
It should also be noted that this option is not meant to replace UDP fragmentation at the IP stack level. It is only meant as a last resort when path MTU discovery is broken. Using this option is less efficient than fixing path MTU discovery for your IP link and using native IP fragmentation instead.
Having said that, there are circumstances where using OpenVPN's internal fragmentation capability may be your only option, such as tunneling a UDP multicast stream which requires fragmentation.
--mssfix max
Announce to TCP sessions running over the tunnel that they should limit their send packet sizes such that after OpenVPN has encapsulated them, the resulting UDP packet size that OpenVPN sends to its peer will not exceed max bytes.
The max parameter is interpreted in the same way as the --link-mtu parameter, i.e. the UDP packet size after encapsulation overhead has been added in, but not including the UDP header itself.
The --mssfix option only makes sense when you are using the UDP protocol for OpenVPN peer-to-peer communication, i.e. --proto udp.
--mssfix and --fragment can be ideally used together, where --mssfix will try to keep TCP from needing packet fragmentation in the first place, and if big packets come through anyhow (from protocols other than TCP), --fragment will internally fragment them.
Both --fragment and --mssfix are designed to work around cases where Path MTU discovery is broken on the network path between OpenVPN peers.
The usual symptom of such a breakdown is an OpenVPN connection which successfully starts, but then stalls during active usage.
If --fragment and --mssfix are used together, --mssfix will take its default max parameter from the --fragment max option.
Therefore, one could lower the maximum UDP packet size to 1300 (a good first try for solving MTU-related connection problems) with the following options:
--tun-mtu 1500 --fragment 1300 --mssfix
--sndbuf size
Set the TCP/UDP socket send buffer size. Currently defaults to 65536 bytes.
--rcvbuf size
Set the TCP/UDP socket receive buffer size. Currently defaults to 65536 bytes.
--txqueuelen n
(Linux only) Set the TX queue length on the TUN/TAP interface. Currently defaults to 100.
--shaper n
Limit bandwidth of outgoing tunnel data to n bytes per second on the TCP/UDP port. If you want to limit the bandwidth in both directions, use this option on both peers.
OpenVPN uses the following algorithm to implement traffic shaping: Given a shaper rate of n bytes per second, after a datagram write of b bytes is queued on the TCP/UDP port, wait a minimum of (b / n) seconds before queuing the next write.
It should be noted that OpenVPN supports multiple tunnels between the same two peers, allowing you to construct full-speed and reduced bandwidth tunnels at the same time, routing low-priority data such as off-site backups over the reduced bandwidth tunnel, and other data over the full-speed tunnel.
Also note that for low bandwidth tunnels (under 1000 bytes per second), you should probably use lower MTU values as well (see above), otherwise the packet latency will grow so large as to trigger timeouts in the TLS layer and TCP connections running over the tunnel.
OpenVPN allows n to be between 100 bytes/sec and 100 Mbytes/sec.
--inactive n
(Experimental) Causes OpenVPN to exit after n seconds of inactivity on the TUN/TAP device. The time length of inactivity is measured since the last incoming tunnel packet.
--ping n
Ping remote over the TCP/UDP control channel if no packets have been sent for at least n seconds (specify --ping on both peers to cause ping packets to be sent in both directions since OpenVPN ping packets are not echoed like IP ping packets). When used in one of OpenVPN's secure modes (where --secret, --tls-server, or --tls-client is specified), the ping packet will be cryptographically secure.
This option has two intended uses:
(1) Compatibility with stateful firewalls. The periodic ping will ensure that a stateful firewall rule which allows OpenVPN UDP packets to pass will not time out.
(2) To provide a basis for the remote to test the existence of its peer using the --ping-exit option.
--ping-exit n
Causes OpenVPN to exit after n seconds pass without reception of a ping or other packet from remote. This option can be combined with --inactive, --ping, and --ping-exit to create a two-tiered inactivity disconnect.
For example,
openvpn [options...] --inactive 3600 --ping 10 --ping-exit 60
when used on both peers will cause OpenVPN to exit within 60 seconds if its peer disconnects, but will exit after one hour if no actual tunnel data is exchanged.
--ping-restart n
Similar to --ping-exit, but trigger a SIGUSR1 restart after n seconds pass without reception of a ping or other packet from remote.
This option is useful in cases where the remote peer has a dynamic IP address and a low-TTL DNS name is used to track the IP address using a service such as http://dyndns.org/ + a dynamic DNS client such as ddclient.
If the peer cannot be reached, a restart will be triggered, causing the hostname used with --remote to be re-resolved (if --resolv-retry is also specified).
In server mode, --ping-restart, --inactive, or any other type of internally generated signal will always be applied to individual client instance objects, never to whole server itself. Note also in server mode that any internally generated signal which would normally cause a restart, will cause the deletion of the client instance object instead.
In client mode, the --ping-restart parameter is set to 120 seconds by default. This default will hold until the client pulls a replacement value from the server, based on the --keepalive setting in the server configuration. To disable the 120 second default, set --ping-restart 0 on the client.
See the signals section below for more information on SIGUSR1.
Note that the behavior of SIGUSR1 can be modified by the --persist-tun, --persist-key, --persist-local-ip, and --persist-remote-ip options.
Also note that --ping-exit and --ping-restart are mutually exclusive and cannot be used together.
--keepalive