vestasys-vpn - Configure, start, or stop a VPN connection to the vestasys.org network.
vestasys-vpn setup|start|stop|status|restart|help
At this time, this script has only been tested on Linux systems (both IA-32 and Alpha) running 2.4 kernels. pppd (2.4 and up), the ssh client (OpenSSH 2.5.2p2 or newer), and the iptables tools must be installed. The kernel must have support for ppp and iptables, including NAT. RedHat 7.1 meets these requirements out of the box. The Debian ``testing'' distribution with a 2.4 kernel added can meet them.
Lastly, since this script uses native iptables rules, it is incompatible with the backwards-compatibility ipchains support in the 2.4 kernel. RedHat 7.1 uses this by default, and it must be disabled (usually by disabling the /etc/init.d/ipchains script with ``chkconfig --level 0123456 ipchains off''). You can check whether your system is using the ipchains compatibility code with ``lsmod | grep ipchains''.
Before running the setup process, be sure to contact the administrator of the remote server and get some key pieces of information. The setup dialog will ask you for both of these:
Also, you must know enough about your local network setup to be able to decide which hosts will need specific IP associations for NAT. Specifically, if you have any local servers that need to be accessible from the remote network (such as a local Vesta repository), you must assign those hosts specific translated addresses. (See ``Network Address Translation'' below.)
After running the setup process, you must send your ssh authentication key to the VPN administrator so that your connection can be authenticated. (Until you do this, you will be unable to connect.)
This script is designed to be usable in the rc/init framework. On a RedHat system, you can simply place it in /etc/rc.d/init.d and execute ``chkconfig --add vestasys-vpn'' to add the necessary symlinks in the runlevel sub-directories.
IP addresses on the local network are not necessarily usable on the remote network. Therefore, outgoing connections and selected incoming connections will have their addresses translated.
Any hosts on the local network which will provide specific services to the remote one (such as a local Vesta repository or other server) should be assigned a specific IP addresses out of your assigned IP address range. These will get both source and destination NAT rules.
Unassigned addresses in your range will be used for a catch-all multiple-target SNAT rule. This will cause outgoing connections over the VPN link to have their source address translated to an IP selected from the otherwise unused ones.
[The next paragraph gives some details on the NAT rules added by this script. Most people can skip it.]
The address translation rules are placed in user-defined chains in the ``nat'' table named <server>-pre and <server>-post (e.g. wall.vestasys.org-pre and wall.vestasys.org-post). The source NAT rules are placed in the <server>-post chain, and all connections going out over the VPN link are sent to it from the POSTROUTING chain. The destination NAT rules for local hosts assigned specific translated addresses are placed in the <server>-pre chain, and all connections coming in from the VPN link are sent to it from the PREROUTING chain.
Since the point of this script is to create a connection between two networks, it allows the user to specify a list of hosts and networks to be routed over the VPN connection. Once the link becomes active and the NAT packet mangling rules have been added, the routes are set up.
Also, this script assumes that the machine running it will act as a gateway for other machines. For that reason, packet forwarding is enabled once the link is active.
In order to make this useful for other machines, the user must modify other routing tables to direct packets to the machine making the VPN connection that should be forwarded over it. This script provides no help with that.
At this time, this script does not add any rules to filter packets going to or coming from the VPN connection. However, the user is free to add such rules.
Almost all of the information gathered and created during the setup step is stored in a central configuration file. This is usually in /etc/vestasys-org-vpn.conf. The location of the configuration file may be overridden by setting the environment variable VESTASYS_ORG_VPN_CONFIG before running this script.
The config file can contain:
In general, if you need to change something in the configuration, you can just rerun the setup step.
The only environment variable used by this script is VESTASYS_ORG_VPN_CONFIG which can be used to point to an alternate config file location.
A different directory from /etc/ppp can be set in the setup step, but it must be the parent of the peers directory that your pppd uses.
If you have a global ppp options file (usually /etc/ppp/options), it may contain options which will interfere with this script. This script is not smart enough to examine the contents of such a file to determine if the options there will cause problems for the VPN connection. However, it will warn you during the setup step if you have a non-empty global options file.
If the machine running this script has other NAT rules in its PREROUTING and POSTROUTING chains, the rules this script adds may not function properly. (However, we believe that the rules added by this script will not interfere with existing NAT rules.) You can check for existing rules before starting a connection with this script with the command ``iptables --list --table nat --numeric''.
This script does not currently add any rules to filter packets coming from or going to the VPN link.
The setup procedure could probably be a bit less chatty and just assume that if it finds things like pppd and ssh in the standard places that it can use them without asking the user for confirmation of this.
pppd(8), ssh(1), iptables(8), route(8)
The Linux VPN HOWTO (which describes the method this script is based on)
The Netfilter NAT HOWTO (which gives some background on packet mangling with iptables)
Kenneth C. Schalk <ken@xorian.net>