Merge branch 'docs' into 'master'

Document Permissions and other Docs Improvments

Closes #1253

See merge request allianceauth/allianceauth!1283

docs/features/apps/autogroups.md

@@ -33,3 +33,20 @@ When you create an autogroup config you will be given the following options:
 - Corp/Alliance name source sets the source of the Corp/Alliance name used in creating the group name. Currently the options are Full name and Ticker.
 
 - Replace spaces allows you to replace spaces in the autogroup name with the value in the Replace spaces with field. This can be blank.
+
+## Permissions
+
+Auto Groups are configured via models in the Admin Interface, a user will require the `Staff` Flag in addition to the following permissions.
+
+```eval_rst
++-------------------------------------------+------------------+----------------+
+| Permission                                | Admin Site       | Auth Site      |
++===========================================+==================+================+
+| eve_autogroups.add_autogroupsconfig	    | Can create model | None.          |
++-------------------------------------------+------------------+----------------+
+| eve_autogroups.change_autogroupsconfig	| Can edit model   | None.          |
++-------------------------------------------+------------------+----------------+
+| eve_autogroups.delete_autogroupsconfig	| Can delete model | None.          |
++-------------------------------------------+------------------+----------------+
+```
+There exists more models that will be automatically created and maintained by this module, they do not require end-user/admin interaction. `managedalliancegroup` `managedcorpgroups`

docs/features/apps/corpstats.md

@@ -102,11 +102,6 @@ To use this feature, users will require some of the following:
 +---------------------------------------+------------------+----------------------------------------------------+
 | corpstats.add_corpstats               | Can create model | Can add new corpstats using an SSO token.          |
 +---------------------------------------+------------------+----------------------------------------------------+
-| corpstats.change_corpstats            | Can edit model   | None.                                              |
-+---------------------------------------+------------------+----------------------------------------------------+
-| corpstats.remove_corpstats            | Can delete model | None.                                              |
-+---------------------------------------+------------------+----------------------------------------------------+
-
 ```
 
 Users who add a Corp Stats with their token will be granted permissions to view it regardless of the above permissions. View permissions are interpreted in the "OR" sense: a user can view their corporation's Corp Stats without the `view_corp_corpstats` permission if they have the `view_alliance_corpstats` permission, same idea for their state. Note that these evaluate against the user's main character.

docs/features/apps/fleetactivitytracking.md

@@ -9,3 +9,20 @@ The Fleet Activity Tracking (FAT) app allows you to track fleet participation.
 Fleet Activity Tracking requires access to the `esi-location.read_location.v1`, `esi-location.read_ship_type.v1`, and `esi-universe.read_structures.v1` SSO scopes. Update your application on the [EVE Developers site](https://developers.eveonline.com) to ensure these are available.
 
 Add `'allianceauth.fleetactivitytracking',` to your `INSTALLED_APPS` list in your auth project's settings file. Run migrations to complete installation.
+
+## Permissions
+
+To administer this feature, users will require some of the following.
+
+Users do not require any permissions to interact with FAT Links created.
+
+```eval_rst
++---------------------------------------+------------------+--------------------------------------------------------------------------+
+| Permission                            | Admin Site       | Auth Site                                                                |
++=======================================+==================+==========================================================================+
+| auth.fleetactivitytracking            | None             | Create and Modify FATLinks                                               |
++---------------------------------------+------------------+--------------------------------------------------------------------------+
+| auth.fleetactivitytracking_statistics	| None             | Can view detailed statistics for corp models and other characters.       |
++---------------------------------------+------------------+--------------------------------------------------------------------------+
+
+```

docs/features/apps/hrapplications.md

@@ -40,7 +40,9 @@ Any reviewer who can see the application can view the applicant's APIs if they p
 
 ## Permissions
 
-The following permissions have an effect on the website above and beyond their usual admin site functions.
+To administer this feature, users will require some of the following.
+
+Users do not require any permission to apply to a corporation and fill out the form.
 
 ```eval_rst
 +---------------------------------------+------------------+----------------------------------------------------+
@@ -54,13 +56,12 @@ The following permissions have an effect on the website above and beyond their u
 +---------------------------------------+------------------+----------------------------------------------------+
 | hrapplications.reject_applications    | None             | Can reject applications                            |
 +---------------------------------------+------------------+----------------------------------------------------+
-| hrapplications.view_apis              | None             | Can view applicant API keys, and audit in Jacknife |
-+---------------------------------------+------------------+----------------------------------------------------+
 | hrapplications.add_applicationcomment | Can create model | Can comment on applications                        |
 +---------------------------------------+------------------+----------------------------------------------------+
