Skip to main content

Setting up Adminbot and Auditbot

Overview

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.

On using Admin Bot and Audit Bot

Currently, we deploy a special version of Element Web to allow you to log in as the adminbot and auditbot. Given this, please do not make changes to widgets in rooms while logged in as the adminbot or the auditbot. The special Element Web does not have any custom settings that you have applied to the main Element Web that your users use and as such, you can cause problems for yourself by working with widgets as the adminbot and auditbot. In the future, we are working to provide custom interfaces for these bots.

Configuring Admin Bot

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

For the adminbot.yml presented by the installer, edit the file and ensure the following values are set:

bot_backup_phrase: adminsecret
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. If you are deploying to Kubernetes, you need to comment this out!
  • 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.

Configuring Audit Bot

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

For the auditbot.yml presented by the installer, edit the file and ensure the following values are set:

bot_backup_phrase: auditsecret
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. If you are deploying to Kubernetes, you need to comment this out!
  • 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.

Adminbot Federation

On the central admin bot server

Complete the values for the provided central.yml 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 the access.yml file in the installer interface 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

Complete the values for the provided central.yml 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 the access.yml file in the installer interface by providing the fqdn of the central audit bot server.

  • central_auditbot_fqdn : The value of auditbot_fqdn on the central audit bot server
Back to top