Skip to main content

Setting up Adminbot and Auditbot

Overview

Starting with Installer version 2022.07-03, we have enabled the configuration of our Adminbot and Auditbot products, which are available as add-ons to our Enterprise customers.

Adminbot allows for an Element Administrator to become admin in any existing room or space on a managed homeserver. This enables you to delete rooms for which the room administrator has left your company and other useful administration actions.

Auditbot allows you to have the ability to export any communications in any room that the auditbot is a member of, even if encryption is in use. This is important in enabling you to handle compliance requirements that require chat histories be obtainable.

This document details how to configure the Adminbot and Auditbot themselves, but you will also need to install and configure our Enterprise Admin Dashboard so that an Element Administrator can log in and then log in as the Adminbot or Auditbot and perform specific functions.

Configuring Admin Bot

Start by copying config-sample/adminbot/adminbot.yml into your configuration directory, by running these commands from your installer directory:

mkdir ~/.element-onpremise-config/adminbot
cp config-sample/adminbot/adminbot.yml ~/.element-onpremise-config/adminbot/

The above assumes that ~/.element-onpremise-config is your configuration directory. Change it as necessary.

The config starts with these items:

bot_backup_phrase: # your secret storage backup phrase
bot_data_path: /mnt/data/adminbot
bot_data_size: 10M

enable_dm_admin: false

Let's discuss them:

  • bot_backup_phrase: This is the security phrase that will guard access to your encryption keys. Do NOT share this phrase with anyone. This is required.
  • bot_data_path: This is the directory where the bot's data will be stored. If you need to change the path, please do, but for most cases, you can leave this alone.
  • bot_data_size: In most cases, you can leave this at 10M, but it does put a limit on the amount of data that can be written by the bot to the path.
  • enable_dm_admin: This defaults to false and that behavior means that adminbot will not join DMs. If you want full control of DMs, simply set this to true.

Once this configuration is in place, you can re-run the installer and watch adminbot come up and then start joining rooms on your server. You may also choose to continue configuring audit bot and then the Enterprise Admin Dashboard prior to re-running the installer.

Configuring Audit Bot

Start by copying config-sample/auditbot/auditbot.yml into your configuration directory, by running these commands from your installer directory:

mkdir ~/.element-onpremise-config/auditbot
cp config-sample/auditbot/auditbot.yml ~/.element-onpremise-config/auditbot/

The above assumes that ~/.element-onpremise-config is your configuration directory. Change it as necessary.

The config starts with these items:

bot_backup_phrase: # your secret storage backup phrase
bot_data_path: /mnt/data/auditbot
bot_data_size: 10M

enable_dm_audit: false

### optional :the S3 bucket where to store the audit logs
#s3_bucket:
#s3_access_key_id:
#s3_secret_access_key:
#s3_key_prefix:
#s3_region:
#s3_endpoint:

### optional : the local logfile settings. Used if s3 bucket is not enabled.
logfile_size: 1M
logfile_keep: 3

Let's discuss them:

  • bot_backup_phrase: This is the security phrase that will guard access to your encryption keys. Do NOT share this phrase with anyone. This is required.
  • bot_data_path: This is the directory where the bot's data will be stored. If you need to change the path, please do, but for most cases, you can leave this alone.
  • bot_data_size: In most cases, you can leave this at 10M, but it does put a limit on the amount of data that can be written by the bot to the path.
  • enable_dm_admin: This defaults to false and that behavior means that adminbot will not join DMs. If you want full control of DMs, simply set this to true.

Once this configuration is in place, you can re-run the installer and watch auditbot come up and then start joining rooms on your server. You may also choose to continue configuring the Enterprise Admin Dashboard prior to re-running the installer.

Adminbot Federation

On the central admin bot server

  • Copy sample file from config-sample/adminbot/central.yml to the adminbot sub-directory within your config folder
  • adminbot_fqdn : The FQDN which will be targeted by remote federated servers as the central audit server
  • remote_federated_homeservers: A list containing every remote audited server. It contains the following variables :
    • matrix_server: URL of the synapse server
    • domain_name: Domain name from parameters.yaml (the server name part of the users mxid)
    • If the server is managed by the installer :
      • generic_shared_secret: The generic shared secret to get from secrets.yaml
      • adminuser_token: The token from the admin user, to get via kubectl get synapseusers/adminuser-donotdelete -n element-onprem -o yaml. It's the value of the field status.accessToken.
    • If the server is not managed by the installer :
    • as_token : The as token configured on the remote appservice file on the remote server.
    • hs_token : The as token configured on the remote appservice file on the remote server.
    • adminuser_token : An access token to an user which is server admin.

On the remote admin bot server

  • Copy sample file from config-sample/adminbot_access/access.yml :
  • Configure the following variables :
    • central_adminbot_fqdn : The value of adminbot_fqdn on the central audit bot server

Auditbot Federation

On the central auditbot server

  • Copy sample file from config-sample/auditbot/central.yml to the auditbot sub-directory within your config folder
  • auditbot_fqdn : The FQDN which will be targeted by remote federated servers as the central audit server
  • remote_federated_homeservers: A list containing every remote audited server. It contains the following variables :
    • matrix_server: URL of the synapse server
    • domain_name: Domain name from parameters.yaml (the server name part of the users mxid)
    • If the server is managed by the installer :
      • generic_shared_secret: The generic shared secret to get from secrets.yaml
      • adminuser_token: The token from the admin user, to get via kubectl get synapseusers/adminuser-donotdelete -n element-onprem -o yaml. It's the value of the field status.accessToken.
    • If the server is not managed by the installer :
    • as_token : The as token configured on the remote appservice file on the remote server.
    • hs_token : The as token configured on the remote appservice file on the remote server.
    • adminuser_token : An access token to an user which is server admin.

On the remote audit bot server

  • Copy sample file from config-sample/auditbot_access/access.yml :
  • Configure the following variables :
    • central_auditbot_fqdn : The value of auditbot_fqdn on the central audit bot server

Enterprise Admin Dashboard

Please see this document on Configuring the Enterprise Admin Dashboard

Back to top