-
 ```
 
+A user with `auth.human_resources` can only see applications to their own corp.
+
 Best practice is to bundle the `auth.human_resources` permission alongside the `hrapplications.approve_application` and `hrapplications.reject_application` permissions, as in isolation these don't make much sense.
 
 ## Models

docs/features/apps/optimer.md

@@ -7,3 +7,17 @@ Fleet Operations is an app for organizing and communicating fleet schedules.
 ## Installation
 
 Add `'allianceauth.optimer',` to your `INSTALLED_APPS` list in your auth project's settings file. Run migrations to complete installation.
+
+## Permissions
+
+To use and administer this feature, users will require some of the following.
+
+```eval_rst
++---------------------------------------+------------------+--------------------------------------------------------------------------+
+| Permission                            | Admin Site       | Auth Site                                                                |
++=======================================+==================+==========================================================================+
+| auth.optimer_view                     | None             | Can view Fleet Operation Timers                                          |
++---------------------------------------+------------------+--------------------------------------------------------------------------+
+| auth.optimer_manage                   | None             | Can Manage Fleet Operation timers                                        |
++---------------------------------------+------------------+--------------------------------------------------------------------------+
+```

docs/features/apps/permissions_tool.md

@@ -37,3 +37,15 @@ The permissions audit page will give you an overview of all the users who have a
 ![permissions audit](/_static/images/features/apps/permissions_tool/audit.png)
 
 Please note that users may appear multiple times if this permission is granted via multiple sources.
+
+## Permissions
+
+To use this feature, users will require some of the following.
+
+```eval_rst
++---------------------------------------+------------------+--------------------------------------------------------------------------+
+| Permission                            | Admin Site       | Auth Site                                                                |
++=======================================+==================+==========================================================================+
+| permissions_tool.audit_permissions    | None             | Can view the Permissions Audit tool                                      |
++---------------------------------------+------------------+--------------------------------------------------------------------------+
+```

docs/features/apps/srp.md

@@ -7,3 +7,19 @@ Ship Replacement helps you to organize ship replacement programs (SRP) for your
 ## Installation
 
 Add `'allianceauth.srp',` to your `INSTALLED_APPS` list in your auth project's settings file. Run migrations to complete installation.
+
+## Permissions
+
+To use and administer this feature, users will require some of the following.
+
+```eval_rst
++----------------------+------------------+------------------------------------------------------------+
+| Permission           | Admin Site       | Auth Site                                                  |
++======================+==================+============================================================+
+| auth.access_srp      | None             | Can create an SRP request from a fleet                     |
++----------------------+------------------+------------------------------------------------------------+
+| auth.srp_management  | None             | Can Approve and Deny SRP requests, Can create an SRP Fleet |
++----------------------+------------------+------------------------------------------------------------+
+| srp.add_srpfleetmain | Can Add Model    | Can Create an SRP Fleet                                    |
++----------------------+------------------+------------------------------------------------------------+
+```

docs/features/apps/timerboard.md

@@ -7,3 +7,17 @@ Structure Timers helps you keep track of both offensive and defensive structure
 ## Installation
 
 Add `'allianceauth.timerboard',` to your `INSTALLED_APPS` list in your auth project's settings file. Run migrations to complete installation.
+
+## Permissions
+
+To use and administer this feature, users will require some of the following.
+
+```eval_rst
++---------------------------------------+------------------+--------------------------------------------------------------------------+
+| Permission                            | Admin Site       | Auth Site                                                                |
++=======================================+==================+==========================================================================+
+| auth.timer_view                       | None             | Can view Timerboard Timers                                               |
++---------------------------------------+------------------+--------------------------------------------------------------------------+
+| auth.timer_manage                     | None             | Can Manage Timerboard timers                                             |
++---------------------------------------+------------------+--------------------------------------------------------------------------+
+```

docs/features/core/groupmanagement.md

@@ -38,4 +38,26 @@ Group leaders have the same abilities as users with the `group_management` permi
 - Approve requests for groups they are a leader of.
 - View the Group Membership and Group Members of groups they are leaders of.
 
-This allows you to more finely control who has access to manage which groups. Currently it is not possible to add a Group as group leaders.
+This allows you to more finely control who has access to manage which groups.
+
+## Permissions
+
+Group Management should be mostly done using group leaders, a series of permissions are included below for thoroughness.
+
+```eval_rst
++--------------------------------+-------------------+------------------------------------------------------------------------------------+
+| Permission                     | Admin Site        | Auth Site                                                                          |
++================================+===================+====================================================================================+
+| auth.group_management          | None              | Can Approve and Deny all Group Requests, Can view and manage all group memberships |
++--------------------------------+-------------------+------------------------------------------------------------------------------------+
+| groupmanagement.request_groups | None              | Can Request Non-Public Groups                                                      |
++--------------------------------+-------------------+------------------------------------------------------------------------------------+
+| groupmanagement.add_group      | Can Add Models    | None                                                                               |
++--------------------------------+-------------------+------------------------------------------------------------------------------------+
+| groupmanagement.change_group   | Can Edit Models   | None                                                                               |
++--------------------------------+-------------------+------------------------------------------------------------------------------------+
+| groupmanagement.delete_group   | Can Delete Models | None                                                                               |
++--------------------------------+-------------------+------------------------------------------------------------------------------------+
+| groupmanagement.view_group     | Can View Models   | None                                                                               |
++--------------------------------+-------------------+------------------------------------------------------------------------------------+
+```

docs/features/core/groups.md

@@ -26,7 +26,7 @@ This option still respects the Open option.
 
 ### Open
 
-When a group is toggled open, users who request to join the group will be immediately added to the group. 
+When a group is toggled open, users who request to join the group will be immediately added to the group.
 
 If the group is not open, their request will have to be approved manually by someone with the group management role, or a group leader of that group.
 

docs/features/services/discord.md

@@ -139,6 +139,18 @@ Name                                Description
 =================================== ============================================================================================= =======
 ```
 
