--- /dev/null
+@node Client part
+@section Client part
+
+Except for common @code{-mtu}, @code{-noncediff}, @code{-timeout},
+@code{-stats} options client has the following ones:
+
+@table @code
+@item -remote
+Address (@code{host:port} format) of remote server we need to connect to.
+@item -iface
+TAP interface name.
+@item -id
+Our client's identification (hexadecimal string).
+@item -key
+Path to the file with the PSK key.
+@item -up
+Optional path to script that will be executed after connection is
+established. Interface name will be given to it as a first argument.
+@item -down
+Same as @code{-up} above, but it is executed when connection is lost,
+when we exit.
+@end table
+
+Example up-script that calls DHCP client and IPv6 advertisement
+solicitation:
+
+@example
+client% cat > up.sh <<EOF
+#!/bin/sh
+dhclient $1
+rtsol $1
+EOF
+client% chmod +x up.sh
+@end example
--- /dev/null
+@node Example usage
+@section Example usage
+
+Let's assume that there is some insecure link between your computer and
+WiFi-reachable gateway.
+
+@itemize @bullet
+@item You have got @code{wlan0} NIC with 192.168.0/24 network on it.
+@item You want to create virtual encrypted and authenticated 172.16.0/24
+network and use it as a default transport.
+@item @code{wlan0} MTU is 1500, 20 bytes overhead per IPv4. So MTU for
+GoVPN is 1500 - 20 - 8 = 1472.
+@item During startup client and server will say that TAP interface MTU
+is 1432.
+@end itemize
+
+Do not forget about setting @code{GOMAXPROC} environment variable for
+using more than one CPU.
+
+GNU/Linux IPv4 client-server example:
+
+@example
+server% echo "echo tap10" >> peers/CLIENTID/up.sh
+server% ip addr add 192.168.0.1/24 dev wlan0
+server% tunctl -t tap10
+server% ip link set mtu 1432 dev tap10
+server% ip addr add 172.16.0.1/24 dev tap10
+server% ip link set up dev tap10
+server% GOMAXPROC=4 govpn-server -bind 192.168.0.1:1194 -mtu 1472
+@end example
+
+@example
+client% umask 066
+client% echo MYLONG64HEXKEY > key.txt
+client% ip addr add 192.168.0.2/24 dev wlan0
+client% tunctl -t tap10
+client% ip link set mtu 1432 dev tap10
+client% ip addr add 172.16.0.2/24 dev tap10
+client% ip link set up dev tap10
+client% ip route add default via 172.16.0.1
+client% export GOMAXPROC=4
+client% while :; do
+ govpn-client -key key.txt -id CLIENTID -iface tap10 \
+ -remote 192.168.0.1:1194 -mtu 1472
+done
+@end example
+
+FreeBSD IPv6 client-server example:
+
+@example
+server% ifconfig em0 inet6 fe80::1/64
+server% GOMAXPROC=4 govpn-server -bind "fe80::1%em0"
+@end example
+
+@example
+client% ifconfig me0 inet6 -ifdisabled auto_linklocal
+client% ifconfig tap10
+client% ifconfig tap10 inet6 fc00::2/96 mtu 1412 up
+client% route -6 add default fc00::1
+client% export GOMAXPROC=4
+client% while :; do
+ govpn-client -key key.txt -id CLIENTID -iface tap10 \
+ -remote [fe80::1%me0]:1194
+done
+@end example
--- /dev/null
+@node MTU
+@section MTU
+
+MTU command line argument is maximum allowable size of outgoing GoVPN's
+packets. It varies and depends on your environment, so probably has to
+be tuned. By default MTU equals to 1452 bytes: 40 bytes per IPv6 and 8
+bytes per UDP.
+
+Underlying TAP interface has lower MTU value -- 42 bytes smaller: 26
+bytes overhead on transport message and 14 bytes for Ethernet frame.
+Client and server will print what MTU value should be used on TAP
+interface.
--- /dev/null
+@node Nonce difference
+@section Nonce difference
+
+GoVPN prevents replay attacks by remembering the last used nonce in
+messages from the remote peer. All incoming messages must have higher
+nonce number (technically it is counter), otherwise they are dropped.
+
+Because of UDP nature that does not guarantee packet ordering during
+transmission, GoVPN will drop valid non-replayed UDP packets. That leads
+to performance decrease.
+
+In most cases there is no need in so strict nonce boundaries and
+@code{-noncediff} command line option allows to create the window of
+allowable nonce differences. This is trade-off between highest security
+and possible performance degradation. For example @code{-noncediff 128}
+works rather well (no packet drops) with 1 Gbps link with two switches.
--- /dev/null
+@node Server part
+@section Server part
+
+Except for common @code{-mtu}, @code{-noncediff}, @code{-timeout},
+@code{-stats} options server has the following ones:
+
+@table @code
+@item -bind
+Address (@code{host:port} format) we must bind to.
+@item -peers
+Path to the directory containing peers information, database.
+@end table
+
+Peers directory must contain subdirectories with the names of client's identities
+in hexadecimal notation. Each of those subdirectories must have
+@strong{key} file with the corresponding authentication key,
+@strong{up.sh} script that executes each time connection with the client
+establishes, optional @code{name} file containing human readable
+client's name and optional @code{down.sh} that executes during
+connection lost.
+
+@code{up.sh} script @strong{must} print on the first stdout line the
+name of TAP interface. This script can be simple @code{echo tap10},
+maybe more advanced with dynamic interface creation:
+
+@example
+#!/bin/sh
+$tap=$(ifconfig tap create)
+ifconfig $tap inet6 fc00::1/96 mtu 1412 up
+echo $tap
+@end example
+
+Each minute server refreshes peers directory contents and adds newly
+appeared identities, deletes an obsolete ones.
+
+You can use convenient @code{utils/newclient.sh} script for new client
+creation:
+
+@example
+% ./utils/newclient.sh Alice
+9b40701bdaf522f2b291cb039490312
+@end example
+
+@code{9b40701bdaf522f2b291cb039490312} is client's identification.
+@code{peers/9b40701bdaf522f2b291cb039490312/name} contains @emph{Alice},
+@code{peers/9b40701bdaf522f2b291cb039490312/key} contains authentication key and
+@code{peers/9b40701bdaf522f2b291cb039490312/up.sh} contains currently
+dummy empty up-script.
--- /dev/null
+@node Stats
+@section Stats
+
+Both client and server has ability to show statistics about known
+connected peers. You retrieve them by downloading JSON from built-in
+background HTTP-server. You can enable it by specifying
+@code{-stats host:port} argument.
+
+Actually it is not full-fledged HTTP-server: it just accepts connection,
+reads from it (does not parse anything) and writes dummy headers with
+JSON document.
+
+@verbatim
+% govpn-server [...] -stats "[::1]:5678"
+% curl http://localhost:5678/ | jq .
+[
+ {
+ "HeartbeatSent": 1,
+ "HeartbeatRecv": 2,
+ "FramesDup": 0,
+ "FramesUnauth": 0,
+ "Addr": {
+ "Zone": "igb1",
+ "Port": 12989,
+ "IP": "fe80::221:ccff:feb9:ba7f"
+ },
+ "Id": "stargrave",
+ "LastPing": "2015-04-30T22:05:49.426616166+03:00",
+ "LastSent": "2015-04-30T22:05:49.426704138+03:00",
+ "BytesIn": 1392774,
+ "BytesOut": 17228877,
+ "FramesIn": 12412,
+ "FramesOut": 16588
+ }
+]
+@end verbatim
--- /dev/null
+@node Timeout
+@section Timeout
+
+Because of stateless UDP nature there is no way to reliably know if
+remote peer is alive. That is why timeouts are necessary. If no packets
+are sent during timeout period, then remote peer is considered to be
+dead. Timeout option should be synchronized both for server and client.
+
+If there were no packets at all during third part of timeout, then
+special heartbeat packet is sent. So VPN connection should be alive all
+the time, even if there is no traffic in corresponding TAP interfaces.
+@strong{Beware}: this consumes traffic.
+
+Stale peers and handshake states are cleaned up every timeout period.
@ref{Reporting bugs}.
GoVPN is split into two pieces: client and server. Each of them work on
-top of UDP and TAP virtual network interfaces. Client and server have
-several common configuration command line options:
-
-@table @asis
-@item Timeout
-Because of stateless UDP nature there is no way to know if
-remote peer is dead, but after some timeout. Client and server
-heartbeats each other every third part of heartbeat. Also this timeout
-is the time when server purge his obsolete handshake and peers states.
-@item Allowable nonce difference
-To prevent replay attacks we just remember latest received nonce number
-from the remote peer and drop those who has lower ones. Because UDP
-packets can be reordered: that behaviour can lead to dropping of not
-replayed ones. This option gives ability to create some window of
-allowable difference. That opens the door for replay attacks for narrow
-time interval.
-@item MTU
-Maximum transmission unit for outgoing GoVPN's packets. It varies and
-depends on your environment. By default MTU equals to 1452 bytes: 40
-bytes per IPv6 and 8 bytes per UDP. So GoVPN's packets won't be larger
-than this value. It will print maximum acceptable value for TAP
-interface during startup. As a rule TAP's MTU is 42 bytes smaller: 26
-bytes overheard for transport message, 14 bytes Ethernet frame overhead.
-@end table
-
-Client needs to know his identification, path to the authentication key,
-remote server's address, TAP interface name, and optional path to up and
-down scripts, that will be executed after connection is either initiated
-or terminated.
-
-Server needs to know only the address to listen on and path to directory
-containing peers information. This directory must contain subdirectories
-with the names equal to client's identifications. Each of them must have
-@strong{key} file with corresponding authentication key, @strong{up.sh}
-script that has to print interface's name on the first output line.
-Optionally there can be @code{down.sh} that will be executed when client
-disconnects, and @code{name} file containing human readable client's name.
-
-Each of them have ability to show statistics about known connected
-peers. If you specify @emph{host:port} in @code{-stats} argument, then
-it will run HTTP server on it, responding with JSON documents.
+top of UDP and TAP virtual network interfaces. GoVPN is just a
+tunnelling of Ethernet frames, nothing less, nothing more. All you
+IP-level network management is not touched by VPN at all. You can
+automate it using up and down shell scripts.
@menu
+* Timeout::
+* Nonce difference::
+* MTU::
+* Client part::
+* Server part::
+* Stats::
* Example usage::
@end menu
-@node Example usage
-@section Example usage
-
-Let's assume that there is some insecure link between your computer and
-WiFi-reachable gateway. You have got preconfigured @code{wlan0} network
-interface with 192.168.0/24 network. You want to create virtual
-encrypted and authenticated 172.16.0/24 network and use it as a default
-transport. MTU for that wlan0 is 1500 bytes. GoVPN will say that maximum
-MTU for the link is 1476, however it does not take in account TAP's
-Ethernet frame header length, that in my case is 14 bytes long (1476 - 14).
-
-Do not forget about setting @code{GOMAXPROC} environment variable for
-using more than one CPU.
-
-At first you have to generate client's authentication key and client's
-unique identification. There is @code{utils/newclient.sh} script for
-convenience.
-
-@example
-% ./utils/newclient.sh Alice
-9b40701bdaf522f2b291cb039490312
-@end example
-
-@code{9b40701bdaf522f2b291cb039490312} is client's identification.
-@code{peers/9b40701bdaf522f2b291cb039490312/name} contains @emph{Alice},
-@code{peers/9b40701bdaf522f2b291cb039490312/key} contains authentication key and
-@code{peers/9b40701bdaf522f2b291cb039490312/up.sh} contains currently
-dummy empty up-script.
-
-GNU/Linux IPv4 client-server example:
-
-@example
-server% echo "echo tap10" >> peers/CLIENTID/up.sh
-server% ip addr add 192.168.0.1/24 dev wlan0
-server% tunctl -t tap10
-server% ip link set mtu 1412 dev tap10
-server% ip addr add 172.16.0.1/24 dev tap10
-server% ip link set up dev tap10
-server% GOMAXPROC=4 govpn-server -bind 192.168.0.1:1194
-@end example
-
-@example
-client% umask 066
-client% echo MYLONG64HEXKEY > key.txt
-client% ip addr add 192.168.0.2/24 dev wlan0
-client% tunctl -t tap10
-client% ip link set mtu 1412 dev tap10
-client% ip addr add 172.16.0.2/24 dev tap10
-client% ip link set up dev tap10
-client% ip route add default via 172.16.0.1
-client% export GOMAXPROC=4
-client% while :; do
- govpn-client -key key.txt -id CLIENTID -iface tap10 -remote 192.168.0.1:1194
-done
-@end example
-
-FreeBSD IPv6 client-server example, with stats enabled on the server
-(localhost's 5678 port):
-
-@example
-server% cat > peers/CLIENTID/up.sh <<EOF
-#!/bin/sh
-$tap=$(ifconfig tap create)
-ifconfig $tap inet6 fc00::1/96 mtu 1412 up
-echo $tap
-EOF
-server% ifconfig em0 inet6 fe80::1/64
-server% GOMAXPROC=4 govpn-server -bind fe80::1%em0 -stats [::1]:5678
-@end example
+@include timeout.texi
-@example
-client% ifconfig me0 inet6 -ifdisabled auto_linklocal
-client% ifconfig tap10
-client% ifconfig tap10 inet6 fc00::2/96 mtu 1412 up
-client% route -6 add default fc00::1
-client% export GOMAXPROC=4
-client% while :; do
- govpn-client -key key.txt -id CLIENTID -iface tap10 -remote [fe80::1%me0]:1194
-done
-@end example
+@include noncediff.texi
-Example up-script:
+@include mtu.texi
-@example
-client% cat > up.sh <<EOF
-#!/bin/sh
-dhclient $1
-rtsol $1
-EOF
-client% chmod +x up.sh
-client% govpn -id CLIENTID -key key.txt -iface tap10 -remote [fe80::1%me0]:1194 -up ./up.sh
-@end example
+@include client.texi
-Client will exit if won't finish handshake during @code{-timeout}.
-If no packets are received from remote side during timeout, then daemon
-will stop sending packets to the client and client will exit. In all
-cases you have to rehandshake again.
+@include server.texi
-To view stats you should make GET request on a stats port and receive
-JSON in the response. For example:
+@include stats.texi
-@verbatim
-% curl http://localhost:5678/ | jq .
-[
- {
- "HeartbeatSent": 1,
- "HeartbeatRecv": 2,
- "FramesDup": 0,
- "FramesUnauth": 0,
- "Addr": {
- "Zone": "igb1",
- "Port": 12989,
- "IP": "fe80::221:ccff:feb9:ba7f"
- },
- "Id": "stargrave",
- "LastPing": "2015-04-30T22:05:49.426616166+03:00",
- "LastSent": "2015-04-30T22:05:49.426704138+03:00",
- "BytesIn": 1392774,
- "BytesOut": 17228877,
- "FramesIn": 12412,
- "FramesOut": 16588
- }
-]
-@end verbatim
+@include example.texi