### Install from Test PyPI

Source: https://github.com/tpo/onion-services/onionbalance/blob/main/docs/development.md

Install the package from Test PyPI in a fresh virtual machine to verify.

```bash
sudo apt-get install -y python3-pip tor
```

```bash
pip install -i https://pypi.org/simple/ \ 
            --extra-index-url https://test.pypi.org/simple \ 
            --break-system-packages \ 
            onionbalance==$ONIONBALANCE_VERSION
```

--------------------------------

### Install from PyPI

Source: https://github.com/tpo/onion-services/onionbalance/blob/main/docs/development.md

Install the package from PyPI in a new virtual machine for final verification.

```bash
sudo apt-get install -y python3-pip tor
```

```bash
pip install --break-system-packages \ 
  onionbalance==$ONIONBALANCE_VERSION
```

--------------------------------

### Install Dependencies and Clone Repository

Source: https://github.com/tpo/onion-services/onionbalance/blob/main/docs/installation.md

Installs necessary system packages, clones the Onionbalance repository, sets up a Python virtual environment, and installs project dependencies.

```bash
sudo apt install -y python-is-python3 python3-pip
git clone https://gitlab.torproject.org/tpo/onion-services/onionbalance
cd onionbalance
python3 -m venv venv
source venv/bin/activate
pip3 install -r requirements.txt
pip3 install -r test-requirements.txt
```

--------------------------------

### Set up Virtual Environment and Install Onionbalance with pip

Source: https://github.com/tpo/onion-services/onionbalance/blob/main/docs/installation.md

Creates a virtual environment, activates it, and installs Onionbalance using pip. This method isolates the installation from system-wide Python packages.

```bash
mkdir onionbalance
cd onionbalance
python3 -m venv venv
source venv/bin/activate
pip install onionbalance
```

--------------------------------

### Start Onionbalance with Configuration File

Source: https://github.com/tpo/onion-services/onionbalance/blob/main/docs/man/onionbalance.1.txt

Use this command to start the Onionbalance management server with a specified configuration file.

```bash
$ onionbalance -c config.yaml
```

--------------------------------

### Install Local Python Package

Source: https://github.com/tpo/onion-services/onionbalance/blob/main/docs/development.md

Install the built Python package from a local wheel file in a new virtual environment.

```bash
sudo apt-get install -y python3-pip tor
```

```bash
pip install --break-system-packages \ 
  dist/onionbalance-$ONIONBALANCE_VERSION-*.whl
```

--------------------------------

### Start Onionbalance Service

Source: https://github.com/tpo/onion-services/onionbalance/blob/main/docs/man/onionbalance.1.txt

Use this command to start the Onionbalance service using systemd or init scripts.

```bash
$ sudo service onionbalance start
```

--------------------------------

### System-wide Installation of Onionbalance from Source

Source: https://github.com/tpo/onion-services/onionbalance/blob/main/docs/installation.md

Installs Onionbalance system-wide from source using pip. The executable will typically be available in /usr/local/bin.

```bash
sudo python3 -m pip install . --break-system-packages
```

--------------------------------

### Onionbalance Config File Example

Source: https://github.com/tpo/onion-services/onionbalance/blob/main/docs/man/onionbalance-config.1.txt

An example configuration file format for Onionbalance. This defines services, their instances with addresses and names, and associated keys.

```yaml
# 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
```

--------------------------------

### Install Tor Daemon on Debian

Source: https://github.com/tpo/onion-services/onionbalance/blob/main/docs/installation.md

Installs the Tor daemon package on Debian-like systems, a prerequisite for Python package installations.

```bash
sudo apt install -y tor
```

--------------------------------

### Start Onionbalance Service

Source: https://github.com/tpo/onion-services/onionbalance/blob/main/docs/tutorial.md

Run this command on the frontend server to start the Onionbalance service. Adjust the control port ('-p') if your Tor 'ControlPort' setting differs. Verbosity can be controlled with '-v'.

```console
onionbalance -v info -c config/config.yaml -p 6666
```

--------------------------------

### Onionbalance Configuration Example (Key)

Source: https://github.com/tpo/onion-services/onionbalance/blob/main/docs/tutorial.md

