Setting up the external database

  • Last updated: October 6, 2021

  • Read time: 5 Minutes

In this section, we'll show you how to set up a database that you want to connect to Burp Suite Enterprise Edition. This is relevant in the following cases:

  • You have been using Burp Suite Enterprise Edition's embedded database and want to transfer your data to an external one.

  • You want to deploy Burp Suite Enterprise Edition and use an external database from the start. If you're a first-time user, remember that you can always start out with the embedded database and migrate to a different one later.

Preparing the database for Burp Suite Enterprise Edition involves the following high-level steps:

  1. Connect to your database server.

  2. Run the setup script for your database type. This creates a database and two users for Burp Suite Enterprise Edition.

  3. Note the connection URL for your database. You will need this later to connect Burp Suite Enterprise Edition.

Database setup scripts

The setup scripts below create a new database and two users: burp_enterprise and burp_agent. These are used by the Enterprise server and your agents to connect to your database. If you're setting up this database in order to migrate from the embedded one, you must use these exact usernames.

You should obviously substitute the placeholder ******** strings used in the example script with your own strong passwords.


CREATE DATABASE burp_enterprise;
CREATE USER burp_enterprise PASSWORD '********';
CREATE USER burp_agent PASSWORD '********';
GRANT ALL ON DATABASE burp_enterprise TO burp_enterprise;

If you're migrating data from Burp Suite Enterprise Edition's bundled database to a new PostgreSQL database, you must also temporarily assign the SUPERUSER role to the burp_enterprise user. This is a prerequisite for running the database transfer tool that we provide. We recommend demoting the user again once you have completed the migration.

Microsoft SQL Server

sp_configure 'contained database authentication', 1;
USE burp_enterprise;
CREATE USER burp_enterprise WITH PASSWORD = '********';
CREATE USER burp_agent WITH PASSWORD = '********';
ALTER ROLE db_owner ADD MEMBER burp_enterprise;

To support password-based logins, you need to ensure that the Windows Authentication and SQL Server Authentication option is enabled for the installation. This option is sometimes referred to as Mixed Mode Authentication.


CREATE TABLESPACE burp_enterprise_tabspace DATAFILE 'burp_enterprise_tabspace.dat' SIZE 100M AUTOEXTEND ON;
CREATE USER burp_enterprise DEFAULT TABLESPACE burp_enterprise_tabspace QUOTA UNLIMITED ON burp_enterprise_tabspace IDENTIFIED BY ********;
CREATE USER burp_agent IDENTIFIED BY ********;

MariaDB / MySQL

CREATE DATABASE burp_enterprise CHARACTER SET = 'utf8mb4' COLLATE = 'utf8mb4_unicode_ci';
CREATE USER 'burp_enterprise'@'%' IDENTIFIED BY '********';
CREATE USER 'burp_agent'@'%' IDENTIFIED BY '********';
GRANT ALL PRIVILEGES ON burp_enterprise.* TO 'burp_enterprise'@'%' WITH GRANT OPTION;

If you run into errors during installation with a MySQL database, please refer to the troubleshooting section below for details on how to resolve a couple of known issues.

Database connection URL format

To connect Burp Suite Enterprise Edition to your new database, you will need to provide the JDBC URL in various places. The format for this URL differs slightly depending on the database type.

  • PostgreSQL: jdbc:postgresql://<host>:5432/burp_enterprise

  • Microsoft SQL Server: jdbc:sqlserver://<host>:1433;databaseName=burp_enterprise

  • Oracle: jdbc:oracle:thin:@//<host>:1521/<instance-id>

  • MariaDB / MySQL: jdbc:mysql://<host>:3306/burp_enterprise

When setting up an on-premise deployment of Burp Suite Enterprise Edition, you will be prompted to provide your JDBC URL in the installation wizard. In this case, you don't need to include the jdbc:<subprotocol>:// prefix as this is derived automatically based on the database type that you selected. During a cloud deployment, however, you need to provide the full JDBC URL as specified above.

Troubleshooting for MySQL databases

There are a couple of known issues with using MySQL databases. Fortunately, these are easy to resolve. If you run into either of the following errors during the installation, please follow the instructions below.

You do not have the SUPER privilege and binary logging is enabled

While attempting to install Burp Suite Enterprise Edition with a MySQL database, you may initially encounter the following exception:

liquibase.exception.MigrationFailedException: Migration failed for change set true::in_progress_scan_by_agent_mysql::PortSwigger:
Reason: liquibase.exception.DatabaseException: (conn=21) You do not have the SUPER privilege and binary logging is enabled (you *might* want to use the less safe log_bin_trust_function_creators variable) [Failed SQL: (1419) CREATE FUNCTION in_progress_scans_for_agent(machine_id VARCHAR(64))

To resolve this issue, set the global system variable log_bin_trust_function_creators = 1. This enables Burp Suite Enterprise Edition to create the functions it needs to set up your database. If you're using a cloud service, please consult your service provider's documentation for details on how to do this.

Note that even if you didn't explicitly enable binary logging, it is often enabled by default for cloud services, such as an RDS instance on AWS.

RSA public key is not available client side

When using the default authentication mechanism for MySQL 8, the Burp Suite Enterprise Edition driver validates the public key of the database. If the key is self-signed, you will encounter the following exception:

liquibase.exception.DatabaseException: liquibase.exception.DatabaseException: java.sql.SQLTransientConnectionException: Could not connect to address=(host= : RSA public key is not available client side (option serverRsaPublicKeyFile not set)

There are several options for resolving this issue:

  • Use a certificate signed by a well-known certification authority instead.

  • Distribute the public key of the self-signed certificate manually. Please see the instructions below for details on how to do this.

  • Disable the security feature that is raising this issue by appending the allowPublicKeyRetrieval=true parameter to the database connection URL. You should not do this unless you fully understand the security implications as this could potentially enable man-in-the-middle attacks on the connection.

Distributing the public key manually

  1. Obtain an RSA key pair on your database server by following the steps detailed in the MySQL documentation.

  2. Copy the .pem file containing the public key to the machine on which the Burp Suite Enterprise Edition server is hosted, as well as any external agent machines that you've deployed. The path to this file must be identical across all of your machines.

  3. Append the serverRsaPublicKeyFile parameter to your database connection URL, pointing it to the location of the key on your machines. For example: