2 @unnumbered User manual
4 Announcements about updates and new releases can be found in
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:
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
25 Maximum transmission unit, maximum frame size that is acceptable on TAP
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
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.
47 @section Example usage
49 Let's assume that there is some insecure link between your computer and
50 WiFi-reachable gateway. You have got preconfigured @code{wlan0} network
51 interface with 192.168.0/24 network. You want to create virtual
52 encrypted and authenticated 172.16.0/24 network and use it as a default
53 transport. MTU for that wlan0 is 1500 bytes. GoVPN will say that maximum
54 MTU for the link is 1476, however it does not take in account TAP's
55 Ethernet frame header length, that in my case is 14 bytes long (1476 - 14).
57 Do not forget about setting @code{GOMAXPROC} environment variable for
58 using more than one CPU.
60 At first you have to generate client's authentication key and client's
61 unique identification. There is @code{utils/newclient.sh} script for
65 % ./utils/newclient.sh Alice
66 9b40701bdaf522f2b291cb039490312
69 @code{9b40701bdaf522f2b291cb039490312} is client's identification.
70 @code{peers/9b40701bdaf522f2b291cb039490312/name} contains @emph{Alice},
71 @code{peers/9b40701bdaf522f2b291cb039490312/key} contains authentication key and
72 @code{peers/9b40701bdaf522f2b291cb039490312/up.sh} contains currently
73 dummy empty up-script.
75 GNU/Linux IPv4 client-server example:
78 server% echo "echo tap10" >> peers/CLIENTID/up.sh
79 server% ip addr add 192.168.0.1/24 dev wlan0
80 server% tunctl -t tap10
81 server% ip link set mtu 1462 dev tap10
82 server% ip addr add 172.16.0.1/24 dev tap10
83 server% ip link set up dev tap10
84 server% GOMAXPROC=4 govpn-server -bind 192.168.0.1:1194
89 client% echo MYLONG64HEXKEY > key.txt
90 client% ip addr add 192.168.0.2/24 dev wlan0
91 client% tunctl -t tap10
92 client% ip link set mtu 1462 dev tap10
93 client% ip addr add 172.16.0.2/24 dev tap10
94 client% ip link set up dev tap10
95 client% ip route add default via 172.16.0.1
96 client% export GOMAXPROC=4
98 govpn-client -key key.txt -id CLIENTID -iface tap10 -remote 192.168.0.1:1194
102 FreeBSD IPv6 client-server example:
105 server% cat > peers/CLIENTID/up.sh <<EOF
107 $tap=$(ifconfig tap create)
108 ifconfig $tap inet6 fc00::1/96 mtu 1462 up
111 server% ifconfig em0 inet6 fe80::1/64
112 server% GOMAXPROC=4 govpn-server -bind fe80::1%em0
116 client% ifconfig me0 inet6 -ifdisabled auto_linklocal
117 client% ifconfig tap10
118 client% ifconfig tap10 inet6 fc00::2/96 mtu 1462 up
119 client% route -6 add default fc00::1
120 client% export GOMAXPROC=4
122 govpn-client -key key.txt -id CLIENTID -iface tap10 -remote [fe80::1%me0]:1194
129 client% cat > up.sh <<EOF
134 client% chmod +x up.sh
135 client% govpn -id CLIENTID -key key.txt -iface tap10 -remote [fe80::1%me0]:1194 -up ./up.sh
138 Client will exit if won't finish handshake during @code{-timeout}.
139 If no packets are received from remote side during timeout, then daemon
140 will stop sending packets to the client and client will exit. In all
141 cases you have to rehandshake again.