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, maximum frame size that is acceptable on TAP
  26 interface.
  27 @end table
  28
  29 Client needs to know his identification, path to the authentication key,
  30 remote server's address, TAP interface name, and optional path to up and
  31 down scripts, that will be executed after connection is either initiated
  32 or terminated.
  33
  34 Server needs to know only the address to listen on and path to directory
  35 containing peers information. This directory must contain subdirectories
  36 with the names equal to client's identifications. Each of them must have
  37 @strong{key} file with corresponding authentication key, @strong{up.sh}
  38 script that has to print interface's name on the first output line.
  39 Optionally there can be @code{down.sh} that will be executed when client
  40 disconnects, and @code{name} file containing human readable client's name.
  41
  42 Each of them have ability to show statistics about known connected
  43 peers. If you specify @emph{host:port} in @code{-stats} argument, then
  44 it will run HTTP server on it, responding with JSON documents.
  45
  46 @menu
  47 * Example usage::
  48 @end menu
  49
  50 @node Example usage
  51 @section Example usage
  52
  53 Let's assume that there is some insecure link between your computer and
  54 WiFi-reachable gateway. You have got preconfigured @code{wlan0} network
  55 interface with 192.168.0/24 network. You want to create virtual
  56 encrypted and authenticated 172.16.0/24 network and use it as a default
  57 transport. MTU for that wlan0 is 1500 bytes. GoVPN will say that maximum
  58 MTU for the link is 1476, however it does not take in account TAP's
  59 Ethernet frame header length, that in my case is 14 bytes long (1476 - 14).
  60
  61 Do not forget about setting @code{GOMAXPROC} environment variable for
  62 using more than one CPU.
  63
  64 At first you have to generate client's authentication key and client's
  65 unique identification. There is @code{utils/newclient.sh} script for
  66 convenience.
  67
  68 @example
  69 % ./utils/newclient.sh Alice
  70 9b40701bdaf522f2b291cb039490312
  71 @end example
  72
  73 @code{9b40701bdaf522f2b291cb039490312} is client's identification.
  74 @code{peers/9b40701bdaf522f2b291cb039490312/name} contains @emph{Alice},
  75 @code{peers/9b40701bdaf522f2b291cb039490312/key} contains authentication key and
  76 @code{peers/9b40701bdaf522f2b291cb039490312/up.sh} contains currently
  77 dummy empty up-script.
  78
  79 GNU/Linux IPv4 client-server example:
  80
  81 @example
  82 server% echo "echo tap10" >> peers/CLIENTID/up.sh
  83 server% ip addr add 192.168.0.1/24 dev wlan0
  84 server% tunctl -t tap10
  85 server% ip link set mtu 1462 dev tap10
  86 server% ip addr add 172.16.0.1/24 dev tap10
  87 server% ip link set up dev tap10
  88 server% GOMAXPROC=4 govpn-server -bind 192.168.0.1:1194
  89 @end example
  90
  91 @example
  92 client% umask 066
  93 client% echo MYLONG64HEXKEY > key.txt
  94 client% ip addr add 192.168.0.2/24 dev wlan0
  95 client% tunctl -t tap10
  96 client% ip link set mtu 1462 dev tap10
  97 client% ip addr add 172.16.0.2/24 dev tap10
  98 client% ip link set up dev tap10
  99 client% ip route add default via 172.16.0.1
 100 client% export GOMAXPROC=4
 101 client% while :; do
 102     govpn-client -key key.txt -id CLIENTID -iface tap10 -remote 192.168.0.1:1194
 103 done
 104 @end example
 105
 106 FreeBSD IPv6 client-server example, with stats enabled on the server
 107 (localhost's 5678 port):
 108
 109 @example
 110 server% cat > peers/CLIENTID/up.sh <<EOF
 111 #!/bin/sh
 112 $tap=$(ifconfig tap create)
 113 ifconfig $tap inet6 fc00::1/96 mtu 1462 up
 114 echo $tap
 115 EOF
 116 server% ifconfig em0 inet6 fe80::1/64
 117 server% GOMAXPROC=4 govpn-server -bind fe80::1%em0 -stats [::1]:5678
 118 @end example
 119
 120 @example
 121 client% ifconfig me0 inet6 -ifdisabled auto_linklocal
 122 client% ifconfig tap10
 123 client% ifconfig tap10 inet6 fc00::2/96 mtu 1462 up
 124 client% route -6 add default fc00::1
 125 client% export GOMAXPROC=4
 126 client% while :; do
 127     govpn-client -key key.txt -id CLIENTID -iface tap10 -remote [fe80::1%me0]:1194
 128 done
 129 @end example
 130
 131 Example up-script:
 132
 133 @example
 134 client% cat > up.sh <<EOF
 135 #!/bin/sh
 136 dhclient $1
 137 rtsol $1
 138 EOF
 139 client% chmod +x up.sh
 140 client% govpn -id CLIENTID -key key.txt -iface tap10 -remote [fe80::1%me0]:1194 -up ./up.sh
 141 @end example
 142
 143 Client will exit if won't finish handshake during @code{-timeout}.
 144 If no packets are received from remote side during timeout, then daemon
 145 will stop sending packets to the client and client will exit. In all
 146 cases you have to rehandshake again.