Voice Communications¶

MAGK integrates with Mumble to provide event-based voice communications. When enabled, the platform deploys a Mumble server alongside an Ice Admin Sidecar that manages channels, ACLs, and LDAP-based authentication — all orchestrated through the MAGK admin interface.

Architecture Overview¶

graph TB
    subgraph Docker Network
        Web[MAGK Web Service] -->|HTTP API| Sidecar[Ice Admin Sidecar<br/>magk-mumble-admin]
        Sidecar -->|ZeroC Ice RPC| Mumble[Mumble Server<br/>magk-mumble]
        Sidecar -->|LDAP Bind| LDAP[OpenLDAP<br/>magk-openldap]
        Monitor[Monitoring Bot] -->|node-grumble| Mumble
    end
    TAK[ATAK Vx Plugin] -->|Mumble Protocol| Mumble
    Desktop[Mumble Desktop/Mumla] -->|Mumble Protocol| Mumble
    Browser[Admin Browser] -->|WebSocket| Monitor

The architecture uses a hybrid Ice + node-grumble approach:

• Ice Admin Sidecar — A Python service that connects to Mumble's ZeroC Ice RPC interface for all server administration (channel CRUD, ACL management, user registration, LDAP authentication delegation).
• Monitoring Bot (optional) — A TypeScript client using node-grumble that observes real-time channel/user state for the admin dashboard.

Enabling Mumble¶

Voice communications require two environment variables to be set in your .env file:

MUMBLE_ENABLED=true
MUMBLE_LDAP_ENABLED=true

MUMBLE_SUPERUSER_PASSWORD=$(openssl rand -base64 24)

After setting these variables, restart the Docker Compose stack. The magk-mumble and magk-mumble-admin services will start automatically.

Voice Admin Page¶

The Voice admin page is accessible at /admin/mumble and provides a centralized interface for managing the Mumble server.

Channel Tree¶

The channel tree displays the full Mumble channel hierarchy in a collapsible tree view:

• Root — The server root channel
  • Event channels — One per event with Mumble enabled
    • Platoon channels — Grouped by platoon
      • Squad channels — One per squad in the roster
    • Admin channel — Restricted to organizers and administrators

Each channel node shows:

Connected Users¶

The connected users panel shows all users currently on the Mumble server:

Channel CRUD¶

From the Voice admin page you can:

• Create Channel — Add a new channel under any parent. Specify a name and optional team-based ACL.
• Rename Channel — Edit an existing channel's display name.
• Delete Channel — Remove a channel and all its subchannels. Connected users are moved to the parent channel.
• Move Channel — Drag a channel to a new position in the tree hierarchy.

Channel Access Management¶

Each channel can have access restrictions configured through ACLs (Access Control Lists).

Adding Teams to Channels¶

1. Select a channel in the tree view
2. Click Manage Access in the channel detail panel
3. Use the Add Team dropdown to select a team affiliation
4. The system sets an ACL rule using the format team:<team_name> that restricts the channel to members of that team

When a team is added, the ACL denies enter, speak, and listen to @all and grants those permissions to the team:<team_name> group.

ACL Display¶

The access panel shows current ACL assignments with human-readable labels:

Removing Access¶

To remove a team from a channel's ACL:

1. Select the channel
2. In the Manage Access panel, click the × next to the team entry
3. The corresponding ACL rule is removed from the channel

Event-Based Voice Provisioning¶

Voice channels are automatically provisioned during roster finalization. This is the recommended workflow for event-based voice communications.

sequenceDiagram
    participant Admin
    participant Web as MAGK Web
    participant Sidecar as Ice Admin Sidecar
    participant Mumble as Mumble Server

    Admin->>Web: Finalize Roster
    Web->>Sidecar: Create root event channel
    Sidecar->>Mumble: Ice addChannel()
    Mumble-->>Sidecar: Channel ID
    Web->>Sidecar: Create platoon channels
    Web->>Sidecar: Create squad channels
    Web->>Sidecar: Create admin channel
    Web->>Sidecar: Set ACLs per channel
    Sidecar->>Mumble: Ice setACL()
    Web->>Web: Update event (mumbleChannelsCreated=true)
    Web-->>Admin: Provisioning complete