+## Permissions
+
+To use this service, users will require some of the following.
+
+```eval_rst
++---------------------------------------+------------------+--------------------------------------------------------------------------+
+| Permission                            | Admin Site       | Auth Site                                                                |
++=======================================+==================+==========================================================================+
+| discord.access_discord                | None             | Can Access the Discord Service                                           |
++---------------------------------------+------------------+--------------------------------------------------------------------------+
+```
+
 ## Troubleshooting
 
 ### "Unknown Error" on Discord site when activating service

docs/features/services/discourse.md

@@ -17,20 +17,26 @@ DISCOURSE_SSO_SECRET = ''
 
 ## Install Docker
 
-    wget -qO- https://get.docker.io/ | sh
+```bash
+wget -qO- https://get.docker.io/ | sh
+```
 
 ## Install Discourse
 
 ### Download Discourse
 
-    mkdir /var/discourse
+```bash
-    git clone https://github.com/discourse/discourse_docker.git /var/discourse
+mkdir /var/discourse
+git clone https://github.com/discourse/discourse_docker.git /var/discourse
+```
 
 ### Configure
 
-    cd /var/discourse
+```bash
-    cp samples/standalone.yml containers/app.yml
+cd /var/discourse
-    nano containers/app.yml
+cp samples/standalone.yml containers/app.yml
+nano containers/app.yml
+```
 
 Change the following:
 
@@ -40,38 +46,50 @@ Change the following:
 
 To install behind Apache/Nginx, look for this section:
 
-    ...
+```ini
-    ## which TCP/IP ports should this container expose?
+...
-    expose:
+## which TCP/IP ports should this container expose?
-      - "80:80"   # fwd host port 80   to container port 80 (http)
+expose:
-    ...
+    - "80:80"   # fwd host port 80   to container port 80 (http)
+...
+```
 
 Change it to this:
 
-    ...
+```ini
-    ## which TCP/IP ports should this container expose?
+...
-    expose:
+## which TCP/IP ports should this container expose?
-      - "7890:80"   # fwd host port 7890   to container port 80 (http)
+expose:
-    ...
+    - "7890:80"   # fwd host port 7890   to container port 80 (http)
+...
+```
 
 Or any other port will do, if taken. Remember this number.
 
 ### Build and launch
 
-    nano /etc/default/docker
+```bash
+nano /etc/default/docker
+```
 
 Uncomment this line:
 
+```ini
     DOCKER_OPTS="--dns 8.8.8.8 --dns 8.8.4.4"
+```
 
 Restart Docker:
 
+```bash
     service docker restart
+```
 
 Now build:
 
+```bash
     ./launcher bootstrap app
     ./launcher start app
+```
 
 ## Web Server Configuration
 
@@ -79,22 +97,26 @@ You will need to configure your web server to proxy requests to Discourse.
 
 A minimal Apache config might look like:
 
-    <VirtualHost *:80>
+```ini
-        ServerName discourse.example.com
+<VirtualHost *:80>
-        ProxyPass / http://0.0.0.0:7890/
+    ServerName discourse.example.com
-        ProxyPassReverse / http://0.0.0.0:7890/
+    ProxyPass / http://0.0.0.0:7890/
-    </VirtualHost>
+    ProxyPassReverse / http://0.0.0.0:7890/
+</VirtualHost>
+```
 
 A minimal Nginx config might look like:
 
