Configuring management database backups

Configure your management subsystem to take regular scheduled database backups, and enable on-demand database backups.

About this task

You use the apicup command to configure database backup settings for the management subsystem.
Database backups can be scheduled or generated manually (on-demand).
You must backup both the management and portal databases at the same time to ensure synchronicity across the services.
You must have a remote SFTP server or S3-compatible object-store available to store your management database backups.
OpenSSH key authentication for SFTP is supported.
Types of object-stores supported:
- IBM Cloud Object Storage.
- AWS S3.
- Any custom S3, such as minIO.
The public certificate on the object-store provider must be signed by a known certificate authority that your management subsystem trusts. Use of an untrusted authority can cause the following error during backup upload: x509: certificate signed by unknown authority.
Restoring a database backup restores the registration credentials (client_ID, client_secret) that were in use at the time that the selected backup was created. For information about the registration credentials, see Changing the registration client_id and client_secret for applications.
You can modify any of the backup settings at any time, but if you change the database-backup-auth-user or database-backup-auth-pass settings, you must run:
```
apicup subsys db-reload <subsystem_name>
```
after the new settings are applied with:
```
apicup subsys install <subsystem_name>
```

Important: A management database backup alone cannot be used for disaster recovery. Ensure that you also always have an up to date Project directory backup.

Procedure

Use apicup to specify backup settings:

apicup subsys set <subsystem_name> <setting>=<value>

Table 1. Configuration settings for management subsystem database backup
Parameter	Description
`database-backup-auth-pass`	The password or access key for the SFTP server or object-store that you specified in `database-backup-host`. The password is converted and stored in Base64 encoded format. For example: `apicup subsys set <subsystem_name> database-backup-auth-pass '<password>'` Note: You cannot use the ``=`` sign to assign the password to `database-backup-auth-pass`. If you change this value later, to apply the change you must run `apicup subsys db-reload <subsystem_name>` after you run: `apicup subsys install <subsystem_name>`
`database-backup-auth-ssh-key`	Applies to SFTP only. OpenSSH private key. Changing this value restarts the management database. Important: Use `apicup certs` to set this value. Do not use `apicup subsys`. Only OpenSSH keys are supported.¹ `apicup certs set <subsystem_name> database-backup-auth-ssh-key <ssh private key filepath>`
`database-backup-auth-user`	The username or secret key ID for the host that you specify in `database-backup-host`. `apicup subsys set <subsystem_name> database-backup-auth-user <username>` If you change this value later, to apply the change you must run `apicup subsys db-reload <subsystem_name>` after you run: `apicup subsys install <subsystem_name>`
`database-backup-host`	Not required if `database-backup-protocol=local`. Specify your SFTP server hostname or object-store endpoint with the corresponding object-store region in the format `<S3endpoint>/<S3region>`. Examples: `apicup subsys set <subsystem_name> database-backup-host=sftp.example.com` `apicup subsys set <subsystem_name> database-backup-host=s3.ibm.com/eu-west-2` `apicup subsys set <subsystem_name> database-backup-host=s3.eu-gb.cloud-object-storage.appdomain.cloud/eu-standard`
`database-backup-path`	Not required if `database-backup-protocol=local`. The path to the location of the backup. SFTP: The absolute path of the folder on the SFTP server, beginning with /. `apicup subsys set mgmt database-backup-path=<full path to backups directory>` Object-store: The bucket on your object-store, in the format `bucket-name/folder`. The use of subdirectories in the bucket name is not supported. Ensure that the bucket is empty. When your deployment includes a management subsystem in two different clusters (with active databases), the two management subsystems cannot use the same object-store bucket name in the database backup configurations. Each management subsystem must use a unique object-store bucket name. `apicup subsys set <subsystem_name> database-backup-path=<bucket-name/folder>`
`database-backup-port`	Applies to SFTP only. The port for the protocol to connect to the `database-backup-host`. The default value is 22. `apicup subsys set mgmt database-backup-port=<port_number>`
`database-backup-protocol`	Set to `objstore`, `sftp`, or `local`. Default is `local`. `apicup subsys set <subsystem_name> database-backup-protocol=<protocol>`
`database-backup-schedule`	Cron schedule for when database backups are run. 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) +-------------- sec (0 - 59)` The default is an empty string, which means no backups are taken. The time zone for backups is UTC. This example schedules a backup to run daily at 01:00: `apicup subsys set <subsystem_name> database-backup-schedule="0 0 1 * * *"`
`database-backup-certs`	Applies to object-store only. If your object-store has a custom CA certificate, then you must configure your management subsystem to trust this certificate. To create a secret of the custom certificate, run one of the following command: Important: Use `apicup certs` to set this value. Do not use `apicup subsys`. `./apicup certs set <mgmt subsystem> database-backup-custom-credential --encoded-string <base64 encoding of the custom certificate file>` Or `./apicup certs set <mgmt subsystem> database-backup-custom-credential <path-to-custom-cert-file>` To create the secret, run the following command: `./apicup subsys install`
`database-backup-s3-uri-style`	Applies to object-store only. Optional: Specifies whether the URI is in the form of `host` or `path`. `apicup subsys set <subsystem_name> database-backup-s3-uri-style='<host\|path>'` Supported values: `host` `path`
`database-backup-repo-retention-full`	The number of days of backups to retain. For example, if `database-backup-repo-retention-full` is set to 30, then backups for the last 30 days are retained. Older backups are deleted. After a restore, the count of the number of days is reset to zero. Minimum value: 1 Maximum value: 9999999 Default: none

Confirm that the backup settings pass validation:
- 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
```
If you are configuring the backup settings before installation, then skip the remaining steps and continue with the installation process. Verify that your backups are working after installation.
Apply the settings:
```
apicup subsys install <subsystem name>
```
Ensure that the changes were applied successfully:
```
apicup subsys health-check <subsystem name>
```
Take a new backup of your project directory.

Your backup configuration settings are stored in your project directory. Take a new backup of your project directory every time you update your backup settings or make any other configuration updates with the apicup command.
Verify that your backup settings are correct by running an on-demand backup: Running an on-demand backup of the management database.