Example of a key directive within the Onionbalance YAML configuration file, pointing to the private key of an existing Tor onion service.

```yaml
key: dpkhemrbs3oiv2fww5sxs6r2uybczwijzfn2ezy2osaj7iox7kl7nhad.key
```

--------------------------------

### Install Dependencies and Run Onionbalance from Source on Debian

Source: https://github.com/tpo/onion-services/onionbalance/blob/main/docs/installation.md

Installs necessary dependencies for Onionbalance on Debian-based systems and then runs the application directly from the cloned repository.

```bash
sudo apt install -y python3 python-is-python3 python3-cryptography \
                        python3-future python3-pycryptodome \
                        python3-setproctitle python3-stem python3-yaml \
                        tor
./onionbalance.py
```

--------------------------------

### Create ob_config file for Backend Instance

Source: https://github.com/tpo/onion-services/onionbalance/blob/main/docs/tutorial.md

Create an 'ob_config' file in your hidden service directory. Replace the example onion address with your frontend's actual onion address. This file is crucial for backend instance recognition.

```config
MasterOnionAddress dpkhemrbs3oiv2fww5sxs6r2uybczwijzfn2ezy2osaj7iox7kl7nhad.onion
```

--------------------------------

### Install Onionbalance using pipx

Source: https://github.com/tpo/onion-services/onionbalance/blob/main/docs/installation.md

Installs the Onionbalance Python package using pipx, the recommended method for isolated Python applications.

```bash
pipx install onionbalance
```

--------------------------------

### Install Onionbalance using Debian Package

Source: https://github.com/tpo/onion-services/onionbalance/blob/main/docs/installation.md

Installs Onionbalance and its dependencies, including the Tor daemon, on Debian-like systems.

```bash
sudo apt install onionbalance
```

--------------------------------

### Start Tor Daemon (Compiled)

Source: https://github.com/tpo/onion-services/onionbalance/blob/main/docs/tutorial.md

Command to start the Tor daemon locally when compiled from source. Requires specifying the torrc configuration file.

```bash
./src/app/tor -c torrc
```

--------------------------------

### Onionbalance Frontend Configuration Example

Source: https://github.com/tpo/onion-services/onionbalance/blob/main/docs/tutorial.md

This YAML configuration defines the backend instances for Onionbalance. Ensure the 'key' field matches your frontend's private key file name. Backend instances can be dynamically managed.

```yaml
services:
- instances:
  - address: wmilwokvqistssclrjdi5arzrctn6bznkwmosvfyobmyv2fc3idbpwyd.onion
    name: node1
  - address: fp32xzad7wlnpd4n7jltrb3w3xyj23ppgsnuzhhkzlhbt5337aw2joad.onion
    name: node2
  - address: u6uoeftsysttxeheyxtgdxssnhutmoo2y2rw6igh5ez4hpxaz4dap7ad.onion
    name: node3
  key: dpkhemrbs3oiv2fww5sxs6r2uybczwijzfn2ezy2osaj7iox7kl7nhad.key

```

--------------------------------

### Onionbalance Configuration Example (Migrating Key)

Source: https://github.com/tpo/onion-services/onionbalance/blob/main/docs/tutorial.md

Example of a key directive in the Onionbalance YAML config file when migrating an existing Tor onion service. It points to the location of the onion service's private key.

```yaml
key: hs_keys/hs_ed25519_secret_key
```

--------------------------------

### Clone and Build Tor from Source

Source: https://github.com/tpo/onion-services/onionbalance/blob/main/docs/tutorial.md

Clone the Tor project repository and build the Tor daemon from source. Ensure you have necessary C dependencies like libssl-dev and libevent-dev installed.

```bash
git clone https://git.torproject.org/tor.git
cd tor
./autogen.sh && ./configure && make
```

--------------------------------

### Install Onionbalance with pip without Virtual Environment

Source: https://github.com/tpo/onion-services/onionbalance/blob/main/docs/installation.md

Installs Onionbalance directly using pip without a virtual environment. This method is not recommended as it may conflict with system-wide Python packages.

