NGINX Documentation

Back Up and Restore NGINX Controller v3

This guide explains how to back up and restore your NGINX Controller database.

Before You Begin

To backup and restore the NGINX Controller database, you’ll need the following:

  • Login credentials for your NGINX Controller PostgreSQL database
  • A connection to your NGINX Controller PostgreSQL database
  • psql and pg_dump installed on the server where you’ll be performing the backup or restore

Set the PostgreSQL Environment Variables

  1. Log in to the NGINX Controller host using SSH.

  2. Set the following environment variables using the credentials for your NGINX Controller PostgreSQL database:

    export PGHOST=<postgres host>
    export PGPORT=5432
    export PGUSER=<postgres user>
    export PGPASSWORD=<postgres password>
    

    Note: If you’ve configured PostgreSQL to use SSL, ensure that you’ve placed your certs in ~/.postgresql. For more information, see Client Certificates in the PostgreSQL documentation.

Back Up NGINX Controller

To back up the NGINX Controller PostgreSQL database:

  1. Stop NGINX Controller:

    ./opt/nginx-controller/helper.sh controller stop
    
  2. Run the following script to back up the NGINX Controller database. The backup files are saved in a directory that looks like pgbackup_<timestamp>.

    DATE=$(date +"%Y%m%d%H%M")
    mkdir ~/pgbackup_${DATE}
    
    for db in common data system; do
      pg_dump -w -E utf8 -d ${db} -F c -f ~/pgbackup_${DATE}/${db}-${DATE}.backup
    done
    
  3. Make a backup copy of the ClickHouse binary data. This data is located in /opt/nginx-controller/clickhouse_data or on the external volume that you specified during the installation.

  4. Back up the following platform settings:

    • database credentials
    • SMTP credentials
    • apigw certs
  5. After the backup is complete, start NGINX Controller:

    ./opt/nginx-controller/helper.sh controller start
    

Restore NGINX Controller

To restore the NGINX Controller PostgreSQL database:

  1. Stop NGINX Controller:

    ./opt/nginx-controller/helper.sh controller stop
    
  2. Locate the backup directory and save the name as a local environment variable. The name of the backup directory follows the format pgbackup_<timestamp>.

    BACKUP_PATH=~/pgbackup_<timestamp>
    
  3. Run the restore script:

    for backup_file in "$(ls ${BACKUP_PATH})"; do
      db="$(echo ${backup_file} | cut -d '-' -f 1)"
    
      pg_restore -c -C -d "${db}" "${BACKUP_PATH}/${backup_file}"
    done
    
  4. Restore the backup copy of the ClickHouse binary data. Copy the data to /opt/nginx-controller/clickhouse_data or to the external volume that you specified during the installation.

  5. After the restore is finished, start NGINX Controller:

    ./opt/nginx-controller/helper.sh controller start
    
  6. To update the SMTP and apigw cert settings, you can send a PATCH request to the platform/global endpoint. See the NGINX Controller API Reference Guide that’s installed with NGINX Controller for more information. The API docs are located at https://<Controller-FQDN/docs/api/api-reference/.

Important: If you installed a new version of NGINX Controller before restoring the database, you’ll need to reset the admin password:

  1. Open the NGINX Controller web interface.

  2. On the Sign In page, select Forgot Password.

  3. Type the admin email address in the email box.

  4. Select Reset. You’ll receive an email with a link to reset the password.

    If you don’t receive an email to reset the admin password, see the AskF5 KB article K06962163 for instructions on how to reset the admin password from the command line.