ONIONBALANCE-CONFIG(1)

✨ ONIONBALANCE-CONFIG(1) ✨

okay bestie, buckle UP — this is the manual page for onionbalance-config, the little generator that makes your onionbalance(1) config files and your keys, all in one go. No cap. 🧅💖

---

🌸 NAME 🌸

onionbalance-config — the tool for generating onionbalance(1) config files and keys. That's it, that's the whole job, and she does it flawlessly. 👑

---

🎀 SYNOPSIS 🎀

onionbalance-config [-h] [--hs-version {v3}] [--key KEY] [-p PASSWORD] [-n
NUM_INSTANCES] [-s NUM_SERVICES] [-t TAG] [--output OUTPUT]
[--no-interactive] [-v VERBOSITY] [--service-virtual-port
SERVICE_VIRTUAL_PORT] [--service-target SERVICE_TARGET] [--version]

---

🦋 DESCRIPTION 🦋

Real talk: onionbalance-config is the fastest way to generate the keys and config files you need to get your onion service up and running. Like, the whole "ugh where do I even start" era is over. She's giving main character energy and she's doing it for you. ✨

---

💅 FULL INVOCATION 💅

onionbalance-config [-h] [--hs-version {v3}] [--key KEY] [-p PASSWORD]
                           [-n NUM_INSTANCES] [-s NUM_SERVICES] [-t TAG]
                           [--output OUTPUT] [--no-interactive] [-v VERBOSITY]
                           [--service-virtual-port SERVICE_VIRTUAL_PORT]
                           [--service-target SERVICE_TARGET] [--version]

So what's happening here? onionbalance-config generates config files and keys for Onionbalance instances and management servers. And the iconic part: calling it with no options at all drops you straight into an interactive mode. She'll just ask you things. Conversational queen. 💬

🌈 options: 🌈

• -h, --help — shows this help message and dips. ✌️
• --hs-version {v3} — the Onion service version. And listen, only v3 is supported, so don't come at her with anything else. 🙅
• --key KEY — the RSA private key for the master onion service. 🔑
• -p, --password PASSWORD — an optional password you can use to encrypt the master service private key. Optional but honestly? Use it. 🔐
• -n NUM_INSTANCES — how many instances to generate. Default: 2.
• -s NUM_SERVICES — how many services to generate. Default: 1.
• -t, --tag TAG — the prefix name for the service instances. Default: node.
• --output OUTPUT — the directory to store the generated config files in. She'll create the directory for you if it doesn't already exist, which is so thoughtful of her. Default: config/. 🗂️
• --no-interactive — tries to run automatically without prompting you for input. For the girlies who don't want to be perceived. 🙈
• -v VERBOSITY — minimum verbosity level for logging. Available in ascending order: debug, info, warning, error, critical. Default: info. 📢
• --service-virtual-port SERVICE_VIRTUAL_PORT — the Onion service port for external client connections. Default: 80.
• --service-target SERVICE_TARGET — the target IP and port where your service is actually listening. Default: 127.0.0.1:80.
• --version — shows the program's version number and exits. ⭐

And fr fr, when you call it without any arguments at all, the config generator runs in interactive mode and prompts for user input. She's chatty like that. 💖

---

👑 CONFIGURATION FILE FORMAT 👑

Here's a sample configuration file that you can adapt. Copy her energy, not her contents. 🎀

# Onion Load Balancer Config File example
#
# Each Onion Service key line should be associated with a list of 0 or more
# instances which contain the onion address of the load balancing backend
# service.

services:
- instances: # web
  - address: wmilwokvqistssclrjdi5arzrctn6bznkwmosvfyobmyv2fc3idbpwyd.onion
    name: web1
  - address: fp32xzad7wlnpd4n7jltrb3w3xyj23ppgsnuzhhkzlhbt5337aw2joad.onion
    name: web2
  key: lsainlbvqg6obox2xkcmlv65rlctarxzuzod4juicfj6cstmoimkxyyd.key
- instances: # irc
  - address: drdoqmg4p43tbtoqxuxs2ax2vgfpetqtvgnpdugh5b2i7f7zxrzvy7id.key
    name: irc1
  - address: u6uoeftsysttxeheyxtgdxssnhutmoo2y2rw6igh5ez4hpxaz4dap7ad.onion
    name: irc2
  key: 6kjmifbfmd2232gpsu7am2psp2ydennc4zhq53zcwlirps5jmpnaikyd.key

---

🍓 FILES 🍓

onionbalance-config generates the following files, and yes she names them herself, she's very organized:

• config.yaml — the configuration file that the Onionbalance management server uses. 🗄️
• ONION_ADDRESS.key — every service instance has a private key, and that key gets derived into the public address and identity for the Onion Service. Each private key file is named after the .onion address, so ONION_ADDRESS.key will actually look something like dpkhemrbs3oiv2fww5sxs6r2uybczwijzfn2ezy2osaj7iox7kl7nhad.key.

BESTIE. LISTEN TO ME. It is essential that you keep this file secure. This is not a drill, this is not a vibe, this is your whole identity. 🚨💀

By default, onionbalance-config writes these files in the config/ folder, relative to the folder where it was invoked from.

If you want to be specific about it, you can explicitly set the actual folder by invoking onionbalance-config with the --output flag.

And to configure the system-wide service, onionbalance-config should set --output to /etc/onionbalance.

---

🌈 EXIT STATUS 🌈

• onionbalance-config exits with a non-zero status in case of errors. 😭
• Exit status is 2 on command line invocation errors.
• For other, general errors, the exit status is 1.
• Otherwise? Exit status is 0. Slay. ✨

---

💜 AUTHOR 💜

George Kadianakis, Donncha O'Cearbhaill, Silvio Rhatto <rhatto@torproject.org>

---

🔥 SEE ALSO 🔥

The docs/ folder distributed with Onionbalance contains the full documentation, which should also be available at <https://onionservices.torproject.org/apps/web/onionbalance/>.

The Onionbalance source code and all documentation may be downloaded from <https://gitlab.torproject.org/tpo/onion-services/onionbalance>.

---

🌟 AUTHORS 🌟

Silvio Rhatto rhatto@torproject.org

---

and that's the whole page, babe 🫶 This was the Onionbalance User Manual, dated Apr 24, 2025, for ONIONBALANCE-CONFIG(1). Go forth and balance your onions, you gorgeous nerd. 🧅💖✨