README.Debian 8.15 KB
Newer Older
1 2 3 4 5 6 7 8 9 10 11 12
In this file:

- 'writepid' option warning
- Multiple tunnels
- Starting or stopping multiple tunnels with a single command
- Compatibility notes on 2.x vs 1.x #
- Changes in string remapping (affects tls-remote certificate names)
- plugin support
- Using resolvconf
- Out of memory issues
- LDAP+TLS authentication runs into file exhaustion
- Possible consequences of the 'chroot' option
13
- Disabling all.send_redirects on tun + topology subnet setups
14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59


openvpn for Debian
------------------

Documentation to get OpenVPN to work is mostly on the openvpn(8) man page.
You'll find example configuration files and additional docs in the 
/usr/share/doc/openvpn/examples directory.

OpenVPN requires TUN/TAP driver support in the kernel. You'll also need a 
tun device file. If it's not present on your system, you may create one
with these commands (as root):
# mkdir /dev/net
# mknod /dev/net/tun c 10 200

'writepid' option warning
-------------------------

Don't specify a 'writepid' option in the .conf files, or the init.d 
script won't be able to stop/reload the tunnels.

Multiple tunnels
----------------

When OpenVPN is started by /etc/init.d/openvpn the default is to start
a separate openvpn daemon for each .conf configuration file in the
/etc/openvpn directory.  The /etc/default/openvpn file may be used to
alter this behavior.

[UPDATE: with OpenVPN 2.0 one openvpn daemon can serve multiple clients. That
way multiple instances of openvpn are no longer required to achieve this, and
one configuration file should be enough for these cases. Take a look at the
'Multi-Client Server options' on the man page]

Be sure that each .conf file defines a different local port
number with the "port" or "lport" options; see the openvpn
man page for more information.

Starting or stopping multiple tunnels with a single command
-----------------------------------------------------------

It is now possible to specify multiple tunnel names to the init.d script.
Just put the names after the action (start|stop), like this:

/etc/init.d/openvpn start vpn1 vpn4 vpn5

60 61 62 63 64 65 66 67
This only works with sysvinit(-core), if you're running systemd, you cannot
pass arguments to init.d scripts. 

In order to start/stop a particular VPN you may use:
# service openvpn@VPN_NAME start
or
# systemctl start openvpn@VPN_NAME

68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 137 138 139 140 141 142 143 144 145 146 147 148 149 150 151 152 153 154 155 156 157 158 159 160 161 162 163 164 165 166 167 168 169 170 171 172 173 174 175 176 177 178 179 180 181 182 183 184 185 186 187 188 189 190 191 192 193 194 195 196 197 198 199 200 201 202 203 204 205 206 207 208 209 210 211 212 213 214 215 216 217 218 219 220 221 222 223 224 225 226 227
/etc/network/interfaces
-----------------------

/etc/network/interfaces can be configured to start and stop openvpn when the
underlying network interface is brought up and down. To do so add a line such
as "openvpn vpn1" to the stanza for the underlying network interface, where
"vpn1" is the name of the vpn to start and stop.

It is possible to control vpn interfaces using the standard ifup/ifdown
commands. This is helpful in case you want tunnels to be started right
after physical networks, so any network filesystems listed in fstab can be
mounted during the standard boot sequence. In order to do this several
steps need to be taken:

-   Select a specific tun/tap device name using the 'dev' option in your
    config file (e.g. dev tun_work). This will ensure that the name you
    use in /etc/network/interfaces will always match the one this vpn 
    will utilize.
    
-   Create a 'manual' type interface entry in /etc/network/interfaces. 
    There should be only one option - openvpn, which takes a config file
    name as the argument (without the .conf suffix) For example:
    
    auto tun_work
    iface tun_work inet manual
        openvpn work_vpn

-   You should prevent openvpn from trying to start this tunnel when its
    own init script runs, since the interface is already up. This is done 
    in /etc/default/openvpn by changing the AUTOSTART option as described 
    in the same file


If you'd like to use a bridged setup (utilizing a tap device) Debian provides
some helper tools in the bridge-utils package to help you setting up your
bridge via /etc/network/interfaces.

An easy example, creating a bridge interface 'br0' from 'eth0' and 'tap0',
can look like this:

      auto lo br0 eth1
      allow-hotplug eth0

      iface br0 inet static
      address 192.168.1.1
      network 192.168.1.0
      netmask 255.255.255.0
      broadcast 192.168.1.255
      bridge_ports eth0 tap0
      pre-up openvpn --mktun --dev tap0

