ENTERPRISE

Migrating to an external database

  • Last updated: September 9, 2022

  • 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:

  • Install the database transfer tool.
  • Prepare for the migration.
  • Migrate your data.
  • Restart services.

Installing the database transfer tool

Note

If your first ever version of Burp Suite Enterprise Edition was 2020.1-2902 or later, you can skip this section and go straight to preparing for the migration.

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 ever version of Burp Suite Enterprise Edition was 2020.1-2902 or earlier, you need to install the tool 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 "databaseServer/${VERSION}/lib/*" net.portswigger.enterprise.database.transfer.DatabaseTransferMain ${INSTALLATION_DIR} ${DATA_DIR}/data

Key

  • ${VERSION} is the version number of your current Burp Suite Enterprise Edition installation, for example, 2020.6.
  • ${INSTALLATION_DIR} is the directory where Burp Suite Enterprise Edition is installed.
  • ${DATA_DIR} is the directory where your Burp Suite Enterprise Edition data is stored. You specified this directory during the installation process.

The resulting command would look something like this:

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

Preparing for 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 both of the following locations:

    <installation-directory>/databaseServer/<version-number>/lib/ojdbc8.jar <installation-directory>/enterpriseServer/<version-number>/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.

If you've already deployed any external scanning machines, you also need to perform the following steps on each machine:

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

    <installation-directory>/enterpriseAgent/<version-number>/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.

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.
  4. Provide the JDBC URL and credentials for the new external database.

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.

Restarting 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.

Was this article helpful?