ViewVC Help
View File | Revision Log | Show Annotations | Download File
/cvs/gvpe/doc/vpe.8
Revision: 1.4
Committed: Fri Mar 28 18:14:57 2003 UTC (21 years, 2 months ago) by pcg
Branch: MAIN
CVS Tags: HEAD
Changes since 1.3: +0 -0 lines
State: FILE REMOVED
Log Message:
*** empty log message ***

File Contents

# User Rev Content
1 pcg 1.1 .\" Automatically generated by Pod::Man v1.36, Pod::Parser v1.13
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. | will give a
29     .\" real vertical bar. \*(C+ will give a nicer C++. Capital omega is used to
30     .\" do unbreakable dashes and therefore won't be available. \*(C` and \*(C'
31     .\" expand to `' in nroff, nothing in troff, for use with C<>.
32     .tr \(*W-|\(bv\*(Tr
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     .\" If the F register is turned on, we'll generate index entries on stderr for
52     .\" titles (.TH), headers (.SH), subsections (.Sh), items (.Ip), and index
53     .\" entries marked with X<> in POD. Of course, you'll have to process the
54     .\" output yourself in some meaningful fashion.
55     .if \nF \{\
56     . de IX
57     . tm Index:\\$1\t\\n%\t"\\$2"
58     ..
59     . nr % 0
60     . rr F
61     .\}
62     .\"
63     .\" For nroff, turn off justification. Always turn off hyphenation; it makes
64     .\" way too many mistakes in technical documents.
65     .hy 0
66     .if n .na
67     .\"
68     .\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2).
69     .\" Fear. Run. Save yourself. No user-serviceable parts.
70     . \" fudge factors for nroff and troff
71     .if n \{\
72     . ds #H 0
73     . ds #V .8m
74     . ds #F .3m
75     . ds #[ \f1
76     . ds #] \fP
77     .\}
78     .if t \{\
79     . ds #H ((1u-(\\\\n(.fu%2u))*.13m)
80     . ds #V .6m
81     . ds #F 0
82     . ds #[ \&
83     . ds #] \&
84     .\}
85     . \" simple accents for nroff and troff
86     .if n \{\
87     . ds ' \&
88     . ds ` \&
89     . ds ^ \&
90     . ds , \&
91     . ds ~ ~
92     . ds /
93     .\}
94     .if t \{\
95     . ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u"
96     . ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u'
97     . ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u'
98     . ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u'
99     . ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u'
100     . ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u'
101     .\}
102     . \" troff and (daisy-wheel) nroff accents
103     .ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V'
104     .ds 8 \h'\*(#H'\(*b\h'-\*(#H'
105     .ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#]
106     .ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H'
107     .ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u'
108     .ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#]
109     .ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#]
110     .ds ae a\h'-(\w'a'u*4/10)'e
111     .ds Ae A\h'-(\w'A'u*4/10)'E
112     . \" corrections for vroff
113     .if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u'
114     .if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u'
115     . \" for low resolution devices (crt and lpr)
116     .if \n(.H>23 .if \n(.V>19 \
117     \{\
118     . ds : e
119     . ds 8 ss
120     . ds o a
121     . ds d- d\h'-1'\(ga
122     . ds D- D\h'-1'\(hy
123     . ds th \o'bp'
124     . ds Th \o'LP'
125     . ds ae ae
126     . ds Ae AE
127     .\}
128     .rm #[ #] #H #V #F C
129     .\" ========================================================================
130     .\"
131     .IX Title "VPE 8"
132 pcg 1.3 .TH VPE 8 "2003-03-26" "0.1" "Virtual Private Ethernet"
133 pcg 1.1 .SH "NAME"
134     vpe \- Overview of the virtual private ethernet suite.
135     .SH "DESCRIPTION"
136     .IX Header "DESCRIPTION"
137     Vpe is a suite designed to provide a virtual private network for multiple
138     nodes over an untrusted network.
139     .PP
140     \&\*(L"Virtual\*(R" means that no physical network is created (of course), but an
141     ethernet is emulated by creating multiple tunnels between the member
142 pcg 1.3 nodes.
143     .PP
144     \&\*(L"Private\*(R" means that non-participating nodes cannot decode (\*(L"sniff)\*(R" nor
145     inject (\*(L"spoof\*(R") packets.
146     .PP
147     In the case of vpe, even participating nodes cannot sniff packets send to
148     other nodes or spoof packets as if sent from other nodes.
149     .PP
150     \&\*(L"Network\*(R" means that more than two parties can participate in the
151     network, so for instance it's possible to connect multiple branches of a
152     company into a single network. Many so-called \*(L"vpn\*(R" solutions only create
153     point-to-point tunnels.
154 pcg 1.1 .Sh "\s-1DESIGN\s0 \s-1GOALS\s0"
155     .IX Subsection "DESIGN GOALS"
156     .IP "\s-1SIMPLE\s0 \s-1DESIGN\s0" 4
157     .IX Item "SIMPLE DESIGN"
158     Cipher, \s-1HMAC\s0 algorithms and other key parameters must be selected
159     at compile time \- this makes it possible to only link in algorithms
160     you actually need. It also makes the crypto part of the source very
161     transparent and easy to inspect.
162     .IP "\s-1EASY\s0 \s-1TO\s0 \s-1SETUP\s0" 4
163     .IX Item "EASY TO SETUP"
164     A few lines of config (the config file is shared unmodified between all
165     hosts) and a single run of \f(CW\*(C`vpectrl\*(C'\fR to generate the keys suffices to
166     make it work.
167     .IP "MAC-BASED \s-1SECURITY\s0" 4
168     .IX Item "MAC-BASED SECURITY"
169     Since every host has it's own private key, other hosts cannot spoof
170     traffic from this host. That makes it possible to filter packest by \s-1MAC\s0
171     address, e.g. to ensure that packets from a specific \s-1IP\s0 address come, in
172     fact, from a specific host.
173     .SH "PROGRAMS"
174     .IX Header "PROGRAMS"
175     Vpe comes with two programs: one daemon (\f(CW\*(C`vped\*(C'\fR) and one control program
176 pcg 1.2 (\f(CW\*(C`vpectrl\*(C'\fR).
177 pcg 1.1 .IP "vpectrl" 4
178     .IX Item "vpectrl"
179 pcg 1.2 Is used to generate the keys, check and give an overview of of the
180     configuration and contorl the daemon (restarting etc.).
181 pcg 1.1 .IP "vped" 4
182     .IX Item "vped"
183     Is the daemon used to establish and maintain conenctions to the other
184     network members. It should be run on the gateway machine.
185 pcg 1.2 .SH "COMPILETIME CONFIGURATION"
186     .IX Header "COMPILETIME CONFIGURATION"
187     Here are a few recipes for compiling your vpe:
188 pcg 1.1 .Sh "\s-1AS\s0 \s-1LOW\s0 \s-1PACKET\s0 \s-1OVERHEAD\s0 \s-1AS\s0 \s-1POSSIBLE\s0"
189     .IX Subsection "AS LOW PACKET OVERHEAD AS POSSIBLE"
190     .Vb 1
191 pcg 1.2 \& ./configure --enable-hmac-length=4 --enable-rand-length=0
192 pcg 1.1 .Ve
193     .PP
194 pcg 1.2 Minimize the header overhead of \s-1VPN\s0 packets (the above will result in only
195     4 bytes of overhead over the raw ethernet frame).
196 pcg 1.1 .Sh "\s-1MINIMIZE\s0 \s-1CPU\s0 \s-1TIME\s0 \s-1REQUIRED\s0"
197     .IX Subsection "MINIMIZE CPU TIME REQUIRED"
198     .Vb 1
199 pcg 1.2 \& ./configure --enable-cipher=bf --enable-digest=md4
200 pcg 1.1 .Ve
201     .PP
202 pcg 1.2 Use the fastest cipher and digest algorithms currently available in vpe.
203 pcg 1.1 .Sh "\s-1MAXIMIZE\s0 \s-1SECURITY\s0"
204     .IX Subsection "MAXIMIZE SECURITY"
205     .Vb 1
206 pcg 1.2 \& ./configure --enable-hmac-length=16 --enable-rand-length=8 --enable-digest=sha1
207 pcg 1.1 .Ve
208     .PP
209 pcg 1.2 This uses a 16 byte \s-1HMAC\s0 checksum to authenticate packets (I guess 8\-12
210     would also be pretty secure ;) and will additionally prefix each packet
211     with 8 bytes of random data.
212     .PP
213 pcg 1.1 In general, remember that \s-1AES\-128\s0 seems to be more secure and faster than
214 pcg 1.2 \&\s-1AES\-192\s0 or \s-1AES\-256\s0, more randomness helps against sniffing and a longer
215     \&\s-1HMAC\s0 helps against spoofing. \s-1MD4\s0 is a fast digest, \s-1SHA1\s0 or \s-1RIPEMD160\s0 are
216     better, and Blowfish is a fast cipher (and also quite secure).
217 pcg 1.1 .SH "HOW TO SET UP A SIMPLE VPN"
218     .IX Header "HOW TO SET UP A SIMPLE VPN"
219     In this section I will describe how to get a simple \s-1VPN\s0 consisting of
220     three hosts up and running.
221     .Sh "\s-1STEP\s0 1: configuration"
222     .IX Subsection "STEP 1: configuration"
223     First you have to create a daemon configuation file and put it into the
224     configuration directory. This is usually \f(CW\*(C`/etc/vpe\*(C'\fR, depending on how you
225     configured vpe, and can be overwritten using the \f(CW\*(C`\-c\*(C'\fR commandline switch.
226     .PP
227     Put the following lines into \f(CW\*(C`/etc/vpe/vped.conf\*(C'\fR:
228     .PP
229     .Vb 3
230 pcg 1.2 \& udp-port = 50000 # the external port to listen on (configure your firewall)
231     \& mtu = 1400 # minimum MTU of all outgoing interfaces on all hosts
232     \& ifname = vpn0 # the local network device name
233 pcg 1.1 .Ve
234     .PP
235     .Vb 2
236 pcg 1.2 \& node = first # just a nickname
237     \& hostname = first.example.net # the DNS name or IP address of the host
238 pcg 1.1 .Ve
239     .PP
240     .Vb 2
241 pcg 1.2 \& node = second
242     \& hostname = 133.55.82.9
243 pcg 1.1 .Ve
244     .PP
245     .Vb 2
246 pcg 1.2 \& node = third
247     \& hostname = third.example.net
248 pcg 1.1 .Ve
249     .PP
250     The only other file neccessary if the \f(CW\*(C`if\-up\*(C'\fR script that initializes the
251     local ethernet interface. Put the following lines into \f(CW\*(C`/etc/vpe/if\-up\*(C'\fR
252     and make it execute (\f(CW\*(C`chmod 755 /etc/vpe/if\-up\*(C'\fR):
253     .PP
254     .Vb 6
255 pcg 1.2 \& #!/bin/sh
256     \& ip link set $IFNAME address $MAC mtu $MTU up
257     \& [ $NODENAME = first ] && ip addr add 10.0.1.1 dev $IFNAME
258     \& [ $NODENAME = second ] && ip addr add 10.0.2.1 dev $IFNAME
259     \& [ $NODENAME = third ] && ip addr add 10.0.3.1 dev $IFNAME
260     \& ip route add 10.0.0.0/16 dev $IFNAME
261 pcg 1.1 .Ve
262     .PP
263     This script will give each node a different \s-1IP\s0 address in the \f(CW\*(C`10.0/16\*(C'\fR
264     network. The internal network (e.g. the \f(CW\*(C`eth0\*(C'\fR interface) should then be
265     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,
266     \&\f(CW\*(C`10.0.2.0/24\*(C'\fR on node \f(CW\*(C`second\*(C'\fR, and so on.
267     .PP
268     By enabling routing on the gateway host that runs \f(CW\*(C`vped\*(C'\fR all nodes will
269     be able to reach the other nodes. You can, of course, also use proxy arp
270     or other means of pseudo-bridging (or even real briding), or (best) full
271     routing \- the choice is yours.
272     .Sh "\s-1STEP\s0 2: create the \s-1RSA\s0 key pairs for all hosts"
273     .IX Subsection "STEP 2: create the RSA key pairs for all hosts"
274     Run the following command to generate all key pairs (that might take a
275     while):
276     .PP
277     .Vb 1
278 pcg 1.2 \& vpectrl -c /etc/vpe -g
279 pcg 1.1 .Ve
280     .PP
281     This command will put the public keys into \f(CW\*(C`/etc/vpe/pubkeys/\f(CInodename\f(CW\*(C'\fR and the private keys into \f(CW\*(C`/etc/vpe/hostkeys/\f(CInodename\f(CW\*(C'\fR.
282     .Sh "\s-1STEP\s0 3: distribute the config files to all nodes"
283     .IX Subsection "STEP 3: distribute the config files to all nodes"
284     Now distribute the config files to the other nodes. This should be done in two steps, since the
285     private keys should not be distributed. The example uses rsync-over-ssh
286     .PP
287     First all the config files without the hostkeys should be distributed:
288     .PP
289     .Vb 3
290 pcg 1.2 \& rsync -avzessh /etc/vpe first.example.net:/etc/. --exclude hostkeys
291     \& rsync -avzessh /etc/vpe 133.55.82.9:/etc/. --exclude hostkeys
292     \& rsync -avzessh /etc/vpe third.example.net:/etc/. --exclude hostkeys
293 pcg 1.1 .Ve
294     .PP
295     Then the hostkeys should be copied:
296     .PP
297     .Vb 3
298 pcg 1.2 \& rsync -avzessh /etc/vpe/hostkeys/first first.example.net:/etc/hostkey
299     \& rsync -avzessh /etc/vpe/hostkeys/second 133.55.82.9:/etc/hostkey
300     \& rsync -avzessh /etc/vpe/hostkeys/third third.example.net:/etc/hostkey
301 pcg 1.1 .Ve
302     .PP
303     You should now check the configration by issuing the command \f(CW\*(C`vpectrl \-c
304     /etc/vpe \-s\*(C'\fR on each node and verify it's output.
305     .Sh "\s-1STEP\s0 4: starting vped"
306     .IX Subsection "STEP 4: starting vped"
307     You should then start vped on each node by issuing a command like:
308     .PP
309     .Vb 1
310 pcg 1.2 \& vped -D -linfo first # first is the nodename
311 pcg 1.1 .Ve
312     .PP
313     This will make the vped stay in foreground. You should then see
314     \&\*(L"connection established\*(R" messages. If you don't see them check your
315     firewall and routing (use tcpdump ;).
316     .PP
317     If this works you should check your networking setup by pinging various
318     endpoints.
319     .PP
320     To make vped run more permanently you can either run it as a daemon
321     (by starting it without the \f(CW\*(C`\-D\*(C'\fR switch), or, much better, from your
322     inittab. I use a line like this on my systems:
323     .PP
324     .Vb 1
325 pcg 1.2 \& t1:2345:respawn:/opt/vpe/sbin/vped -D -L first >/dev/null 2>&1
326 pcg 1.1 .Ve
327     .Sh "\s-1STEP\s0 5: enjoy"
328     .IX Subsection "STEP 5: enjoy"
329     \&... and play around. Sending a \-HUP (\f(CW\*(C`vpectrl \-kHUP\*(C'\fR) to the daemon
330     will make it try to connect to all other nodes again. If you run it from
331     inittab, as is recommended, \f(CW\*(C`vpectrl \-k\*(C'\fR (or simply \f(CW\*(C`killall vped\*(C'\fR) will
332     kill the daemon, start it again, making it read it's configuration files
333     again.
334     .SH "SEE ALSO"
335     .IX Header "SEE ALSO"
336     \&\fIvpe\fR\|(8), \fIvpectrl\fR\|(8), \fIvped.conf\fR\|(5).
337     .SH "AUTHOR"
338     .IX Header "AUTHOR"
339     Marc Lehmann <vpe@plan9.de>