```bash
pip install onionbalance --break-system-packages
```

--------------------------------

### Install Onionbalance Python Package from Source

Source: https://github.com/tpo/onion-services/onionbalance/blob/main/docs/installation.md

Installs the Onionbalance Python package from its source code using pip. This requires cloning the repository and may conflict with system-wide packages if --break-system-packages is used.

```bash
sudo apt install -y python3-pip
git clone https://gitlab.torproject.org/tpo/onion-services/onionbalance
cd onionbalance
python3 -m pip install . --break-system-packages
```

--------------------------------

### Test Local Python Package

Source: https://github.com/tpo/onion-services/onionbalance/blob/main/docs/development.md

Test the installed local package by checking its version and configuration command.

```bash
$HOME/.local/bin/onionbalance --version
```

```bash
$HOME/.local/bin/onionbalance-config --no-interactive
```

--------------------------------

### Run Onionbalance from Source

Source: https://github.com/tpo/onion-services/onionbalance/blob/main/docs/installation.md

Executes the Onionbalance script directly from the cloned repository after dependencies have been installed and the virtual environment is activated.

```bash
./onionbalance.py
```

--------------------------------

### Onionbalance-Config Command-Line Options

Source: https://github.com/tpo/onion-services/onionbalance/blob/main/docs/man/onionbalance-config.md

Displays the help message and all available command-line options for onionbalance-config.

```bash
onionbalance-config -h
```

--------------------------------

### Onionbalance Config Command Synopsis

Source: https://github.com/tpo/onion-services/onionbalance/blob/main/docs/man/onionbalance-config.1.txt

Shows the general command-line options available for onionbalance-config. Use this to understand the parameters for generating configurations.

```bash
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]
```

--------------------------------

### Upload to PyPI

Source: https://github.com/tpo/onion-services/onionbalance/blob/main/docs/development.md

Upload the final Python package to the main PyPI instance.

```bash
make upload-python-package
```

--------------------------------

### Regenerate Manpages

Source: https://github.com/tpo/onion-services/onionbalance/blob/main/docs/development.md

Build updated manual pages for Onionbalance.

```bash
make manpages
```

--------------------------------

### Build Python Package

Source: https://github.com/tpo/onion-services/onionbalance/blob/main/docs/development.md

Build the Python package for distribution.

```bash
make build-python-package
```

--------------------------------

### Upload to Test PyPI

Source: https://github.com/tpo/onion-services/onionbalance/blob/main/docs/development.md

Upload the Python package to the Test PyPI instance.

```bash
make upload-python-test-package
```

--------------------------------

### Onionbalance-Config Specify Output Directory

Source: https://github.com/tpo/onion-services/onionbalance/blob/main/docs/man/onionbalance-config.md

Use the --output flag to specify a custom directory for generated configuration files and keys.

```bash
onionbalance-config --output /etc/onionbalance
```

--------------------------------

### Check Manpages

Source: https://github.com/tpo/onion-services/onionbalance/blob/main/docs/development.md

Locally check the generated manpages.

```bash
man -l docs/man/onionbalance.1
```

```bash
man -l docs/man/onionbalance-config.1
```

--------------------------------

### Configure Tor Daemon (torrc)

Source: https://github.com/tpo/onion-services/onionbalance/blob/main/docs/tutorial.md

Minimal torrc configuration to enable a control port. Ensure DataDirectory is set to a valid path.

```bash
SocksPort 0
ControlPort 127.0.0.1:6666
DataDirectory /home/user/frontend_data/
```

--------------------------------

### Generate Onionbalance Configuration

Source: https://github.com/tpo/onion-services/onionbalance/blob/main/docs/tutorial.md

Use the onionbalance-config tool to create a new Onionbalance configuration file. The -n flag specifies the number of backend slots.

```bash
onionbalance-config -n 2
```

--------------------------------

### Run onionbalance-config interactively

Source: https://github.com/tpo/onion-services/onionbalance/blob/main/docs/config.md

When called without arguments, onionbalance-config runs in interactive mode to prompt for user input.

```bash
onionbalance-config
```

--------------------------------

### Onionbalance Configuration File Not Found

