doc/user.texi

   1 @node User manual
   2 @unnumbered User manual
   3
   4 Announcements about updates and new releases can be found in
   5 @ref{Reporting bugs}.
   6
   7 GoVPN is split into two pieces: client and server. Each of them work on
   8 top of UDP and TAP virtual network interfaces. Client and server have
   9 several common configuration command line options:
  10
  11 @table @asis
  12 @item Timeout
  13 Because of stateless UDP nature there is no way to know if
  14 remote peer is dead, but after some timeout. Client and server
  15 heartbeats each other every third part of heartbeat. Also this timeout
  16 is the time when server purge his obsolete handshake and peers states.
  17 @item Allowable nonce difference
  18 To prevent replay attacks we just remember latest received nonce number
  19 from the remote peer and drop those who has lower ones. Because UDP
  20 packets can be reordered: that behaviour can lead to dropping of not
  21 replayed ones. This option gives ability to create some window of
  22 allowable difference. That opens the door for replay attacks for narrow
  23 time interval.
  24 @item MTU
  25 Maximum transmission unit for outgoing GoVPN's packets. It varies and
  26 depends on your environment. By default MTU equals to 1452 bytes: 40
  27 bytes per IPv6 and 8 bytes per UDP. So GoVPN's packets won't be larger
  28 than this value. It will print maximum acceptable value for TAP
  29 interface during startup. As a rule TAP's MTU is 42 bytes smaller: 26
  30 bytes overheard for transport message, 14 bytes Ethernet frame overhead.
  31 @end table
  32
  33 Client needs to know his identification, path to the authentication key,
  34 remote server's address, TAP interface name, and optional path to up and
  35 down scripts, that will be executed after connection is either initiated
  36 or terminated.
  37
  38 Server needs to know only the address to listen on and path to directory
  39 containing peers information. This directory must contain subdirectories
  40 with the names equal to client's identifications. Each of them must have
  41 @strong{key} file with corresponding authentication key, @strong{up.sh}
  42 script that has to print interface's name on the first output line.
  43 Optionally there can be @code{down.sh} that will be executed when client
  44 disconnects, and @code{name} file containing human readable client's name.
  45
  46 Each of them have ability to show statistics about known connected
  47 peers. If you specify @emph{host:port} in @code{-stats} argument, then
  48 it will run HTTP server on it, responding with JSON documents.
  49
  50 @menu
  51 * Example usage::
  52 @end menu
  53
  54 @node Example usage
  55 @section Example usage
  56
  57 Let's assume that there is some insecure link between your computer and
  58 WiFi-reachable gateway. You have got preconfigured @code{wlan0} network
  59 interface with 192.168.0/24 network. You want to create virtual
  60 encrypted and authenticated 172.16.0/24 network and use it as a default
  61 transport. MTU for that wlan0 is 1500 bytes. GoVPN will say that maximum
  62 MTU for the link is 1476, however it does not take in account TAP's
  63 Ethernet frame header length, that in my case is 14 bytes long (1476 - 14).
  64
  65 Do not forget about setting @code{GOMAXPROC} environment variable for
  66 using more than one CPU.
  67
  68 At first you have to generate client's authentication key and client's
  69 unique identification. There is @code{utils/newclient.sh} script for
  70 convenience.
  71
  72 @example
  73 % ./utils/newclient.sh Alice
  74 9b40701bdaf522f2b291cb039490312
  75 @end example
  76
  77 @code{9b40701bdaf522f2b291cb039490312} is client's identification.
  78 @code{peers/9b40701bdaf522f2b291cb039490312/name} contains @emph{Alice},
  79 @code{peers/9b40701bdaf522f2b291cb039490312/key} contains authentication key and
  80 @code{peers/9b40701bdaf522f2b291cb039490312/up.sh} contains currently
  81 dummy empty up-script.
  82
  83 GNU/Linux IPv4 client-server example:
  84
  85 @example
  86 server% echo "echo tap10" >> peers/CLIENTID/up.sh
  87 server% ip addr add 192.168.0.1/24 dev wlan0
  88 server% tunctl -t tap10
  89 server% ip link set mtu 1412 dev tap10
  90 server% ip addr add 172.16.0.1/24 dev tap10
  91 server% ip link set up dev tap10
  92 server% GOMAXPROC=4 govpn-server -bind 192.168.0.1:1194
  93 @end example
  94
  95 @example
  96 client% umask 066
  97 client% echo MYLONG64HEXKEY > key.txt
  98 client% ip addr add 192.168.0.2/24 dev wlan0
  99 client% tunctl -t tap10
 100 client% ip link set mtu 1412 dev tap10
 101 client% ip addr add 172.16.0.2/24 dev tap10
 102 client% ip link set up dev tap10
 103 client% ip route add default via 172.16.0.1
 104 client% export GOMAXPROC=4
 105 client% while :; do
 106     govpn-client -key key.txt -id CLIENTID -iface tap10 -remote 192.168.0.1:1194
 107 done
 108 @end example
 109
 110 FreeBSD IPv6 client-server example, with stats enabled on the server
 111 (localhost's 5678 port):
 112
 113 @example
 114 server% cat > peers/CLIENTID/up.sh <<EOF
 115 #!/bin/sh
 116 $tap=$(ifconfig tap create)
 117 ifconfig $tap inet6 fc00::1/96 mtu 1412 up
 118 echo $tap
 119 EOF
 120 server% ifconfig em0 inet6 fe80::1/64
 121 server% GOMAXPROC=4 govpn-server -bind fe80::1%em0 -stats [::1]:5678
 122 @end example
 123
 124 @example
 125 client% ifconfig me0 inet6 -ifdisabled auto_linklocal
 126 client% ifconfig tap10
 127 client% ifconfig tap10 inet6 fc00::2/96 mtu 1412 up
 128 client% route -6 add default fc00::1
 129 client% export GOMAXPROC=4
 130 client% while :; do
 131     govpn-client -key key.txt -id CLIENTID -iface tap10 -remote [fe80::1%me0]:1194
 132 done
 133 @end example
 134
 135 Example up-script:
 136
 137 @example
 138 client% cat > up.sh <<EOF
 139 #!/bin/sh
 140 dhclient $1
 141 rtsol $1
 142 EOF
 143 client% chmod +x up.sh
 144 client% govpn -id CLIENTID -key key.txt -iface tap10 -remote [fe80::1%me0]:1194 -up ./up.sh
 145 @end example
 146
 147 Client will exit if won't finish handshake during @code{-timeout}.
 148 If no packets are received from remote side during timeout, then daemon
 149 will stop sending packets to the client and client will exit. In all
 150 cases you have to rehandshake again.
 151
 152 To view stats you should make GET request on a stats port and receive
 153 JSON in the response. For example:
 154
 155 @verbatim
 156 % curl http://localhost:5678/ | jq .
 157 [
 158   {
 159     "HeartbeatSent": 1,
 160     "HeartbeatRecv": 2,
 161     "FramesDup": 0,
 162     "FramesUnauth": 0,
 163     "Addr": {
 164       "Zone": "igb1",
 165       "Port": 12989,
 166       "IP": "fe80::221:ccff:feb9:ba7f"
 167     },
 168     "Id": "stargrave",
 169     "LastPing": "2015-04-30T22:05:49.426616166+03:00",
 170     "LastSent": "2015-04-30T22:05:49.426704138+03:00",
 171     "BytesIn": 1392774,
 172     "BytesOut": 17228877,
 173     "FramesIn": 12412,
 174     "FramesOut": 16588
 175   }
 176 ]
 177 @end verbatim