Backup and Snapshot Strategies for Layer7 API Gateway (VMware)

Products

• CA API Gateway

Issue/Introduction

An administrator needs to perform a full system backup or point-in-time snapshot of a Layer7 API Gateway hosted on VMware. Standard VM snapshots may result in database inconsistency if not performed correctly.

Environment

Product: Layer7 API Gateway

Component: Gateway Appliance (OVA)

Version: 10.x, 11.x

Cause

Taking a VMware snapshot while the MySQL database is under high I/O can lead to "Inconsistent State" errors upon restoration. The Gateway application maintains active connections that may not be gracefully handled by a simple hypervisor-level capture without quiescing.

Resolution

Broadcom recommends a layered backup approach. A VMware snapshot provides disaster recovery for the OS, while the ssgbackup.sh utility ensures application-level integrity.
Because the Gateway relies on a tight coupling between the Gateway Application, the MySQL Database, and the OS-level configuration, a simple VMware snapshot alone can sometimes lead to database corruption if taken while the database is under heavy write load.

Option 1: Infrastructure Snapshot (VMware)

This method captures the entire Virtual Machine state. It is the preferred method before applying Platform Updates or Monthly CR Patches or even for date based backup's.

1. Stop Services: To ensure database consistency, stop the Gateway service: service ssg stop

2. Take Snapshot: In vCenter, right-click the VM → Snapshots → Take Snapshot.

3. Settings: * Snapshot the virtual machine's memory: Uncheck (unless troubleshooting a specific memory leak).

   • Quiesce guest file system: Check (requires VMware Tools installed).

4. Restart Services: Once the snapshot task is 100% complete, run: service ssg start

Best Practice:

• Quiesce Guest File System: Always enable this. It ensures the OS is in a consistent state.

• Offline Snapshot (Recommended): For major upgrades and long term backups (this depends upon the available storage, organization backup policy), shut down the Gateway services (service ssg stop) or power off the VM before taking the snapshot. This guarantees 100% database integrity.

Option 2: Gateway Application Backup (ssgbackup.sh)

This is the Broadcom-native method and also Broadcom-recommended method for a "logical" snapshot of the Gateway. It creates a .tar.gz file containing the database, configuration files, and certificates.. Use this for migrating to new versions or as a scheduled daily backup.

1. Navigate to the backup directory: cd /opt/SecureSpan/Gateway/config/backup
   [Review the ssgbackup.sh in the documentation for all the options]

2. Execute the backup script:

   Bash

   ./ssgbackup.sh -o /path/to/backup_file.tar.gz -maindb -p -ca
   

   • -maindb: Includes the full MySQL schema.

   • -p: Includes OS-level config (network, hosts, etc.).

   • -ca: Includes the Private Keys and Trusted Certificates.

3. Troubleshooting the backup failure issues 500 Internal Server Error

Option 3: Logical Policy Export (GMU)

For backing up specific services or folders without taking the Gateway offline, use the Gateway Migration Utility (GMU).

• Command: bash ./GatewayMigrationUtility.sh export --folderPath "/InternalServices" --recursive --argFile common.properties --dest internal_services.xml

   

Note: 

If you are running a cluster (Primary/Secondary), do not snapshot both nodes at the same time.
1. Stop the Gateway service on the Secondary node.
2. Take a VMware Snapshot of the Secondary.
3. Perform your maintenance/upgrade.
4. If successful, repeat for the Primary node.

If only taking a snapshot, point 3 above can be ignored.

[!IMPORTANT] Warning on Hardware Security Modules (HSM): If your Gateway uses a physical or networked HSM, a VMware snapshot will not backup the keys inside the HSM. You must perform a separate "Safety Backup" of the HSM according to the manufacturer’s (e.g., Thales/nCipher) instructions.

Additional Information

• Cluster Consistency: In a multi-node cluster, always perform backups/snapshots on the Secondary node first to ensure the Primary remains available.

• External Database: If using an external MySQL/Oracle DB, the VMware snapshot of the Gateway will not include your policy data. Use DB-native tools (mysqldump).