1badvpn-client(8)            System Manager's Manual           badvpn-client(8)
2
3
4

NAME

6       badvpn-client - VPN node daemon for the BadVPN peer-to-peer VPN system
7

SYNOPSIS

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

INTRODUCTION

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

DESCRIPTION

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

OPTIONS

63       The BadVPN client is configured entirely from command line.
64
65       --help Print version and command line syntax and exit.
66
67       --version
68              Print version and exit.
69
70       --logger <stdout/syslog>
71              Select where to log messages. Default is stdout. Syslog  is  not
72              available on Windows.
73
74       --syslog-facility <string>
75              When  logging  to syslog, set the logging facility. The facility
76              name must be in lower case.
77
78       --syslog-ident <string>
79              When logging to syslog, set the ident.
80
81       --loglevel <0-5/none/error/warning/notice/info/debug>
82              Set the default logging level.
83
84       --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
88       --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
97       --ssl  Use TLS. Requires --nssdb and --server-cert-name.
98
99       --nssdb <string>
100              When using TLS, the NSS database to use. Probably something like
101              sql:/some/folder.
102
103       --client-cert-name <string>
104              When using TLS, the name of the certificate to use. The certifi‐
105              cate must be readily accessible.
106
107       --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
112       --server-addr <addr>
113              Set  the  address  for  the  server  to listen on. See below for
114              address format.
115
116       --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
125       --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
134       --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
145       --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
150       --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
162       --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
168       --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
174       --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
180       --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
196       --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
205       --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
212       --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
219       --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
223       --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
227       --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
232       --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
237       --igmp-group-membership-interval <ms>
238              Sets  the Group Membership Interval parameter for IGMP snooping,
239              in milliseconds.
240
241       --igmp-last-member-query-time <ms>
242              Sets the Last Member Query Time parameter for IGMP snooping,  in
243              milliseconds.
244
245       --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

EXIT CODE

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

ADDRESS FORMAT

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

TAP DEVICE CONFIGURATION

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
271       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
275       Linux
276
277       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
281       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
290       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
295       Windows
296
297       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
304       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
310       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
313       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

EXAMPLES

320       For examples of using BadVPN, see badvpn(7).
321

SEE ALSO

323       badvpn-server(8), badvpn(7)
324

AUTHORS

326       Ambroz Bizjak <ambrop7@gmail.com>
327
328
329
330                                 14 July 2011                 badvpn-client(8)
Impressum