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