1. Support Center
  2. Documentation
  3. Enterprise Edition
  4. Getting started
  5. Setting up the external DB

Setting up the external database

This process is only relevant if you plan to use an external database rather than the embedded one provided with Burp Suite Enterprise Edition. If this is your first time setting up Burp Suite Enterprise Edition, remember you can always start with the bundled database and migrate to an external database later.

If using an external database, you will need to create a database schema for Burp Suite Enterprise Edition to use. To do this, you can simply connect to your database server and run the setup script below that corresponds to your database type.

The script will create two users, called burp_enterprise and burp_agent respectively. You may occasionally see these referred to as the "admin repository username" and "agent repository username". These will be used by the Enterprise server and your agents in order to connect to your database. You should obviously substitute the placeholder ******** passwords used in the example script with your own strong passwords.

Note

If you're setting up this database as part of the initial Burp Suite Enterprise Edition installation process, you can call these users whatever you want. However, if you're setting up the database in order to migrate from Burp Suite Enterprise Edition's bundled database, you need to use these exact names.

After creating the users, make sure you keep a record of the connection details for your database. You will need to provide these later during the installation or migration process.

Please be aware that if you're setting up an on-premise version of Burp Suite Enterprise Edition, when prompted to provide your JDBC URL in the installation wizard, you do not need to include the jdbc:<subprotocol>:// prefix; this will be derived automatically based on the database type that you selected. During a cloud deployment, however, you will still need to provide the full JDBC URL as specified below.

PostgreSQL

Setup script: CREATE DATABASE burp_enterprise;
CREATE USER burp_enterprise PASSWORD '********';
CREATE USER burp_agent PASSWORD '********';
GRANT ALL ON DATABASE burp_enterprise TO burp_enterprise;
JDBC URL format: jdbc:postgresql://{Server address}:5432/burp_enterprise

Note

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.

Note that this requirement applies only to our database transfer tool. If you're just setting up a PostgreSQL database as part of the initial installation of Burp Suite Enterprise Edition, you do not need to do this.

Microsoft SQL Server

Setup script: sp_configure 'contained database authentication', 1;
RECONFIGURE;
CREATE DATABASE burp_enterprise CONTAINMENT = PARTIAL;
USE burp_enterprise;
CREATE USER burp_enterprise WITH PASSWORD = '********';
CREATE USER burp_agent WITH PASSWORD = '********';
ALTER ROLE db_owner ADD MEMBER burp_enterprise;
JDBC URL format: jdbc:sqlserver://[serverName]:1433;databaseName=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".

Oracle

Setup script: 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 ********;
GRANT CREATE PROCEDURE, CREATE SEQUENCE, CREATE SESSION, CREATE TABLE, CREATE TRIGGER,
  CREATE SYNONYM, CREATE PUBLIC SYNONYM, DROP PUBLIC SYNONYM TO burp_enterprise;
CREATE USER burp_agent IDENTIFIED BY ********;
GRANT CREATE SESSION to burp_agent;
JDBC URL format: jdbc:oracle:thin:@//[serverName]:1521/[instanceId]

MariaDB / MySQL

Setup script: CREATE DATABASE burp_enterprise;
CREATE USER 'burp_enterprise'@'%' IDENTIFIED BY '********';
CREATE USER 'burp_agent'@'%' IDENTIFIED BY '********';
GRANT ALL PRIVILEGES ON burp_enterprise.* TO 'burp_enterprise'@'%' WITH GRANT OPTION;
JDBC URL format: jdbc:mysql://{server address}:3306/burp_enterprise

Note for MySQL users

If binary logging is enabled for your MySQL database, users cannot create stored functions unless they have SUPER privileges. As a result, Burp Suite Enterprise Edition may be unable to create the functions it needs to set up your database. Although you might not have explicitly enabled binary logging, if you're using a cloud service, such as an RDS instance on AWS, it is often enabled by default. In this case, you may encounter the following error when trying to install Burp Suite Enterprise Edition:

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 prevent this error, you just need to set the global system variable log_bin_trust_function_creators = 1. If you're using a cloud service, you may need to consult your service provider's documentation for details on how to do this.