ViewVC Help
View File | Revision Log | Show Annotations | Download File
/cvs/gvpe/doc/vpe.8
Revision: 1.2
Committed: Mon Mar 24 15:20:24 2003 UTC (21 years, 2 months ago) by pcg
Branch: MAIN
Changes since 1.1: +44 -38 lines
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.2 .TH VPE 8 "2003-03-24" "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     nodes. \*(L"Private\*(R" means that non-participating nodes cannot decode
143     (\*(L"sniff)\*(R" nor inject (\*(L"spoof\*(R") packets. In the case of vpe, even
144     participating nodes cannot spoof packets from other nodes. And \*(L"network\*(R"
145     means that more than two parties \- many so-called vpn solutions only
146     create point-to-point tunnels \- can participate in the network, so it's
147     possible to connect multiple branches of a company into a single network.
148     .Sh "\s-1DESIGN\s0 \s-1GOALS\s0"
149     .IX Subsection "DESIGN GOALS"
150     .IP "\s-1SIMPLE\s0 \s-1DESIGN\s0" 4
151     .IX Item "SIMPLE DESIGN"
152     Cipher, \s-1HMAC\s0 algorithms and other key parameters must be selected
153     at compile time \- this makes it possible to only link in algorithms
154     you actually need. It also makes the crypto part of the source very
155     transparent and easy to inspect.
156     .IP "\s-1EASY\s0 \s-1TO\s0 \s-1SETUP\s0" 4
157     .IX Item "EASY TO SETUP"
158     A few lines of config (the config file is shared unmodified between all
159     hosts) and a single run of \f(CW\*(C`vpectrl\*(C'\fR to generate the keys suffices to
160     make it work.
161     .IP "MAC-BASED \s-1SECURITY\s0" 4
162     .IX Item "MAC-BASED SECURITY"
163     Since every host has it's own private key, other hosts cannot spoof
164     traffic from this host. That makes it possible to filter packest by \s-1MAC\s0
165     address, e.g. to ensure that packets from a specific \s-1IP\s0 address come, in
166     fact, from a specific host.
167     .SH "PROGRAMS"
168     .IX Header "PROGRAMS"
169     Vpe comes with two programs: one daemon (\f(CW\*(C`vped\*(C'\fR) and one control program
170 pcg 1.2 (\f(CW\*(C`vpectrl\*(C'\fR).
171 pcg 1.1 .IP "vpectrl" 4
172     .IX Item "vpectrl"
173 pcg 1.2 Is used to generate the keys, check and give an overview of of the
174     configuration and contorl the daemon (restarting etc.).
175 pcg 1.1 .IP "vped" 4
176     .IX Item "vped"
177     Is the daemon used to establish and maintain conenctions to the other
178     network members. It should be run on the gateway machine.
179 pcg 1.2 .SH "COMPILETIME CONFIGURATION"
180     .IX Header "COMPILETIME CONFIGURATION"
181     Here are a few recipes for compiling your vpe:
182 pcg 1.1 .Sh "\s-1AS\s0 \s-1LOW\s0 \s-1PACKET\s0 \s-1OVERHEAD\s0 \s-1AS\s0 \s-1POSSIBLE\s0"
183     .IX Subsection "AS LOW PACKET OVERHEAD AS POSSIBLE"
184     .Vb 1
185 pcg 1.2 \& ./configure --enable-hmac-length=4 --enable-rand-length=0
186 pcg 1.1 .Ve
187     .PP
188 pcg 1.2 Minimize the header overhead of \s-1VPN\s0 packets (the above will result in only
189     4 bytes of overhead over the raw ethernet frame).
190 pcg 1.1 .Sh "\s-1MINIMIZE\s0 \s-1CPU\s0 \s-1TIME\s0 \s-1REQUIRED\s0"
191     .IX Subsection "MINIMIZE CPU TIME REQUIRED"
192     .Vb 1
193 pcg 1.2 \& ./configure --enable-cipher=bf --enable-digest=md4
194 pcg 1.1 .Ve
195     .PP
196 pcg 1.2 Use the fastest cipher and digest algorithms currently available in vpe.
197 pcg 1.1 .Sh "\s-1MAXIMIZE\s0 \s-1SECURITY\s0"
198     .IX Subsection "MAXIMIZE SECURITY"
199     .Vb 1
200 pcg 1.2 \& ./configure --enable-hmac-length=16 --enable-rand-length=8 --enable-digest=sha1
201 pcg 1.1 .Ve
202     .PP
203 pcg 1.2 This uses a 16 byte \s-1HMAC\s0 checksum to authenticate packets (I guess 8\-12
204     would also be pretty secure ;) and will additionally prefix each packet
205     with 8 bytes of random data.
206     .PP
207 pcg 1.1 In general, remember that \s-1AES\-128\s0 seems to be more secure and faster than
208 pcg 1.2 \&\s-1AES\-192\s0 or \s-1AES\-256\s0, more randomness helps against sniffing and a longer
209     \&\s-1HMAC\s0 helps against spoofing. \s-1MD4\s0 is a fast digest, \s-1SHA1\s0 or \s-1RIPEMD160\s0 are
210     better, and Blowfish is a fast cipher (and also quite secure).
211 pcg 1.1 .SH "HOW TO SET UP A SIMPLE VPN"
212     .IX Header "HOW TO SET UP A SIMPLE VPN"
213     In this section I will describe how to get a simple \s-1VPN\s0 consisting of
214     three hosts up and running.
215     .Sh "\s-1STEP\s0 1: configuration"
216     .IX Subsection "STEP 1: configuration"
217     First you have to create a daemon configuation file and put it into the
218     configuration directory. This is usually \f(CW\*(C`/etc/vpe\*(C'\fR, depending on how you
219     configured vpe, and can be overwritten using the \f(CW\*(C`\-c\*(C'\fR commandline switch.
220     .PP
221     Put the following lines into \f(CW\*(C`/etc/vpe/vped.conf\*(C'\fR:
222     .PP
223     .Vb 3
224 pcg 1.2 \& udp-port = 50000 # the external port to listen on (configure your firewall)
225     \& mtu = 1400 # minimum MTU of all outgoing interfaces on all hosts
226     \& ifname = vpn0 # the local network device name
227 pcg 1.1 .Ve
228     .PP
229     .Vb 2
230 pcg 1.2 \& node = first # just a nickname
231     \& hostname = first.example.net # the DNS name or IP address of the host
232 pcg 1.1 .Ve
233     .PP
234     .Vb 2
235 pcg 1.2 \& node = second
236     \& hostname = 133.55.82.9
237 pcg 1.1 .Ve
238     .PP
239     .Vb 2
240 pcg 1.2 \& node = third
241     \& hostname = third.example.net
242 pcg 1.1 .Ve
243     .PP
244     The only other file neccessary if the \f(CW\*(C`if\-up\*(C'\fR script that initializes the
245     local ethernet interface. Put the following lines into \f(CW\*(C`/etc/vpe/if\-up\*(C'\fR
246     and make it execute (\f(CW\*(C`chmod 755 /etc/vpe/if\-up\*(C'\fR):
247     .PP
248     .Vb 6
249 pcg 1.2 \& #!/bin/sh
250     \& ip link set $IFNAME address $MAC mtu $MTU up
251     \& [ $NODENAME = first ] && ip addr add 10.0.1.1 dev $IFNAME
252     \& [ $NODENAME = second ] && ip addr add 10.0.2.1 dev $IFNAME
253     \& [ $NODENAME = third ] && ip addr add 10.0.3.1 dev $IFNAME
254     \& ip route add 10.0.0.0/16 dev $IFNAME
255 pcg 1.1 .Ve
256     .PP
257     This script will give each node a different \s-1IP\s0 address in the \f(CW\*(C`10.0/16\*(C'\fR
258     network. The internal network (e.g. the \f(CW\*(C`eth0\*(C'\fR interface) should then be
259     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,
260     \&\f(CW\*(C`10.0.2.0/24\*(C'\fR on node \f(CW\*(C`second\*(C'\fR, and so on.
261     .PP
262     By enabling routing on the gateway host that runs \f(CW\*(C`vped\*(C'\fR all nodes will
263     be able to reach the other nodes. You can, of course, also use proxy arp
264     or other means of pseudo-bridging (or even real briding), or (best) full
265     routing \- the choice is yours.
266     .Sh "\s-1STEP\s0 2: create the \s-1RSA\s0 key pairs for all hosts"
267     .IX Subsection "STEP 2: create the RSA key pairs for all hosts"
268     Run the following command to generate all key pairs (that might take a
269     while):
270     .PP
271     .Vb 1
272 pcg 1.2 \& vpectrl -c /etc/vpe -g
273 pcg 1.1 .Ve
274     .PP
275     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.
276     .Sh "\s-1STEP\s0 3: distribute the config files to all nodes"
277     .IX Subsection "STEP 3: distribute the config files to all nodes"
278     Now distribute the config files to the other nodes. This should be done in two steps, since the
279     private keys should not be distributed. The example uses rsync-over-ssh
280     .PP
281     First all the config files without the hostkeys should be distributed:
282     .PP
283     .Vb 3
284 pcg 1.2 \& rsync -avzessh /etc/vpe first.example.net:/etc/. --exclude hostkeys
285     \& rsync -avzessh /etc/vpe 133.55.82.9:/etc/. --exclude hostkeys
286     \& rsync -avzessh /etc/vpe third.example.net:/etc/. --exclude hostkeys
287 pcg 1.1 .Ve
288     .PP
289     Then the hostkeys should be copied:
290     .PP
291     .Vb 3
292 pcg 1.2 \& rsync -avzessh /etc/vpe/hostkeys/first first.example.net:/etc/hostkey
293     \& rsync -avzessh /etc/vpe/hostkeys/second 133.55.82.9:/etc/hostkey
294     \& rsync -avzessh /etc/vpe/hostkeys/third third.example.net:/etc/hostkey
295 pcg 1.1 .Ve
296     .PP
297     You should now check the configration by issuing the command \f(CW\*(C`vpectrl \-c
298     /etc/vpe \-s\*(C'\fR on each node and verify it's output.
299     .Sh "\s-1STEP\s0 4: starting vped"
300     .IX Subsection "STEP 4: starting vped"
301     You should then start vped on each node by issuing a command like:
302     .PP
303     .Vb 1
304 pcg 1.2 \& vped -D -linfo first # first is the nodename
305 pcg 1.1 .Ve
306     .PP
307     This will make the vped stay in foreground. You should then see
308     \&\*(L"connection established\*(R" messages. If you don't see them check your
309     firewall and routing (use tcpdump ;).
310     .PP
311     If this works you should check your networking setup by pinging various
312     endpoints.
313     .PP
314     To make vped run more permanently you can either run it as a daemon
315     (by starting it without the \f(CW\*(C`\-D\*(C'\fR switch), or, much better, from your
316     inittab. I use a line like this on my systems:
317     .PP
318     .Vb 1
319 pcg 1.2 \& t1:2345:respawn:/opt/vpe/sbin/vped -D -L first >/dev/null 2>&1
320 pcg 1.1 .Ve
321     .Sh "\s-1STEP\s0 5: enjoy"
322     .IX Subsection "STEP 5: enjoy"
323     \&... and play around. Sending a \-HUP (\f(CW\*(C`vpectrl \-kHUP\*(C'\fR) to the daemon
324     will make it try to connect to all other nodes again. If you run it from
325     inittab, as is recommended, \f(CW\*(C`vpectrl \-k\*(C'\fR (or simply \f(CW\*(C`killall vped\*(C'\fR) will
326     kill the daemon, start it again, making it read it's configuration files
327     again.
328     .SH "SEE ALSO"
329     .IX Header "SEE ALSO"
330     \&\fIvpe\fR\|(8), \fIvpectrl\fR\|(8), \fIvped.conf\fR\|(5).
331     .SH "AUTHOR"
332     .IX Header "AUTHOR"
333     Marc Lehmann <vpe@plan9.de>