BadVPN – Blame information for rev 1
?pathlinks?
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> |