BadVPN – Blame information for rev 1

Subversion Repositories:
Rev:
Rev Author Line No. Line
1 office 1 .TH badvpn-client 8 "14 July 2011"
2 .SH NAME
3 badvpn-client \- VPN node daemon for the BadVPN peer-to-peer VPN system
4 .SH SYNOPSIS
5 .B badvpn-client
6 .RS
7 .RB "[" --help "]"
8 .br
9 .RB "[" --version "]"
10 .br
11 .RB "[" --logger " <stdout/syslog>]"
12 .br
13 (logger=syslog?
14 .br
15 .RS
16 .br
17 .RB "[" --syslog-facility " <string>]"
18 .br
19 .RB "[" --syslog-ident " <string>]"
20 .br
21 .RE
22 )
23 .br
24 .RB "[" --loglevel " <0-5/none/error/warning/notice/info/debug>]"
25 .br
26 .RB "[" --channel-loglevel " <channel-name> <0-5/none/error/warning/notice/info/debug>] ..."
27 .br
28 .RB "[" --threads " <integer>]"
29 .br
30 .RB "[" --ssl " " --nssdb " <string> " --client-cert-name " <string>]"
31 .br
32 .RB "[" --server-name " <string>]"
33 .br
34 .BR --server-addr " <addr>"
35 .br
36 .RB "[" --tapdev " <name>]"
37 .br
38 .RB "[" --scope " <scope_name>] ..."
39 .br
40 [
41 .br
42 .RS
43 .BR --bind-addr " <addr>"
44 .br
45 .RB "(transport-mode=udp? " --num-ports " <num>)"
46 .br
47 .RB "[" --ext-addr " <addr / {server_reported}:port> <scope_name>] ..."
48 .br
49 .RE
50 ] ...
51 .br
52 .BR --transport-mode " <udp/tcp>"
53 .br
54 (transport-mode=udp?
55 .br
56 .RS
57 .BR --encryption-mode " <blowfish/aes/none>"
58 .br
59 .BR --hash-mode " <md5/sha1/none>"
60 .br
61 .RB "[" --otp " <blowfish/aes> <num> <num-warn>]"
62 .br
63 .RB "[" --fragmentation-latency " <milliseconds>]"
64 .br
65 .RE
66 )
67 .br
68 (transport-mode=tcp?
69 .br
70 .RS
71 .RB "(ssl? [" --peer-ssl "])"
72 .br
73 .RB "[" --peer-tcp-socket-sndbuf " <bytes / 0>]"
74 .br
75 .RE
76 )
77 .br
78 .RB "[" --send-buffer-size " <num-packets>]"
79 .br
80 .RB "[" --send-buffer-relay-size " <num-packets>]"
81 .br
82 .RB "[" --max-macs " <num>]"
83 .br
84 .RB "[" --max-groups " <num>]"
85 .br
86 .RB "[" --igmp-group-membership-interval " <ms>]"
87 .br
88 .RB "[" --igmp-last-member-query-time " <ms>]"
89 .br
90 .RB "[" --allow-peer-talk-without-ssl "]"
91 .br
92 .RE
93 .SH INTRODUCTION
94 .P
95 This page documents the BadVPN client, a daemon for a node in a BadVPN VPN network.
96 For a general description of BadVPN, see
97 .BR badvpn (7).
98 .SH DESCRIPTION
99 .P
100 The BadVPN client is a daemon that runs on a VPN node. It opens the TAP device, connects to
101 the server, then keeps running while attempting to establish data connection to peers and
102 tranferring data between the TAP device and the peers. Once it initializes, the program only
103 terminates if it loses connection to the server, or if a signal is received.
104 .SH OPTIONS
105 .P
106 The BadVPN client is configured entirely from command line.
107 .TP
108 .BR --help
109 Print version and command line syntax and exit.
110 .TP
111 .BR --version
112 Print version and exit.
113 .TP
114 .BR --logger " <stdout/syslog>"
115 Select where to log messages. Default is stdout. Syslog is not available on Windows.
116 .TP
117 .BR --syslog-facility " <string>"
118 When logging to syslog, set the logging facility. The facility name must be in lower case.
119 .TP
120 .BR --syslog-ident " <string>"
121 When logging to syslog, set the ident.
122 .TP
123 .BR --loglevel " <0-5/none/error/warning/notice/info/debug>"
124 Set the default logging level.
125 .TP
126 .BR --channel-loglevel " <channel-name> <0-5/none/error/warning/notice/info/debug>"
127 Set the logging level for a specific logging channel.
128 .TP
129 .BR --threads " <integer>"
130 Hint for the number of additional threads to use for potentionally long computations (such as
131 encryption and OTP generation). If zero (0) (default), additional threads will be disabled and all
132 computations will be done in the event loop. If negative (<0), a guess will be made, possibly
133 based on the number of CPUs. If positive (>0), the given number of threads will be used.
134 .TP
135 .BR --ssl
136 Use TLS. Requires --nssdb and --server-cert-name.
137 .TP
138 .BR --nssdb " <string>"
139 When using TLS, the NSS database to use. Probably something like sql:/some/folder.
140 .TP
141 .BR --client-cert-name " <string>"
142 When using TLS, the name of the certificate to use. The certificate must be readily accessible.
143 .TP
144 .BR --server-name " <string>"
145 Set the name of the server used for validating the server's certificate. The server name defaults
146 to the the name in the server address (or a numeric address).
147 .TP
148 .BR --server-addr " <addr>"
149 Set the address for the server to listen on. See below for address format.
150 .TP
151 .BR --tapdev " <name>"
152 Set the TAP device to use. See below on how to configure the device. A TAP device is a virtual card
153 in the operating system, but rather than receiving from and sending frames to a piece of hardware,
154 a program (this one) opens it to read from and write frames into. If the VPN network is set up correctly,
155 the TAP devices on the VPN nodes will act as if they were all connected into a network switch.
156 .TP
157 .BR --scope " <scope_name>"
158 Add an address scope allowed for connecting to peers. May be specified multiple times to add multiple
159 scopes. The order of the scopes is irrelevant. Note that it must actually be possible to connect
160 to addresses in the given scope; when another peer binds for us to connect to, we choose the first
161 external address whose scope we recognize, and do not attempt further external addresses, even if
162 establishing the connection fails.
163 .TP
164 .BR --bind-addr " <addr>"
165 Add an address to allow binding on. See below for address format. When attempting to bind in order
166 for some peer to connect to us, the addresses will be tried in the order they are specified. If UDP
167 data transport is being used, a --num-ports option must follow to specify how many continuous ports
168 to allow binding to. For the address to be useful, one or more --ext-addr options must follow.
169 Note that when two peers need to establish a data connection, it is arbitrary which one will attempt
170 to bind first.
171 .TP
172 .BR --num-ports " <num>"
173 When using UDP transport, set the number of continuous ports for a previously specified bind address.
174 Must follow a previous --bind-addr option.
175 .TP
176 .BR --ext-addr " <addr / {server_reported}:port> <scope_name>"
177 Add an external address for a previously specified bind address. Must follow a previous --bind-addr
178 option. May be specified multiple times to add multiple external addresses. See below for address
179 format. Additionally, the IP address part can be {server_reported} to use the IPv4 address as the
180 server sees us. The external addresses are tried by the connecting peer in the order they are specified.
181 Note that the connecting peer only attempts to connect to the first address whose scope it recognizes
182 and does not try other addresses. This means that all addresses must work for be able to communicate.
183 .TP
184 .BR --transport-mode " <udp/tcp>"
185 Sets the transport protocol for data connections. UDP is recommended and works best for most networks.
186 TCP can be used instead if the underlying network has high packet loss which your virtual network
187 cannot tolerate. Must match on all peers.
188 .TP
189 .BR --encryption-mode " <blowfish/aes/none>"
190 When using UDP transport, sets the encryption mode. None means no encryption, other options mean
191 a specific cipher. Note that encryption is only useful if clients use TLS to connect to the server.
192 The encryption mode must match on all peers.
193 .TP
194 .BR --hash-mode " <md5/sha1/none>"
195 When using UDP transport, sets the hashing mode. None means no hashes, other options mean a specific
196 type of hash. Note that hashing is only useful if encryption is used as well. The hash mode must
197 match on all peers.
198 .TP
199 .BR --otp " <blowfish/aes> <num> <num-warn>"
200 When using UDP transport, enables one-time passwords. The first argument specifies a block cipher
201 used to generate passwords from a seed. The second argument specifies how many passwords are
202 generated from a single seed. The third argument specifies after how many passwords used up for
203 sending packets an attempt is made to negotiate a new seed with the other peer. num must be >0,
204 and num-warn must be >0 and <=num. The difference (num - num-warn) should be large enough to allow
205 a new seed to be negotiated before the sender runs out of passwords. Negotiating a seed involves
206 the sending peer sending it to the receiving peer via the server and the receiving peer confirming
207 it via the server. Note that one-time passwords are only useful if clients use TLS to connect to the
208 server. The OTP option must match on all peers, except for num-warn.
209 .TP
210 .BR --fragmentation-latency " <milliseconds>"
211 When using UDP transport, sets the maximum latency to sacrifice in order to pack frames into data
212 packets more efficiently. If it is >=0, a timer of that many milliseconds is used to wait for further
213 frames to put into an incomplete packet since the first chunk of the packet was written. If it is
214 <0, packets are sent out immediately. Defaults to 0, which is the recommended setting.
215 .TP
216 .BR --peer-ssl
217 When using TCP transport, enables TLS for data connections. Requires using TLS for server connection.
218 For this to work, the peers must trust each others' cerificates, and the cerificates must grant the
219 TLS server usage context. This option must match on all peers.
220 .TP
221 .BR --peer-tcp-socket-sndbuf " <bytes / 0>"
222 Sets the value of the SO_SNDBUF socket option for peer TCP sockets (zero to not set). Lower values
223 will improve fairness when data from multiple sources (local and relaying) is being sent to a
224 given peer, but may result in lower bandwidth if the network's bandwidth-delay product is too big.
225 .TP
226 .BR --send-buffer-size " <num-packets>"
227 Sets the minimum size of the peers' send buffers for sending frames originating from this system, in
228 number of packets.
229 .TP
230 .BR --send-buffer-relay-size " <num-packets>"
231 Sets the minimum size of the peers' send buffers for relaying frames from other peers, in number of
232 packets.
233 .TP
234 .BR --max-macs " <num>"
235 Sets the maximum number of MAC addresses to remember for a peer. When the number is exceeded, the least
236 recently used slot will be reused.
237 .TP
238 .BR --max-groups " <num>"
239 Sets the maximum number of IGMP group memberships to remember for a peer. When the number is exceeded,
240 the least recently used slot will be reused.
241 .TP
242 .BR --igmp-group-membership-interval " <ms>"
243 Sets the Group Membership Interval parameter for IGMP snooping, in milliseconds.
244 .TP
245 .BR --igmp-last-member-query-time " <ms>"
246 Sets the Last Member Query Time parameter for IGMP snooping, in milliseconds.
247 .TP
248 .BR --allow-peer-talk-without-ssl
249 When SSL is enabled, the clients not only connect to the server using SSL, but also exchange messages through
250 the server through another layer of SSL. This protects the messages from attacks on the server. Older versions
251 of BadVPN (<1.999.109), however, do not support this. This option allows older and newer clients to
252 interoperate by not using SSL if the other peer does not support it. It does however negate the security
253 benefits of using SSL, since the (potentionally compromised) server can then order peers not to use SSL.
254 .SH "EXIT CODE"
255 .P
256 If initialization fails, exits with code 1. Otherwise runs until termination is requested or server connection
257 is broken and exits with code 1.
258 .SH "ADDRESS FORMAT"
259 .P
260 Addresses have the form ipaddr:port, where ipaddr is either an IPv4 address (name or numeric), or an
261 IPv6 address enclosed in brackets [] (name or numeric again).
262 .SH "TAP DEVICE CONFIGURATION"
263 .P
264 To use this program, you first have to configure a TAP network device that will act as an endpoint for
265 the virtual network. The configuration depends on your operating system.
266 .P
267 Note that the client program does not configure the TAP device in any way; it only reads and writes
268 frames from/to it. You are responsible for configuring it (e.g. putting it up and setting its IP address).
269 .P
270 .B Linux
271 .P
272 You need to enable the kernel configuration option CONFIG_TUN. If you enabled it as a module, you may
273 have to load it (`modprobe tun`) before you can create the device.
274 .P
275 Then you should create a persistent TAP device for the VPN client program to open. This can be done with
276 either the
277 .B tunctl
278 or the
279 .B openvpn
280 program. The device will be associated with a user account that will have permission to use it, which should
281 be the same user as the client program will run as (not root!). To create the device with tunctl, use `tunctl -u <user> -t tapN`,
282 and to create it with openvpn, use `openvpn --mktun --user <user> --dev tapN`, where N is a number that identifies the
283 TAP device.
284 .P
285 Once the TAP device is created, pass `--tapdev tapN` to the client program to make it use this device. Note that the
286 device will not be preserved across a shutdown of the system; consult your OS documentaton if you want to automate
287 the creation or configuration of the device.
288 .P
289 .B Windows
290 .P
291 Windows does not come with a TAP driver. The client program uses the TAP-Win32 driver, which is part of OpenVPN.
292 You need to install the OpenVPN open source (!) version, and in the installer enable at least the
293 `TAP Virtual Ethernet Adapter` and `Add Shortcuts to Start Menu` options.
294 You can get the installer at
295 .br
296 <http://openvpn.net/index.php/open-source/downloads.html>.
297 .P
298 The OpenVPN installer automatically creates one TAP device on your system when it's run for the first time.
299 To create another device, use `Programs -> OpenVPN -> Utilities -> Add a new TAP virtual ethernet adapter`.
300 You may have to install OpenVPN once again to make this shortcut appear.
301 .P
302 Once you have a TAP device, you can configure it like a physical network card. You can recognize TAP devices
303 by their `Device Name` field.
304 .P
305 To use the device, pass `--tapdev "<driver_name>:<interface_name>"` to the client program, where <driver_name> is the name of
306 the TAP driver (tap0901 for OpenVPN 2.1 and 2.2) (case sensitive), and <interface_name> is the (human) name of the TAP
307 network interface (e.g. `Local Area Connection 2`).
308 .SH "EXAMPLES"
309 .P
310 For examples of using BadVPN, see
311 .BR badvpn (7).
312 .SH "SEE ALSO"
313 .BR badvpn-server (8),
314 .BR badvpn (7)
315 .SH AUTHORS
316 Ambroz Bizjak <ambrop7@gmail.com>