badvpn-server(8)

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

💖 badvpn-server — the manual page, bestie edition 💖

okay so you're in the badvpn-server(8) page, from the System Manager's Manual, and honestly? this one's a whole vibe. it's the chat server for BadVPN, and no cap, it's the little matchmaker that lets your VPN peers actually find each other. let's get into it 🫶

✨ NAME ✨

badvpn-server — chat server for the BadVPN peer-to-peer VPN system

🌸 SYNOPSIS 🌸

badvpn-server
       [--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>] ...
       [--listen-addr <addr>] ...
       [--ssl --nssdb <string> --server-cert-name <string>]
       [--comm-predicate <string>]
       [--relay-predicate <string>]
       [--client-socket-sndbuf <bytes / 0>]

🌈 INTRODUCTION 🌈

so this page is all about the BadVPN server, which lives inside a BadVPN VPN network and lets peers talk to each other so they can set up their data connections. it's giving "social secretary for your VPN" energy. 💅

want the full BadVPN lore, the whole cinematic universe? that's over in badvpn(7). go read it, i'll wait 🎀

💜 DESCRIPTION 💜

the BadVPN server is a chat server used by the nodes in the VPN network to talk to each other and establish data connections. that's its whole job and it does it beautifully. ✨

once it initializes, the server only terminates if a signal is received. so like, it's not gonna quit on you for no reason — you gotta tell it. periodt.

👑 OPTIONS 👑

the BadVPN server is configured entirely from command line. no config file, no drama, just flags. iconic honestly.

  • --help — print version and command line syntax, then exit. it's the "wait what do i type" button 💖
  • --version — print version and exit. that's it, that's the whole thing 🦋
  • --logger <stdout/syslog> — pick where your messages go. default is stdout. heads up: syslog is not available on Windows 😭
  • --syslog-facility <string> — when you're logging to syslog, this sets the logging facility. the facility name has to be in lower case, no uppercase shenanigans.
  • --syslog-ident <string> — when you're logging to syslog, this sets the ident.
  • --loglevel <0-5/none/error/warning/notice/info/debug> — sets the default logging level.
  • --channel-loglevel <channel-name> <0-5/none/error/warning/notice/info/debug> — sets the logging level for one specific logging channel. per-channel glow-up ✨
  • --listen-addr <addr> — add an address for the server to listen on. address format is further down, keep scrolling bestie 👇
  • --ssl — use TLS. this one requires --nssdb and --server-cert-name, so don't show up without them 🔒
  • --nssdb <string> — when using TLS, this is the NSS database to use. probably something like sql:/some/folder.
  • --server-cert-name <string> — when using TLS, the name of the certificate to use. the certificate must be readily accessible, so like, have it ready bestie.
  • --comm-predicate <string> — sets a predicate defining which pairs of clients are allowed to communicate. it's a logical expression, details below. available functions:
    • p1name(string) — true if the TLS common name of peer 1 equals the given string. if TLS isn't used, the common name is assumed to be an empty string.
    • p1addr(string) — true if the IP address of peer 1 equals the given string. the string must not be a name.
    • p2name(string) — true if the TLS common name of peer 2 equals the given string. if TLS isn't used, the common name is assumed to be an empty string.
    • p2addr(string) — true if the IP address of peer 2 equals the given string. the string must not be a name.
    • and there's no rule about which one is peer 1 and which is peer 2. when the server needs to figure out whether two peers can communicate, it evaluates the predicate once and in no specific order. so don't build your whole personality on which is which 🙈
  • --relay-predicate <string> — sets a predicate defining how peers can relay data through other peers. it's a logical expression, details below. if the predicate evaluates to true, peer P can relay data through peer R. available functions:
    • pname(string) — true if the TLS common name of peer P peer equals the given string. if TLS isn't used, the common name is assumed to be an empty string.
    • paddr(string) — true if the IP address of peer P equals the given string. the string must not be a name.
    • rname(string) — true if the TLS common name of peer R peer equals the given string. if TLS isn't used, the common name is assumed to be an empty string.
    • raddr(string) — true if the IP address of peer R equals the given string. the string must not be a name.
  • --client-socket-sndbuf <bytes / 0> — sets the value of the SO_SNDBUF socket option for client TCP sockets (zero means don't set it). lower values improve fairness when data from multiple peers is being sent to a given peer, but heads up — they may result in lower bandwidth if the network's bandwidth-delay product is too big. trade-offs, bestie, it's giving ✨balance✨

💀 EXIT CODE 💀

  • if initialization fails, it exits with code 1.
  • otherwise it runs until termination is requested and exits with code 1.

yeah. both of them are 1. that's not a typo, that's just how it is. fr fr. 🫠

🎀 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 for the v6 girlies, we love to see it 💅

🧚 PREDICATES 🧚

the BadVPN server includes a small predicate language used to define certain policies. the syntax and semantics of the language are described right here, bestie. grab a snack. 🍓

  • true — logical true constant. evaluates to 1.
  • false — logical false constant. evaluates to 0.
  • NOT expression — logical negation. if the expression evaluates to error, the negation evaluates to error.
  • expression OR expression — logical disjunction. the second expression is only evaluated if the first expression evaluates to false. if a sub-expression evaluates to error, the disjunction evaluates to error.
  • expression AND expression — logical conjunction. the second expression is only evaluated if the first expression evaluates to true. if a sub-expression evaluates to error, the conjunction evaluates to error.
  • function(arg, ..., arg) — evaluation of a user-provided function (where function is the name of the function, [a-zA-Z0-9_]+).
    • if the function with the given name doesn't exist, it evaluates to error.
    • arguments are evaluated from left to right.
    • each argument can either be a logical expression or a string (characters enclosed in double quotes, without any double quote).
    • if an argument is encountered but all needed arguments have already been evaluated, the function evaluates to error.
    • if an argument is of the wrong type, it is not evaluated and the function evaluates to error.
    • if an argument evaluates to error, the function evaluates to error.
    • if after all arguments have been evaluated the function needs more arguments, it evaluates to error.
    • then the handler function is called. if it returns anything other than 1 and 0, the function evaluates to error. otherwise it evaluates to what the handler function returned.

so many error paths, and every single one of them is valid. the error handling in this language is honestly main character energy 😤

🌟 EXAMPLES 🌟

for examples of using BadVPN, see badvpn(7). yes, it's a cross-reference, yes it's still an example section, we don't make the rules 💖

🌸 SEE ALSO 🌸

💖 AUTHORS 💖

Ambroz Bizjak <ambrop7@gmail.com> — thank you for your service, king 👑

and that's the whole page bestie!! the source is the System Manager's Manual, and this beauty is dated 21 June 2011. go forth and chat-server responsibly 💅✨🦋

💌 one last thing

bye babes, good luck with your predicates, drink water, and remember: if init fails, you're getting a 1, and if it doesn't, you're still getting a 1. slay 🎀

📦 where this page comes from