ViewVC Help
View File | Revision Log | Show Annotations | Download File
/cvs/gvpe/doc/gvpe.5
Revision: 1.11
Committed: Wed Sep 3 04:58:46 2008 UTC (15 years, 8 months ago) by pcg
Branch: MAIN
CVS Tags: rel-2_21, rel-2_22
Changes since 1.10: +6 -6 lines
Log Message:
2.21

File Contents

# Content
1 .\" Automatically generated by Pod::Man 2.16 (Pod::Simple 3.05)
2 .\"
3 .\" Standard preamble:
4 .\" ========================================================================
5 .de Sh \" Subsection heading
6 .br
7 .if t .Sp
8 .ne 5
9 .PP
10 \fB\\$1\fR
11 .PP
12 ..
13 .de Sp \" Vertical space (when we can't use .PP)
14 .if t .sp .5v
15 .if n .sp
16 ..
17 .de Vb \" Begin verbatim text
18 .ft CW
19 .nf
20 .ne \\$1
21 ..
22 .de Ve \" End verbatim text
23 .ft R
24 .fi
25 ..
26 .\" Set up some character translations and predefined strings. \*(-- will
27 .\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
28 .\" double quote, and \*(R" will give a right double quote. \*(C+ will
29 .\" give a nicer C++. Capital omega is used to do unbreakable dashes and
30 .\" therefore won't be available. \*(C` and \*(C' expand to `' in nroff,
31 .\" nothing in troff, for use with C<>.
32 .tr \(*W-
33 .ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
34 .ie n \{\
35 . ds -- \(*W-
36 . ds PI pi
37 . if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
38 . if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\" diablo 12 pitch
39 . ds L" ""
40 . ds R" ""
41 . ds C`
42 . ds C'
43 'br\}
44 .el\{\
45 . ds -- \|\(em\|
46 . ds PI \(*p
47 . ds L" ``
48 . ds R" ''
49 'br\}
50 .\"
51 .\" Escape single quotes in literal strings from groff's Unicode transform.
52 .ie \n(.g .ds Aq \(aq
53 .el .ds Aq '
54 .\"
55 .\" If the F register is turned on, we'll generate index entries on stderr for
56 .\" titles (.TH), headers (.SH), subsections (.Sh), items (.Ip), and index
57 .\" entries marked with X<> in POD. Of course, you'll have to process the
58 .\" output yourself in some meaningful fashion.
59 .ie \nF \{\
60 . de IX
61 . tm Index:\\$1\t\\n%\t"\\$2"
62 ..
63 . nr % 0
64 . rr F
65 .\}
66 .el \{\
67 . de IX
68 ..
69 .\}
70 .\"
71 .\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2).
72 .\" Fear. Run. Save yourself. No user-serviceable parts.
73 . \" fudge factors for nroff and troff
74 .if n \{\
75 . ds #H 0
76 . ds #V .8m
77 . ds #F .3m
78 . ds #[ \f1
79 . ds #] \fP
80 .\}
81 .if t \{\
82 . ds #H ((1u-(\\\\n(.fu%2u))*.13m)
83 . ds #V .6m
84 . ds #F 0
85 . ds #[ \&
86 . ds #] \&
87 .\}
88 . \" simple accents for nroff and troff
89 .if n \{\
90 . ds ' \&
91 . ds ` \&
92 . ds ^ \&
93 . ds , \&
94 . ds ~ ~
95 . ds /
96 .\}
97 .if t \{\
98 . ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u"
99 . ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u'
100 . ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u'
101 . ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u'
102 . ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u'
103 . ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u'
104 .\}
105 . \" troff and (daisy-wheel) nroff accents
106 .ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V'
107 .ds 8 \h'\*(#H'\(*b\h'-\*(#H'
108 .ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#]
109 .ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H'
110 .ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u'
111 .ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#]
112 .ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#]
113 .ds ae a\h'-(\w'a'u*4/10)'e
114 .ds Ae A\h'-(\w'A'u*4/10)'E
115 . \" corrections for vroff
116 .if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u'
117 .if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u'
118 . \" for low resolution devices (crt and lpr)
119 .if \n(.H>23 .if \n(.V>19 \
120 \{\
121 . ds : e
122 . ds 8 ss
123 . ds o a
124 . ds d- d\h'-1'\(ga
125 . ds D- D\h'-1'\(hy
126 . ds th \o'bp'
127 . ds Th \o'LP'
128 . ds ae ae
129 . ds Ae AE
130 .\}
131 .rm #[ #] #H #V #F C
132 .\" ========================================================================
133 .\"
134 .IX Title "GVPE 5"
135 .TH GVPE 5 "2008-09-01" "2.2" "GNU Virtual Private Ethernet"
136 .\" For nroff, turn off justification. Always turn off hyphenation; it makes
137 .\" way too many mistakes in technical documents.
138 .if n .ad l
139 .nh
140 .SH "NAME"
141 GNU\-VPE \- Overview of the GNU Virtual Private Ethernet suite.
142 .SH "DESCRIPTION"
143 .IX Header "DESCRIPTION"
144 \&\s-1GVPE\s0 is a suite designed to provide a virtual private network for multiple
145 nodes over an untrusted network. This document first gives an introduction
146 to VPNs in general and then describes the specific implementation of \s-1GVPE\s0.
147 .Sh "\s-1WHAT\s0 \s-1IS\s0 A \s-1VPN\s0?"
148 .IX Subsection "WHAT IS A VPN?"
149 \&\s-1VPN\s0 is an acronym, it stands for:
150 .IP "Virtual" 4
151 .IX Item "Virtual"
152 Virtual means that no physical network is created (of course), but a
153 network is \fIemulated\fR by creating multiple tunnels between the member
154 nodes by encapsulating and sending data over another transport network.
155 .Sp
156 Usually the emulated network is a normal \s-1IP\s0 or Ethernet, and the transport
157 network is the Internet. However, using a \s-1VPN\s0 system like \s-1GVPE\s0 to connect
158 nodes over other untrusted networks such as Wireless \s-1LAN\s0 is not uncommon.
159 .IP "Private" 4
160 .IX Item "Private"
161 Private means that non-participating nodes cannot decode (\*(L"sniff)\*(R" nor
162 inject (\*(L"spoof\*(R") packets. This means that nodes can be connected over
163 untrusted networks such as the public Internet without fear of being
164 eavesdropped while at the same time being able to trust data sent by other
165 nodes.
166 .Sp
167 In the case of \s-1GVPE\s0, even participating nodes cannot sniff packets
168 send to other nodes or spoof packets as if sent from other nodes, so
169 communications between any two nodes is private to those two nodes.
170 .IP "Network" 4
171 .IX Item "Network"
172 Network means that more than two parties can participate in the network,
173 so for instance it's possible to connect multiple branches of a company
174 into a single network. Many so-called \*(L"\s-1VPN\s0\*(R" solutions only create
175 point-to-point tunnels, which in turn can be used to build larger
176 networks.
177 .Sp
178 \&\s-1GVPE\s0 provides a true multi-point network in which any number of nodes (at
179 least a few dozen in practise, the theoretical limit is 4095 nodes) can
180 participate.
181 .Sh "\s-1GVPE\s0 \s-1DESIGN\s0 \s-1GOALS\s0"
182 .IX Subsection "GVPE DESIGN GOALS"
183 .IP "\s-1SIMPLE\s0 \s-1DESIGN\s0" 4
184 .IX Item "SIMPLE DESIGN"
185 Cipher, \s-1HMAC\s0 algorithms and other key parameters must be selected
186 at compile time \- this makes it possible to only link in algorithms
187 you actually need. It also makes the crypto part of the source very
188 transparent and easy to inspect, and last not least this makes it possible
189 to hardcode the layout of all packets into the binary. \s-1GVPE\s0 goes a step
190 further and internally reserves blocks of the same length for all packets,
191 which virtually removes all possibilities of buffer overflows, as there is
192 only a single type of buffer and it's always of fixed length.
193 .IP "\s-1EASY\s0 \s-1TO\s0 \s-1SETUP\s0" 4
194 .IX Item "EASY TO SETUP"
195 A few lines of config (the config file is shared unmodified between all
196 hosts) and a single run of \f(CW\*(C`gvpectrl\*(C'\fR to generate the keys suffices to
197 make it work.
198 .IP "MAC-BASED \s-1SECURITY\s0" 4
199 .IX Item "MAC-BASED SECURITY"
200 Since every host has it's own private key, other hosts cannot spoof
201 traffic from this host. That makes it possible to filter packet by \s-1MAC\s0
202 address, e.g. to ensure that packets from a specific \s-1IP\s0 address come, in
203 fact, from a specific host that is associated with that \s-1IP\s0 and not from
204 another host.
205 .SH "PROGRAMS"
206 .IX Header "PROGRAMS"
207 Gvpe comes with two programs: one daemon (\f(CW\*(C`gvpe\*(C'\fR) and one control program
208 (\f(CW\*(C`gvpectrl\*(C'\fR).
209 .IP "gvpectrl" 4
210 .IX Item "gvpectrl"
211 This program is used to generate the keys, check and give an overview of of the
212 configuration and to control the daemon (restarting etc.).
213 .IP "gvpe" 4
214 .IX Item "gvpe"
215 This is the daemon used to establish and maintain connections to the other
216 network nodes. It should be run on the gateway of each \s-1VPN\s0 subnet.
217 .SH "COMPILETIME CONFIGURATION"
218 .IX Header "COMPILETIME CONFIGURATION"
219 Please have a look at the \f(CW\*(C`gvpe.osdep(5)\*(C'\fR manpage for platform-specific
220 information.
221 .PP
222 Gvpe hardcodes most encryption parameters. While this reduces flexibility,
223 it makes the program much simpler and helps making buffer overflows
224 impossible under most circumstances.
225 .PP
226 Here are a few recipes for compiling your gvpe, showing the extremes
227 (fast, small, insecure \s-1OR\s0 slow, large, more secure), between which you
228 should choose:
229 .Sh "\s-1AS\s0 \s-1LOW\s0 \s-1PACKET\s0 \s-1OVERHEAD\s0 \s-1AS\s0 \s-1POSSIBLE\s0"
230 .IX Subsection "AS LOW PACKET OVERHEAD AS POSSIBLE"
231 .Vb 1
232 \& ./configure \-\-enable\-hmac\-length=4 \-\-enable\-rand\-length=0
233 .Ve
234 .PP
235 Minimize the header overhead of \s-1VPN\s0 packets (the above will result in
236 only 4 bytes of overhead over the raw ethernet frame). This is a insecure
237 configuration because a \s-1HMAC\s0 length of 4 makes collision attacks based on
238 the birthday paradox pretty easy.
239 .Sh "\s-1MINIMIZE\s0 \s-1CPU\s0 \s-1TIME\s0 \s-1REQUIRED\s0"
240 .IX Subsection "MINIMIZE CPU TIME REQUIRED"
241 .Vb 1
242 \& ./configure \-\-enable\-cipher=bf \-\-enable\-digest=md4
243 .Ve
244 .PP
245 Use the fastest cipher and digest algorithms currently available in
246 gvpe. \s-1MD4\s0 has been broken and is quite insecure, though, so using another
247 digest algorithm is recommended.
248 .Sh "\s-1MAXIMIZE\s0 \s-1SECURITY\s0"
249 .IX Subsection "MAXIMIZE SECURITY"
250 .Vb 1
251 \& ./configure \-\-enable\-hmac\-length=16 \-\-enable\-rand\-length=8 \-\-enable\-digest=sha1
252 .Ve
253 .PP
254 This uses a 16 byte \s-1HMAC\s0 checksum to authenticate packets (I guess 8\-12
255 would also be pretty secure ;) and will additionally prefix each packet
256 with 8 bytes of random data. In the long run, people should move to
257 \&\s-1SHA\-256\s0 and beyond).
258 .PP
259 In general, remember that \s-1AES\-128\s0 seems to be as secure but faster than
260 \&\s-1AES\-192\s0 or \s-1AES\-256\s0, more randomness helps against sniffing and a longer
261 \&\s-1HMAC\s0 helps against spoofing. \s-1MD4\s0 is a fast digest, \s-1SHA1\s0, \s-1RIPEMD160\s0, \s-1SHA256\s0
262 are consecutively better, and Blowfish is a fast cipher (and also quite
263 secure).
264 .SH "HOW TO SET UP A SIMPLE VPN"
265 .IX Header "HOW TO SET UP A SIMPLE VPN"
266 In this section I will describe how to get a simple \s-1VPN\s0 consisting of
267 three hosts up and running.
268 .Sh "\s-1STEP\s0 1: configuration"
269 .IX Subsection "STEP 1: configuration"
270 First you have to create a daemon configuration file and put it into the
271 configuration directory. This is usually \f(CW\*(C`/etc/gvpe\*(C'\fR, depending on how you
272 configured gvpe, and can be overwritten using the \f(CW\*(C`\-c\*(C'\fR command line switch.
273 .PP
274 Put the following lines into \f(CW\*(C`/etc/gvpe/gvpe.conf\*(C'\fR:
275 .PP
276 .Vb 3
277 \& udp\-port = 50000 # the external port to listen on (configure your firewall)
278 \& mtu = 1400 # minimum MTU of all outgoing interfaces on all hosts
279 \& ifname = vpn0 # the local network device name
280 \&
281 \& node = first # just a nickname
282 \& hostname = first.example.net # the DNS name or IP address of the host
283 \&
284 \& node = second
285 \& hostname = 133.55.82.9
286 \&
287 \& node = third
288 \& hostname = third.example.net
289 .Ve
290 .PP
291 The only other file necessary is the \f(CW\*(C`if\-up\*(C'\fR script that initializes the
292 virtual ethernet interface on the local host. Put the following lines into
293 \&\f(CW\*(C`/etc/gvpe/if\-up\*(C'\fR and make it executable (\f(CW\*(C`chmod 755 /etc/gvpe/if\-up\*(C'\fR):
294 .PP
295 .Vb 6
296 \& #!/bin/sh
297 \& ip link set $IFNAME address $MAC mtu $MTU up
298 \& [ $NODENAME = first ] && ip addr add 10.0.1.1 dev $IFNAME
299 \& [ $NODENAME = second ] && ip addr add 10.0.2.1 dev $IFNAME
300 \& [ $NODENAME = third ] && ip addr add 10.0.3.1 dev $IFNAME
301 \& ip route add 10.0.0.0/16 dev $IFNAME
302 .Ve
303 .PP
304 This script will give each node a different \s-1IP\s0 address in the \f(CW\*(C`10.0/16\*(C'\fR
305 network. The internal network (if gvpe runs on a router) should then be
306 set to a subset of that network, e.g. \f(CW\*(C`10.0.1.0/24\*(C'\fR on node \f(CW\*(C`first\*(C'\fR,
307 \&\f(CW\*(C`10.0.2.0/24\*(C'\fR on node \f(CW\*(C`second\*(C'\fR, and so on.
308 .PP
309 By enabling routing on the gateway host that runs \f(CW\*(C`gvpe\*(C'\fR all nodes will
310 be able to reach the other nodes. You can, of course, also use proxy \s-1ARP\s0
311 or other means of pseudo-bridging, or (best) full routing \- the choice is
312 yours.
313 .Sh "\s-1STEP\s0 2: create the \s-1RSA\s0 key pairs for all hosts"
314 .IX Subsection "STEP 2: create the RSA key pairs for all hosts"
315 Run the following command to generate all key pairs for all nodes (that
316 might take a while):
317 .PP
318 .Vb 1
319 \& gvpectrl \-c /etc/gvpe \-g
320 .Ve
321 .PP
322 This command will put the public keys into \f(CW\*(C`/etc/gvpe/pubkeys/\f(CInodename\f(CW\*(C'\fR and the private keys into \f(CW\*(C`/etc/gvpe/hostkeys/\f(CInodename\f(CW\*(C'\fR.
323 .Sh "\s-1STEP\s0 3: distribute the config files to all nodes"
324 .IX Subsection "STEP 3: distribute the config files to all nodes"
325 Now distribute the config files and private keys to the other nodes. This
326 should be done in two steps, since only the private keys meant for a node
327 should be distributed (so each node has only it's own private key).
328 .PP
329 The example uses rsync-over-ssh
330 .PP
331 First all the config files without the hostkeys should be distributed:
332 .PP
333 .Vb 3
334 \& rsync \-avzessh /etc/gvpe first.example.net:/etc/. \-\-exclude hostkeys
335 \& rsync \-avzessh /etc/gvpe 133.55.82.9:/etc/. \-\-exclude hostkeys
336 \& rsync \-avzessh /etc/gvpe third.example.net:/etc/. \-\-exclude hostkeys
337 .Ve
338 .PP
339 Then the hostkeys should be copied:
340 .PP
341 .Vb 3
342 \& rsync \-avzessh /etc/gvpe/hostkeys/first first.example.net:/etc/hostkey
343 \& rsync \-avzessh /etc/gvpe/hostkeys/second 133.55.82.9:/etc/hostkey
344 \& rsync \-avzessh /etc/gvpe/hostkeys/third third.example.net:/etc/hostkey
345 .Ve
346 .PP
347 You should now check the configuration by issuing the command \f(CW\*(C`gvpectrl \-c
348 /etc/gvpe \-s\*(C'\fR on each node and verify it's output.
349 .Sh "\s-1STEP\s0 4: starting gvpe"
350 .IX Subsection "STEP 4: starting gvpe"
351 You should then start gvpe on each node by issuing a command like:
352 .PP
353 .Vb 1
354 \& gvpe \-D \-l info first # first is the nodename
355 .Ve
356 .PP
357 This will make the gvpe daemon stay in foreground. You should then see
358 \&\*(L"connection established\*(R" messages. If you don't see them check your
359 firewall and routing (use tcpdump ;).
360 .PP
361 If this works you should check your networking setup by pinging various
362 endpoints.
363 .PP
364 To make gvpe run more permanently you can either run it as a daemon (by
365 starting it without the \f(CW\*(C`\-D\*(C'\fR switch), or, much better, from your inittab
366 or equivalent. I use a line like this on all my systems:
367 .PP
368 .Vb 1
369 \& t1:2345:respawn:/opt/gvpe/sbin/gvpe \-D \-L first >/dev/null 2>&1
370 .Ve
371 .Sh "\s-1STEP\s0 5: enjoy"
372 .IX Subsection "STEP 5: enjoy"
373 \&... and play around. Sending a \-HUP (\f(CW\*(C`gvpectrl \-kHUP\*(C'\fR) to the daemon
374 will make it try to connect to all other nodes again. If you run it from
375 inittab, as is recommended, \f(CW\*(C`gvpectrl \-k\*(C'\fR (or simply \f(CW\*(C`killall gvpe\*(C'\fR) will
376 kill the daemon, start it again, making it read it's configuration files
377 again.
378 .SH "SEE ALSO"
379 .IX Header "SEE ALSO"
380 \&\fIgvpe.osdep\fR\|(5) for OS-dependent information, \fIgvpe.conf\fR\|(5), \fIgvpectrl\fR\|(8),
381 and for a description of the transports, protocol, and routing algorithm,
382 \&\fIgvpe.protocol\fR\|(7).
383 .PP
384 The \s-1GVPE\s0 mailing list, at <http://lists.schmorp.de/>, or
385 \&\f(CW\*(C`gvpe@lists.schmorp.de\*(C'\fR.
386 .SH "AUTHOR"
387 .IX Header "AUTHOR"
388 Marc Lehmann <gvpe@schmorp.de>
389 .SH "COPYRIGHTS AND LICENSES"
390 .IX Header "COPYRIGHTS AND LICENSES"
391 \&\s-1GVPE\s0 itself is distributed under the \s-1GENERAL\s0 \s-1PUBLIC\s0 \s-1LICENSE\s0 (see the file
392 \&\s-1COPYING\s0 that should be part of your distribution).
393 .PP
394 In some configurations it uses modified versions of the tinc vpn suite,
395 which is also available under the \s-1GENERAL\s0 \s-1PUBLIC\s0 \s-1LICENSE\s0.