| 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 | GVPE 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 gvpe, 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 |
| … | |
… | |
| 28 | actually need. It also makes the crypto part of the source very |
33 | actually need. It also makes the crypto part of the source very |
| 29 | transparent and easy to inspect. |
34 | transparent and easy to inspect. |
| 30 | |
35 | |
| 31 | : EASY TO SETUP |
36 | : EASY TO SETUP |
| 32 | A few lines of config (the config file is shared unmodified between |
37 | A few lines of config (the config file is shared unmodified between |
| 33 | all hosts) and a single run of ``vpectrl'' to generate the keys |
38 | all hosts) and a single run of ``gvpectrl'' to generate the keys |
| 34 | suffices to make it work. |
39 | suffices to make it work. |
| 35 | |
40 | |
| 36 | : MAC-BASED SECURITY |
41 | : MAC-BASED SECURITY |
| 37 | Since every host has it's own private key, other hosts cannot spoof |
42 | Since every host has it's own private key, other hosts cannot spoof |
| 38 | traffic from this host. That makes it possible to filter packest by |
43 | traffic from this host. That makes it possible to filter packet by |
| 39 | MAC address, e.g. to ensure that packets from a specific IP address |
44 | MAC address, e.g. to ensure that packets from a specific IP address |
| 40 | come, in fact, from a specific host. |
45 | come, in fact, from a specific host that is associated with that IP |
|
|
46 | and not from another host. |
| 41 | |
47 | |
| 42 | |
48 | |
| 43 | ==== PROGRAMS ==== |
49 | ==== PROGRAMS ==== |
| 44 | |
50 | |
| 45 | Vpe comes with two programs: one daemon (``vped'') and one control |
51 | Vpe comes with two programs: one daemon (``gvpe'') and one control |
| 46 | program (``vpectrl''). |
52 | program (``gvpectrl''). |
| 47 | |
53 | |
| 48 | : vpectrl |
54 | : gvpectrl |
| 49 | Is used to generate the keys, check and give an overview of of the |
55 | Is used to generate the keys, check and give an overview of of the |
| 50 | configuration and contorl the daemon (restarting etc.). |
56 | configuration and contorl the daemon (restarting etc.). |
| 51 | |
57 | |
| 52 | : vped |
58 | : gvpe |
| 53 | Is the daemon used to establish and maintain conenctions to the |
59 | Is the daemon used to establish and maintain connections to the |
| 54 | other network members. It should be run on the gateway machine. |
60 | other network members. It should be run on the gateway machine. |
| 55 | |
61 | |
| 56 | |
62 | |
| 57 | ==== COMPILETIME CONFIGURATION ==== |
63 | ==== COMPILETIME CONFIGURATION ==== |
| 58 | |
64 | |
|
|
65 | Please have a look at the ``gvpe.osdep(5)'' manpage for |
|
|
66 | platform-specific information. |
|
|
67 | |
| 59 | Here are a few recipes for compiling your vpe: |
68 | Here are a few recipes for compiling your gvpe: |
| 60 | |
69 | |
| 61 | |
70 | |
| 62 | == AS LOW PACKET OVERHEAD AS POSSIBLE == |
71 | == AS LOW PACKET OVERHEAD AS POSSIBLE == |
| 63 | |
72 | |
| 64 | ./configure --enable-hmac-length=4 --enable-rand-length=0 |
73 | ./configure --enable-hmac-length=4 --enable-rand-length=0 |
| … | |
… | |
| 69 | |
78 | |
| 70 | == MINIMIZE CPU TIME REQUIRED == |
79 | == MINIMIZE CPU TIME REQUIRED == |
| 71 | |
80 | |
| 72 | ./configure --enable-cipher=bf --enable-digest=md4 |
81 | ./configure --enable-cipher=bf --enable-digest=md4 |
| 73 | |
82 | |
| 74 | Use the fastest cipher and digest algorithms currently available in vpe. |
83 | Use the fastest cipher and digest algorithms currently available in |
|
|
84 | gvpe. |
| 75 | |
85 | |
| 76 | |
86 | |
| 77 | == MAXIMIZE SECURITY == |
87 | == MAXIMIZE SECURITY == |
| 78 | |
88 | |
| 79 | ./configure --enable-hmac-length=16 --enable-rand-length=8 --enable-digest=sha1 |
89 | ./configure --enable-hmac-length=16 --enable-rand-length=8 --enable-digest=sha1 |
| … | |
… | |
| 96 | |
106 | |
| 97 | |
107 | |
| 98 | == STEP 1: configuration == |
108 | == STEP 1: configuration == |
| 99 | |
109 | |
| 100 | First you have to create a daemon configuation file and put it into the |
110 | First you have to create a daemon configuation file and put it into the |
| 101 | configuration directory. This is usually ``/etc/vpe'', depending on how |
111 | configuration directory. This is usually ``/etc/gvpe'', depending on how |
| 102 | you configured vpe, and can be overwritten using the ``-c'' commandline |
112 | you configured gvpe, and can be overwritten using the ``-c'' commandline |
| 103 | switch. |
113 | switch. |
| 104 | |
114 | |
| 105 | Put the following lines into ``/etc/vpe/vped.conf'': |
115 | Put the following lines into ``/etc/gvpe/gvpe.conf'': |
| 106 | |
116 | |
| 107 | udp-port = 50000 # the external port to listen on (configure your firewall) |
117 | udp-port = 50000 # the external port to listen on (configure your firewall) |
| 108 | mtu = 1400 # minimum MTU of all outgoing interfaces on all hosts |
118 | mtu = 1400 # minimum MTU of all outgoing interfaces on all hosts |
| 109 | ifname = vpn0 # the local network device name |
119 | ifname = vpn0 # the local network device name |
| 110 | |
120 | |
| … | |
… | |
| 117 | node = third |
127 | node = third |
| 118 | hostname = third.example.net |
128 | hostname = third.example.net |
| 119 | |
129 | |
| 120 | The only other file neccessary if the ``if-up'' script that initializes |
130 | The only other file neccessary if the ``if-up'' script that initializes |
| 121 | the local ethernet interface. Put the following lines into |
131 | the local ethernet interface. Put the following lines into |
| 122 | ``/etc/vpe/if-up'' and make it execute (``chmod 755 /etc/vpe/if-up''): |
132 | ``/etc/gvpe/if-up'' and make it execute (``chmod 755 /etc/gvpe/if-up''): |
| 123 | |
133 | |
| 124 | #!/bin/sh |
134 | #!/bin/sh |
| 125 | ip link set $IFNAME address $MAC mtu $MTU up |
135 | ip link set $IFNAME address $MAC mtu $MTU up |
| 126 | [ $NODENAME = first ] && ip addr add 10.0.1.1 dev $IFNAME |
136 | [ $NODENAME = first ] && ip addr add 10.0.1.1 dev $IFNAME |
| 127 | [ $NODENAME = second ] && ip addr add 10.0.2.1 dev $IFNAME |
137 | [ $NODENAME = second ] && ip addr add 10.0.2.1 dev $IFNAME |
| … | |
… | |
| 131 | This script will give each node a different IP address in the |
141 | This script will give each node a different IP address in the |
| 132 | ``10.0/16'' network. The internal network (e.g. the ``eth0'' interface) |
142 | ``10.0/16'' network. The internal network (e.g. the ``eth0'' interface) |
| 133 | should then be set to a subset of that network, e.g. ``10.0.1.0/24'' on |
143 | should then be set to a subset of that network, e.g. ``10.0.1.0/24'' on |
| 134 | node ``first'', ``10.0.2.0/24'' on node ``second'', and so on. |
144 | node ``first'', ``10.0.2.0/24'' on node ``second'', and so on. |
| 135 | |
145 | |
| 136 | By enabling routing on the gateway host that runs ``vped'' all nodes |
146 | By enabling routing on the gateway host that runs ``gvpe'' all nodes |
| 137 | will be able to reach the other nodes. You can, of course, also use |
147 | will be able to reach the other nodes. You can, of course, also use |
| 138 | proxy arp or other means of pseudo-bridging (or even real briding), or |
148 | proxy arp or other means of pseudo-bridging (or even real briding), or |
| 139 | (best) full routing - the choice is yours. |
149 | (best) full routing - the choice is yours. |
| 140 | |
150 | |
| 141 | |
151 | |
| 142 | == STEP 2: create the RSA key pairs for all hosts == |
152 | == STEP 2: create the RSA key pairs for all hosts == |
| 143 | |
153 | |
| 144 | Run the following command to generate all key pairs (that might take a |
154 | Run the following command to generate all key pairs (that might take a |
| 145 | while): |
155 | while): |
| 146 | |
156 | |
| 147 | vpectrl -c /etc/vpe -g |
157 | gvpectrl -c /etc/gvpe -g |
| 148 | |
158 | |
| 149 | This command will put the public keys into |
159 | This command will put the public keys into |
| 150 | ``/etc/vpe/pubkeys/*nodename*'' and the private keys into |
160 | ``/etc/gvpe/pubkeys/*nodename*'' and the private keys into |
| 151 | ``/etc/vpe/hostkeys/*nodename*''. |
161 | ``/etc/gvpe/hostkeys/*nodename*''. |
| 152 | |
162 | |
| 153 | |
163 | |
| 154 | == STEP 3: distribute the config files to all nodes == |
164 | == STEP 3: distribute the config files to all nodes == |
| 155 | |
165 | |
| 156 | Now distribute the config files to the other nodes. This should be done |
166 | Now distribute the config files to the other nodes. This should be done |
| 157 | in two steps, since the private keys should not be distributed. The |
167 | in two steps, since the private keys should not be distributed. The |
| 158 | example uses rsync-over-ssh |
168 | example uses rsync-over-ssh |
| 159 | |
169 | |
| 160 | First all the config files without the hostkeys should be distributed: |
170 | First all the config files without the hostkeys should be distributed: |
| 161 | |
171 | |
| 162 | rsync -avzessh /etc/vpe first.example.net:/etc/. --exclude hostkeys |
172 | rsync -avzessh /etc/gvpe first.example.net:/etc/. --exclude hostkeys |
| 163 | rsync -avzessh /etc/vpe 133.55.82.9:/etc/. --exclude hostkeys |
173 | rsync -avzessh /etc/gvpe 133.55.82.9:/etc/. --exclude hostkeys |
| 164 | rsync -avzessh /etc/vpe third.example.net:/etc/. --exclude hostkeys |
174 | rsync -avzessh /etc/gvpe third.example.net:/etc/. --exclude hostkeys |
| 165 | |
175 | |
| 166 | Then the hostkeys should be copied: |
176 | Then the hostkeys should be copied: |
| 167 | |
177 | |
| 168 | rsync -avzessh /etc/vpe/hostkeys/first first.example.net:/etc/hostkey |
178 | rsync -avzessh /etc/gvpe/hostkeys/first first.example.net:/etc/hostkey |
| 169 | rsync -avzessh /etc/vpe/hostkeys/second 133.55.82.9:/etc/hostkey |
179 | rsync -avzessh /etc/gvpe/hostkeys/second 133.55.82.9:/etc/hostkey |
| 170 | rsync -avzessh /etc/vpe/hostkeys/third third.example.net:/etc/hostkey |
180 | rsync -avzessh /etc/gvpe/hostkeys/third third.example.net:/etc/hostkey |
| 171 | |
181 | |
| 172 | You should now check the configration by issuing the command ``vpectrl |
182 | You should now check the configration by issuing the command ``gvpectrl |
| 173 | -c /etc/vpe -s'' on each node and verify it's output. |
183 | -c /etc/gvpe -s'' on each node and verify it's output. |
| 174 | |
184 | |
| 175 | |
185 | |
| 176 | == STEP 4: starting vped == |
186 | == STEP 4: starting gvpe == |
| 177 | |
187 | |
| 178 | You should then start vped on each node by issuing a command like: |
188 | You should then start gvpe on each node by issuing a command like: |
| 179 | |
189 | |
| 180 | vped -D -linfo first # first is the nodename |
190 | gvpe -D -linfo first # first is the nodename |
| 181 | |
191 | |
| 182 | This will make the vped stay in foreground. You should then see |
192 | This will make the gvpe stay in foreground. You should then see |
| 183 | "connection established" messages. If you don't see them check your |
193 | "connection established" messages. If you don't see them check your |
| 184 | firewall and routing (use tcpdump ;). |
194 | firewall and routing (use tcpdump ;). |
| 185 | |
195 | |
| 186 | If this works you should check your networking setup by pinging various |
196 | If this works you should check your networking setup by pinging various |
| 187 | endpoints. |
197 | endpoints. |
| 188 | |
198 | |
| 189 | To make vped run more permanently you can either run it as a daemon (by |
199 | To make gvpe run more permanently you can either run it as a daemon (by |
| 190 | starting it without the ``-D'' switch), or, much better, from your |
200 | starting it without the ``-D'' switch), or, much better, from your |
| 191 | inittab. I use a line like this on my systems: |
201 | inittab. I use a line like this on my systems: |
| 192 | |
202 | |
| 193 | t1:2345:respawn:/opt/vpe/sbin/vped -D -L first >/dev/null 2>&1 |
203 | t1:2345:respawn:/opt/gvpe/sbin/gvpe -D -L first >/dev/null 2>&1 |
| 194 | |
204 | |
| 195 | |
205 | |
| 196 | == STEP 5: enjoy == |
206 | == STEP 5: enjoy == |
| 197 | |
207 | |
| 198 | ... and play around. Sending a -HUP (``vpectrl -kHUP'') to the daemon |
208 | ... and play around. Sending a -HUP (``gvpectrl -kHUP'') to the daemon |
| 199 | will make it try to connect to all other nodes again. If you run it from |
209 | will make it try to connect to all other nodes again. If you run it from |
| 200 | inittab, as is recommended, ``vpectrl -k'' (or simply ``killall vped'') |
210 | inittab, as is recommended, ``gvpectrl -k'' (or simply ``killall gvpe'') |
| 201 | will kill the daemon, start it again, making it read it's configuration |
211 | will kill the daemon, start it again, making it read it's configuration |
| 202 | files again. |
212 | files again. |
| 203 | |
213 | |
| 204 | |
214 | |
| 205 | ==== SEE ALSO ==== |
215 | ==== SEE ALSO ==== |
| 206 | |
216 | |
| 207 | vpe(8), vpectrl(8), vped.conf(5). |
217 | gvpe.osdep(5) for OS-depedendent information, gvpe.conf(5), gvpectrl(8), |
|
|
218 | and for a description of the protocol and routing algorithms, |
|
|
219 | gvpe.protocol(7). |
| 208 | |
220 | |
| 209 | |
221 | |
| 210 | ==== AUTHOR ==== |
222 | ==== AUTHOR ==== |
| 211 | |
223 | |
| 212 | Marc Lehmann <vpe@plan9.de> |
224 | Marc Lehmann <gvpe@plan9.de> |
| 213 | |
225 | |
|
|
226 | |
|
|
227 | ==== COPYRIGHTS AND LICENSES ==== |
|
|
228 | |
|
|
229 | Vpe itself is distributed under the GENERAL PUBLIC LICENSE (see the file |
|
|
230 | COPYING that should be part of your distribution). |
|
|
231 | |
|
|
232 | In some configurations it uses modified versions of the tinc vpn suite, |
|
|
233 | which is also available under the GENERAL PUBLIC LICENSE. |
|
|
234 | |
|
|
235 | In some configurations (notably darwin), it uses a poll emulation |
|
|
236 | library that comes with the following license notice: |
|
|
237 | |
|
|
238 | Copyright (c) 1995-2002 Brian M. Clapper |
|
|
239 | All rights reserved. |
|
|
240 | |
|
|
241 | Redistribution and use in source and binary forms are permitted |
|
|
242 | provided that: (1) source distributions retain this entire |
|
|
243 | copyright notice and comment; (2) modifications made to the |
|
|
244 | software are prominently mentioned, and a copy of the original |
|
|
245 | software (or a pointer to its location) are included; and (3) |
|
|
246 | distributions including binaries display the following |
|
|
247 | acknowledgement: "This product includes software developed by Brian |
|
|
248 | M. Clapper <bmc@clapper.org>" in the documentation or other |
|
|
249 | materials provided with the distribution. The name of the author |
|
|
250 | may not be used to endorse or promote products derived from this |
|
|
251 | software without specific prior written permission. |
|
|
252 | |
|
|
253 | THIS SOFTWARE IS PROVIDED ``AS IS'' AND WITHOUT ANY EXPRESS OR |
|
|
254 | IMPLIED WARRANTIES, INCLUDING, WITHOUT LIMITATION, THE IMPLIED |
|
|
255 | WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE. |
|
|
256 | |
