badvpn-client(8)

📦 version 1.999.130, in arch rolling, fedora 43, nixos 26.05, nixpkgs unstable

💖 badvpn-client — the manual, but make it make sense 💖

okay bestie, so this is badvpn-client(8) from the System Manager's Manual, and we're gonna get through it together, no cap. Sit down, grab a strawberry 🍓, and let's go.

✨ NAME ✨

badvpn-client — the VPN node daemon for the BadVPN peer-to-peer VPN system 👑

🌸 SYNOPSIS 🌸

like, here's the whole vibe of how you call it. every bracket matters, don't @ me:

badvpn-client
       [--help]
       [--version]
       [--logger <stdout/syslog>]
       (logger=syslog?
              [--syslog-facility <string>]
              [--syslog-ident <string>]
       )
       [--loglevel <0-5/none/error/warning/notice/info/debug>]
       [--channel-loglevel <channel-name>
       <0-5/none/error/warning/notice/info/debug>] ...
       [--threads <integer>]
       [--ssl --nssdb <string> --client-cert-name <string>]
       [--server-name <string>]
       --server-addr <addr>
       [--tapdev <name>]
       [--scope <scope_name>] ...
       [
              --bind-addr <addr>
              (transport-mode=udp? --num-ports <num>)
              [--ext-addr <addr / {server_reported}:port> <scope_name>]
              ...
       ] ...
       --transport-mode <udp/tcp>
       (transport-mode=udp?
              --encryption-mode <blowfish/aes/none>
              --hash-mode <md5/sha1/none>
              [--otp <blowfish/aes> <num> <num-warn>]
              [--fragmentation-latency <milliseconds>]
       )
       (transport-mode=tcp?
              (ssl? [--peer-ssl])
              [--peer-tcp-socket-sndbuf <bytes / 0>]
       )
       [--send-buffer-size <num-packets>]
       [--send-buffer-relay-size <num-packets>]
       [--max-macs <num>]
       [--max-groups <num>]
       [--igmp-group-membership-interval <ms>]
       [--igmp-last-member-query-time <ms>]
       [--allow-peer-talk-without-ssl]

🦋 INTRODUCTION 🦋

This page is literally the whole documentation for the BadVPN client — a daemon for a node in a BadVPN VPN network. That's the tea. ☕

Want the big-picture lore of BadVPN itself? That's a whole other page, bestie: see badvpn(7). 💜

🌈 DESCRIPTION 🌈

The BadVPN client is a daemon, and it runs on a VPN node. Main character energy only. 💅

Here's the whole routine, step by step:

It opens the TAP device. 🎀
It connects to the server.
Then it just… keeps running, fr fr — attempting to establish data connection to peers and transferring data between the TAP device and the peers the whole time. 🔥

Once it initializes, the program only terminates if:

it loses connection to the server, or
a signal is received. 😭

so yeah — no chill-exit option, no "actually I'm done now" button. It either gets cut off from the server or somebody sends it a signal. periodt.

✨ OPTIONS ✨

okay bestie, so the BadVPN client is configured entirely from the command line. no secret config file, no hidden menu, just you and the flags. 💅

