ViewVC Help
View File | Revision Log | Show Annotations | Download File
/cvs/gvpe/doc/gvpe.5.pod
(Generate patch)

Comparing gvpe/doc/gvpe.5.pod (file contents):
Revision 1.7 by pcg, Fri Mar 18 01:53:05 2005 UTC vs.
Revision 1.8 by pcg, Mon Sep 1 05:31:28 2008 UTC

… …
38 38
39=item X<Network> 39=item X<Network>
40 40
41Network means that more than two parties can participate in the network, 41Network means that more than two parties can participate in the network,
42so for instance it's possible to connect multiple branches of a company 42so for instance it's possible to connect multiple branches of a company
43into a single network. Many so-called "vpn" solutions only create 43into a single network. Many so-called "VPN" solutions only create
44point-to-point tunnels, which in turn can be used to build larger 44point-to-point tunnels, which in turn can be used to build larger
45networks. 45networks.
46 46
47GVPE provides a true multi-point network in wich any number of nodes (at 47GVPE provides a true multi-point network in which any number of nodes (at
48least a few dozen in practise, the theoretical limit is 4095 nodes) can 48least a few dozen in practise, the theoretical limit is 4095 nodes) can
49participate. 49participate.
50 50
51=back 51=back
52 52
… …
81 81
82=back 82=back
83 83
84=head1 PROGRAMS 84=head1 PROGRAMS
85 85
86Vpe comes with two programs: one daemon (C<gvpe>) and one control program 86Gvpe comes with two programs: one daemon (C<gvpe>) and one control program
87(C<gvpectrl>). 87(C<gvpectrl>).
88 88
89=over 4 89=over 4
90 90
91=item gvpectrl 91=item gvpectrl
92 92
93Is used to generate the keys, check and give an overview of of the 93This program is used to generate the keys, check and give an overview of of the
94configuration and contorl the daemon (restarting etc.). 94configuration and to control the daemon (restarting etc.).
95 95
96=item gvpe 96=item gvpe
97 97
98Is the daemon used to establish and maintain connections to the other 98This is the daemon used to establish and maintain connections to the other
99network members. It should be run on the gateway machine. 99network nodes. It should be run on the gateway of each VPN subnet.
100 100
101=back 101=back
102 102
103=head1 COMPILETIME CONFIGURATION 103=head1 COMPILETIME CONFIGURATION
104 104
105Please have a look at the C<gvpe.osdep(5)> manpage for platform-specific 105Please have a look at the C<gvpe.osdep(5)> manpage for platform-specific
106information. 106information.
107 107
108Gvpe hardcodes most encryption parameters. While this reduces flexibility,
109it makes the program much simpler and helps making buffer overflows
110impossible under most circumstances.
111
108Here are a few recipes for compiling your gvpe, showing the extremes 112Here are a few recipes for compiling your gvpe, showing the extremes
109(fast, small, insecure OR slow, large, more secure), between you should 113(fast, small, insecure OR slow, large, more secure), between which you
110choose: 114should choose:
111 115
112=head2 AS LOW PACKET OVERHEAD AS POSSIBLE 116=head2 AS LOW PACKET OVERHEAD AS POSSIBLE
113 117
114 ./configure --enable-hmac-length=4 --enable-rand-length=0 118 ./configure --enable-hmac-length=4 --enable-rand-length=0
115 119
116Minimize the header overhead of VPN packets (the above will result in 120Minimize the header overhead of VPN packets (the above will result in
117only 4 bytes of overhead over the raw ethernet frame). This is a insecure 121only 4 bytes of overhead over the raw ethernet frame). This is a insecure
118configuration because a HMAC length of 4 makes collision attacks based on 122configuration because a HMAC length of 4 makes collision attacks based on
119the birthday paradox easy, though. 123the birthday paradox pretty easy.
120 124
121=head2 MINIMIZE CPU TIME REQUIRED 125=head2 MINIMIZE CPU TIME REQUIRED
122 126
123 ./configure --enable-cipher=bf --enable-digest=md4 127 ./configure --enable-cipher=bf --enable-digest=md4
124 128
125Use the fastest cipher and digest algorithms currently available in 129Use the fastest cipher and digest algorithms currently available in
126gvpe. MD4 has been broken and is quite insecure, though. 130gvpe. MD4 has been broken and is quite insecure, though, so using another
131digest algorithm is recommended.
127 132
128=head2 MAXIMIZE SECURITY 133=head2 MAXIMIZE SECURITY
129 134
130 ./configure --enable-hmac-length=16 --enable-rand-length=8 --enable-digest=sha1 135 ./configure --enable-hmac-length=16 --enable-rand-length=8 --enable-digest=sha1
131 136
132This uses a 16 byte HMAC checksum to authenticate packets (I guess 8-12 137This uses a 16 byte HMAC checksum to authenticate packets (I guess 8-12
133would also be pretty secure ;) and will additionally prefix each packet 138would also be pretty secure ;) and will additionally prefix each packet
134with 8 bytes of random data. In the long run, people should move to 139with 8 bytes of random data. In the long run, people should move to
135SHA-224 and beyond, but support in openssl is missing as of writing this 140SHA-256 and beyond).
136document.
137 141
138In general, remember that AES-128 seems to be more secure and faster than 142In general, remember that AES-128 seems to be as secure but faster than
139AES-192 or AES-256, more randomness helps against sniffing and a longer 143AES-192 or AES-256, more randomness helps against sniffing and a longer
140HMAC helps against spoofing. MD4 is a fast digest, SHA1 or RIPEMD160 are 144HMAC helps against spoofing. MD4 is a fast digest, SHA1, RIPEMD160, SHA256
141better, and Blowfish is a fast cipher (and also quite secure). 145are consecutively better, and Blowfish is a fast cipher (and also quite
146secure).
142 147
143=head1 HOW TO SET UP A SIMPLE VPN 148=head1 HOW TO SET UP A SIMPLE VPN
144 149
145In this section I will describe how to get a simple VPN consisting of 150In this section I will describe how to get a simple VPN consisting of
146three hosts up and running. 151three hosts up and running.
147 152
148=head2 STEP 1: configuration 153=head2 STEP 1: configuration
149 154
150First you have to create a daemon configuation file and put it into the 155First you have to create a daemon configuration file and put it into the
151configuration directory. This is usually C</etc/gvpe>, depending on how you 156configuration directory. This is usually C</etc/gvpe>, depending on how you
152configured gvpe, and can be overwritten using the C<-c> commandline switch. 157configured gvpe, and can be overwritten using the C<-c> command line switch.
153 158
154Put the following lines into C</etc/gvpe/gvpe.conf>: 159Put the following lines into C</etc/gvpe/gvpe.conf>:
155 160
156 udp-port = 50000 # the external port to listen on (configure your firewall) 161 udp-port = 50000 # the external port to listen on (configure your firewall)
157 mtu = 1400 # minimum MTU of all outgoing interfaces on all hosts 162 mtu = 1400 # minimum MTU of all outgoing interfaces on all hosts
… …
164 hostname = 133.55.82.9 169 hostname = 133.55.82.9
165 170
166 node = third 171 node = third
167 hostname = third.example.net 172 hostname = third.example.net
168 173
169The only other file neccessary if the C<if-up> script that initializes the 174The only other file necessary is the C<if-up> script that initializes the
170local ethernet interface. Put the following lines into C</etc/gvpe/if-up> 175virtual ethernet interface on the local host. Put the following lines into
171and make it execute (C<chmod 755 /etc/gvpe/if-up>): 176C</etc/gvpe/if-up> and make it executable (C<chmod 755 /etc/gvpe/if-up>):
172 177
173 #!/bin/sh 178 #!/bin/sh
174 ip link set $IFNAME address $MAC mtu $MTU up 179 ip link set $IFNAME address $MAC mtu $MTU up
175 [ $NODENAME = first ] && ip addr add 10.0.1.1 dev $IFNAME 180 [ $NODENAME = first ] && ip addr add 10.0.1.1 dev $IFNAME
176 [ $NODENAME = second ] && ip addr add 10.0.2.1 dev $IFNAME 181 [ $NODENAME = second ] && ip addr add 10.0.2.1 dev $IFNAME
177 [ $NODENAME = third ] && ip addr add 10.0.3.1 dev $IFNAME 182 [ $NODENAME = third ] && ip addr add 10.0.3.1 dev $IFNAME
178 ip route add 10.0.0.0/16 dev $IFNAME 183 ip route add 10.0.0.0/16 dev $IFNAME
179 184
180This script will give each node a different IP address in the C<10.0/16> 185This script will give each node a different IP address in the C<10.0/16>
181network. The internal network (e.g. the C<eth0> interface) should then be 186network. The internal network (if gvpe runs on a router) should then be
182set to a subset of that network, e.g. C<10.0.1.0/24> on node C<first>, 187set to a subset of that network, e.g. C<10.0.1.0/24> on node C<first>,
183C<10.0.2.0/24> on node C<second>, and so on. 188C<10.0.2.0/24> on node C<second>, and so on.
184 189
185By enabling routing on the gateway host that runs C<gvpe> all nodes will 190By enabling routing on the gateway host that runs C<gvpe> all nodes will
186be able to reach the other nodes. You can, of course, also use proxy arp 191be able to reach the other nodes. You can, of course, also use proxy ARP
187or other means of pseudo-bridging (or even real briding), or (best) full 192or other means of pseudo-bridging, or (best) full routing - the choice is
188routing - the choice is yours. 193yours.
189 194
190=head2 STEP 2: create the RSA key pairs for all hosts 195=head2 STEP 2: create the RSA key pairs for all hosts
191 196
192Run the following command to generate all key pairs (that might take a 197Run the following command to generate all key pairs for all nodes (that
193while): 198might take a while):
194 199
195 gvpectrl -c /etc/gvpe -g 200 gvpectrl -c /etc/gvpe -g
196 201
197This command will put the public keys into C<< 202This command will put the public keys into C<<
198/etc/gvpe/pubkeys/I<nodename> >> and the private keys into C<< 203/etc/gvpe/pubkeys/I<nodename> >> and the private keys into C<<
199/etc/gvpe/hostkeys/I<nodename> >>. 204/etc/gvpe/hostkeys/I<nodename> >>.
200 205
201=head2 STEP 3: distribute the config files to all nodes 206=head2 STEP 3: distribute the config files to all nodes
202 207
203Now distribute the config files to the other nodes. This should be done in two steps, since the 208Now distribute the config files and private keys to the other nodes. This
204private keys should not be distributed. The example uses rsync-over-ssh 209should be done in two steps, since only the private keys meant for a node
210should be distributed (so each node has only it's own private key).
211
212The example uses rsync-over-ssh
205 213
206First all the config files without the hostkeys should be distributed: 214First all the config files without the hostkeys should be distributed:
207 215
208 rsync -avzessh /etc/gvpe first.example.net:/etc/. --exclude hostkeys 216 rsync -avzessh /etc/gvpe first.example.net:/etc/. --exclude hostkeys
209 rsync -avzessh /etc/gvpe 133.55.82.9:/etc/. --exclude hostkeys 217 rsync -avzessh /etc/gvpe 133.55.82.9:/etc/. --exclude hostkeys
… …
213 221
214 rsync -avzessh /etc/gvpe/hostkeys/first first.example.net:/etc/hostkey 222 rsync -avzessh /etc/gvpe/hostkeys/first first.example.net:/etc/hostkey
215 rsync -avzessh /etc/gvpe/hostkeys/second 133.55.82.9:/etc/hostkey 223 rsync -avzessh /etc/gvpe/hostkeys/second 133.55.82.9:/etc/hostkey
216 rsync -avzessh /etc/gvpe/hostkeys/third third.example.net:/etc/hostkey 224 rsync -avzessh /etc/gvpe/hostkeys/third third.example.net:/etc/hostkey
217 225
218You should now check the configration by issuing the command C<gvpectrl -c 226You should now check the configuration by issuing the command C<gvpectrl -c
219/etc/gvpe -s> on each node and verify it's output. 227/etc/gvpe -s> on each node and verify it's output.
220 228
221=head2 STEP 4: starting gvpe 229=head2 STEP 4: starting gvpe
222 230
223You should then start gvpe on each node by issuing a command like: 231You should then start gvpe on each node by issuing a command like:
224 232
225 gvpe -D -linfo first # first is the nodename 233 gvpe -D -l info first # first is the nodename
226 234
227This will make the gvpe stay in foreground. You should then see 235This will make the gvpe daemon stay in foreground. You should then see
228"connection established" messages. If you don't see them check your 236"connection established" messages. If you don't see them check your
229firewall and routing (use tcpdump ;). 237firewall and routing (use tcpdump ;).
230 238
231If this works you should check your networking setup by pinging various 239If this works you should check your networking setup by pinging various
232endpoints. 240endpoints.
233 241
234To make gvpe run more permanently you can either run it as a daemon 242To make gvpe run more permanently you can either run it as a daemon (by
235(by starting it without the C<-D> switch), or, much better, from your 243starting it without the C<-D> switch), or, much better, from your inittab
236inittab. I use a line like this on my systems: 244or equivalent. I use a line like this on all my systems:
237 245
238 t1:2345:respawn:/opt/gvpe/sbin/gvpe -D -L first >/dev/null 2>&1 246 t1:2345:respawn:/opt/gvpe/sbin/gvpe -D -L first >/dev/null 2>&1
239 247
240=head2 STEP 5: enjoy 248=head2 STEP 5: enjoy
241 249
… …
245kill the daemon, start it again, making it read it's configuration files 253kill the daemon, start it again, making it read it's configuration files
246again. 254again.
247 255
248=head1 SEE ALSO 256=head1 SEE ALSO
249 257
250gvpe.osdep(5) for OS-depedendent information, gvpe.conf(5), gvpectrl(8), 258gvpe.osdep(5) for OS-dependent information, gvpe.conf(5), gvpectrl(8),
251and for a description of the transports, protocol, and routing algorithm, 259and for a description of the transports, protocol, and routing algorithm,
252gvpe.protocol(7). 260gvpe.protocol(7).
253 261
254The GVPE mailinglist, at L<http://lists.schmorp.de/>, or 262The GVPE mailing list, at L<http://lists.schmorp.de/>, or
255C<gvpe@lists.schmorp.de>. 263C<gvpe@lists.schmorp.de>.
256 264
257=head1 AUTHOR 265=head1 AUTHOR
258 266
259Marc Lehmann <gvpe@schmorp.de> 267Marc Lehmann <gvpe@schmorp.de>

Diff Legend

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