doc/user.texi

   1 @node User manual
   2 @unnumbered User manual
   3
   4 GoVPN is split into two pieces: client and server. Each of them work on
   5 top of UDP and TAP virtual network interfaces. Client and server have
   6 several common configuration command line options:
   7
   8 @table @asis
   9 @item Timeout
  10 Because of stateless UDP nature there is no way to know if
  11 remote peer is dead, but after some timeout. Client and server
  12 heartbeats each other every third part of heartbeat. Also this timeout
  13 is the time when server purge his obsolete handshake and peers states.
  14 @item Allowable nonce difference
  15 To prevent replay attacks we just remembers
  16 latest received nonce number from the remote peer and drops those who
  17 has lower ones. Because UDP packets can be reordered during: that
  18 behaviour can lead to dropping of not replayed ones. This options gives
  19 ability to create some window of allows difference. That opens the door
  20 for replay attacks for narrow time interval.
  21 @item MTU
  22 Maximum transmission unit.
  23 @end table
  24
  25 Client needs to know his identification, path to the authentication key,
  26 remote server's address, TAP interface name, and optional path to up and
  27 down scripts, that will be executed after connection is either initiated
  28 or terminated.
  29
  30 Server needs to know only the address to listen on and path to directory
  31 containing peers information. This directory must contain subdirectories
  32 with the names equal to client's identifications. Each of them must have
  33 key file with corresponding authentication key, up.sh script that has to
  34 print interface's name on the first line and optional down.sh.
  35
  36 @menu
  37 * Example usage::
  38 @end menu
  39
  40 @node Example usage
  41 @section Example usage
  42
  43 Let's assume that there is some insecure link between your computer and
  44 WiFi-reachable gateway. You have got preconfigured @code{wlan0} network
  45 interface with 192.168.0/24 network. You want to create virtual
  46 encrypted and authenticated 172.16.0/24 network and use it as a default
  47 transport. MTU for that wlan0 is 1500 bytes. GoVPN will say that maximum
  48 MTU for the link is 1476, however it does not take in account TAP's
  49 Ethernet frame header length, that in my case is 14 bytes long (1476 - 14).
  50
  51 Do not forget about setting @code{GOMAXPROC} environment variable for
  52 using more than one CPU.
  53
  54 At first you have to generate client's authentication key and client's
  55 unique identification. There is @code{utils/newclient.sh} script for
  56 convenience.
  57
  58 @example
  59 % ./utils/newclient.sh Alice
  60 peers/9b40701bdaf522f2b291cb039490312/Alice
  61 @end example
  62
  63 @code{9b40701bdaf522f2b291cb039490312} is client's identification.
  64 @code{Alice} is just an empty file that can help to search them like
  65 this: @verb{|find peers -name Alice|}. @code{key} file inside peer's
  66 directory contains authentication key.
  67
  68 GNU/Linux IPv4 client-server example:
  69
  70 @example
  71 server% echo "#!/bin/sh" > peers/CLIENTID/up.sh
  72 server% echo "echo tap10" >> peers/CLIENTID/up.sh
  73 server% chmod 500 peers/CLIENTID/up.sh
  74 server% ip addr add 192.168.0.1/24 dev wlan0
  75 server% tunctl -t tap10
  76 server% ip link set mtu 1462 dev tap10
  77 server% ip addr add 172.16.0.1/24 dev tap10
  78 server% ip link set up dev tap10
  79 server% GOMAXPROC=4 govpn-server -bind 192.168.0.1:1194
  80 @end example
  81
  82 @example
  83 client% umask 066
  84 client% echo MYLONG64HEXKEY > key.txt
  85 client% ip addr add 192.168.0.2/24 dev wlan0
  86 client% tunctl -t tap10
  87 client% ip link set mtu 1462 dev tap10
  88 client% ip addr add 172.16.0.2/24 dev tap10
  89 client% ip link set up dev tap10
  90 client% ip route add default via 172.16.0.1
  91 client% export GOMAXPROC=4
  92 client% while :; do
  93     govpn-client -key key.txt -id CLIENTID -iface tap10 -remote 192.168.0.1:1194
  94 done
  95 @end example
  96
  97 FreeBSD IPv6 client-server example:
  98
  99 @example
 100 server% cat > peers/CLIENTID/up.sh <<EOF
 101 #!/bin/sh
 102 $tap=$(ifconfig tap create)
 103 ifconfig $tap inet6 fc00::1/96 mtu 1462 up
 104 echo $tap
 105 EOF
 106 server% chmod 500 peers/CLIENTID/up.sh
 107 server% ifconfig em0 inet6 fe80::1/64
 108 server% GOMAXPROC=4 govpn-server -bind fe80::1%em0
 109 @end example
 110
 111 @example
 112 client% ifconfig me0 inet6 -ifdisabled auto_linklocal
 113 client% ifconfig tap10
 114 client% ifconfig tap10 inet6 fc00::2/96 mtu 1462 up
 115 client% route -6 add default fc00::1
 116 client% export GOMAXPROC=4
 117 client% while :; do
 118     govpn-client -key key.txt -id CLIENTID -iface tap10 -remote [fe80::1%me0]:1194
 119 done
 120 @end example
 121
 122 Example up-script:
 123
 124 @example
 125 client% cat > up.sh <<EOF
 126 #!/bin/sh
 127 dhclient $1
 128 rtsol $1
 129 EOF
 130 client% chmod +x up.sh
 131 client% govpn -id CLIENTID -key key.txt -iface tap10 -remote [fe80::1%me0]:1194 -up ./up.sh
 132 @end example
 133
 134 Client will exit if won't finish handshake during @code{-timeout}.
 135 If no packets are received from remote side during timeout, then daemon
 136 will stop sending packets to the client and client will exit. In all
 137 cases you have to rehandshake again.