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:

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 name Mumble shows after login is configurable via MA__BACKENDS__DISPLAY_NAME_FORMAT (and MA__BACKENDS__TEMP_DISPLAY_NAME_FORMAT for guests), composed from Alliance Auth NameFormatter-compatible placeholders such as {character_name}, {corp_ticker}, and {state}, plus operator-defined {group_tags} drawn from MA__BACKENDS__GROUP_TAGS. Left unset, each backend keeps its previous naming. The full reference, generated from the settings schema, is example.env.

MA__BACKENDS__GROUP_TAGS keys must use the Mumble-ACL form of the group name, not the human-readable one. The same group list is what the authenticator hands Murmur for channel ACLs, and a Mumble group name cannot contain a space, so Alliance Auth replaces spaces (and other non-word characters) in group names with hyphens. An AA group Academy Fleetcom is reported — and must be matched — as Academy-Fleetcom:

MA__BACKENDS__GROUP_TAGS: '{"Mumble-admin": "#ADM", "Academy-Fleetcom": "#FC", "Fleetcom": "#FC"}'

Matching is case-insensitive, but the hyphenation is not optional — a key with a literal space never matches. To see the exact tokens a user carries, read the groups the backend resolves (live auth_group names on alliance_auth5, or the mumble_mumbleuser.groups snapshot on the legacy alliance_auth backend).

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"]'
  

  alliance_auth5 is also exclusive within MA__BACKENDS__ENABLED: startup fails when any other backend is listed alongside it, and any MA__GUEST_LINK__* configuration is rejected. Templinks are served natively from the AA5 mumble_tempuser table, so do not enable guest_link — that backend targets the legacy mumbletemps_tempuser schema of the AA3/4 mumble-temps app.

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 — architecture overview: composition root, layering, ICE dispatch pipeline.
• docs/ice-properties.md — ICE property assembly order and thread-pool tuning 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.