ViewVC Help
View File | Revision Log | Show Annotations | Download File
/cvs/gvpe/README
(Generate patch)

Comparing gvpe/README (file contents):
Revision 1.2 by pcg, Sun Mar 23 14:58:21 2003 UTC vs.
Revision 1.6 by pcg, Mon Jun 7 03:21:16 2004 UTC

1 1
2==== NAME ==== 2==== NAME ====
3 3
4 vpe - Overview of the virtual private ethernet suite. 4 GNU-VPE - Overview of the GNU Virtual Private Ethernet suite.
5 5
6 6
7==== DESCRIPTION ==== 7==== DESCRIPTION ====
8 8
9 Vpe is a suite designed to provide a virtual private network for 9 Vpe is a suite designed to provide a virtual private network for
10 multiple nodes over an untrusted network. 10 multiple nodes over an untrusted network.
11 11
12 "Virtual" means that no physical network is created (of course), but an 12 "Virtual" means that no physical network is created (of course), but an
13 ethernet is emulated by creating multiple tunnels between the member 13 ethernet is emulated by creating multiple tunnels between the member
14 nodes.
15
14 nodes. "Private" means that non-participating nodes cannot decode 16 "Private" means that non-participating nodes cannot decode ("sniff)" nor
15 ("sniff)" nor inject ("spoof") packets. In the case of vpe, even 17 inject ("spoof") packets.
16 participating nodes cannot spoof packets from other nodes. And "network" 18
17 means that more than two parties - many so-called vpn solutions only 19 In the case of vpe, even participating nodes cannot sniff packets send
18 create point-to-point tunnels - can participate in the network, so it's 20 to other nodes or spoof packets as if sent from other nodes.
19 possible to connect multiple branches of a company into a single 21
20 network. 22 "Network" means that more than two parties can participate in the
23 network, so for instance it's possible to connect multiple branches of a
24 company into a single network. Many so-called "vpn" solutions only
25 create point-to-point tunnels.
21 26
22 27
23== DESIGN GOALS == 28== DESIGN GOALS ==
24 29
25: SIMPLE DESIGN 30: SIMPLE DESIGN
… …
41 46
42 47
43==== PROGRAMS ==== 48==== PROGRAMS ====
44 49
45 Vpe comes with two programs: one daemon (``vped'') and one control 50 Vpe comes with two programs: one daemon (``vped'') and one control
46 program ``vpectrl''). 51 program (``vpectrl'').
47 52
48: vpectrl 53: vpectrl
49 Is used to generate the keys and give an overview of the 54 Is used to generate the keys, check and give an overview of of the
50 configuration. 55 configuration and contorl the daemon (restarting etc.).
51 56
52: vped 57: vped
53 Is the daemon used to establish and maintain conenctions to the 58 Is the daemon used to establish and maintain conenctions to the
54 other network members. It should be run on the gateway machine. 59 other network members. It should be run on the gateway machine.
55 60
56 61
57==== CONFIGURING VPE ==== 62==== COMPILETIME CONFIGURATION ====
58 63
64 Please have a look at the ``vpe.osdep(5)'' manpage for platform-specific
65 information.
66
59 Here are a few recipes for configuring your vpe: 67 Here are a few recipes for compiling your vpe:
60 68
61 69
62== AS LOW PACKET OVERHEAD AS POSSIBLE == 70== AS LOW PACKET OVERHEAD AS POSSIBLE ==
63 71
64 ./configure --enable-hmac-length=4 --enable-rand-length=0 72 ./configure --enable-hmac-length=4 --enable-rand-length=0
65 73
66 Minimize the header overhead of VPN packets. 74 Minimize the header overhead of VPN packets (the above will result in
75 only 4 bytes of overhead over the raw ethernet frame).
67 76
68 77
69== MINIMIZE CPU TIME REQUIRED == 78== MINIMIZE CPU TIME REQUIRED ==
70 79
71 ./configure --enable-cipher=bf --enable-digest=md4 80 ./configure --enable-cipher=bf --enable-digest=md4
72 81
73 Use the fastest cipher and digest algorithms. 82 Use the fastest cipher and digest algorithms currently available in vpe.
74 83
75 84
76== MAXIMIZE SECURITY == 85== MAXIMIZE SECURITY ==
77 86
78 ./configure --enable-hmac-length=16 --enable-rand-length=8 --enable-digest=sha1 87 ./configure --enable-hmac-length=16 --enable-rand-length=8 --enable-digest=sha1
88
89 This uses a 16 byte HMAC checksum to authenticate packets (I guess 8-12
90 would also be pretty secure ;) and will additionally prefix each packet
91 with 8 bytes of random data.
79 92
80 In general, remember that AES-128 seems to be more secure and faster 93 In general, remember that AES-128 seems to be more secure and faster
81 than AES-192 or AES-256, more randomness and longer hmac is more secure, 94 than AES-192 or AES-256, more randomness helps against sniffing and a
82 MD4 is a fast digest, SHA1 or RIPEMD160 are better, and Blowfish is a 95 longer HMAC helps against spoofing. MD4 is a fast digest, SHA1 or
83 fast and so-far quite secure cipher. 96 RIPEMD160 are better, and Blowfish is a fast cipher (and also quite
97 secure).
84 98
85 99
86==== HOW TO SET UP A SIMPLE VPN ==== 100==== HOW TO SET UP A SIMPLE VPN ====
87 101
88 In this section I will describe how to get a simple VPN consisting of 102 In this section I will describe how to get a simple VPN consisting of
… …
96 you configured vpe, and can be overwritten using the ``-c'' commandline 110 you configured vpe, and can be overwritten using the ``-c'' commandline
97 switch. 111 switch.
98 112
99 Put the following lines into ``/etc/vpe/vped.conf'': 113 Put the following lines into ``/etc/vpe/vped.conf'':
100 114
101 udp-port = 50000 # the external port to listen on (configure your firewall) 115 udp-port = 50000 # the external port to listen on (configure your firewall)
102 mtu = 1400 # minimum MTU of all outgoing interfaces on all hosts 116 mtu = 1400 # minimum MTU of all outgoing interfaces on all hosts
103 ifname = vpn0 # the local network device name 117 ifname = vpn0 # the local network device name
104 118
105 node = first # just a nickname 119 node = first # just a nickname
106 hostname = first.example.net # the DNS name or IP address of the host 120 hostname = first.example.net # the DNS name or IP address of the host
107 121
108 node = second 122 node = second
109 hostname = 133.55.82.9 123 hostname = 133.55.82.9
110 124
111 node = third 125 node = third
112 hostname = third.example.net 126 hostname = third.example.net
113 127
114 The only other file neccessary if the ``if-up'' script that initializes 128 The only other file neccessary if the ``if-up'' script that initializes
115 the local ethernet interface. Put the following lines into 129 the local ethernet interface. Put the following lines into
116 ``/etc/vpe/if-up'' and make it execute (``chmod 755 /etc/vpe/if-up''): 130 ``/etc/vpe/if-up'' and make it execute (``chmod 755 /etc/vpe/if-up''):
117 131
118 #!/bin/sh 132 #!/bin/sh
119 ip link set $IFNAME address $MAC mtu $MTU up 133 ip link set $IFNAME address $MAC mtu $MTU up
120 [ $NODENAME = first ] && ip addr add 10.0.1.1 dev $IFNAME 134 [ $NODENAME = first ] && ip addr add 10.0.1.1 dev $IFNAME
121 [ $NODENAME = second ] && ip addr add 10.0.2.1 dev $IFNAME 135 [ $NODENAME = second ] && ip addr add 10.0.2.1 dev $IFNAME
122 [ $NODENAME = third ] && ip addr add 10.0.3.1 dev $IFNAME 136 [ $NODENAME = third ] && ip addr add 10.0.3.1 dev $IFNAME
123 ip route add 10.0.0.0/16 dev $IFNAME 137 ip route add 10.0.0.0/16 dev $IFNAME
124 138
125 This script will give each node a different IP address in the 139 This script will give each node a different IP address in the
126 ``10.0/16'' network. The internal network (e.g. the ``eth0'' interface) 140 ``10.0/16'' network. The internal network (e.g. the ``eth0'' interface)
127 should then be set to a subset of that network, e.g. ``10.0.1.0/24'' on 141 should then be set to a subset of that network, e.g. ``10.0.1.0/24'' on
128 node ``first'', ``10.0.2.0/24'' on node ``second'', and so on. 142 node ``first'', ``10.0.2.0/24'' on node ``second'', and so on.
… …
136== STEP 2: create the RSA key pairs for all hosts == 150== STEP 2: create the RSA key pairs for all hosts ==
137 151
138 Run the following command to generate all key pairs (that might take a 152 Run the following command to generate all key pairs (that might take a
139 while): 153 while):
140 154
141 vpectrl -c /etc/vpe -g 155 vpectrl -c /etc/vpe -g
142 156
143 This command will put the public keys into 157 This command will put the public keys into
144 ``/etc/vpe/pubkeys/*nodename*'' and the private keys into 158 ``/etc/vpe/pubkeys/*nodename*'' and the private keys into
145 ``/etc/vpe/hostkeys/*nodename*''. 159 ``/etc/vpe/hostkeys/*nodename*''.
146 160
… …
151 in two steps, since the private keys should not be distributed. The 165 in two steps, since the private keys should not be distributed. The
152 example uses rsync-over-ssh 166 example uses rsync-over-ssh
153 167
154 First all the config files without the hostkeys should be distributed: 168 First all the config files without the hostkeys should be distributed:
155 169
156 rsync -avzessh /etc/vpe first.example.net:/etc/. --exclude hostkeys 170 rsync -avzessh /etc/vpe first.example.net:/etc/. --exclude hostkeys
157 rsync -avzessh /etc/vpe 133.55.82.9:/etc/. --exclude hostkeys 171 rsync -avzessh /etc/vpe 133.55.82.9:/etc/. --exclude hostkeys
158 rsync -avzessh /etc/vpe third.example.net:/etc/. --exclude hostkeys 172 rsync -avzessh /etc/vpe third.example.net:/etc/. --exclude hostkeys
159 173
160 Then the hostkeys should be copied: 174 Then the hostkeys should be copied:
161 175
162 rsync -avzessh /etc/vpe/hostkeys/first first.example.net:/etc/hostkey 176 rsync -avzessh /etc/vpe/hostkeys/first first.example.net:/etc/hostkey
163 rsync -avzessh /etc/vpe/hostkeys/second 133.55.82.9:/etc/hostkey 177 rsync -avzessh /etc/vpe/hostkeys/second 133.55.82.9:/etc/hostkey
164 rsync -avzessh /etc/vpe/hostkeys/third third.example.net:/etc/hostkey 178 rsync -avzessh /etc/vpe/hostkeys/third third.example.net:/etc/hostkey
165 179
166 You should now check the configration by issuing the command ``vpectrl 180 You should now check the configration by issuing the command ``vpectrl
167 -c /etc/vpe -s'' on each node and verify it's output. 181 -c /etc/vpe -s'' on each node and verify it's output.
168 182
169 183
170== STEP 4: starting vped == 184== STEP 4: starting vped ==
171 185
172 You should then start vped on each node by issuing a command like: 186 You should then start vped on each node by issuing a command like:
173 187
174 vped -D -linfo first # first is the nodename 188 vped -D -linfo first # first is the nodename
175 189
176 This will make the vped stay in foreground. You should then see 190 This will make the vped stay in foreground. You should then see
177 "connection established" messages. If you don't see them check your 191 "connection established" messages. If you don't see them check your
178 firewall and routing (use tcpdump ;). 192 firewall and routing (use tcpdump ;).
179 193
… …
182 196
183 To make vped run more permanently you can either run it as a daemon (by 197 To make vped run more permanently you can either run it as a daemon (by
184 starting it without the ``-D'' switch), or, much better, from your 198 starting it without the ``-D'' switch), or, much better, from your
185 inittab. I use a line like this on my systems: 199 inittab. I use a line like this on my systems:
186 200
187 t1:2345:respawn:/opt/vpe/sbin/vped -D -L first >/dev/null 2>&1 201 t1:2345:respawn:/opt/vpe/sbin/vped -D -L first >/dev/null 2>&1
188 202
189 203
190== STEP 5: enjoy == 204== STEP 5: enjoy ==
191 205
192 ... and play around. Sending a -HUP (``vpectrl -kHUP'') to the daemon 206 ... and play around. Sending a -HUP (``vpectrl -kHUP'') to the daemon
… …
196 files again. 210 files again.
197 211
198 212
199==== SEE ALSO ==== 213==== SEE ALSO ====
200 214
201 vpe(8), vpectrl(8), vped.conf(5). 215 vpe.osdep(5) for OS-depedendent information, vped.conf(5), vpectrl(8),
216 and for a description of the protocol and routing algorithms,
217 vpe.protocol(7).
202 218
203 219
204==== AUTHOR ==== 220==== AUTHOR ====
205 221
206 Marc Lehmann <vpe@plan9.de> 222 Marc Lehmann <vpe@plan9.de>
207 223
224
225==== COPYRIGHTS AND LICENSES ====
226
227 Vpe itself is distributed under the GENERAL PUBLIC LICENSE (see the file
228 COPYING that should be part of your distribution).
229
230 In some configurations it uses modified versions of the tinc vpn suite,
231 which is also available under the GENERAL PUBLIC LICENSE.
232
233 In some configurations (notably darwin), it uses a poll emulation
234 library that comes with the following license notice:
235
236 Copyright (c) 1995-2002 Brian M. Clapper
237 All rights reserved.
238
239 Redistribution and use in source and binary forms are permitted
240 provided that: (1) source distributions retain this entire
241 copyright notice and comment; (2) modifications made to the
242 software are prominently mentioned, and a copy of the original
243 software (or a pointer to its location) are included; and (3)
244 distributions including binaries display the following
245 acknowledgement: "This product includes software developed by Brian
246 M. Clapper <bmc@clapper.org>" in the documentation or other
247 materials provided with the distribution. The name of the author
248 may not be used to endorse or promote products derived from this
249 software without specific prior written permission.
250
251 THIS SOFTWARE IS PROVIDED ``AS IS'' AND WITHOUT ANY EXPRESS OR
252 IMPLIED WARRANTIES, INCLUDING, WITHOUT LIMITATION, THE IMPLIED
253 WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE.
254

Diff Legend

– Removed lines
+ Added lines
< Changed lines
> Changed lines