From 498b8765721035880a6f050fa76a91555f4855a9 Mon Sep 17 00:00:00 2001 From: Joel Falknau Date: Mon, 30 Dec 2024 13:29:25 +1000 Subject: [PATCH] begin docs for new authenticator --- docs/features/services/mumble-docker.md | 80 ++++++++------- docs/features/services/mumble.md | 129 +++++++++--------------- 2 files changed, 89 insertions(+), 120 deletions(-) diff --git a/docs/features/services/mumble-docker.md b/docs/features/services/mumble-docker.md index 974a3d6b..c09bf69e 100644 --- a/docs/features/services/mumble-docker.md +++ b/docs/features/services/mumble-docker.md @@ -6,25 +6,25 @@ Mumble is a free voice chat server. While not as flashy as TeamSpeak, it has all ## Configuring Auth -In your auth project's settings file (`aa-docker/conf/local.py`), do the following: +In your auth project's settings file (`myauth/settings/local.py`), do the following: -- Add `'allianceauth.services.modules.mumble',` to `INSTALLED_APPS` in your `local.py` -- Append the following to your auth project's settings file: +- Add `'allianceauth.services.modules.mumble',` to your `INSTALLED_APPS` list +- Set `MUMBLE_URL` to the public address of your mumble server. Do not include any leading `http://` or `mumble://`. + +Example config: ```python +# Installed apps +INSTALLED_APPS += [ + # ... + 'allianceauth.services.modules.mumble' + # ... +] + # Mumble Configuration MUMBLE_URL = "mumble.example.com" ``` -Add the following lines to your `.env` file - -```env -# Mumble -MUMBLE_SUPERUSER_PASSWORD = superuser_password -MUMBLE_ICESECRETWRITE = icesecretwrite -MUMBLE_SERVERPASSWORD = serverpassword -``` - Finally, restart your stack and run migrations ```shell @@ -33,16 +33,29 @@ docker compose exec allianceauth_gunicorn bash auth migrate ``` +## Configuring Authenticator + +The Authenticator is configured via Django Admin, visit `/admin/mumble/mumbleserverserver/` in + +Name: TEST +Host IP Address: 127.0.0.1 +Endpoint IP Address: 127.0.0.1 +Port: 6502 +ICE Secret: ICESECRETWRITE +Watchdog Interval: 30 +Slice: MumbleServer.ice (Mumble >=1.5.17) +Virtual Servers: 1 + +Enable EVE Avatars + +Reject Unauthenticated +ID Offset: 1000000000 +Idler Handler: + ## Docker Installations ### Installing Mumble and Authenticator -Inside your `aa-docker` directory, clone the authenticator to a sub directory as follows - -```shell -git clone https://gitlab.com/allianceauth/mumble-authenticator.git -``` - Add the following to your `docker-compose.yml` under the `services:` section ```docker @@ -66,27 +79,16 @@ Add the following to your `docker-compose.yml` under the `services:` section max-size: "10Mb" max-file: "5" - mumble-authenticator: - build: - context: . - dockerfile: ./mumble-authenticator/Dockerfile - restart: always - volumes: - - ./mumble-authenticator/authenticator.py:/authenticator.py - - ./mumble-authenticator/authenticator.ini.docker:/authenticator.ini - environment: - - MUMBLE_SUPERUSER_PASSWORD=${MUMBLE_SUPERUSER_PASSWORD} - - MUMBLE_CONFIG_ice="tcp -h 127.0.0.1 -p 6502" - - MUMBLE_CONFIG_icesecretwrite=${MUMBLE_ICESECRETWRITE} - - MUMBLE_CONFIG_serverpassword=${MUMBLE_SERVERPASSWORD} - depends_on: - - mumble-server - - auth_mysql - logging: - driver: "json-file" - options: - max-size: "10Mb" - max-file: "5" + allianceauth_mumble_authenticator: + container_name: allianceauth_mumble_authenticator + <<: [*allianceauth-base] + entrypoint: [ + "python", + "manage.py", + "mumble_authenticator", + "--server_id=1" + ] + ``` ## Permissions diff --git a/docs/features/services/mumble.md b/docs/features/services/mumble.md index 1c08a468..f9797abb 100644 --- a/docs/features/services/mumble.md +++ b/docs/features/services/mumble.md @@ -49,26 +49,6 @@ sudo yum install mumble-server ::: :::: -### Installing Mumble Authenticator - -Next, we need to download the latest authenticator release from the [authenticator repository](https://gitlab.com/allianceauth/mumble-authenticator). - -```shell -git clone https://gitlab.com/allianceauth/mumble-authenticator /home/allianceserver/mumble-authenticator -``` - -We will now install the authenticator into your Auth virtual environment. Please make sure to activate it first: - -```shell -source /home/allianceserver/venv/auth/bin/activate -``` - -Install the python dependencies for the mumble authenticator. Note that this process can take 2 to 10 minutes to complete. - -```shell -pip install -r requirements.txt -``` - ## Configuring Mumble Server Mumble ships with a configuration file that needs customization. By default, it's located at `/etc/mumble-server.ini`. Open it with your favorite text editor: @@ -102,66 +82,6 @@ sudo service mumble-server restart That's it! Your server is ready to be connected to at example.com:64738 -## Configuring Mumble Authenticator - -The ICE authenticator lives in the mumble-authenticator repository, cd to the directory where you cloned it. - -Make a copy of the default config: - -```shell -cp authenticator.ini.example authenticator.ini -``` - -Edit `authenticator.ini` and change these values: - -- `[database]` - - `user =` your allianceserver MySQL user - - `password =` your allianceserver MySQL user's password -- `[ice]` - - `secret =` the `icewritesecret` password set earlier - -Test your configuration by starting it: - -```shell -python /home/allianceserver/mumble-authenticator/authenticator.py -``` - -And finally, ensure the allianceserver user has read/write permissions to the mumble authenticator files before proceeding: - -```shell -sudo chown -R allianceserver:allianceserver /home/allianceserver/mumble-authenticator -``` - -The authenticator needs to be running 24/7 to validate users on Mumble. This can be achieved by adding a section to your auth project's supervisor config file like the following example: - -```ini -[program:authenticator] -command=/home/allianceserver/venv/auth/bin/python authenticator.py -directory=/home/allianceserver/mumble-authenticator -user=allianceserver -stdout_logfile=/home/allianceserver/myauth/log/authenticator.log -stderr_logfile=/home/allianceserver/myauth/log/authenticator.log -autostart=true -autorestart=true -startsecs=10 -priority=996 -``` - -In addition, we'd recommend adding the authenticator to Auth's restart group in your supervisor conf. For that, you need to add it to the group line as shown in the following example: - -```ini -[group:myauth] -programs=beat,worker,gunicorn,authenticator -priority=999 -``` - -To enable the changes in your supervisor configuration, you need to restart the supervisor process itself. And before we do that, we are shutting down the current Auth supervisors gracefully: - -```shell -sudo supervisor stop myauth: -sudo systemctl restart supervisor -``` - ## Configuring Auth In your auth project's settings file (`myauth/settings/local.py`), do the following: @@ -187,10 +107,57 @@ Finally, run migrations and restart your supervisor to complete the setup: ```shell python /home/allianceserver/myauth/manage.py migrate +supervisorctl restart myauth: ``` +## Configuring Authenticator + +The Authenticator is configured via Django Admin, visit `/admin/mumble/mumbleserverserver/` in + +Name: TEST +Host IP Address: 127.0.0.1 +Endpoint IP Address: 127.0.0.1 +Port: 6502 +ICE Secret: ICESECRETWRITE +Watchdog Interval: 30 +Slice: MumbleServer.ice (Mumble >=1.5.17) +Virtual Servers: 1 + +Enable EVE Avatars + +Reject Unauthenticated +ID Offset: 1000000000 +Idler Handler: + +## Running Authenticator + +The authenticator needs to be running 24/7 to validate users on Mumble. This can be achieved by adding a section to your auth project's supervisor config file like the following example: + +```ini +[program:authenticator] +command=/home/allianceserver/venv/auth/bin/python manage.py mumble_authenticator +directory=/home/allianceserver/myauth/ +stdout_logfile=/home/allianceserver/myauth/log/authenticator.log +stderr_logfile=/home/allianceserver/myauth/log/authenticator.log +autostart=true +autorestart=true +startsecs=10 +priority=996 +``` + +In addition, we'd recommend adding the authenticator to Auth's restart group in your supervisor conf. For that, you need to add it to the group line as shown in the following example: + +```ini +[group:myauth] +programs=beat,worker,gunicorn,authenticator +priority=999 +``` + +To enable the changes in your supervisor configuration, you need to restart the supervisor process itself. And before we do that, we are shutting down the current Auth supervisors gracefully: + ```shell -supervisorctl restart myauth: +sudo supervisor stop myauth: +sudo systemctl restart supervisor ``` ## Permissions