--- gvpe/doc/gvpe.5	2008/09/01 05:31:28	1.10
+++ gvpe/doc/gvpe.5	2016/11/02 07:06:38	1.14
@@ -1,15 +1,7 @@
-.\" Automatically generated by Pod::Man 2.16 (Pod::Simple 3.05)
+.\" Automatically generated by Pod::Man 2.28 (Pod::Simple 3.30)
 .\"
 .\" Standard preamble:
 .\" ========================================================================
-.de Sh \" Subsection heading
-.br
-.if t .Sp
-.ne 5
-.PP
-\fB\\$1\fR
-.PP
-..
 .de Sp \" Vertical space (when we can't use .PP)
 .if t .sp .5v
 .if n .sp
@@ -46,6 +38,8 @@
 .    ds PI \(*p
 .    ds L" ``
 .    ds R" ''
+.    ds C`
+.    ds C'
 'br\}
 .\"
 .\" Escape single quotes in literal strings from groff's Unicode transform.
@@ -53,20 +47,27 @@
 .el       .ds Aq '
 .\"
 .\" If the F register is turned on, we'll generate index entries on stderr for
-.\" titles (.TH), headers (.SH), subsections (.Sh), items (.Ip), and index
+.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
 .\" entries marked with X<> in POD.  Of course, you'll have to process the
 .\" output yourself in some meaningful fashion.
-.ie \nF \{\
-.    de IX
-.    tm Index:\\$1\t\\n%\t"\\$2"
+.\"
+.\" Avoid warning from groff about undefined register 'F'.
+.de IX
 ..
-.    nr % 0
-.    rr F
-.\}
-.el \{\
-.    de IX
+.nr rF 0
+.if \n(.g .if rF .nr rF 1
+.if (\n(rF:(\n(.g==0)) \{
+.    if \nF \{
+.        de IX
+.        tm Index:\\$1\t\\n%\t"\\$2"
 ..
+.        if !\nF==2 \{
+.            nr % 0
+.            nr F 2
+.        \}
+.    \}
 .\}
+.rr rF
 .\"
 .\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2).
 .\" Fear.  Run.  Save yourself.  No user-serviceable parts.
@@ -132,7 +133,7 @@
 .\" ========================================================================
 .\"
 .IX Title "GVPE 5"
-.TH GVPE 5 "2008-09-01" "2.2" "GNU Virtual Private Ethernet"
+.TH GVPE 5 "2016-11-02" "2.25" "GNU Virtual Private Ethernet"
 .\" For nroff, turn off justification.  Always turn off hyphenation; it makes
 .\" way too many mistakes in technical documents.
 .if n .ad l
@@ -143,12 +144,12 @@
 .IX Header "DESCRIPTION"
 \&\s-1GVPE\s0 is a suite designed to provide a virtual private network for multiple
 nodes over an untrusted network. This document first gives an introduction
-to VPNs in general and then describes the specific implementation of \s-1GVPE\s0.
-.Sh "\s-1WHAT\s0 \s-1IS\s0 A \s-1VPN\s0?"
+to VPNs in general and then describes the specific implementation of \s-1GVPE.\s0
+.SS "\s-1WHAT IS A VPN\s0?"
 .IX Subsection "WHAT IS A VPN?"
 \&\s-1VPN\s0 is an acronym, it stands for:
-.IP "" 4
-.IX Xref "Virtual"
+.IP "Virtual" 4
+.IX Item "Virtual"
 Virtual means that no physical network is created (of course), but a
 network is \fIemulated\fR by creating multiple tunnels between the member
 nodes by encapsulating and sending data over another transport network.
@@ -156,31 +157,31 @@
 Usually the emulated network is a normal \s-1IP\s0 or Ethernet, and the transport
 network is the Internet. However, using a \s-1VPN\s0 system like \s-1GVPE\s0 to connect
 nodes over other untrusted networks such as Wireless \s-1LAN\s0 is not uncommon.
-.IP "" 4
-.IX Xref "Private"
+.IP "Private" 4
+.IX Item "Private"
 Private means that non-participating nodes cannot decode (\*(L"sniff)\*(R" nor
 inject (\*(L"spoof\*(R") packets. This means that nodes can be connected over
 untrusted networks such as the public Internet without fear of being
 eavesdropped while at the same time being able to trust data sent by other
 nodes.
 .Sp
-In the case of \s-1GVPE\s0, even participating nodes cannot sniff packets
+In the case of \s-1GVPE,\s0 even participating nodes cannot sniff packets
 send to other nodes or spoof packets as if sent from other nodes, so
 communications between any two nodes is private to those two nodes.
-.IP "" 4
-.IX Xref "Network"
+.IP "Network" 4
+.IX Item "Network"
 Network means that more than two parties can participate in the network,
 so for instance it's possible to connect multiple branches of a company
-into a single network. Many so-called \*(L"\s-1VPN\s0\*(R" solutions only create
+into a single network. Many so-called \*(L"\s-1VPN\*(R"\s0 solutions only create
 point-to-point tunnels, which in turn can be used to build larger
 networks.
 .Sp
 \&\s-1GVPE\s0 provides a true multi-point network in which any number of nodes (at
 least a few dozen in practise, the theoretical limit is 4095 nodes) can
 participate.
-.Sh "\s-1GVPE\s0 \s-1DESIGN\s0 \s-1GOALS\s0"
+.SS "\s-1GVPE DESIGN GOALS\s0"
 .IX Subsection "GVPE DESIGN GOALS"
-.IP "\s-1SIMPLE\s0 \s-1DESIGN\s0" 4
+.IP "\s-1SIMPLE DESIGN\s0" 4
 .IX Item "SIMPLE DESIGN"
 Cipher, \s-1HMAC\s0 algorithms and other key parameters must be selected
 at compile time \- this makes it possible to only link in algorithms
@@ -190,11 +191,11 @@
 further and internally reserves blocks of the same length for all packets,
 which virtually removes all possibilities of buffer overflows, as there is
 only a single type of buffer and it's always of fixed length.
-.IP "\s-1EASY\s0 \s-1TO\s0 \s-1SETUP\s0" 4
+.IP "\s-1EASY TO SETUP\s0" 4
 .IX Item "EASY TO SETUP"
 A few lines of config (the config file is shared unmodified between all
-hosts) and a single run of \f(CW\*(C`gvpectrl\*(C'\fR to generate the keys suffices to
-make it work.
+hosts) and generating an \s-1RSA\s0 key-pair on each node suffices to make it
+work.
 .IP "MAC-BASED \s-1SECURITY\s0" 4
 .IX Item "MAC-BASED SECURITY"
 Since every host has it's own private key, other hosts cannot spoof
@@ -226,7 +227,7 @@
 Here are a few recipes for compiling your gvpe, showing the extremes
 (fast, small, insecure \s-1OR\s0 slow, large, more secure), between which you
 should choose:
-.Sh "\s-1AS\s0 \s-1LOW\s0 \s-1PACKET\s0 \s-1OVERHEAD\s0 \s-1AS\s0 \s-1POSSIBLE\s0"
+.SS "\s-1AS LOW PACKET OVERHEAD AS POSSIBLE\s0"
 .IX Subsection "AS LOW PACKET OVERHEAD AS POSSIBLE"
 .Vb 1
 \&   ./configure \-\-enable\-hmac\-length=4 \-\-enable\-rand\-length=0
@@ -234,9 +235,9 @@
 .PP
 Minimize the header overhead of \s-1VPN\s0 packets (the above will result in
 only 4 bytes of overhead over the raw ethernet frame). This is a insecure
-configuration because a \s-1HMAC\s0 length of 4 makes collision attacks based on
-the birthday paradox pretty easy.
-.Sh "\s-1MINIMIZE\s0 \s-1CPU\s0 \s-1TIME\s0 \s-1REQUIRED\s0"
+configuration because a \s-1HMAC\s0 length of 4 makes collision attacks almost
+trivial.
+.SS "\s-1MINIMIZE CPU TIME REQUIRED\s0"
 .IX Subsection "MINIMIZE CPU TIME REQUIRED"
 .Vb 1
 \&   ./configure \-\-enable\-cipher=bf \-\-enable\-digest=md4
@@ -245,27 +246,26 @@
 Use the fastest cipher and digest algorithms currently available in
 gvpe. \s-1MD4\s0 has been broken and is quite insecure, though, so using another
 digest algorithm is recommended.
-.Sh "\s-1MAXIMIZE\s0 \s-1SECURITY\s0"
+.SS "\s-1MAXIMIZE SECURITY\s0"
 .IX Subsection "MAXIMIZE SECURITY"
 .Vb 1
-\&   ./configure \-\-enable\-hmac\-length=16 \-\-enable\-rand\-length=8 \-\-enable\-digest=sha1
+\&   ./configure \-\-enable\-hmac\-length=16 \-\-enable\-rand\-length=12 \-\-enable\-digest=ripemd610
 .Ve
 .PP
 This uses a 16 byte \s-1HMAC\s0 checksum to authenticate packets (I guess 8\-12
 would also be pretty secure ;) and will additionally prefix each packet
-with 8 bytes of random data. In the long run, people should move to
-\&\s-1SHA\-256\s0 and beyond).
+with 12 bytes of random data.
 .PP
 In general, remember that \s-1AES\-128\s0 seems to be as secure but faster than
