badvpn/badvpn-client.8

.TH badvpn-client 8 "21 June 2011"
.SH NAME
badvpn-client \- VPN node daemon for the BadVPN peer-to-peer VPN system
.SH SYNOPSIS
.B badvpn-client
.RS
.RB "[" --help "]"
.br
.RB "[" --version "]"
.br
.RB "[" --logger " <stdout/syslog>]"
.br
(logger=syslog?
.br
.RS
.br
.RB "[" --syslog-facility " <string>]"
.br
.RB "[" --syslog-ident " <string>]"
.br
.RE
)
.br
.RB "[" --loglevel " <0-5/none/error/warning/notice/info/debug>]"
.br
.RB "[" --channel-loglevel " <channel-name> <0-5/none/error/warning/notice/info/debug>] ..."
.br
.RB "[" --threads " <integer>]"
.br
.RB "[" --ssl " " --nssdb " <string> " --client-cert-name " <string>]"
.br
.RB "[" --server-name " <string>]"
.br
.BR --server-addr " <addr>"
.br
.RB "[" --tapdev " <name>]"
.br
.RB "[" --scope " <scope_name>] ..."
.br
[
.br
.RS
.BR --bind-addr " <addr>"
.br
.RB "(transport-mode=udp? " --num-ports " <num>)"
.br
.RB "[" --ext-addr " <addr / {server_reported}:port> <scope_name>] ..."
.br
.RE
]
.br
.BR --transport-mode " <udp/tcp>"
.br
(transport-mode=udp?
.br
.RS
.BR --encryption-mode " <blowfish/aes/none>"
.br
.BR --hash-mode " <md5/sha1/none>"
.br
.RB "[" --otp " <blowfish/aes> <num> <num-warn>]"
.br
.RB "[" --fragmentation-latency " <milliseconds>]"
.br
.RE
)
.br
(transport-mode=tcp?
.br
.RS
.RB "(ssl? [" --peer-ssl "])"
.br
.RB "[" --peer-tcp-socket-sndbuf " <bytes / 0>]"
.br
.RE
)
.br
.RB "[" --send-buffer-size " <num-packets>]"
.br
.RB "[" --send-buffer-relay-size " <num-packets>]"
.br
.RB "[" --max-macs " <num>]"
.br
.RB "[" --max-groups " <num>]"
.br
.RB "[" --igmp-group-membership-interval " <ms>]"
.br
.RB "[" --igmp-last-member-query-time " <ms>]"
.br
.RE
.SH INTRODUCTION
.P
This page documents the BadVPN client, a daemon for a node in a BadVPN VPN network.
For a general description of BadVPN, see
.BR badvpn (7).
.SH DESCRIPTION
.P
The BadVPN client is a daemon that runs on a VPN node. It opens the TAP device, connects to
the server, then keeps running while attempting to establish data connection to peers and
tranferring data between the TAP device and the peers. Once it initializes, the program only
terminates if it loses connection to the server, or if a signal is received.
.SH OPTIONS
.P
The BadVPN client is configured entirely from command line.
.TP
.BR --help
Print version and command line syntax and exit.
.TP
.BR --version
Print version and exit.
.TP
.BR --logger " <stdout/syslog>"
Select where to log messages. Default is stdout. Syslog is not available on Windows.
.TP
.BR --syslog-facility " <string>"
When logging to syslog, set the logging facility. The facility name must be in lower case.
.TP
.BR --syslog-ident " <string>"
When logging to syslog, set the ident.
.TP
.BR --loglevel " <0-5/none/error/warning/notice/info/debug>"
Set the default logging level.
.TP
.BR --channel-loglevel " <channel-name> <0-5/none/error/warning/notice/info/debug>"
Set the logging level for a specific logging channel.
.TP
.BR --threads " <integer>"
Hint for the number of additional threads to use for potentionally long computations (such as
encryption and OTP generation). If zero (0) (default), additional threads will be disabled and all
computations will be done in the event loop. If negative (<0), a guess will be made, possibly
based on the number of CPUs. If positive (>0), the given number of threads will be used.
.TP
.BR --ssl
Use TLS. Requires --nssdb and --server-cert-name.
.TP
.BR --nssdb " <string>"
When using TLS, the NSS database to use. Probably something like sql:/some/folder.
.TP
.BR --client-cert-name " <string>"
When using TLS, the name of the certificate to use. The certificate must be readily accessible.
.TP
.BR --server-name " <string>"
Set the name of the server used for validating the server's certificate. The server name defaults
to the the name in the server address (or a numeric address).
.TP
.BR --server-addr " <addr>"
Set the address for the server to listen on. See below for address format.
.TP
.BR --tapdev " <name>"
Set the TAP device to use. See below on how to configure the device. A TAP device is a virtual card
in the operating system, but rather than receiving from and sending frames to a piece of hardware,
a program (this one) opens it to read from and write frames into. If the VPN network is set up correctly,
the TAP devices on the VPN nodes will act as if they were all connected into a network switch.
.TP
.BR --scope " <scope_name>"
Add an address scope allowed for connecting to peers. May be specified multiple times to add multiple
scopes. The order of the scopes is irrelevant. Note that it must actually be possible to connect
to addresses in the given scope; when another peer binds for us to connect to, we choose the first
external address whose scope we recognize, and do not attempt further external addresses, even if
establishing the connection fails.
.TP
.BR --bind-addr " <addr>"
Add an address to allow binding on. See below for address format. When attempting to bind in order
for some peer to connect to us, the addresses will be tried in the order they are specified. If UDP
data transport is being used, a --num-ports option must follow to specify how many continuous ports
to allow binding to. For the address to be useful, one or more --ext-addr options must follow.
Note that when two peers need to establish a data connection, it is arbitrary which one will attempt
to bind first.
.TP
.BR --num-ports " <num>"
When using UDP transport, set the number of continuous ports for a previously specified bind address.
Must follow a previous --bind-addr option.
.TP
.BR --ext-addr " <addr / {server_reported}:port> <scope_name>"
Add an external address for a previously specified bind address. Must follow a previous --bind-addr
option. May be specified multiple times to add multiple external addresses. See below for address
format. Additionally, the IP address part can be {server_reported} to use the IPv4 address as the
server sees us. The external addresses are tried by the connecting peer in the order they are specified.
Note that the connecting peer only attempts to connect to the first address whose scope it recognizes
and does not try other addresses. This means that all addresses must work for be able to communicate.
.TP
.BR --transport-mode " <udp/tcp>"
Sets the transport protocol for data connections. UDP is recommended and works best for most networks.
TCP can be used instead if the underlying network has high packet loss which your virtual network
cannot tolerate. Must match on all peers.
.TP
.BR --encryption-mode " <blowfish/aes/none>"
When using UDP transport, sets the encryption mode. None means no encryption, other options mean
a specific cipher. Note that encryption is only useful if clients use TLS to connect to the server.
The encryption mode must match on all peers.
.TP
.BR --hash-mode " <md5/sha1/none>"
When using UDP transport, sets the hashing mode. None means no hashes, other options mean a specific
type of hash. Note that hashing is only useful if encryption is used as well. The hash mode must
match on all peers.
.TP
.BR --otp " <blowfish/aes> <num> <num-warn>"
When using UDP transport, enables one-time passwords. The first argument specifies a block cipher
used to generate passwords from a seed. The second argument specifies how many passwords are
generated from a single seed. The third argument specifies after how many passwords used up for
sending packets an attempt is made to negotiate a new seed with the other peer. num must be >0,
and num-warn must be >0 and <=num. The difference (num - num-warn) should be large enough to allow
a new seed to be negotiated before the sender runs out of passwords. Negotiating a seed involves
the sending peer sending it to the receiving peer via the server and the receiving peer confirming
it via the server. Note that one-time passwords are only useful if clients use TLS to connect to the
server. The OTP option must match on all peers, except for num-warn.
.TP
.BR --fragmentation-latency " <milliseconds>"
When using UDP transport, sets the maximum latency to sacrifice in order to pack frames into data
packets more efficiently. If it is >=0, a timer of that many milliseconds is used to wait for further
frames to put into an incomplete packet since the first chunk of the packet was written. If it is
<0, packets are sent out immediately. Defaults to 0, which is the recommended setting.
.TP
.BR --peer-ssl
When using TCP transport, enables TLS for data connections. Requires using TLS for server connection.
For this to work, the peers must trust each others' cerificates, and the cerificates must grant the
TLS server usage context. This option must match on all peers.
.TP
.BR --peer-tcp-socket-sndbuf " <bytes / 0>"
Sets the value of the SO_SNDBUF socket option for peer TCP sockets (zero to not set). Lower values
will improve fairness when data from multiple sources (local and relaying) is being sent to a
given peer, but may result in lower bandwidth if the network's bandwidth-delay product to too big.
.TP
.BR --send-buffer-size " <num-packets>"
Sets the minimum size of the peers' send buffers for sending frames originating from this system, in
number of packets.
.TP
.BR --send-buffer-relay-size " <num-packets>"
Sets the minimum size of the peers' send buffers for relaying frames from other peers, in number of
packets.
.TP
.BR --max-macs " <num>"
Sets the maximum number of MAC addresses to remember for a peer. When the number is exceeded, the least
recently used slot will be reused.
.TP
.BR --max-groups " <num>"
Sets the maximum number of IGMP group memberships to remember for a peer. When the number is exceeded,
the least recently used slot will be reused.
.TP
.BR --igmp-group-membership-interval " <ms>"
Sets the Group Membership Interval parameter for IGMP snooping, in milliseconds.
.TP
.BR --igmp-last-member-query-time " <ms>"
Sets the Last Member Query Time parameter for IGMP snooping, in milliseconds.
.SH "EXIT CODE"
.P
If initialization fails, exits with code 1. Otherwise runs until termination is requested or server connection
is broken and exits with code 1.
.SH "ADDRESS FORMAT"
.P
Addresses have the form ipaddr:port, where ipaddr is either an IPv4 address (name or numeric), or an
IPv6 address enclosed in brackets [] (name or numeric again).
.SH "TAP DEVICE CONFIGURATION"
.P
To use this program, you first have to configure a TAP network device that will act as an endpoint for
the virtual network. The configuration depends on your operating system.
.P
Note that the client program does not configure the TAP device in any way; it only reads and writes
frames from/to it. You are responsible for configuring it (e.g. putting it up and setting its IP address).
.P
.B Linux
.P
You need to enable the kernel configuration option CONFIG_TUN. If you enabled it as a module, you may
have to load it (`modprobe tun`) before you can create the device.
.P
Then you should create a persistent TAP device for the VPN client program to open. This can be done with
either the
.B tunctl
or the
.B openvpn
program. The device will be associated with a user account that will have permission to use it, which should
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`,
and to create it with openvpn, use `openvpn --mktun --user <user> --dev tapN`, where N is a number that identifies the
TAP device.
.P
Once the TAP device is created, pass `--tapdev tapN` to the client program to make it use this device. Note that the
device will not be preserved across a shutdown of the system; consult your OS documentaton if you want to automate
the creation or configuration of the device.
.P
.B Windows
.P
Windows does not come with a TAP driver. The client program uses the TAP-Win32 driver, which is part of OpenVPN.
You need to install the OpenVPN open source (!) version, and in the installer enable at least the
`TAP Virtual Ethernet Adapter` and `Add Shortcuts to Start Menu` options.
You can get the installer at
.br
<http://openvpn.net/index.php/open-source/downloads.html>.
.P
The OpenVPN installer automatically creates one TAP device on your system when it's run for the first time.
To create another device, use `Programs -> OpenVPN -> Utilities -> Add a new TAP virtual ethernet adapter`.
You may have to install OpenVPN once again to make this shortcut appear.
.P
Once you have a TAP device, you can configure it like a physical network card. You can recognize TAP devices
by their `Device Name` field.
.P
To use the device, pass `--tapdev "<driver_name>:<interface_name>"` to the client program, where <driver_name> is the name of
the TAP driver (tap0901 for OpenVPN 2.1 and 2.2) (case sensitive), and <interface_name> is the (human) name of the TAP
network interface (e.g. `Local Area Connection 2`).
.SH "EXAMPLES"
.P
For examples of using BadVPN, see
.BR badvpn (7).
.SH "SEE ALSO"
.BR badvpn-server (8),
.BR badvpn (7)
.SH COPYRIGHT
Copyright (C) 2010 Ambroz Bizjak. BadVPN is free software; you can redistribute it and/or
modify it under the terms of the GNU General Public License version 2 as published by the
Free Software Foundation.
.SH AUTHORS
Ambroz Bizjak <ambrop7@gmail.com>