1. Support Center
  2. Documentation
  3. Enterprise Edition
  4. Administration tasks
  5. Migrating to an external database

Migrating to an external database

During the initial installation of Burp Suite Enterprise Edition, you can choose whether to use the bundled database or an external database. If you choose to use the bundled database, you can migrate to an external one at any time.

The migration process involves the following phases.

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 will automatically be 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 will need to install this tool manually.

From a command prompt, navigate to your Burp Suite Enterprise Edition installation directory. Then, 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.

For example, 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. Perform the required setup for your new external database. Keep a note of the credentials that you create for the external database.
  2. Stop all scans.
  3. On agent machines, stop the burpsuiteenterpriseedition_agent services.
  4. Perform a backup of the bundled database. This can be done from the Burp Suite Enterprise Edition web UI in the database backup settings.
  5. On the Enterprise server machine, stop the burpsuiteenterpriseedition_enterpriseserver and burpsuiteenterpriseedition_webserver services.
  6. Create a copy of the enterprise-server.config file in case it is necessary to revert to using the original database.

Migrating your data

  1. On the Enterprise server machine, open a command prompt.
  2. From the installation directory, run database_transfer as either the burpsuite user or root.
  3. Provide the JDBC URL and credentials for the new external database.
  4. Data will be transferred table by table and progress is reported in the console.
  5. Once the migration has completed, a summary of the rows transferred per table is reported and the enterprise-server.config file will have been 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 agent machines, restart the burpsuiteenterpriseedition_agent services.