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

StartFrom the Installer's Integrations page, click "Install" under "Admin Bot"

For the adminbot.yml presented by copyingthe config-sample/adminbot/adminbot.ymlinstaller, intoedit yourthe configurationfile directory,and byensure runningthe thesefollowing commandsvalues fromare 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:set:

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

enable_dm_admin: false

join_local_rooms_only: true
access_elementweb_fqdn: adminbot.airgap.local

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.
  • join_local_rooms_only: This defaults to true and that behavior means that adminbot will only join rooms on your local homeserver.
  • access_elementweb_fqdn: You should set this to a hostname that is resolvable in your environment which will host a special instance of Element Web for logging in. This hostname will need a crt/key PEM encoded key pair and these files will need to be stored in ~/.element-enterprise-server/config/legacy/certs prior to running the installer. In the above example, we have the hostname of adminbot.airgap.local. This means that the installer expects to find adminbot.airgap.local.crt and adminbot.airgap.local.key in the ~/.element-enterprise-server/config/legacy/certs` directory. If you are using Let's Encrypt, you do not need to add these files.
  • verify_tls : Optional. If doing a POC with self-signed certificates, set this to 0. Defaults to 1.

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

StartFrom the Installer's Integrations page, click "Install" under "Audit Bot"

For the auditbot.yml presented by copyingthe config-sample/auditbot/auditbot.ymlinstaller, intoedit yourthe configurationfile directory,and byensure runningthe thesefollowing commandsvalues fromare 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:set:

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

join_local_rooms_only: true
enable_dm_audit: false
access_elementweb_fqdn: auditbot.airgap.local

### 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.
  • join_local_rooms_only: This defaults to true and that behavior means that adminbot will only join rooms on your local homeserver.
  • 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.
  • access_elementweb_fqdn: You should set this to a hostname that is resolvable in your environment which will host a special instance of Element Web for logging in. This hostname will need a crt/key PEM encoded key pair and these files will need to be stored in ~/.element-enterprise-server/config/legacy/certs prior to running the installer. In the above example, we have the hostname of auditbot.airgap.local. This means that the installer expects to find auditbot.airgap.local.crt and auditbot.airgap.local.key in the ~/.element-enterprise-server/config/legacy/certs` directory. If you are using Let's Encrypt, you do not need to add these files.
  • verify_tls : Optional. If doing a POC with self-signed certificates, set this to 0. Defaults to 1.

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

    Complete the adminbotvalues sub-directoryfor withinthe yourprovided configcentral.yml folder

    • in the installer interface. Here is an explanation of the parameters:

    • 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

      Complete

    • Copythe sampleaccess.yml file from config-sample/adminbot_access/access.yml :
    • Configurein the followinginstaller variablesinterface :by providing the fqdn of the central admin bot server.

      • 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

      Complete the auditbotvalues sub-directoryfor withinthe yourprovided configcentral.yml folder

      • in the installer interface. Here is an explanation of the parameters:

      • 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

        Complete

      • Copythe sampleaccess.yml file from config-sample/auditbot_access/access.yml :
      • Configurein the followinginstaller variablesinterface :by providing the fqdn of the central audit bot server.

        • 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