It's recommended to read the manpage - man 5 bridge-utils-interfaces - aswell.


#####################################
# Compatibility notes on 2.x vs 1.x #
#####################################

In version 2.0, --tun-mtu 1500 --mssfix 1450 is now the default. In 1.x the
default is --link-mtu 1300 for tun interfaces and --tun-mtu 1500 for tap
interfaces, with --mssfix disabled).

Also in version 2.0, when using TLS, --key-method 2 is now the default, 
it was 1 in versions 1.x.

To sum up, to make 2.0 work with 1.x put the following in the 1.x configuration
files:

  tun-mtu 1500
  tun-mtu-extra 32
  mssfix 1450
  key-method 2   ## (if you're using TLS)


Or, in case you'd rather not modify the 1.x configuration, set the 2.x side
configuration like this:

If using TLS:
  key-method 1
If "dev tun":
  link-mtu 1300
If "dev tap":
  tun-mtu 1500
  tun-mtu-extra 32

OpenVPN 1.x won't be able to act as a client against a OpenVPN 2.x 
acting as multiple client server. OpenVPN 1.x can only work with 2.x
in point-to-point tunnels.

Changes in string remapping
---------------------------

Quoting James Yonan:
"Prior to 2.0-beta12, the string remapping code was a bit ad-hoc.  Since then
I've tried to unify all string remapping towards a consistent model which
remaps illegal chars to '_'.  The choice of underbar is arbitrary -- any inert
character will do."

So, you must use '_' instead of '.' to represent spaces in certificates names
from now on.

plugin support
--------------

Plugins are now included in the package. They get installed in /usr/lib/openvpn.
Info on what they are and what they do in README.auth-pam and README.down-root.
Append /usr/lib/openvpn/ to the plugin name in the plugin option. 
i.e. 
	plugin /usr/lib/openvpn/openvpn-auth-pam.so [service-type]

Using resolvconf
----------------

Have a look at the shell script /etc/openvpn/update-resolv-conf
It parses DHCP options from openvpn to update /etc/resolv.conf 
To use set as 'up' and 'down' script in your openvpn *.conf:   

up /etc/openvpn/update-resolv-conf
down /etc/openvpn/update-resolv-conf

You will need to install resolvconf package.

Out of Memory issues
-------------------

You might run into issues with openvpn complaining about out of memory. The
reason for this behavior is that openvpn uses mlockall to pin all of its
pages into memory. To correct this issue you can put a "ulimit -l
<reasonable number>" in the openvpn init script.

LDAP+TLS authentication runs into file exhaustion
-------------------------------------------------

When LDAP is used with TLS support a file handle to /dev/urandom is created but
never released on every authentication. This is due to a bug in libgcrypt. 

Lars Ellenberg provided the following worked around: 
Append LD_PRELOAD=/lib/security/pam_ldap.so before the call to openvpn (in the
init.d script). ie:

..... (around line 58 of the init.d script)....
LD_PRELOAD=/lib/security/pam_ldap.so start-stop-daemon --start --quiet --oknodo 

Thanks Andreas Metzler, Lars Ellenberg, Simon Josefsson & chantra for folling
this issue.


Possible consequences of the 'chroot' option
--------------------------------------------

When running OpenVPN on a chroot environment you have to take into account that
things as /dev/log may change (i.e. when syslog is reloaded by logrotate) and
that may result in OpenVPN not logging anymore.

Christian Schneider suggested this solution:
Create an additional "dev/log" socket in the jail by "-a" option to sysklogd or
"$AddUnixListenSocket" parameter in /etc/rsyslog.conf, respectively

Kudos to him, for finding out and proposing a solution.

228 229 230 231 232 233 234 235 236 237 238

Disabling all.send_redirects on tun + topology subnet setups
------------------------------------------------------------

If any of your VPNs uses "dev tun" and "topology subnet" but does not use
"client-to-client", OpenVPN's init.d script will disable all.send_redirects
(set it to 0) to avoid sending ICMP redirects trough the tun interfaces (and
confusing clients).


 -- Alberto Gonzalez Iniesta <agi@inittab.org>  Fri, 24 Feb 2012 11:03:50 +0100