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

Comparing gvpe/doc/gvpe.5 (file contents):
Revision 1.12 by root, Sat Jul 13 04:10:29 2013 UTC vs.
Revision 1.13 by root, Wed Mar 30 04:02:50 2016 UTC

1.\" Automatically generated by Pod::Man 2.25 (Pod::Simple 3.20) 1.\" Automatically generated by Pod::Man 2.28 (Pod::Simple 3.30)
2.\" 2.\"
3.\" Standard preamble: 3.\" Standard preamble:
4.\" ======================================================================== 4.\" ========================================================================
5.de Sp \" Vertical space (when we can't use .PP) 5.de Sp \" Vertical space (when we can't use .PP)
6.if t .sp .5v 6.if t .sp .5v
36.el\{\ 36.el\{\
37. ds -- \|\(em\| 37. ds -- \|\(em\|
38. ds PI \(*p 38. ds PI \(*p
39. ds L" `` 39. ds L" ``
40. ds R" '' 40. ds R" ''
41. ds C`
42. ds C'
41'br\} 43'br\}
42.\" 44.\"
43.\" Escape single quotes in literal strings from groff's Unicode transform. 45.\" Escape single quotes in literal strings from groff's Unicode transform.
44.ie \n(.g .ds Aq \(aq 46.ie \n(.g .ds Aq \(aq
45.el .ds Aq ' 47.el .ds Aq '
46.\" 48.\"
47.\" If the F register is turned on, we'll generate index entries on stderr for 49.\" If the F register is turned on, we'll generate index entries on stderr for
48.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index 50.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
49.\" entries marked with X<> in POD. Of course, you'll have to process the 51.\" entries marked with X<> in POD. Of course, you'll have to process the
50.\" output yourself in some meaningful fashion. 52.\" output yourself in some meaningful fashion.
51.ie \nF \{\ 53.\"
54.\" Avoid warning from groff about undefined register 'F'.
55.de IX
56..
57.nr rF 0
58.if \n(.g .if rF .nr rF 1
59.if (\n(rF:(\n(.g==0)) \{
60. if \nF \{
52. de IX 61. de IX
53. tm Index:\\$1\t\\n%\t"\\$2" 62. tm Index:\\$1\t\\n%\t"\\$2"
54.. 63..
55. nr % 0 64. if !\nF==2 \{
56. rr F 65. nr % 0
66. nr F 2
67. \}
68. \}
57.\} 69.\}
58.el \{\ 70.rr rF
59. de IX
60..
61.\}
62.\" 71.\"
63.\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2). 72.\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2).
64.\" Fear. Run. Save yourself. No user-serviceable parts. 73.\" Fear. Run. Save yourself. No user-serviceable parts.
65. \" fudge factors for nroff and troff 74. \" fudge factors for nroff and troff
66.if n \{\ 75.if n \{\
122.\} 131.\}
123.rm #[ #] #H #V #F C 132.rm #[ #] #H #V #F C
124.\" ======================================================================== 133.\" ========================================================================
125.\" 134.\"
126.IX Title "GVPE 5" 135.IX Title "GVPE 5"
127.TH GVPE 5 "2013-07-10" "2.24" "GNU Virtual Private Ethernet" 136.TH GVPE 5 "2015-10-31" "2.25" "GNU Virtual Private Ethernet"
128.\" For nroff, turn off justification. Always turn off hyphenation; it makes 137.\" For nroff, turn off justification. Always turn off hyphenation; it makes
129.\" way too many mistakes in technical documents. 138.\" way too many mistakes in technical documents.
130.if n .ad l 139.if n .ad l
131.nh 140.nh
132.SH "NAME" 141.SH "NAME"
133GNU\-VPE \- Overview of the GNU Virtual Private Ethernet suite. 142GNU\-VPE \- Overview of the GNU Virtual Private Ethernet suite.
134.SH "DESCRIPTION" 143.SH "DESCRIPTION"
135.IX Header "DESCRIPTION" 144.IX Header "DESCRIPTION"
136\&\s-1GVPE\s0 is a suite designed to provide a virtual private network for multiple 145\&\s-1GVPE\s0 is a suite designed to provide a virtual private network for multiple
137nodes over an untrusted network. This document first gives an introduction 146nodes over an untrusted network. This document first gives an introduction
138to VPNs in general and then describes the specific implementation of \s-1GVPE\s0. 147to VPNs in general and then describes the specific implementation of \s-1GVPE.\s0
139.SS "\s-1WHAT\s0 \s-1IS\s0 A \s-1VPN\s0?" 148.SS "\s-1WHAT IS A VPN\s0?"
140.IX Subsection "WHAT IS A VPN?" 149.IX Subsection "WHAT IS A VPN?"
141\&\s-1VPN\s0 is an acronym, it stands for: 150\&\s-1VPN\s0 is an acronym, it stands for:
142.IP "Virtual" 4 151.IP "Virtual" 4
143.IX Item "Virtual" 152.IX Item "Virtual"
144Virtual means that no physical network is created (of course), but a 153Virtual means that no physical network is created (of course), but a
154inject (\*(L"spoof\*(R") packets. This means that nodes can be connected over 163inject (\*(L"spoof\*(R") packets. This means that nodes can be connected over
155untrusted networks such as the public Internet without fear of being 164untrusted networks such as the public Internet without fear of being
156eavesdropped while at the same time being able to trust data sent by other 165eavesdropped while at the same time being able to trust data sent by other
157nodes. 166nodes.
158.Sp 167.Sp
159In the case of \s-1GVPE\s0, even participating nodes cannot sniff packets 168In the case of \s-1GVPE,\s0 even participating nodes cannot sniff packets
160send to other nodes or spoof packets as if sent from other nodes, so 169send to other nodes or spoof packets as if sent from other nodes, so
161communications between any two nodes is private to those two nodes. 170communications between any two nodes is private to those two nodes.
162.IP "Network" 4 171.IP "Network" 4
163.IX Item "Network" 172.IX Item "Network"
164Network means that more than two parties can participate in the network, 173Network means that more than two parties can participate in the network,
165so for instance it's possible to connect multiple branches of a company 174so for instance it's possible to connect multiple branches of a company
166into a single network. Many so-called \*(L"\s-1VPN\s0\*(R" solutions only create 175into a single network. Many so-called \*(L"\s-1VPN\*(R"\s0 solutions only create
167point-to-point tunnels, which in turn can be used to build larger 176point-to-point tunnels, which in turn can be used to build larger
168networks. 177networks.
169.Sp 178.Sp
170\&\s-1GVPE\s0 provides a true multi-point network in which any number of nodes (at 179\&\s-1GVPE\s0 provides a true multi-point network in which any number of nodes (at
171least a few dozen in practise, the theoretical limit is 4095 nodes) can 180least a few dozen in practise, the theoretical limit is 4095 nodes) can
172participate. 181participate.
173.SS "\s-1GVPE\s0 \s-1DESIGN\s0 \s-1GOALS\s0" 182.SS "\s-1GVPE DESIGN GOALS\s0"
174.IX Subsection "GVPE DESIGN GOALS" 183.IX Subsection "GVPE DESIGN GOALS"
175.IP "\s-1SIMPLE\s0 \s-1DESIGN\s0" 4 184.IP "\s-1SIMPLE DESIGN\s0" 4
176.IX Item "SIMPLE DESIGN" 185.IX Item "SIMPLE DESIGN"
177Cipher, \s-1HMAC\s0 algorithms and other key parameters must be selected 186Cipher, \s-1HMAC\s0 algorithms and other key parameters must be selected
178at compile time \- this makes it possible to only link in algorithms 187at compile time \- this makes it possible to only link in algorithms
179you actually need. It also makes the crypto part of the source very 188you actually need. It also makes the crypto part of the source very
180transparent and easy to inspect, and last not least this makes it possible 189transparent and easy to inspect, and last not least this makes it possible
181to hardcode the layout of all packets into the binary. \s-1GVPE\s0 goes a step 190to hardcode the layout of all packets into the binary. \s-1GVPE\s0 goes a step
182further and internally reserves blocks of the same length for all packets, 191further and internally reserves blocks of the same length for all packets,
183which virtually removes all possibilities of buffer overflows, as there is 192which virtually removes all possibilities of buffer overflows, as there is
184only a single type of buffer and it's always of fixed length. 193only a single type of buffer and it's always of fixed length.
185.IP "\s-1EASY\s0 \s-1TO\s0 \s-1SETUP\s0" 4 194.IP "\s-1EASY TO SETUP\s0" 4
186.IX Item "EASY TO SETUP" 195.IX Item "EASY TO SETUP"
187A few lines of config (the config file is shared unmodified between all 196A few lines of config (the config file is shared unmodified between all
188hosts) and a single run of \f(CW\*(C`gvpectrl\*(C'\fR to generate the keys suffices to 197hosts) and a single run of \f(CW\*(C`gvpectrl\*(C'\fR to generate the keys suffices to
189make it work. 198make it work.
190.IP "MAC-BASED \s-1SECURITY\s0" 4 199.IP "MAC-BASED \s-1SECURITY\s0" 4
216impossible under most circumstances. 225impossible under most circumstances.
217.PP 226.PP
218Here are a few recipes for compiling your gvpe, showing the extremes 227Here are a few recipes for compiling your gvpe, showing the extremes
219(fast, small, insecure \s-1OR\s0 slow, large, more secure), between which you 228(fast, small, insecure \s-1OR\s0 slow, large, more secure), between which you
220should choose: 229should choose:
221.SS "\s-1AS\s0 \s-1LOW\s0 \s-1PACKET\s0 \s-1OVERHEAD\s0 \s-1AS\s0 \s-1POSSIBLE\s0" 230.SS "\s-1AS LOW PACKET OVERHEAD AS POSSIBLE\s0"
222.IX Subsection "AS LOW PACKET OVERHEAD AS POSSIBLE" 231.IX Subsection "AS LOW PACKET OVERHEAD AS POSSIBLE"
223.Vb 1 232.Vb 1
224\& ./configure \-\-enable\-hmac\-length=4 \-\-enable\-rand\-length=0 233\& ./configure \-\-enable\-hmac\-length=4 \-\-enable\-rand\-length=0
225.Ve 234.Ve
226.PP 235.PP
227Minimize the header overhead of \s-1VPN\s0 packets (the above will result in 236Minimize the header overhead of \s-1VPN\s0 packets (the above will result in
228only 4 bytes of overhead over the raw ethernet frame). This is a insecure 237only 4 bytes of overhead over the raw ethernet frame). This is a insecure
229configuration because a \s-1HMAC\s0 length of 4 makes collision attacks almost 238configuration because a \s-1HMAC\s0 length of 4 makes collision attacks almost
230trivial. 239trivial.
231.SS "\s-1MINIMIZE\s0 \s-1CPU\s0 \s-1TIME\s0 \s-1REQUIRED\s0" 240.SS "\s-1MINIMIZE CPU TIME REQUIRED\s0"
232.IX Subsection "MINIMIZE CPU TIME REQUIRED" 241.IX Subsection "MINIMIZE CPU TIME REQUIRED"
233.Vb 1 242.Vb 1
234\& ./configure \-\-enable\-cipher=bf \-\-enable\-digest=md4 243\& ./configure \-\-enable\-cipher=bf \-\-enable\-digest=md4
235.Ve 244.Ve
236.PP 245.PP
237Use the fastest cipher and digest algorithms currently available in 246Use the fastest cipher and digest algorithms currently available in
238gvpe. \s-1MD4\s0 has been broken and is quite insecure, though, so using another 247gvpe. \s-1MD4\s0 has been broken and is quite insecure, though, so using another
239digest algorithm is recommended. 248digest algorithm is recommended.
240.SS "\s-1MAXIMIZE\s0 \s-1SECURITY\s0" 249.SS "\s-1MAXIMIZE SECURITY\s0"
241.IX Subsection "MAXIMIZE SECURITY" 250.IX Subsection "MAXIMIZE SECURITY"
242.Vb 1 251.Vb 1
243\& ./configure \-\-enable\-hmac\-length=16 \-\-enable\-rand\-length=12 \-\-enable\-digest=ripemd610 252\& ./configure \-\-enable\-hmac\-length=16 \-\-enable\-rand\-length=12 \-\-enable\-digest=ripemd610
244.Ve 253.Ve
245.PP 254.PP
246This uses a 16 byte \s-1HMAC\s0 checksum to authenticate packets (I guess 8\-12 255This uses a 16 byte \s-1HMAC\s0 checksum to authenticate packets (I guess 8\-12
247would also be pretty secure ;) and will additionally prefix each packet 256would also be pretty secure ;) and will additionally prefix each packet
248with 12 bytes of random data. 257with 12 bytes of random data.
249.PP 258.PP
250In general, remember that \s-1AES\-128\s0 seems to be as secure but faster than 259In general, remember that \s-1AES\-128\s0 seems to be as secure but faster than
251\&\s-1AES\-192\s0 or \s-1AES\-256\s0, more randomness helps against sniffing and a longer 260\&\s-1AES\-192\s0 or \s-1AES\-256,\s0 more randomness helps against sniffing and a longer
252\&\s-1HMAC\s0 helps against spoofing. \s-1MD4\s0 is a fast digest, \s-1SHA1\s0, \s-1RIPEMD160\s0, \s-1SHA256\s0 261\&\s-1HMAC\s0 helps against spoofing. \s-1MD4\s0 is a fast digest, \s-1SHA1, RIPEMD160, SHA256\s0
253are consecutively better, and Blowfish is a fast cipher (and also quite 262are consecutively better, and Blowfish is a fast cipher (and also quite
254secure). 263secure).
255.SH "HOW TO SET UP A SIMPLE VPN" 264.SH "HOW TO SET UP A SIMPLE VPN"
256.IX Header "HOW TO SET UP A SIMPLE VPN" 265.IX Header "HOW TO SET UP A SIMPLE VPN"
257In this section I will describe how to get a simple \s-1VPN\s0 consisting of 266In this section I will describe how to get a simple \s-1VPN\s0 consisting of
258three hosts up and running. 267three hosts up and running.
259.SS "\s-1STEP\s0 1: configuration" 268.SS "\s-1STEP 1:\s0 configuration"
260.IX Subsection "STEP 1: configuration" 269.IX Subsection "STEP 1: configuration"
261First you have to create a daemon configuration file and put it into the 270First you have to create a daemon configuration file and put it into the
262configuration directory. This is usually \f(CW\*(C`/etc/gvpe\*(C'\fR, depending on how you 271configuration directory. This is usually \f(CW\*(C`/etc/gvpe\*(C'\fR, depending on how you
263configured gvpe, and can be overwritten using the \f(CW\*(C`\-c\*(C'\fR command line switch. 272configured gvpe, and can be overwritten using the \f(CW\*(C`\-c\*(C'\fR command line switch.
264.PP 273.PP
299.PP 308.PP
300By enabling routing on the gateway host that runs \f(CW\*(C`gvpe\*(C'\fR all nodes will 309By enabling routing on the gateway host that runs \f(CW\*(C`gvpe\*(C'\fR all nodes will
301be able to reach the other nodes. You can, of course, also use proxy \s-1ARP\s0 310be able to reach the other nodes. You can, of course, also use proxy \s-1ARP\s0
302or other means of pseudo-bridging, or (best) full routing \- the choice is 311or other means of pseudo-bridging, or (best) full routing \- the choice is
303yours. 312yours.
304.SS "\s-1STEP\s0 2: create the \s-1RSA\s0 key pairs for all hosts" 313.SS "\s-1STEP 2:\s0 create the \s-1RSA\s0 key pairs for all hosts"
305.IX Subsection "STEP 2: create the RSA key pairs for all hosts" 314.IX Subsection "STEP 2: create the RSA key pairs for all hosts"
306Run the following command to generate all key pairs for all nodes (that 315Run the following command to generate all key pairs for all nodes (that
307might take a while): 316might take a while):
308.PP 317.PP
309.Vb 1 318.Vb 1
310\& gvpectrl \-c /etc/gvpe \-g 319\& gvpectrl \-c /etc/gvpe \-g
311.Ve 320.Ve
312.PP 321.PP
313This 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. 322This 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.
314.SS "\s-1STEP\s0 3: distribute the config files to all nodes" 323.SS "\s-1STEP 3:\s0 distribute the config files to all nodes"
315.IX Subsection "STEP 3: distribute the config files to all nodes" 324.IX Subsection "STEP 3: distribute the config files to all nodes"
316Now distribute the config files and private keys to the other nodes. This 325Now distribute the config files and private keys to the other nodes. This
317should be done in two steps, since only the private keys meant for a node 326should be done in two steps, since only the private keys meant for a node
318should be distributed (so each node has only it's own private key). 327should be distributed (so each node has only it's own private key).
319.PP 328.PP
335\& rsync \-avzessh /etc/gvpe/hostkeys/third third.example.net:/etc/hostkey 344\& rsync \-avzessh /etc/gvpe/hostkeys/third third.example.net:/etc/hostkey
336.Ve 345.Ve
337.PP 346.PP
338You should now check the configuration by issuing the command \f(CW\*(C`gvpectrl \-c 347You should now check the configuration by issuing the command \f(CW\*(C`gvpectrl \-c
339/etc/gvpe \-s\*(C'\fR on each node and verify it's output. 348/etc/gvpe \-s\*(C'\fR on each node and verify it's output.
340.SS "\s-1STEP\s0 4: starting gvpe" 349.SS "\s-1STEP 4:\s0 starting gvpe"
341.IX Subsection "STEP 4: starting gvpe" 350.IX Subsection "STEP 4: starting gvpe"
342You should then start gvpe on each node by issuing a command like: 351You should then start gvpe on each node by issuing a command like:
343.PP 352.PP
344.Vb 1 353.Vb 1
345\& gvpe \-D \-l info first # first is the nodename 354\& gvpe \-D \-l info first # first is the nodename
357or equivalent. I use a line like this on all my systems: 366or equivalent. I use a line like this on all my systems:
358.PP 367.PP
359.Vb 1 368.Vb 1
360\& t1:2345:respawn:/opt/gvpe/sbin/gvpe \-D \-L first >/dev/null 2>&1 369\& t1:2345:respawn:/opt/gvpe/sbin/gvpe \-D \-L first >/dev/null 2>&1
361.Ve 370.Ve
362.SS "\s-1STEP\s0 5: enjoy" 371.SS "\s-1STEP 5:\s0 enjoy"
363.IX Subsection "STEP 5: enjoy" 372.IX Subsection "STEP 5: enjoy"
364\&... and play around. Sending a \-HUP (\f(CW\*(C`gvpectrl \-kHUP\*(C'\fR) to the daemon 373\&... and play around. Sending a \-HUP (\f(CW\*(C`gvpectrl \-kHUP\*(C'\fR) to the daemon
365will make it try to connect to all other nodes again. If you run it from 374will make it try to connect to all other nodes again. If you run it from
366inittab, as is recommended, \f(CW\*(C`gvpectrl \-k\*(C'\fR (or simply \f(CW\*(C`killall gvpe\*(C'\fR) will 375inittab, as is recommended, \f(CW\*(C`gvpectrl \-k\*(C'\fR (or simply \f(CW\*(C`killall gvpe\*(C'\fR) will
367kill the daemon, start it again, making it read it's configuration files 376kill the daemon, start it again, making it read it's configuration files
377.SH "AUTHOR" 386.SH "AUTHOR"
378.IX Header "AUTHOR" 387.IX Header "AUTHOR"
379Marc Lehmann <gvpe@schmorp.de> 388Marc Lehmann <gvpe@schmorp.de>
380.SH "COPYRIGHTS AND LICENSES" 389.SH "COPYRIGHTS AND LICENSES"
381.IX Header "COPYRIGHTS AND LICENSES" 390.IX Header "COPYRIGHTS AND LICENSES"
382\&\s-1GVPE\s0 itself is distributed under the \s-1GENERAL\s0 \s-1PUBLIC\s0 \s-1LICENSE\s0 (see the file 391\&\s-1GVPE\s0 itself is distributed under the \s-1GENERAL PUBLIC LICENSE \s0(see the file
383\&\s-1COPYING\s0 that should be part of your distribution). 392\&\s-1COPYING\s0 that should be part of your distribution).
384.PP 393.PP
385In some configurations it uses modified versions of the tinc vpn suite, 394In some configurations it uses modified versions of the tinc vpn suite,
386which is also available under the \s-1GENERAL\s0 \s-1PUBLIC\s0 \s-1LICENSE\s0. 395which is also available under the \s-1GENERAL PUBLIC LICENSE.\s0

Diff Legend

Removed lines
+ Added lines
< Changed lines
> Changed lines