IBM API Connect 10.0.8.x backup to Amazon S3: Management and Developer Portal

IBM API Connect on VMware can store Management database and Developer Portal backups in Amazon S3 or another supported S3-compatible object store. This gives you an off-appliance backup location for scheduled backups, on-demand backups, disaster recovery and upgrade preparation.

The configuration itself is straightforward, but there are a few details worth getting right: AWS regional endpoints, the different cron formats used by Management and Portal, backup consistency between the two subsystems, certificate handling, and the fact that database backups alone are not a complete disaster-recovery strategy.

Version scope. This guide is written for IBM API Connect 10.0.8.x on VMware and uses apicup. The sample values are sanitized. Always use the apicup binary that matches your installed API Connect release.

What are we backing up?

Subsystem	Backup contains	Remote target
Management	API Connect configuration stored in the Management database, including APIs, Products, TLS profiles, user registries and other Cloud Manager / API Manager configuration.	Amazon S3 object storage
Developer Portal	Portal system configuration and Portal site backups.	Amazon S3 object storage

Architecture

Management and Portal backups must be taken at the same time so the Portal sites remain consistent with the Management database.

Prerequisites

API Connect. A working 10.0.8.x VMware deployment and the matching apicup project directory.
S3 bucket. An Amazon S3 bucket that API Connect can write to.
AWS credentials. An AWS Access Key ID and Secret Access Key with the minimum permissions required for the backup location.
Network access. API Connect must be able to reach the S3 endpoint over HTTPS.
DNS. The AWS regional endpoint must resolve from the API Connect environment.
Project directory backup. Keep a current copy of the original API Connect project directory. It is required for disaster recovery.

AWS endpoint format

For modern AWS regions, use the regional S3 endpoint. IBM documents the pattern as:

s3.<region>.amazonaws.com/<region>

For example, for eu-north-1:

s3.eu-north-1.amazonaws.com/eu-north-1

Certificate note. For normal AWS S3, the server certificate is signed by a publicly trusted CA, so a custom backup CA is normally not required. For MinIO or another custom S3 implementation, configure the required CA trust if the object-store certificate is not already trusted by API Connect.

Step 1 - Configure the Management database backup

Run the commands from your API Connect project directory. Use placeholders for credentials; never store real AWS keys in a public script or blog.

# AWS credentials
apicup subsys set mgmt database-backup-auth-user <AWS_ACCESS_KEY_ID>
apicup subsys set mgmt database-backup-auth-pass '<AWS_SECRET_ACCESS_KEY>'

# S3 destination
apicup subsys set mgmt database-backup-host=s3.eu-north-1.amazonaws.com/eu-north-1
apicup subsys set mgmt database-backup-path=ibmapiconnect/mgmt
apicup subsys set mgmt database-backup-protocol=objstore

# Daily backup at 01:00 UTC
apicup subsys set mgmt database-backup-schedule="0 0 1 * * *"

# Validate
apicup subsys get mgmt --validate

Command syntax detail. IBM documents database-backup-auth-pass without an = sign. Use database-backup-auth-pass '<secret>', not database-backup-auth-pass=<secret>.

Management parameters explained

Setting	Purpose
`database-backup-auth-user`	AWS Access Key ID used to authenticate to the object store.
`database-backup-auth-pass`	AWS Secret Access Key.
`database-backup-host`	S3 endpoint and region.
`database-backup-path`	S3 bucket and backup prefix, for example `ibmapiconnect/mgmt`.
`database-backup-protocol`	Set to `objstore` for S3-compatible object storage.
`database-backup-schedule`	Six-field cron expression. Management schedules use seconds, minutes, hours, day, month and day-of-week.

Step 2 - Configure the Developer Portal backup

The Portal uses a similar object-store configuration but different property names and a five-field cron schedule.

# S3 destination
apicup subsys set ptl site-backup-host=s3.eu-north-1.amazonaws.com/eu-north-1
apicup subsys set ptl site-backup-auth-user=<AWS_ACCESS_KEY_ID>
apicup subsys set ptl site-backup-auth-pass='<AWS_SECRET_ACCESS_KEY>'
apicup subsys set ptl site-backup-path=ibmapiconnect/portal
apicup subsys set ptl site-backup-protocol=objstore

# Daily backup at the same time: 01:00 UTC
apicup subsys set ptl site-backup-schedule="0 1 * * *"

# Validate
apicup subsys get ptl --validate

For object storage, you do not need to configure site-backup-port=22. IBM documents the object-store port as not required; if explicitly configured, HTTPS normally uses port 443.

Why the schedules look different

Subsystem	Cron format	01:00 UTC example
Management	6 fields, including seconds	`0 0 1 * * *`
Portal	5 fields	`0 1 * * *`

Even though the expressions are different, both examples run at 01:00 UTC. This is intentional: IBM requires Management and Portal backups to be taken at the same time to preserve consistency.

Step 3 - Apply the configuration

After validation, apply the updated subsystem configuration.

apicup subsys install mgmt
apicup subsys install ptl

Then verify subsystem health:

apicup subsys health-check mgmt
apicup subsys health-check ptl

A successful health check returns silently with exit code 0.

If you changed existing Management backup credentials: IBM requires a database reload after the updated configuration is installed. Run apicup subsys db-reload mgmt after apicup subsys install mgmt.

Step 4 - Run an on-demand Management backup

