Enterprise Edition

Migrating to an external database

• Last updated: October 31, 2024

• Read time: 3 Minutes

If you are using Burp Suite Enterprise Edition's bundled H2 database, you can migrate to an external one at any time.

The migration process involves the following phases:

1. Preparing for the migration
2. Migrating your data
3. Restarting the Burp Suite Enterprise Edition services

Preparing for the migration

1. Set up your new database. Keep a note of the credentials that you create.
2. Stop all scans.
3. On each scanning machine, stop the burpsuiteenterpriseedition_agent services.
4. Perform a backup of the bundled database. You can do this from the Burp Suite Enterprise Edition web UI in the database backup settings.
5. On the Enterprise server, stop the burpsuiteenterpriseedition_enterpriseserver and burpsuiteenterpriseedition_webserver services.
6. Create a copy of the enterprise-server.config file, in case you need to revert to using the original database.

Prerequisite steps for Oracle databases

To migrate to an Oracle database, you need to perform some additional steps before you begin transferring your data.

On the machine on which you installed the Enterprise server and web server:

1. Download the required driver (ojdbc8.jar) from the Oracle website.

2. Copy the downloaded file to the following locations:

   <installation-directory>/databaseTransferTool/<version>/lib/ojdbc8.jar <installation-directory>/enterpriseServer/<version>/lib/ojdbc8.jar <installation-directory>/webServer/<version>/lib/ojdbc8.jar

3. To make sure that the drivers are installed as part of any future updates, create the following empty marker files:

   <installation-directory>/enterpriseServer/.oracle <installation-directory>/webServer/.oracle

4. Make sure that the ownership and permissions of the newly created files match those of the other files in their respective directories. This should mean that the files are readable by all users.

You also need to perform the following steps on each of your scanning machines. This applies to both internal scanning machines and external scanning machines:

1. Install the driver by adding the downloaded ojdbc8.jar file to the following location:

   <installation-directory>/enterpriseAgent/<version>/lib/ojdbc8.jar

2. Create an empty marker file in the following location:

   <installation-directory>/enterpriseAgent/.oracle

3. Make sure that the permissions for the marker file match the other files in the directory.

When these steps are complete on all of your machines, you can proceed with the rest of the migration process.

Prerequisite steps for PostgreSQL databases

To migrate to a PostgreSQL database, you need to temporarily assign superuser access to Burp Suite. This enables Burp to disable foreign key constraints that will otherwise prevent it importing data.

Assign the superuser role to burp_enterprise by running:

alter user burp_enterprise with superuser;

When you've completed the migration, revoke this permission by running:

alter user burp_enterprise with nosuperuser;

Migrating your data

1. Restart your database server.
2. On the Enterprise server machine, open a command prompt.
3. From the installation directory, run database_transfer as either the burpsuite user or root. If you don't have the database_transfer tool, see Running the database transfer command manually.
4. Provide the JDBC URL and credentials for the new external database.

If you don't have the database_transfer tool, or the command fails with an error message, see Running the database transfer command manually.

Data is transferred table by table and progress is reported in the console. Once the migration is complete, a summary of the rows transferred per table is reported. The enterprise-server.config file is updated with the new database connection details.

Running the database transfer command manually

For most users, the database_transfer tool is automatically installed as part of the main Burp Suite Enterprise Edition installation process. However, if your first version of Burp Suite Enterprise Edition was 2023.9 or earlier, you may not have the tool or it may fail to run. In this case, you need to run the database transfer command manually:

1. From a command prompt, navigate to your Burp Suite Enterprise Edition installation directory.
2. Enter the following command, replacing the variables with the appropriate values:

sudo ./jre/bin/java -cp "databaseTransferTool/<version>/lib/*" net.portswigger.enterprise.database.transfer.DatabaseTransferMain <installation-directory> <data-directory>/data

The resulting command would look something like this:

cd /opt/burpsuite_enterprise/ sudo ./jre/bin/java -cp "databaseTransferTool/2020.6/lib/*" net.portswigger.enterprise.database.transfer.DatabaseTransferMain /opt/burpsuite_enterprise/ /var/lib/BurpSuiteEnterpriseEdition/data

Restarting the Burp Suite Enterprise Edition services

1. On the Enterprise server machine, restart the burpsuiteenterpriseedition_enterpriseserver and burpsuiteenterpriseedition_webserver services.
2. On each of your scanning machines, restart the burpsuiteenterpriseedition_agent services.