-    server {
+```ini
-        listen 80;
+server {
-        server_name discourse.example.com;
+    listen 80;
-        location / {
+    server_name discourse.example.com;
-            include proxy_params;
+    location / {
-            proxy_pass http://127.0.0.1:7890;
+        include proxy_params;
-        }
+        proxy_pass http://127.0.0.1:7890;
     }
+}
+```
 
 ## Configure API
 
@@ -102,8 +124,10 @@ A minimal Nginx config might look like:
 
 From the `/var/discourse` directory,
 
-    ./launcher enter app
+```bash
-    rake admin:create
+./launcher enter app
+rake admin:create
+```
 
 Follow prompts, being sure to answer `y` when asked to allow admin privileges.
 
@@ -128,3 +152,15 @@ Navigate to `discourse.example.com` and log in. Back to the admin site, scroll d
 Save, now set `DISCOURSE_SSO_SECRET` in your auth project's settings file to the secure key you just put in Discourse.
 
 Finally run migrations and restart Gunicorn and Celery.
+
+## Permissions
+
+To use this service, users will require some of the following.
+
+```eval_rst
++---------------------------------------+------------------+--------------------------------------------------------------------------+
+| Permission                            | Admin Site       | Auth Site                                                                |
++=======================================+==================+==========================================================================+
+| discourse.access_discourse            | None             | Can Access the Discourse Service                                         |
++---------------------------------------+------------------+--------------------------------------------------------------------------+
+```

docs/features/services/mumble.md

@@ -200,13 +200,16 @@ python /home/allianceserver/myauth/manage.py migrate
 supervisorctl restart myauth:
 ```
 
-## Permissions on Auth
+## Permissions
 
-To enable the mumble service for users on Auth you need to give them the `access_mumble` permission. This permission is often added to the `Member` state.
+To use this service, users will require some of the following.
 
 ```eval_rst
-.. note::
++---------------------------------------+------------------+--------------------------------------------------------------------------+
-   Note that groups will only be created on Mumble automatically when a user joins who is in the group.
+| Permission                            | Admin Site       | Auth Site                                                                |
++=======================================+==================+==========================================================================+
+| mumble.access_mumble                  | None             | Can Access the Mumble Service                                            |
++---------------------------------------+------------------+--------------------------------------------------------------------------+
 ```
 
 ## ACL configuration
@@ -296,4 +299,4 @@ Edit `authenticator.ini` and change (or add for older installs) This code block.
 avatar_enable = True
 ;Get EvE avatar images from this location. {charid} will be filled in.
 ccp_avatar_url = https://images.evetech.net/characters/{charid}/portrait?size=32
-```
+```

docs/features/services/openfire.md

@@ -20,18 +20,25 @@ BROADCAST_SERVICE_NAME = "broadcast"
 ```
 
 ## Dependencies
+
 Openfire require a Java 8 runtime environment.
 
 Ubuntu:
 
-    apt-get install openjdk-8-jdk
+```bash
+apt-get install openjdk-8-jdk
+```
 
 CentOS:
 
-    yum -y install java-1.8.0-openjdk java-1.8.0-openjdk-devel
+```bash
+yum -y install java-1.8.0-openjdk java-1.8.0-openjdk-devel
+```
 
 ## Setup
+
 ### Download Installer
+
 Openfire is not available through repositories so we need to get a package from the developer.
 
 On your PC, navigate to the [Ignite Realtime downloads section](https://www.igniterealtime.org/downloads/index.jsp), and under Openfire select Linux, click on the Ubuntu: Debian package (second from bottom of list, ends with .deb) or CentOS: RPM Package (no JRE bundled, as we have installed it on the host)
@@ -42,27 +49,31 @@ In the console, ensure you’re in your user’s home directory: `cd ~`
 
 Now download the package. Replace the link below with the link you got earlier.
 
-    wget https://www.igniterealtime.org/downloadServlet?filename=openfire/openfire_4.2.3_all.deb
+`wget https://www.igniterealtime.org/downloadServlet?filename=openfire/openfire_4.2.3_all.deb`
 
 Now install from the package. Replace the filename with your filename (the last part of the download URL is the file name)
 
 Ubuntu:
 
-    dpkg -i openfire_4.2.3_all.deb
+`dpkg -i openfire_4.2.3_all.deb`
 
 CentOS:
 
-    yum install -y openfire-4.2.3-1.noarch.rpm
+`yum install -y openfire-4.2.3-1.noarch.rpm`
 
 ### Create Database
+
 Performance is best when working from a SQL database. If you installed MySQL or MariaDB alongside your auth project, go ahead and create a database for Openfire:
 
-    mysql -u root -p
+```bash
-    create database alliance_jabber;
+mysql -u root -p
-    grant all privileges on alliance_jabber . * to 'allianceserver'@'localhost';
+create database alliance_jabber;
-    exit;
+grant all privileges on alliance_jabber . * to 'allianceserver'@'localhost';
+exit;
+```
 
 ### Web Configuration
+
 The remainder of the setup occurs through Openfire’s web interface. Navigate to http://example.com:9090, or if you’re behind CloudFlare, go straight to your server’s IP:9090.
 
 Select your language. I sure hope it’s English if you’re reading this guide.
@@ -72,9 +83,10 @@ Under Server Settings, set the Domain to `example.com` replacing it with your ac
 Under Database Settings, select `Standard Database Connection`
 
 On the next page, select `MySQL` from the dropdown list and change the following:
- - `[server]` is replaced by `127.0.0.1`
+
- - `[database]` is replaced by the name of the database to be used by Openfire
+- `[server]` is replaced by `127.0.0.1`
- - enter the login details for your auth project's database user
+- `[database]` is replaced by the name of the database to be used by Openfire
+- enter the login details for your auth project's database user
 
 If Openfire returns with a failed to connect error, re-check these settings. Note the lack of square brackets.
 
@@ -85,12 +97,14 @@ Create an administrator account. The actual name is irrelevant, just don’t los
 Finally, log in to the console with your admin account.
 
 Edit your auth project's settings file and enter the values you just set:
- - `JABBER_URL` is the pubic address of your jabber server
+
- - `JABBER_PORT` is the port for clients to connect to (usually 5223)
+- `JABBER_URL` is the pubic address of your jabber server
- - `JABBER_SERVER` is the name of the jabber server. If you didn't alter it during install it'll usually be your domain (eg `example.com`)
+- `JABBER_PORT` is the port for clients to connect to (usually 5223)
- - `OPENFIRE_ADDRESS` is the web address of Openfire's web interface. Use http:// with port 9090 or https:// with port 9091 if you configure SSL in Openfire
+- `JABBER_SERVER` is the name of the jabber server. If you didn't alter it during install it'll usually be your domain (eg `example.com`)
+- `OPENFIRE_ADDRESS` is the web address of Openfire's web interface. Use http:// with port 9090 or https:// with port 9091 if you configure SSL in Openfire
 
 ### REST API Setup
+
 Navigate to the `plugins` tab, and then `Available Plugins` on the left navigation bar. You’ll need to fetch the list of available plugins by clicking the link.
 
 Once loaded, press the green plus on the right for `REST API`.
@@ -109,12 +123,12 @@ Broadcasting requires a plugin. Navigate to the `plugins` tab, press the green p
 
 Navigate to the `Server` tab, `Server Manager` subtab, and select `System Properties`. Enter the following:
 
- - Name: `plugin.broadcast.disableGroupPermissions`
+- Name: `plugin.broadcast.disableGroupPermissions`
-   - Value: `True`
+  - Value: `True`
-   - Do not encrypt this property value
+  - Do not encrypt this property value
- - Name: `plugin.broadcast.allowedUsers`
+- Name: `plugin.broadcast.allowedUsers`
-   - Value: `broadcast@example.com`, replacing the domain name with yours
+  - Value: `broadcast@example.com`, replacing the domain name with yours
-   - Do not encrypt this property value
+  - Do not encrypt this property value
 
 If you have troubles getting broadcasts to work, you can try setting the optional (you will need to add it) `BROADCAST_IGNORE_INVALID_CERT` setting to `True`. This will allow invalid certificates to be used when connecting to the Openfire server to send a broadcast.
 
@@ -123,15 +137,29 @@ If you have troubles getting broadcasts to work, you can try setting the optiona
 Once all settings are entered, run migrations and restart Gunicorn and Celery.
 
 ### Group Chat
+
 Channels are available which function like a chat room. Access can be controlled either by password or ACL (not unlike mumble).
 
 Navigate to the `Group Chat` tab and select `Create New Room` from the left navigation bar.
- - Room ID is a short, easy-to-type version of the room’s name users will connect to
+
- - Room Name is the full name for the room
+- Room ID is a short, easy-to-type version of the room’s name users will connect to
- - Description is short text describing the room’s purpose
+- Room Name is the full name for the room
- - Set a password if you want password authentication
+- Description is short text describing the room’s purpose
- - Every other setting is optional. Save changes.
+- Set a password if you want password authentication
+- Every other setting is optional. Save changes.
 
 Now select your new room. On the left navigation bar, select `Permissions`.
 
 ACL is achieved by assigning groups to each of the three tiers: `Owners`, `Admins` and `Members`. `Outcast` is the blacklist. You’ll usually only be assigning groups to the `Member` category.
+
+## Permissions
+
+To use this service, users will require some of the following.
+
+```eval_rst
++---------------------------------------+------------------+--------------------------------------------------------------------------+
+| Permission                            | Admin Site       | Auth Site                                                                |
++=======================================+==================+==========================================================================+
+| openfire.access_openfire              | None             | Can Access the Openfire Service                                          |
++---------------------------------------+------------------+--------------------------------------------------------------------------+
+```

docs/features/services/phpbb3.md

@@ -1,15 +1,19 @@
 # phpBB3
 
 ## Overview
+
 phpBB is a free PHP-based forum.
 
 ## Dependencies
+
 phpBB3 requires PHP installed in your web server. Apache has `mod_php`, NGINX requires `php-fpm`. See [the official guide](https://www.phpbb.com/community/docs/INSTALL.html) for PHP package requirements.
 
 ## Prepare Your Settings
+
 In your auth project's settings file, do the following:
- - Add `'allianceauth.services.modules.phpbb3',` to your `INSTALLED_APPS` list
+
- - Append the following to the bottom of the settings file:
+- Add `'allianceauth.services.modules.phpbb3',` to your `INSTALLED_APPS` list
+- Append the following to the bottom of the settings file:
 
 ```python
 # PHPBB3 Configuration
@@ -25,32 +29,43 @@ DATABASES['phpbb3'] = {
 ```
 
 ## Setup
+
 ### Prepare the Database
+
 Create a database to install phpBB3 in.
 
-    mysql -u root -p
+```bash
-    create database alliance_forum;
+mysql -u root -p
-    grant all privileges on alliance_forum . * to 'allianceserver'@'localhost';
+create database alliance_forum;
-    exit;
+grant all privileges on alliance_forum . * to 'allianceserver'@'localhost';
+exit;
+```
 
 Edit your auth project's settings file and fill out the `DATABASES['phpbb3']` part.
 
 ### Download phpBB3
+
 phpBB3 is available as a zip from their website. Navigate to the website’s [downloads section](https://www.phpbb.com/downloads/) using your PC browser and copy the URL for the latest version zip.
 
 In the console, navigate to your user’s home directory: `cd ~`
 
 Now download using wget, replacing the URL with the URL for the package you just retrieved
 
-    wget https://www.phpbb.com/files/release/phpBB-3.2.2.zip
+```bash
+wget https://www.phpbb.com/files/release/phpBB-3.2.2.zip
+```
 
 This needs to be unpackaged. Unzip it, replacing the file name with that of the file you just downloaded
 
-    unzip phpBB-3.2.2.zip
+```bash
+unzip phpBB-3.2.2.zip
+```
 
 Now we need to move this to our web directory. Usually `/var/www/forums`.
 
-    mv phpBB3 /var/www/forums
+```bash
+mv phpBB3 /var/www/forums
+```
 
 The web server needs read/write permission to this folder
 
@@ -64,49 +79,55 @@ Nginx: `chown -R nginx:nginx /var/www/forums`
 ```
 
 ### Configuring Web Server
+
 You will need to configure you web server to serve PHPBB3 before proceeding with installation.
 
 A minimal Apache config file might look like:
 
-    <VirtualHost *:80>
+```ini
-        ServerName forums.example.com
+<VirtualHost *:80>
-        DocumentRoot /var/www/forums
+    ServerName forums.example.com
-        <Directory /var/www/forums>
+    DocumentRoot /var/www/forums
-            Require all granted
+    <Directory /var/www/forums>
-            DirectoryIndex index.php
+        Require all granted
-        </Directory>
+        DirectoryIndex index.php
-    </VirtualHost>
+    </Directory>
+</VirtualHost>
+```
 
 A minimal Nginx config file might look like:
 
-    server {
+```ini
-        listen 80;
+server {
-        server_name  forums.example.com;
+    listen 80;
-        root   /var/www/forums;
+    server_name  forums.example.com;
-        index  index.php;
+    root   /var/www/forums;
-        access_log  /var/logs/forums.access.log;
+    index  index.php;
+    access_log  /var/logs/forums.access.log;
 
-        location ~ /(config\.php|common\.php|cache|files|images/avatars/upload|includes|store) {
+    location ~ /(config\.php|common\.php|cache|files|images/avatars/upload|includes|store) {
-            deny all;
+        deny all;
-            return 403;
+        return 403;
-        }
-
-        location ~* \.(gif|jpe?g|png|css)$ {
-            expires   30d;
-        }
-
-        location ~ \.php$ {
-            try_files $uri =404;
-            fastcgi_pass   unix:/tmp/php.socket;
-            fastcgi_index  index.php;
-            fastcgi_param  SCRIPT_FILENAME  $document_root$fastcgi_script_name;
-            include fastcgi_params;
-        }
     }
 
+    location ~* \.(gif|jpe?g|png|css)$ {
+        expires   30d;
+    }
+
+    location ~ \.php$ {
+        try_files $uri =404;
+        fastcgi_pass   unix:/tmp/php.socket;
+        fastcgi_index  index.php;
+        fastcgi_param  SCRIPT_FILENAME  $document_root$fastcgi_script_name;
+        include fastcgi_params;
+    }
+}
+```
+
 Enter your forum's web address as the `PHPBB3_URL` setting in your auth project's settings file.
 
 ### Web Install
+
 Navigate to your forums web address where you will be presented with an installer.
 
 Click on the `Install` tab.
@@ -114,12 +135,13 @@ Click on the `Install` tab.
 All the requirements should be met. Press `Start Install`.
 
 Under Database Settings, set the following:
- - Database Type is `MySQL`
+
- - Database Server Hostname is `127.0.0.1`
+- Database Type is `MySQL`
- - Database Server Port is left blank
+- Database Server Hostname is `127.0.0.1`
- - Database Name is `alliance_forum`
+- Database Server Port is left blank
- - Database Username is your auth MySQL user, usually `allianceserver`
+- Database Name is `alliance_forum`
- - Database Password is this user’s password
+- Database Username is your auth MySQL user, usually `allianceserver`
+- Database Password is this user’s password
 
 If you use a table prefix other than the standard `phpbb_` you need to add an additional setting to your auth project's settings file, `PHPBB3_TABLE_PREFIX = ''`, and enter the prefix.
 
@@ -132,9 +154,12 @@ Everything from here should be intuitive.
 phpBB will then write its own config file.
 
 ### Open the Forums
+
 Before users can see the forums, we need to remove the install directory
 
-    rm -rf /var/www/forums/install
+```bash
+rm -rf /var/www/forums/install
+```
 
 ### Enabling Avatars
 
@@ -146,11 +171,26 @@ You can allow members to overwrite the portrait with a custom image if desired.
 
 Users generated via Alliance Auth do not have a default theme set. You will need to set this on the phpbb_users table in SQL
 
-    mysql -u root -p
+```bash
-    use alliance_forum;
+mysql -u root -p
-    alter table phpbb_users change user_style user_style int not null default 1
+use alliance_forum;
+alter table phpbb_users change user_style user_style int not null default 1
+```
 
 If you would like to use a theme that is NOT prosilver or theme "1". You will need to deactivate prosilver, this will then fall over to the set forum wide default.
 
 ### Prepare Auth
+
 Once settings have been configured, run migrations and restart Gunicorn and Celery.
+
+## Permissions
+
+To use this service, users will require some of the following.
+
+```eval_rst
++---------------------------------------+------------------+--------------------------------------------------------------------------+
+| Permission                            | Admin Site       | Auth Site                                                                |
++=======================================+==================+==========================================================================+
+| phpbb3.access_phpbb3                  | None             | Can Access the PHPBB3 Service                                            |
++---------------------------------------+------------------+--------------------------------------------------------------------------+
+```

docs/features/services/smf.md

@@ -1,12 +1,15 @@
 # SMF
 
 ## Overview
+
 SMF is a free PHP-based forum.
 
 ## Dependencies
+
 SMF requires PHP installed in your web server. Apache has `mod_php`, NGINX requires `php-fpm`. More details can be found in the [SMF requirements page.](https://download.simplemachines.org/requirements.php)
 
 ## Prepare Your Settings
+
 In your auth project's settings file, do the following:
  - Add `'allianceauth.services.modules.smf',` to your `INSTALLED_APPS` list
  - Append the following to the bottom of the settings file:
@@ -25,7 +28,9 @@ DATABASES['smf'] = {
 ```
 
 ## Setup
+
 ### Download SMF
+
 Using your browser, you can download the latest version of SMF to your desktop computer. All SMF downloads can be found at SMF Downloads. The latest recommended version will always be available at http://www.simplemachines.org/download/index.php/latest/install/. Retrieve the file location from the hyperlinked box icon for the zip full install,  depending on your browser you may have a Copy Link or similar option in your right click menu.
 
 
@@ -53,6 +58,7 @@ Nginx: `chown -R nginx:nginx /var/www/forums`
 ```
 
 ### Database Preparation
+
 SMF needs a database. Create one:
 
     mysql -u root -p
@@ -63,6 +69,7 @@ SMF needs a database. Create one:
 Enter the database information into the `DATABASES['smf']` section of your auth project's settings file.
 
 ### Web Server Configuration
+
 Your web server needs to be configured to serve SMF.
 
 A minimal Apache config might look like:
@@ -96,6 +103,7 @@ A minimal Nginx config might look like:
 Enter the web address to your forums into the `SMF_URL` setting in your auth project's settings file.
 
 ### Web Install
+
 Navigate to your forums address where you will be presented with an installer.
 
 Click on the `Install` tab.
@@ -103,16 +111,29 @@ Click on the `Install` tab.
 All the requirements should be met. Press `Start Install`.
 
 Under Database Settings, set the following:
- - Database Type is `MySQL`
+- Database Type is `MySQL`
- - Database Server Hostname is `127.0.0.1`
+- Database Server Hostname is `127.0.0.1`
- - Database Server Port is left blank
+- Database Server Port is left blank
- - Database Name is `alliance_smf`
+- Database Name is `alliance_smf`
- - Database Username is your auth MySQL user, usually `allianceserver`
+- Database Username is your auth MySQL user, usually `allianceserver`
- - Database Password is this user’s password
+- Database Password is this user’s password
 
 If you use a table prefix other than the standard `smf_` you need to add an additional setting to your auth project's settings file, `SMF_TABLE_PREFIX = ''`, and enter the prefix.
 
 Follow the directions in the installer.
 
 ### Preparing Auth
+
 Once settings are entered, apply migrations and restart Gunicorn and Celery.
+
+## Permissions
+
+To use this service, users will require some of the following.
+
+```eval_rst
++---------------------------------------+------------------+--------------------------------------------------------------------------+
+| Permission                            | Admin Site       | Auth Site                                                                |
++=======================================+==================+==========================================================================+
+| smf.access_smf                        | None             | Can Access the SMF Service                                               |
++---------------------------------------+------------------+--------------------------------------------------------------------------+
+```

docs/features/services/teamspeak3.md

@@ -1,17 +1,21 @@
 # TeamSpeak 3
 
 ## Overview
+
 TeamSpeak3 is the most popular VOIP program for gamers.
 
 But have you considered using Mumble? Not only is it free, but it has features and performance far superior to Teamspeak3.
 
 ## Setup
+
 Sticking with TS3? Alright, I tried.
 
 ### Prepare Your Settings
+
 In your auth project's settings file, do the following:
- - Add `'allianceauth.services.modules.teamspeak3',` to your `INSTALLED_APPS` list
+
- - Append the following to the bottom of the settings file:
+- Add `'allianceauth.services.modules.teamspeak3',` to your `INSTALLED_APPS` list
+- Append the following to the bottom of the settings file:
 
 ```python
 # Teamspeak3 Configuration
@@ -29,51 +33,70 @@ CELERYBEAT_SCHEDULE['run_ts3_group_update'] = {
 ```
 
 ### Download Installer
+
 To install we need a copy of the server. You can find the latest version from [this dl server](http://dl.4players.de/ts/releases/) (I’d recommend getting the latest stable version – find this version number from the [TeamSpeak site](https://www.teamspeak.com/downloads#)). Be sure to get a link to the Linux version.
 
 Download the server, replacing the link with the link you got earlier.
 
-    http://dl.4players.de/ts/releases/3.1.1/teamspeak3-server_linux_amd64-3.1.1.tar.bz2
+```url
+http://dl.4players.de/ts/releases/3.13.2/teamspeak3-server_linux_amd64-3.13.2.tar.bz2
+```
 
 Now we need to extract the file.
 
+```bash
     tar -xf teamspeak3-server_linux_amd64-3.1.0.tar.bz2
+```
 
 ### Create User
+
 TeamSpeak needs its own user.
 
-    adduser --disabled-login teamspeak
+```bash
+adduser --disabled-login teamspeak
+```
 
 ### Install Binary
+
 Now we move the server binary somewhere more accessible and change its ownership to the new user.
 
-    mv teamspeak3-server_linux_amd64 /usr/local/teamspeak
+```bash
-    chown -R teamspeak:teamspeak /usr/local/teamspeak
+mv teamspeak3-server_linux_amd64 /usr/local/teamspeak
+chown -R teamspeak:teamspeak /usr/local/teamspeak
+```
 
 ### Startup
+
 Now we generate a startup script so TeamSpeak comes up with the server.
 
-    ln -s /usr/local/teamspeak/ts3server_startscript.sh /etc/init.d/teamspeak
+```bash
-    update-rc.d teamspeak defaults
+ln -s /usr/local/teamspeak/ts3server_startscript.sh /etc/init.d/teamspeak
+update-rc.d teamspeak defaults
+```
 
 Finally we start the server.
 
-    service teamspeak start
+```bash
+service teamspeak start
+```
 
 ### Update Settings
+
 The console will spit out a block of text. If it does not appear, it can be found with `service teamspeak status`. **SAVE THIS**.
 
 If you plan on claiming the ServerAdmin token, do so with a different TeamSpeak client profile than the one used for your auth account, or you will lose your admin status.
 
 Edit the settings you added to your auth project's settings file earlier, entering the following:
- - `TEAMSPEAK3_SERVERQUERY_USER` is `loginname` from that block of text it just spat out (usually `serveradmin`)
+
- - `TEAMSPEAK3_SERVERQUERY_PASSWORD` is `password` from that block of text it just spat out
+- `TEAMSPEAK3_SERVERQUERY_USER` is `loginname` from that block of text it just spat out (usually `serveradmin`)
- - `TEAMSPEAK_VIRTUAL_SERVER` is the virtual server ID of the server to be managed - it will only ever not be 1 if your server is hosted by a professional company
+- `TEAMSPEAK3_SERVERQUERY_PASSWORD` is `password` from that block of text it just spat out
- - `TEAMSPEAK3_PUBLIC_URL` is the public address of your TeamSpeak server. Do not include any leading http:// or teamspeak://
+- `TEAMSPEAK_VIRTUAL_SERVER` is the virtual server ID of the server to be managed - it will only ever not be 1 if your server is hosted by a professional company
+- `TEAMSPEAK3_PUBLIC_URL` is the public address of your TeamSpeak server. Do not include any leading http:// or teamspeak://
 
 Once settings are entered, run migrations and restart Gunicorn and Celery.
 
 ### Generate User Account
+
 And now we can generate ourselves a user account. Navigate to the services in Alliance Auth for your user account and press the checkmark for TeamSpeak 3.
 
 Click the URL provided to automatically connect to our server. It will prompt you to redeem the serveradmin token, enter the `token` from startup.
@@ -95,14 +118,19 @@ Using the advanced permissions editor, ensure the `Guest` group has the permissi
 To enable advanced permissions, on your client go to the `Tools` menu, `Application`, and under the `Misc` section, tick `Advanced permission system`
 
 ### TS group models not populating on admin site
+
 The method which populates these runs every 30 minutes. To populate manually, start a django shell:
 
-    python manage.py shell
+```bash
+python manage.py shell
+```
 
 And execute the update:
 
-    from allianceauth.services.modules.teamspeak3.tasks import Teamspeak3Tasks
+```python
-    Teamspeak3Tasks.run_ts3_group_update()
+from allianceauth.services.modules.teamspeak3.tasks import Teamspeak3Tasks
+Teamspeak3Tasks.run_ts3_group_update()
+```
 
 Ensure that command does not return an error.
 
@@ -129,3 +157,23 @@ The serverquery account login specified in local.py is incorrect. Please verify
 ### `2568 insufficient client permissions`
 
 This usually occurs if you've created a separate serverquery user to use with auth. It has not been assigned sufficient permissions to complete all the tasks required of it. The full list of required permissions is not known, so assign liberally.
+
+## Permissions
+
+To use and configure this service, users will require some of the following.
+
+```eval_rst
++---------------------------------------+------------------+--------------------------------------------------------------------------+
+| Permission                            | Admin Site       | Auth Site                                                                |
++=======================================+==================+==========================================================================+
+| teamspeak.access_teamspeak            | None             | Can Access the Discord Service                                           |
++---------------------------------------+------------------+--------------------------------------------------------------------------+
+| teamspeak.add_authts                  | Can Add Model    | None                                                                     |
++---------------------------------------+------------------+--------------------------------------------------------------------------+
+| teamspeak.change_authts               | Can Change Model | None                                                                     |
++---------------------------------------+------------------+--------------------------------------------------------------------------+
+| teamspeak.delete_authts               | Can Delete Model | None                                                                     |
++---------------------------------------+------------------+--------------------------------------------------------------------------+
+| teamspeak.view_authts                 | Can View Model   | None                                                                     |
++---------------------------------------+------------------+--------------------------------------------------------------------------+
+```

docs/features/services/xenforo.md

@@ -1,12 +1,15 @@
 # XenForo
 
 ## Overview
+
 [XenForo](https://xenforo.com/) is a popular paid forum. This guide will assume that you already have XenForo installed with a valid license (please keep in mind that XenForo is not free nor open-source, therefore you need to purchase a license first). If you come across any problems related with the installation of XenForo please contact their support service.
 
 ## Prepare Your Settings
+
 In your auth project's settings file, do the following:
- - Add `'allianceauth.services.modules.xenforo',` to your `INSTALLED_APPS` list
+
- - Append the following to your local.py settings file:
+- Add `'allianceauth.services.modules.xenforo',` to your `INSTALLED_APPS` list
+- Append the following to your local.py settings file:
 
 ```python
 # XenForo Configuration
@@ -39,3 +42,15 @@ The settings you created earlier now need to be filled out.
 `XENFORO_API_KEY` is the API key value you set earlier.
 
 Once these are entered, run migrations and restart Gunicorn and Celery.
+
+## Permissions
+
+To use this service, users will require some of the following.
+
+```eval_rst
++---------------------------------------+------------------+--------------------------------------------------------------------------+
+| Permission                            | Admin Site       | Auth Site                                                                |
++=======================================+==================+==========================================================================+
+| xenforo.access_xenforo                | None             | Can Access the XenForo Service                                           |
++---------------------------------------+------------------+--------------------------------------------------------------------------+
+```