Before starting a manual backup, verify that no Management backup is already running and that a scheduled backup is not about to start.

apicup subsys list-backups mgmt
apicup subsys health-check mgmt

Start the backup:

apicup subsys backup mgmt

Monitor its status:

apicup subsys list-backups mgmt

For more detail:

apicup subsys list-backups mgmt --detailed-output=true

Step 5 - Run an on-demand Portal backup

A complete Portal backup contains the Portal system configuration and all installed sites. With current 10.0.8.x apicup, omitting flags creates the full Portal backup.

apicup subsys health-check ptl
apicup subsys backup ptl
apicup subsys list-backups ptl

You can also back up only the system configuration or individual sites:

# Portal system only
apicup subsys backup ptl --type system

# One site
apicup subsys backup ptl --type site --site-name <SITE_ID_OR_URL>

# All installed sites
apicup subsys backup ptl --type site --site-name installed

Step 6 - Verify the backup in Amazon S3

After the backup is complete, check the S3 bucket and confirm that objects are being written under the expected Management and Portal paths.

s3://ibmapiconnect/mgmt/
s3://ibmapiconnect/portal/

Also verify from API Connect with list-backups. Seeing files in S3 alone is not enough; API Connect should also recognize the backup records as usable.

Management S3 path: start with an empty location

For Management object-store backups, IBM warns against reusing a location that already contains backup metadata from another database cluster. The backup path should be empty when it is first configured for a new Management database.

This matters because the backup repository contains metadata such as database system identifiers. Reusing a folder from another cluster can cause repository initialization or stanza errors.

Retention: Management and Portal are different

Area	Recommended approach
Management S3 backups	Use API Connect's `database-backup-repo-retention-full`. IBM specifically warns not to use cloud-provider retention features that periodically delete Management backup archive data, because this can make restores fail.
Portal remote backups	Portal remote-backup retention is managed separately. Keep the remote backup count under control and align retention with your Portal backup-record policy.

For example, Management can retain 30 days of full backups with:

apicup subsys set mgmt database-backup-repo-retention-full=30
apicup subsys install mgmt

What is required for real disaster recovery?

An S3 database backup is important, but it is only one piece of API Connect disaster recovery.

Backup item	Why it matters
Project directory	Contains the original `apicup` deployment configuration and is required to recover the VMware deployment.
Management certificates	IBM documents backing these up with the Management disaster-recovery preparation process.
Management DB backup	Restores Management configuration and API lifecycle data.
Portal backup	Restores Portal system configuration and sites.

VM snapshots can help infrastructure recovery, but IBM explicitly states that snapshots are not a replacement for API Connect project-directory and subsystem database backups.

Restore order

If Management and Portal must be restored, restore them from backups taken at the same time and in this order:

Restore Management first.
Restore Developer Portal immediately afterward.

For Management, list available backups and restore the selected backup:

apicup subsys list-backups mgmt
apicup subsys restore mgmt --name <BACKUP_NAME>

For Portal, IBM provides a useful dry-run before the actual restore:

apicup subsys list-backups ptl
apicup subsys restore ptl --dry-run --timestamp now
apicup subsys list-restores ptl

# Actual restore of newest backup
apicup subsys restore ptl --timestamp now
apicup subsys list-restores ptl

Restore warning. A Management restore is destructive and requires downtime. Stop external administrative traffic and follow the full IBM recovery procedure for your environment rather than treating the commands above as the complete disaster-recovery runbook.

Troubleshooting

S3 authentication fails

Verify the AWS Access Key ID, Secret Access Key and IAM permissions on the bucket/prefix. Confirm the credentials are still active and that the access key is allowed to write to the configured location.

x509: certificate signed by unknown authority

This normally points to a custom S3 endpoint using a CA that API Connect does not trust. Configure the custom object-store CA as documented by IBM. Normal AWS S3 endpoints typically use publicly trusted certificates.

Backup configuration validates but no objects appear in S3

Check subsystem health, DNS resolution, HTTPS connectivity to the regional S3 endpoint, the bucket path, IAM permissions and the output of apicup subsys list-backups.

Portal and Management backups have different timestamps

Align the two cron schedules. Remember that Management uses a six-field cron expression while Portal uses five fields. Both schedules use UTC on VMware.

Management repository initialization fails

Confirm that the configured Management S3 path is not being reused from a different Management database cluster and that the location was empty when first configured.

Production checklist

Use least-privilege AWS IAM permissions. Give the backup identity access only to the required bucket and prefix.
Protect credentials. Do not store AWS keys in Git, tickets, screenshots or public documentation.
Keep schedules synchronized. Management and Portal should back up at the same time.
Monitor backup status. Regularly review list-backups and alert on failures.
Keep the project directory current. Take a new copy after configuration changes made with apicup.
Test restores. A backup strategy is incomplete until the restore process has been validated.
Do not rely only on VM snapshots. Keep API Connect-native database and configuration backups.

IBM documentation used to cross-check this guide

Final take

Backing up API Connect to Amazon S3 is mostly about getting a few fundamentals right: use the correct regional endpoint, keep Management and Portal backup times aligned, validate and apply the configuration with apicup, run an on-demand backup before trusting the schedule, and verify the result from both API Connect and S3.

For disaster recovery, remember the bigger picture: Management DB + Portal DB + project directory + Management certificates. With those pieces protected and restore-tested, S3 becomes a reliable part of the API Connect recovery strategy rather than simply another place where backup files are stored.