diff options
Diffstat (limited to 'debian/README.Debian')
| -rw-r--r-- | debian/README.Debian | 257 |
1 files changed, 257 insertions, 0 deletions
diff --git a/debian/README.Debian b/debian/README.Debian new file mode 100644 index 0000000..29b15fe --- /dev/null +++ b/debian/README.Debian @@ -0,0 +1,257 @@ +In this file: + +- systemd service file and limits/capabilities +- '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 +- Disabling all.send_redirects on tun + topology subnet setups + + +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 + +systemd service file and limits/capabilities +-------------------------------------------- + +If you encounter problems [1] (or errors related to permissions) starting +OpenVPN, you may want to check the limits imposed to the OpenVPN service in +/lib/systemd/system/openvpn@.service, notably CapabilityBoundingSet and +LimitNPROC. You may override those executing: +# systemctl edit openvpn@.service + +And setting CapabilityBoundingSet (or LimitNPROC) to be empty: +[Service] +CapabilityBoundingSet=~ + +[1] daemon() failed or unsupported: Resource temporarily unavailable (errno=11) +[2] Failed running command (--route-up): external program exited with error status: 1 + +'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 + +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 + +/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 - as well. + + +##################################### +# 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/<DEB_HOST_MULTIARCH>/openvpn/plugins. +Info on what they are and what they do in README.auth-pam and README.down-root. +Append /usr/lib/<DEB_HOST_MULTIARCH>/openvpn/plugins to the plugin name in +the plugin option. +i.e. + plugin /usr/lib/x86_64-linux-gnu/openvpn/plugins/openvpn-plugin-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. + + +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 |