-\&\s-1AES\-192\s0 or \s-1AES\-256\s0, more randomness helps against sniffing and a longer
-\&\s-1HMAC\s0 helps against spoofing. \s-1MD4\s0 is a fast digest, \s-1SHA1\s0, \s-1RIPEMD160\s0, \s-1SHA256\s0
+\&\s-1AES\-192\s0 or \s-1AES\-256,\s0 more randomness helps against sniffing and a longer
+\&\s-1HMAC\s0 helps against spoofing. \s-1MD4\s0 is a fast digest, \s-1SHA1, RIPEMD160, SHA256\s0
 are consecutively better, and Blowfish is a fast cipher (and also quite
 secure).
 .SH "HOW TO SET UP A SIMPLE VPN"
 .IX Header "HOW TO SET UP A SIMPLE VPN"
 In this section I will describe how to get a simple \s-1VPN\s0 consisting of
 three hosts up and running.
-.Sh "\s-1STEP\s0 1: configuration"
+.SS "\s-1STEP 1:\s0 configuration"
 .IX Subsection "STEP 1: configuration"
 First you have to create a daemon configuration file and put it into the
 configuration directory. This is usually \f(CW\*(C`/etc/gvpe\*(C'\fR, depending on how you
@@ -310,43 +310,51 @@
 be able to reach the other nodes. You can, of course, also use proxy \s-1ARP\s0
 or other means of pseudo-bridging, or (best) full routing \- the choice is
 yours.
-.Sh "\s-1STEP\s0 2: create the \s-1RSA\s0 key pairs for all hosts"
-.IX Subsection "STEP 2: create the RSA key pairs for all hosts"
-Run the following command to generate all key pairs for all nodes (that
-might take a while):
+.SS "\s-1STEP 2:\s0 create the \s-1RSA\s0 key pair for each node"
+.IX Subsection "STEP 2: create the RSA key pair for each node"
+Next you have to generate the \s-1RSA\s0 keys for the nodes. While you can set
+up \s-1GVPE\s0 so you can generate all keys on a single host and centrally
+distribute all keys, it is safer to generate the key for each node on the
+node, so that the secret/private key does not have to be copied over the
+network.
+.PP
+To do so, run the following command to generate a key pair:
 .PP
 .Vb 1
-\&   gvpectrl \-c /etc/gvpe \-g
+\&   gvpectrl \-c /etc/gvpe \-g nodekey
 .Ve
 .PP
-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.
-.Sh "\s-1STEP\s0 3: distribute the config files to all nodes"
-.IX Subsection "STEP 3: distribute the config files to all nodes"
-Now distribute the config files and private keys to the other nodes. This
-should be done in two steps, since only the private keys meant for a node
-should be distributed (so each node has only it's own private key).
+This will create two files, \fInodekey\fR and \fInodekey.privkey\fR. The former
+should be copied to \fI/etc/gvpe/pubkey/\fInodename\fI\fR on the host where
+your config file is (you will have to create the \fIpubkey\fR directory
+first):
 .PP
-The example uses rsync-over-ssh
+.Vb 1
+\&   scp nodekey confighost:/etc/gvpe/pubkey/nodename
+.Ve
 .PP
-First all the config files without the hostkeys should be distributed:
+The private key \fInodekey.privkey\fR should be moved to \fI/etc/gvpe/hostkey\fR:
 .PP
-.Vb 3
-\&   rsync \-avzessh /etc/gvpe first.example.net:/etc/. \-\-exclude hostkeys
-\&   rsync \-avzessh /etc/gvpe 133.55.82.9:/etc/. \-\-exclude hostkeys
-\&   rsync \-avzessh /etc/gvpe third.example.net:/etc/. \-\-exclude hostkeys
+.Vb 2
+\&   mkdir \-p /etc/gvpe
+\&   mv nodekey.privkey /etc/gvpe/hostkey
 .Ve
+.SS "\s-1STEP 3:\s0 distribute the config files to all nodes"
+.IX Subsection "STEP 3: distribute the config files to all nodes"
+Now distribute the config files and public keys to the other nodes.
 .PP
-Then the hostkeys should be copied:
+The example uses rsync-over-ssh to copy the config file and all the public
+keys:
 .PP
 .Vb 3
-\&   rsync \-avzessh /etc/gvpe/hostkeys/first  first.example.net:/etc/hostkey
-\&   rsync \-avzessh /etc/gvpe/hostkeys/second 133.55.82.9:/etc/hostkey
-\&   rsync \-avzessh /etc/gvpe/hostkeys/third  third.example.net:/etc/hostkey
+\&   rsync \-avzessh /etc/gvpe first.example.net:/etc/. \-\-exclude hostkey
+\&   rsync \-avzessh /etc/gvpe 133.55.82.9:/etc/.       \-\-exclude hostkey
+\&   rsync \-avzessh /etc/gvpe third.example.net:/etc/. \-\-exclude hostkey
 .Ve
 .PP
-You should now check the configuration by issuing the command \f(CW\*(C`gvpectrl \-c
-/etc/gvpe \-s\*(C'\fR on each node and verify it's output.
-.Sh "\s-1STEP\s0 4: starting gvpe"
+You should now check the configuration by issuing the command \f(CW\*(C`gvpectrl
+\&\-c /etc/gvpe \-s\*(C'\fR on each node and verify it's output.
+.SS "\s-1STEP 4:\s0 starting gvpe"
 .IX Subsection "STEP 4: starting gvpe"
 You should then start gvpe on each node by issuing a command like:
 .PP
@@ -368,13 +376,36 @@
 .Vb 1
 \&   t1:2345:respawn:/opt/gvpe/sbin/gvpe \-D \-L first >/dev/null 2>&1
 .Ve
-.Sh "\s-1STEP\s0 5: enjoy"
+.SS "\s-1STEP 5:\s0 enjoy"
 .IX Subsection "STEP 5: enjoy"
 \&... and play around. Sending a \-HUP (\f(CW\*(C`gvpectrl \-kHUP\*(C'\fR) to the daemon
 will make it try to connect to all other nodes again. If you run it from
-inittab, as is recommended, \f(CW\*(C`gvpectrl \-k\*(C'\fR (or simply \f(CW\*(C`killall gvpe\*(C'\fR) will
-kill the daemon, start it again, making it read it's configuration files
-again.
+inittab \f(CW\*(C`gvpectrl \-k\*(C'\fR (or simply \f(CW\*(C`killall gvpe\*(C'\fR) will kill the daemon,
+start it again, making it read it's configuration files again.
+.PP
+To run the \s-1GVPE\s0 daemon permanently from your SysV init, you can add it to
+your \fIinittab\fR, e.g.:
+.PP
+.Vb 1
+\&   t1:2345:respawn:/bin/sh \-c "exec nice \-n\-20 /path/to/gvpe \-D node >/var/log/gvpe.log 2>&1"
+.Ve
+.PP
+For systems using systemd, you can use a unit file similar to this one:
+.PP
+.Vb 4
+\&   [Unit]
+\&   Description=gvpe
+\&   After=network.target
+\&   Before=remote\-fs.target
+\&
+\&   [Service]
+\&   ExecStart=/path/to/gvpe \-D node
+\&   KillMode=process
+\&   Restart=always
+\&
+\&   [Install]
+\&   WantedBy=multi\-user.target
+.Ve
 .SH "SEE ALSO"
 .IX Header "SEE ALSO"
 \&\fIgvpe.osdep\fR\|(5) for OS-dependent information, \fIgvpe.conf\fR\|(5), \fIgvpectrl\fR\|(8),
@@ -388,8 +419,8 @@
 Marc Lehmann <gvpe@schmorp.de>
 .SH "COPYRIGHTS AND LICENSES"
 .IX Header "COPYRIGHTS AND LICENSES"
-\&\s-1GVPE\s0 itself is distributed under the \s-1GENERAL\s0 \s-1PUBLIC\s0 \s-1LICENSE\s0 (see the file
+\&\s-1GVPE\s0 itself is distributed under the \s-1GENERAL PUBLIC LICENSE \s0(see the file
 \&\s-1COPYING\s0 that should be part of your distribution).
 .PP
 In some configurations it uses modified versions of the tinc vpn suite,
-which is also available under the \s-1GENERAL\s0 \s-1PUBLIC\s0 \s-1LICENSE\s0.
+which is also available under the \s-1GENERAL PUBLIC LICENSE.\s0