Source: https://github.com/tpo/onion-services/onionbalance/blob/main/docs/troubleshooting.md

This warning suggests that Onionbalance was enabled in the backend without first creating the Onion Service. Ensure the Onion Service is set up and working before configuring Onionbalance.

```text
[notice] Read configuration file "/etc/tor/torrc".
[warn] Could not open "/var/lib/tor/onion_service//ob_config": No such file or directory
[warn] OnionBalance: Unable to read config file "/var/lib/tor/onion_service//ob_config"
[warn] Failed to parse/validate config: Failed to configure rendezvous options. See logs for details.
[err] Reading config failed--see warnings above
```

--------------------------------

### Invalid INTRO2 Keys Error

Source: https://github.com/tpo/onion-services/onionbalance/blob/main/docs/troubleshooting.md

This error occurs when there's a mismatch between the keys defined in the Onionbalance publisher/frontend and backend instances. Verify that the .onion addresses match across all instances.

```text
Tor[30478]: Could not get valid INTRO2 keys on circuit 2603341821 for service [scrubbed]
Tor[30478]: Could not get valid INTRO2 keys on circuit 2603341821 for service [scrubbed]
Tor[30478]: Could not get valid INTRO2 keys on circuit 3369496953 for service [scrubbed]
```

--------------------------------

### Commit and Tag Release

Source: https://github.com/tpo/onion-services/onionbalance/blob/main/docs/development.md

Review changes, commit them with a feature message, and create a signed tag for the new version.

```bash
git diff # review
```

```bash
git commit -a -m "Feat: Onionbalance $ONIONBALANCE_VERSION"
```

```bash
git tag -s $ONIONBALANCE_VERSION -m "Onionbalance $ONIONBALANCE_VERSION"
```

--------------------------------

### Onionbalance API Reference

Source: https://github.com/tpo/onion-services/onionbalance/blob/main/docs/api.md

This section provides the structured documentation for the Onionbalance API as presented in the source.

```APIDOC
## Onionbalance API

### Description
This page contains a raw description of Onionbalance's API. For an overview, consult the [hacking page](hacking.md).

### API Details
This section is intended to contain structured API documentation. The source indicates the presence of an API but does not provide explicit endpoint details, methods, parameters, or examples in a machine-readable or standard API documentation format.

**Note:** The provided text describes the existence of an API but lacks the specific details required to generate structured endpoint documentation (e.g., HTTP methods, paths, parameters, request/response bodies).
```

--------------------------------

### Configure Backend Instance in torrc

Source: https://github.com/tpo/onion-services/onionbalance/blob/main/docs/tutorial.md

Add this line to the HiddenService block in your torrc file on each backend instance. Ensure the Tor daemon is set up correctly before this step.

```torrc
HiddenServiceOnionbalanceInstance 1
```

--------------------------------

### Push Changes and Tags

Source: https://github.com/tpo/onion-services/onionbalance/blob/main/docs/development.md

Push committed changes and tags to both origin and upstream repositories.

```bash
git push origin        && git push upstream
```

```bash
git push origin --tags && git push upstream --tags
```

--------------------------------

### Release Announcement Template

Source: https://github.com/tpo/onion-services/onionbalance/blob/main/docs/development.md

Template for announcing a new Onionbalance release, including subject, body, and placeholders for changelog and links.

```text
Subject: [RELEASE] Onionbalance [security] release $ONIONBALANCE_VERSION

Greetings,

We just released [Onionbalance][] $ONIONBALANCE_VERSION, a descriptor publisher
and load balancer for Onion Services.

[This release fixes a security issue. Please upgrade as soon as possible!]

Found a bug or have a fix? Please [report to us][contact] so it can be solved.

[Onionbalance]: https://onionservices.torproject.org/apps/base/onionbalance
[contact]: https://onionservices.torproject.org/apps/base/onionbalance/contact/

# ChangeLog

$CHANGELOG
```

--------------------------------

### Update ChangeLog File

Source: https://github.com/tpo/onion-services/onionbalance/blob/main/docs/development.md

Manually update the ChangeLog file to reflect recent changes.

```bash
$EDITOR ChangeLog
```

