eveo7-mumble-authenticator 3.1.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. You can also 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 with a single interface, or attach a single network. With network_mode: host and Murmur on the same host, the default MA__ICE_CLIENT__HOST=127.0.0.1 is correct. Override it only when Murmur runs on a different host; in that case ensure the ICE secret is set and the callback port is firewalled from untrusted networks.

Configuration

Variables mirror the nested settings tree: uppercase each key, join nested keys with __, prefix everything with MA__, and pass list values as a single JSON array. For example, a raw ICE property:

MA__ICE_PROPERTIES__LINES='["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.

• Alliance Auth 5 backend — do not run alongside the built-in AA5 authenticator: When using the alliance_auth5 backend, do not run Alliance Auth 5's own built-in Mumble authenticator against the same database simultaneously. Both processes write to certhash, last_connect, last_disconnect, release, and version on the same rows — running both creates a write race that corrupts session state. This authenticator is a replacement for the built-in one, not a supplement. Enable exactly one:

  # In Alliance Auth: disable the built-in authenticator in local.py
  # (remove 'mumble_authenticator' from INSTALLED_APPS or stop its worker).
  
  # In this authenticator: enable the AA5 backend.
  MA__BACKENDS__ENABLED='["alliance_auth5"]'
  

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/architecture.md — v3.0 architecture overview: composition root, layering, ICE dispatch pipeline.
• 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.