CmuLab: README

File README, 4.3 KB (added by pgunn@cs.cmu.edu, 10 years ago)

Release notes for MetaVPN

Line 
1This documentation is of low quality -- I'll replace it with something better when I get time. Sorry -- Pat
2
3Summary
4---------------------
5
6MetaVPN is a tool that wraps the configuration details of using
7OpenVPN so people with only a conceptual understanding of VPNs
8can use it. The details of setting up an OpenVPN instance are
9wrapped, and people can easily create and manage multiple VPNs at
10the same time. The details of getting a configuration/SSLkey pairing
11for the user are also handled.
12
13State of the code
14----------------------
15
16Beta. Users should be willing to tweak some simple configuration
17parameters at the head of the relevant scripts as appropriate for
18their network. This is still easier than learning OpenVPN.
19
20Prerequisites
21----------------------
22Perl 5.8 or higher
23Nonstandard perl modules: SDBM_File, MLDBM, File::Copy, File::Path, Archive::Tar, CGI, DBI
24        Some of these modules may not be needed depending on which utilities
25        you intend to use
26You do not need Emulab to use MetaVPN (using the "loosely managed" key management)
27
28Files
29----------------------
30        docs/   - Development documentation, unlikely to be of interest.
31        ezpurge - Script to completely remove the configuration
32                database and files for all VPNs
33        metavpn - Primary script, creates, configures, and manages VPNs
34        metv_import_openvpn_keys - For those going with a
35                tightly-managed VPN, this imports the node keys into
36                the emulab database
37        metv_direct_keygen - For those going with a loosely-managed VPN,
38                this generates a configuration tarball for a given client
39        serve_openvpn_keys.cgi - For those going with a tightly-managed
40                VPN, this serves the node keys to clients using a CGI
41                interface
42        openvpn-clients.cfg - Template openvpn config for clients, used
43                by both serve_openvpn_keys and metv_direct_keygen
44
45Details
46-----------------------
47MetaVPN is a wrapper for the OpenVPN software. OpenVPN is a popular
48VPN server. It is a powerful package with a steep learning curve
49and a lack of tools to automate common tasks. MetaVPN attempts to
50lessen the learning curve down to understanding VPN basics, as well
51as reduce the labour needed to configure each VPN. OpenVPN clients must
52each have a unique key permitting them access (and identifying them),
53as well as a configfile with settings that approriately match that on
54the server.
55
56MetaVPN can function in two environments, tightly integrated and loosely
57integrated. In the first, MetaVPN has a single shared instance that
58manages VPNs from potentially a number of people, typically on ops.
59OpenVPN client keys are stored inside the database on boss, and clients
60can use a simple wget-wrapping client to request a configuration tarball
61needed to
62allow them to join the VPN. In the second, MetaVPN can be run on an
63experimental node (or even a non-testbed system outside the Emulab
64environment). In this instance, the person managing that VPN will use
65metv_direct_keygen to directly make tarballs for all clients.
66
67In either environment, the user can use metavpn to see the state of all
68configured VPNs, bring them up or down, add new client keys, create new
69VPNs, or archive/delete VPNs.
70
71Getting Started
72-----------------------------
73After unpacking the software, look at the head of each script that
74you intend to use, changing any paths or other configuration details
75to your liking. In each script, any configuration you may need to
76change exists before the call to main(). Look at the "test1" script
77for simple commands that you might run to setup a VPN. MetaVPN will
78need to be run as root if it is to actually bring VPNs up or down -
79otherwise it will only be able to create configurations and manage
80nodekeys.
81
82Future Development/Bugs
83-----------------------------
84Right now, tap VPNs (Layer 2) are the only kind configurable with this tool.
85tun VPNs (Layer 3) will be supported in a future version provided a sensible
86way to manage bridging, avoid IP collisions, etc. can be found. Some
87configuration variables that are presently hardcoded in the head of
88several scripts will be used into the databases MetaVPN uses so the
89scripts themselves will not need to change so much on a per-site basis.
90Documentation will be improved, and a tutorial covering a simple usage
91will be written.