--------------------------------

### Clone Onionbalance Repository

Source: https://github.com/tpo/onion-services/onionbalance/blob/main/docs/installation.md

Clones the Onionbalance Git repository to run or develop directly from the source code.

```bash
git clone https://gitlab.torproject.org/tpo/onion-services/onionbalance
cd onionbalance
```

--------------------------------

### Onionbalance-Config Non-Interactive Mode

Source: https://github.com/tpo/onion-services/onionbalance/blob/main/docs/man/onionbalance-config.md

Use the --no-interactive flag to run onionbalance-config automatically without user prompts.

```bash
onionbalance-config --no-interactive
```

--------------------------------

### Update Debian Changelog

Source: https://github.com/tpo/onion-services/onionbalance/blob/main/docs/development.md

Update the debian/changelog file to record the new version.

```bash
dch -i
```

--------------------------------

### Query Onionbalance Status Socket

Source: https://github.com/tpo/onion-services/onionbalance/blob/main/docs/socket.md

Use `socat` to connect to the status socket and `json_pp` to pretty-print the JSON output. The socket is automatically closed by Onionbalance after reading.

```bash
socat - unix-connect:/var/run/onionbalance/control | json_pp -json_opt pretty
{
   "services" : [
      {
         "instances" : [
            {
               "descriptorReceived" : "2020-06-16 19:59:28",
               "introPointsNum" : 3,
               "introSetModified" : "2020-06-16 19:59:28",
               "onionAddress" : "vkmiy6biqcyphtx5exswxl5sjus2vn2b6pzir7lz5akudhwbqk5muead.onion"
            }
         ],
         "onionAddress" : "bvy46sg2b5dokczabwv2pabqlrps3lppweyrebhat6gjieo2avojdvad.onion.onion",
         "publishAttemptFirstDescriptor" : "2020-06-16 20:00:12",
         "publishAttemptSecondDescriptor" : "2020-06-16 20:00:12"
      }
   ]
}
```

--------------------------------

### Add User to Tor Group (Debian)

Source: https://github.com/tpo/onion-services/onionbalance/blob/main/docs/troubleshooting.md

On Debian systems, add the user running Onionbalance to the 'debian-tor' group to grant necessary permissions for accessing the control port cookie.

```bash
sudo adduser $USER debian-tor
```

--------------------------------

### Configure Onionbalance Status Socket Location

Source: https://github.com/tpo/onion-services/onionbalance/blob/main/docs/socket.md

Set the `status-socket-location` in the YAML config file or the `ONIONBALANCE_STATUS_SOCKET_LOCATION` environment variable to specify the socket file path. Environment variables take precedence.

```yaml
# Onionbalance Config File
status-socket-location: /home/user/test.sock
services:
- instances:
  - address: vkmiy6biqcyphtx5exswxl5sjus2vn2b6pzir7lz5akudhwbqk5muead.onion
    name: node1
  key: bvy46sg2b5dokczabwv2pabqlrps3lppweyrebhat6gjieo2avojdvad.key
```

--------------------------------

### Set Onionbalance Version

Source: https://github.com/tpo/onion-services/onionbalance/blob/main/docs/development.md

Set the version number for the release. This variable is used in subsequent commands.

```bash
ONIONBALANCE_VERSION=0.2.4
```

--------------------------------

### Permission Denied Error for Tor Control Port Cookie

Source: https://github.com/tpo/onion-services/onionbalance/blob/main/docs/troubleshooting.md

This error indicates the user running Onionbalance lacks permissions to access Tor's control port cookie. Ensure the user has the necessary read permissions.

```text
[ERROR]: Unable to authenticate on the Tor control connection: Authentication failed: unable to read '/run/tor/control.authcookie' ([Errno 13] Permission denied: '/run/tor/control.authcookie')
```

--------------------------------

### Update Python Package Version

Source: https://github.com/tpo/onion-services/onionbalance/blob/main/docs/development.md

Update the version number within the main Python package file.

```bash
$EDITOR onionbalance/__init__.py
```

=== COMPLETE CONTENT === This response contains all available snippets from this library. No additional content exists. Do not make further requests.