Channel Hierarchy¶

The provisioning service creates channels mirroring the roster structure:

Event: Operation Sunrise
├── Platoon: 1st Platoon
│   ├── Squad: Alpha
│   └── Squad: Bravo
├── Platoon: 2nd Platoon
│   ├── Squad: Charlie
│   └── Squad: Delta
└── Admin (organizers/admins only)

Channel Modes¶

When enabling Mumble for an event, you choose a channel mode:

Deprovisioning¶

To remove provisioned channels:

1. Navigate to the event's Communications section
2. Click Deprovision Channels
3. Confirm the action

This removes all Mumble channels for the event (including the admin channel) and resets mumbleChannelsCreated to false.

Manual Channel Creation¶

For scenarios outside the roster workflow (e.g., persistent team channels, training rooms), create channels manually:

1. Go to /admin/mumble
2. Click Create Channel
3. Enter a channel name and select a parent channel
4. Optionally assign a team via the Add Team dropdown to restrict access
5. Click Create

ATAK Vx Plugin Integration¶

TAK users connect to Mumble through the ATAK Vx (Voice) plugin. MAGK distributes Mumble connection configuration automatically through two mechanisms:

Data Packages¶

When Mumble is enabled for an event, the TAK data package generator includes Vx plugin configuration:

• ATAK packages — The preference.pref file includes a com.atakmap.app.vx preference section with Mumble host, port, username, and channel settings.
• iTAK packages — The config.pref file includes equivalent Vx configuration entries.

Players who import their data package get Mumble auto-configured alongside their TAK server connection.

QR Code Enrollment¶

QR code payloads are resolved dynamically at scan time. When Mumble is provisioned for an event, the QR payload includes:

{
  "serverHost": "magktech.com",
  "serverPort": 8089,
  "mumbleHost": "magktech.com",
  "mumblePort": 64738,
  "mumbleUsername": "player_alpha_01",
  "mumbleChannel": "Operation Sunrise/1st Platoon/Alpha"
}

TLS Certificate¶

The Mumble server uses a TLS certificate for encrypted connections. The certificate must include the extendedKeyUsage=1.3.6.1.5.5.7.3.1 (TLS Web Server Authentication) extension for the Vx plugin to trust the connection.

Certificate mode is controlled by MUMBLE_CERT_MODE:

Auto-Placement¶

When a player connects to Mumble with LDAP credentials, the authenticator resolves their group memberships and returns them to the Mumble server. Combined with channel ACLs, this means:

1. Player authenticates with their roster username/password
2. The Ice authenticator queries MAGK for the player's squad, platoon, team, and event memberships
3. Mumble receives the group list (e.g., ["event:operation_sunrise", "platoon:1st_platoon", "squad:alpha", "team:blufor"])
4. The player can only enter channels where their groups match the ACL rules
5. The Vx plugin's channel configuration (from the data package) places them directly into their assigned squad channel

Troubleshooting¶

Certificate Errors¶

Connection Timeouts¶

Authentication Issues¶

Connection Test¶

Use the admin UI connection test to verify the voice infrastructure:

1. Go to /admin/mumble
2. Click Test Connection
3. The system verifies:
   • Ice Admin Sidecar is reachable
   • Ice connection to Mumble server is active
   • Mumble server version is reported

If the test fails, check the Docker container logs:

docker logs magk-mumble
docker logs magk-mumble-admin

Related Pages¶

• Configuration Reference — Mumble environment variables
• Data Packages — TAK data package generation including Vx config
• Teams — Team management for ACL assignments
• Events — Event creation and Mumble configuration
• Workflow — Automated workflows triggered by roster finalization