--help — prints the version and command line syntax, then dips. 👋
--version — prints the version and exits. periodt.
--logger <stdout/syslog> — picks where log messages go. Default is stdout. syslog is not available on Windows. 💀
--syslog-facility <string> — when logging to syslog, sets the logging facility. The facility name must be in lower case. no uppercase shenanigans.
--syslog-ident <string> — when logging to syslog, sets the ident.
--loglevel <0-5/none/error/warning/notice/info/debug> — sets the default logging level. pick your drama level.
--channel-loglevel <channel-name> <0-5/none/error/warning/notice/info/debug> — sets the logging level for a specific logging channel. per-channel vibe check.
--threads <integer> — a hint for the number of additional threads to use for potentionally long computations (such as encryption and OTP generation). If it’s zero (0) — the default — additional threads are disabled and all computations are done in the event loop. If it’s negative (<0), a guess is made, possibly based on the number of CPUs. If it’s positive (>0), the given number of threads is used. multitasking but make it optional. 🧵
--ssl — use TLS. Requires --nssdb and --server-cert-name. yes bestie, both. 🔐
--nssdb <string> — when using TLS, the NSS database to use. Probably something like sql:/some/folder.
--client-cert-name <string> — when using TLS, the name of the certificate to use. The certificate must be readily accessible. no digging around.
--server-name <string> — sets 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). certificate validation said “be normal”.
--server-addr <addr> — sets the address for the server to listen on. address format is down below. 👇
--tapdev <name> — sets 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. iconic virtual switch behavior. 🌐
--scope <scope_name> — adds 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. so first recognized scope or bust.
--bind-addr <addr> — adds 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. 🎲
--num-ports <num> — when using UDP transport, sets the number of continuous ports for a previously specified bind address. Must follow a previous --bind-addr option. no skipping the line, bestie.
--ext-addr <addr / {server_reported}:port> <scope_name> — adds 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. all of them, fr fr.
--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. matching outfits but for protocols.
--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. 🔒
--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. hashing is the plus-one to encryption.
--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. OTP but make it ✨secure✨.
--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. patience level: configurable.
--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. yes, “cerificates” is in the original, we don’t fix it, we respect it. 🫶
--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 is too big. fairness vs bandwidth, pick your struggle.
--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. 📦
--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. relay girlies get their own buffer.
--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. LRU said “I’ll allow it”.
--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. same LRU energy.
--igmp-group-membership-interval <ms> — sets the Group Membership Interval parameter for IGMP snooping, in milliseconds.
--igmp-last-member-query-time <ms> — sets the Last Member Query Time parameter for IGMP snooping, in milliseconds.
--allow-peer-talk-without-ssl — when SSL is enabled, the clients not only connect to the server using SSL, but also exchange messages through the server through another layer of SSL. This protects the messages from attacks on the server. Older versions of BadVPN (<1.999.109), however, do not support this. This option allows older and newer clients to interoperate by not using SSL if the other peer does not support it. It does however negate the security benefits of using SSL, since the (potentionally compromised) server can then order peers not to use SSL.

bestie, this is a security trade-off, not a cute accessory. it literally negates the security benefits. use with your eyes open. 👀

🚪 EXIT CODE 🚪

If initialization fails, exits with code 1. Otherwise runs until termination is requested or server connection is broken and exits with code 1. so yeah, code 1 either way in those cases. 💀

📬 ADDRESS FORMAT 📬

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). brackets are the VIP section for IPv6. 💅

✨ TAP DEVICE CONFIGURATION ✨

okay so to use this program, you first have to configure a TAP network device that will act as an endpoint for the virtual network. And bestie, the configuration depends on your operating system. 💅

lowkey the most important thing: 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). No cap. 🫶

🐧 Linux 🐧

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. periodt.

Then you should create a persistent TAP device for the VPN client program to open. This can be done with either the tunctl or the 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:


and to create it with `openvpn`, use:

where N is a number that identifies the TAP device.

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 documentation if you want to automate the creation or configuration of the device. 💖

🪟 Windows 🪟

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 <http://openvpn.net/index.php/open-source/downloads.html>. ✨

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. 😭

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.

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). 🦋

🧪 EXAMPLES 🧪

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

👀 SEE ALSO 👀

badvpn-server(8)
badvpn(7)

💌 AUTHORS 💌

Ambroz Bizjak <ambrop7@gmail.com>

and that's the whole page, bestie! This was badvpn-client(8), dated 14 July 2011. Now go configure those TAP devices like the main character you are. 💅✨🫶

📦 where this page comes from

arch rolling: badvpn 1.999.130-10 · BSD-3-Clause
fedora 43: badvpn 1.999.130-14.fc43 · LicenseRef-Callaway-BSD
nixos 26.05: badvpn 1.999.130
nixpkgs unstable: badvpn 1.999.130
💖 girlified by deepseek-ai/DeepSeek-V4.1-Flash on 2026-10-18: a language model's rewrite of the original, under its terms