Configuring backup settings during initial installation of the management subsystem

You can use the apicup utility to configure backup settings during initial installation of the management subsystem

Before you begin

Review Backing up and restoring the Management subsystem.
Note: You must backup both the Management and Portal subsystems at the same time, to ensure synchronicity across the services.

About this task

  • During an initial installation, use these steps to configure the backup settings prior to creating the initial management ISO.
  • You can configure scheduled backups, or generate manual (on-demand) backups.
  • Changing backup settings results in database downtime, unless database-backup-protocol=sftp.
  • Backup to S3 providers of type custom is supported in v10.0.2.0 or greater. For custom S3, provide values for database-backup-certs and database-backup-s3-uri-style.
  • OpenSSH key authentication for SFTP is supported.

  • When you specify a filepath in a backup setting, be sure to escape any blank spaces in the path.
Important: For S3 backups of the management subsystem, do not use retention features provided by Cloud-based S3 storage providers. Use of such features can result in periodic deletion of archived backups, which can cause backup corruptions that can cause database restores to fail.


  1. Use apicup to specify backup settings:
    • For most settings, use apicup subsys:
      apicup subsys set <subsystem_name> <setting>=<value>
    • When configuring ssh-key authentication for SFTP, use apicup certs
      apicup certs set <subsystem_name> database-backup-auth-ssh-key <ssh-key-file-path>

    Table 1. Configuration settings for backup of management subsystem
    Parameter Description
    database-backup-protocol The type of the backup. Supported types:
    • objstore
      apicup subsys set mgmt database-backup-protocol=objstore
    • sftp
      apicup subsys set mgmt database-backup-protocol=sftp

      The default value is sftp.

    • local - Local storage backups
      apicup subsys set mgmt database-backup-protocol=local
    • The public certificate on the S3 storage provider must be signed by a known certificate authority that is trusted by API Connect. Use of an untrusted authority can cause the following error during backup upload: x509: certificate signed by unknown authority.
    database-backup-auth-pass The password for the server specified in database-backup-host. If using object store, this would be the S3 Secret Access Key parameter. The password will be stored in Base64 encoded format.

    For example:

    apicup subsys set mgmt database-backup-auth-pass '<password>'

    Note that you cannot use the `=` sign to assign the password to database-backup-auth-pass.

    database-backup-auth-user The username for the server specified in database-backup-host. If using object store, this would be the S3 Secret Key ID.
    apicup subsys set mgmt database-backup-auth-user <user_name>
    database-backup-auth-ssh-key Optional: OpenSSH private key for DB backups using SFTP only. Changing this value will restart the DB.
    • Use apicup certs to set this value. Do not use apicup subsys.
    • Only OpenSSH keys are supported.1
    apicup certs set mgmt database-backup-auth-ssh-key <ssh private key filepath>
    database-backup-s3provider When using objstore type backup, specify the name of the S3 provider to use. Specify one of the supported values:
    • ibm
    • aws
    • custom - v10.0.2.0 or later
    Not required for local backups or SFTP backups.
    apicup subsys set mgmt database-backup-s3provider=ibm
    database-backup-host The backups host:
    • For objstore type backup, specify S3 endpoint with the corresponding S3 region in the format <S3endpoint>/<S3region>
      apicup subsys set mgmt
    • For sftp type, the SFTP server hostname
      apicup subsys set mgmt
    • Not required for local storage backups
    database-backup-path The path to the location of the backup:
    • For objstore backups, the name of your S3 bucket to store backup data. For example, bucket-name/folder. The use of subdirectories in the bucket name is not supported.
      apicup subsys set mgmt database-backup-path=apic-backup
      Note: When your deployment includes a management subsystem in two different clusters (with active databases), the two management subsystems cannot use the same s3 bucket name in the database backup configurations. Each management subsystem must use a unique s3 bucket name.

      Ensure that bucket-name/folder is empty. If the folder was previously used for backups, the folder will not be empty, and stanza create might encounter an error.

      • Explanation: Once a folder is used, and files are created. During stanza creation, the process compares the database version and database system id between the two info files and the current Postgres database cluster. Stanza creation fails if there is a mismatch. To prevent this possibility, remove all files from the folder before configuring.
    • For sftp type, the full absolute path of the folder on the SFTP server, beginning with /.
      apicup subsys set mgmt database-backup-path=<folder_name>
    • Not required for local storage backups
    database-backup-port The port for the protocol to connect to the database-backup-host. The backup port is not required for object storage. Default: 22
    apicup subsys set mgmt database-backup-port=<port_number>
    database-backup-retries For sftp type backups, the number of times the ibm-apiconnect Operator attempts backups in the event of a failed SFTP backup.
    apicup subsys set mgmt database-backup-retries=3

    Default value: 0.

    Not used for objstore or local storage backup.

    database-backup-schedule Cron like schedule for performing automatic backups. The format for the schedule is:
    • * * * * *
    • - - - - -
    • | | | | |
    • | | | | +----- day of week (0 - 6) (Sunday=0)
    • | | | +------- month (1 - 12)
    • | | +--------- day of month (1 - 31)
    • | +----------- hour (0 - 23)
    • +------------- min (0 - 59)

    The backup schedule defaults to 0 0 * * *. This means a backup is run every day at midnight and minute zero.

    The timezone for backups is UTC.

    For local backups, the default is 01:00 UTC.

    When you configure a host, if you do not specify a value for database-backup-schedule, the default backup schedule is automatically set. Note that the default backup schedule is not set, and scheduled backups not enabled, until host configuration is completed.

    apicup subsys set mgmt database-backup-schedule="0 0 * * *"

    Custom certificate. Used only when s3Provider is set to custom. Most of the custom S3 providers are created based on custom CA certificate.

    This field accepts name of the Kubernetes secret containing your upstream custom S3 CA certificate. The key of the secret must be ca.crt and value should be base64 encoded value of CA certificate.

    The API Connect management subsystem validates the custom S3 certificate against the customer-provided CA certificate.

    Sample bash script to create the Kubernetes secret:
    cat >customs3ca.yaml <<EOF
    apiVersion: v1
      ca.crt: $(base64 <path-to-ca-certificate> | tr -d '\n' )
    kind: Secret
      name: custom-server-ca
    type: generic
    kubectl apply -f customs3ca.yaml -n <namespace>

    For example:

    apicup subsys set mgmt database-backup-certs=my-custom-s3-ca-cert

    Valid values: host and path. Default value: host

    Only allowed if s3Provider is set to custom.

    Some custom S3 providers require URI style to be set to path. For example, minIO supports both host and path style setup. You can create a minIO S3 server to only accept path style client communications.

    Important: Contact your custom S3 administrator before configuring this field. If not properly configured, upstream custom S3 can reject connections from the client, such as API Connect management subsystem.

    apicup subsys set mgmt database-backup-s3-uri-style='<host|path>'
    database-backup-repo-retention-full The number of full S3 or local backups to retain. Not supported for SFTP.

    When the next full backup successfully completes, and the specified number of retained backups is reached, the oldest full backup is deleted. All incremental backups and archives associated with the oldest full backup also expire. Incremental backups are not counted for this setting.

    Applies to both manual backups and scheduled backups.

    Minimum value: 1

    Maximum value: 9999999

    Default: none (S3 backups), 14 (local backups).

  2. Verify that your settings are valid:
    • To view all subsystem settings except database-backup-auth-ssh-key:
      apicup subsys get <subsystem_name> --validate
    • To view database-backup-auth-ssh-key:
      apicup certs get <subsystem_name> database-backup-auth-ssh-key --type key
  3. Return to the instructions for installing the management subsystem: Deploying the Management virtual appliance.

    Note that the configuration settings for backups will be installed when you run apicup subsys install <subsystem_name> after all configuration settings are complete.

  4. S3 backups only: After you complete the deployment of the Management subsystem in the previous step, continue to Verify configuration for s3 backup.
1 PuTTY style keys can be converted to OpenSSH by using the PuTTY Key Generator (PuTTYgen) application; see