From 8d09a156e94b79f55d1ef37d2e6d2572e5bf6e58 Mon Sep 17 00:00:00 2001 From: Sergey Matveev Date: Fri, 1 May 2015 21:41:50 +0300 Subject: [PATCH] [DOC] User manual refactoring Signed-off-by: Sergey Matveev --- doc/client.texi | 34 +++++++++ doc/example.texi | 65 +++++++++++++++++ doc/mtu.texi | 12 ++++ doc/noncediff.texi | 16 +++++ doc/server.texi | 48 +++++++++++++ doc/stats.texi | 36 ++++++++++ doc/timeout.texi | 14 ++++ doc/user.texi | 176 +++++---------------------------------------- 8 files changed, 242 insertions(+), 159 deletions(-) create mode 100644 doc/client.texi create mode 100644 doc/example.texi create mode 100644 doc/mtu.texi create mode 100644 doc/noncediff.texi create mode 100644 doc/server.texi create mode 100644 doc/stats.texi create mode 100644 doc/timeout.texi diff --git a/doc/client.texi b/doc/client.texi new file mode 100644 index 0000000..076937b --- /dev/null +++ b/doc/client.texi @@ -0,0 +1,34 @@ +@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 <> 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 diff --git a/doc/mtu.texi b/doc/mtu.texi new file mode 100644 index 0000000..e8c5c22 --- /dev/null +++ b/doc/mtu.texi @@ -0,0 +1,12 @@ +@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. diff --git a/doc/noncediff.texi b/doc/noncediff.texi new file mode 100644 index 0000000..14afcb1 --- /dev/null +++ b/doc/noncediff.texi @@ -0,0 +1,16 @@ +@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. diff --git a/doc/server.texi b/doc/server.texi new file mode 100644 index 0000000..7541d57 --- /dev/null +++ b/doc/server.texi @@ -0,0 +1,48 @@ +@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. diff --git a/doc/stats.texi b/doc/stats.texi new file mode 100644 index 0000000..f6284e0 --- /dev/null +++ b/doc/stats.texi @@ -0,0 +1,36 @@ +@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 diff --git a/doc/timeout.texi b/doc/timeout.texi new file mode 100644 index 0000000..5fe7fd0 --- /dev/null +++ b/doc/timeout.texi @@ -0,0 +1,14 @@ +@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. diff --git a/doc/user.texi b/doc/user.texi index 5f3bd59..dfe9534 100644 --- a/doc/user.texi +++ b/doc/user.texi @@ -5,173 +5,31 @@ Announcements about updates and new releases can be found in @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 < up.sh <