eveo7-mumble-authenticator 3.0.0

AllianceAuth Authenticator for Mumble server with support for templinks

Alliance Auth Mumble Authenticator

Русская версия: README.ru.md.

Bridges a Mumble (Murmur) ICE server to an Alliance Auth MariaDB backend, with optional EVE Online templink guest access, EVE portrait textures, Prometheus metrics, and a self-healing ICE healthcheck.

The authenticator runs as a single long-lived process. It connects to the Murmur ICE interface, validates Mumble logins against the Alliance Auth database (and, optionally, short-lived templink guest credentials), serves avatars as channel textures, and parks idle users. Configuration is supplied entirely through MA__-prefixed environment variables.

Prerequisites

• CPython 3.12, Linux amd64 only. zeroc-ice ships pre-built wheels for cp312 on Linux only; Python 3.11 or 3.13 will not resolve.
• A reachable Alliance Auth MariaDB/MySQL database.
• A running Murmur (Mumble) server with the ICE interface enabled and its Ice.Secret known.
• Docker — only for the container install path.

Install

A release X.Y.Z is published to both PyPI and Docker Hub on each tagged release. The first release from this repository is pending; the commands below apply once a release tag exists. Until then, install from source (repository) or build the image locally (see Docker usage).

PyPI:

pip install eveo7-mumble-authenticator

Docker Hub (linux/amd64):

docker pull docker.io/6run0/eveo7-mumble-authenticator:X.Y.Z

Pull a concrete release tag (X.Y.Z); latest tracks the newest release.

Quick start

Configuration is read only from MA__-prefixed environment variables. Create an authenticator.env file with the three required secrets and the connection coordinates:

# Required — startup fails closed if any of these is unset.
MA__ALLIANCE_AUTH__DATABASE__PASSWORD=your-db-password
MA__ICE_SERVER__SECRET=your-murmur-ice-secret
MA__ICE_CLIENT__SECRET=your-murmur-ice-secret   # must equal ICE_SERVER__SECRET

# Point at your Alliance Auth database and Murmur ICE endpoint.
MA__ALLIANCE_AUTH__DATABASE__HOST=127.0.0.1
MA__ALLIANCE_AUTH__DATABASE__NAME=alliance_auth
MA__ALLIANCE_AUTH__DATABASE__USER=alliance
MA__ICE_SERVER__HOST=127.0.0.1
MA__ICE_SERVER__PORT=6502

Run it (installed from PyPI):

set -a; . ./authenticator.env; set +a
authenticator

Verify the console script responds (no configuration required for this):

authenticator --version

The complete set of variables, with every default and which ones are required, lives in example.env.

Docker usage

docker run --rm \
  --env-file authenticator.env \
  -p 13004:13004 \
  -p 8000:8000 \
  -v "$(pwd)/data:/data" \
  docker.io/6run0/eveo7-mumble-authenticator:X.Y.Z

• 13004 — ICE callback adapter; 8000 — Prometheus metrics.
• /data — diskcache directory (avatar textures + the SELECT fallback cache). Persist it with a volume.
• The container runs as a non-root user (uid/gid 10000).
• To expose metrics outside the container, add MA__PROMETHEUS__HOST=0.0.0.0 to the env file — the endpoint binds loopback by default.

Build the image locally instead of pulling:

docker build -t eveo7-mumble-authenticator .

The build is multi-stage: by default it builds the wheel from this source tree; pass --build-arg WHEEL_FROM=pypi to install the published release instead. A reference Compose service is in docker-compose.yml.

Networking caveat

Running the container attached to multiple Docker networks is discouraged. The ICE callback adapter announces a single callback address to Murmur; with several interfaces it may advertise the wrong one, and the Mumble server then tries to reach an address that is unroutable from its network. Prefer network_mode: host (set MA__ICE_CLIENT__HOST to the reachable address), or attach a single network.

Configuration

Variables mirror the nested settings tree: uppercase each key, join nested keys with __, prefix everything with MA__, and index list entries numerically. For example, a raw ICE property:

MA__ICE_PROPERTIES__LINES__0="Ice.ThreadPool.Server.Size = 5"

The most commonly set variables:

Variable	Default	Description
MA__ALLIANCE_AUTH__DATABASE__HOST	127.0.0.1	Alliance Auth MariaDB host
MA__ALLIANCE_AUTH__DATABASE__NAME	alliance_auth	Schema holding the Mumble tables
MA__ALLIANCE_AUTH__DATABASE__USER	alliance	Database user
MA__ALLIANCE_AUTH__DATABASE__PASSWORD	— (required)	Database password
MA__ICE_SERVER__HOST	127.0.0.1	Murmur ICE Meta host
MA__ICE_SERVER__PORT	6502	Murmur ICE Meta port
MA__ICE_SERVER__SECRET	— (required)	Shared ICE secret; empty disables the check
MA__ICE_CLIENT__SECRET	— (required)	Callback secret; must match the server secret
MA__ALLIANCE_AUTH__AVATAR__ENABLED	true	Serve EVE portraits as Mumble textures
MA__IDLEHANDLER__ENABLED	false	Move idle (AFK) users to a parking channel
MA__PROMETHEUS__ENABLED	true	Expose the Prometheus metrics endpoint

Templink guest access is configured under MA__GUEST_LINK__*; it defaults to the Alliance Auth database connection. YAML configuration files are no longer accepted and cause an immediate startup error. The full reference, generated from the settings schema, is example.env.

Limitations

• Platform: linux/amd64, CPython 3.12 only (pinned by the zeroc-ice wheel availability).
• Configuration: environment variables only — YAML and command-line configuration are rejected at startup.
• Templinks: the temporary guest password is carried in the mumble:// URI in plaintext by design, so it cannot be stored hashed. Treat templinks as single-use, short-lived secrets. See docs/behavior-changes-v2.md.

Versioning

Semantic Versioning. A release X.Y.Z is published simultaneously to PyPI (eveo7-mumble-authenticator==X.Y.Z) and Docker Hub (docker.io/6run0/eveo7-mumble-authenticator:X.Y.Z); the Docker latest tag tracks the newest release.

Documentation

• example.env — full configuration reference.
• docs/operator-runbook.md — capture sessions, baseline refreshes, snapshot workflow.
• docs/behavior-changes-v2.md — catalogue of observable behaviour contracts.
• CHANGELOG.md — release history.

License

GPL-3.0-or-later. A fork of the Alliance Auth Mumble authenticator, extended with EVE Online templink guest support and an env-only, protocol-based architecture.