Configuring portal database backups

Use the apicup command to configure scheduled portal database backups on VMware.

1. From your API Connect project directory, run the following commands to set the remote backup location and schedule:

   apicup subsys set <subsystem name> <property>=<value>

   For example:

   apicup subsys set ptl site-backup-host=mybackuphost.com
   apicup subsys set ptl site-backup-port=22
   apicup subsys set ptl site-backup-auth-user=mybackupauthusername
   apicup subsys set ptl site-backup-auth-pass=mybackupauthpassword
   apicup subsys set ptl site-backup-path=/site-backups
   apicup subsys set ptl site-backup-protocol=sftp
   apicup subsys set ptl site-backup-certs=<custom-s3-server-CA-cert>
   apicup subsys set ptl site-backup-s3-uri-style=<host-or-path>
   apicup subsys set ptl site-backup-schedule="0 2 * * *"
   apicup subsys set ptl site-priority-list=portal.a1.example.com/test-1/spacecatalog,portal.a1.example.com/test-4/cat3,portal.a1.example.com/test-3/cat1
   apicup certs set <subsystem name> site-backup-auth-ssh-key <ssh-key-file-path>

   The backup parameters are detailed in the following table.

   Table 1. Portal backup parameters

   Parameter	Description
   site-backup-host	The fully qualified domain name of the backup server, in lowercase only. For objstore type backup, specify the S3 endpoint with the corresponding S3 region in the format <S3endpoint>, or with an optional S3 region in the format <S3endpoint>/<S3region>. apicup subsys set ptl site-backup-host=s3.eu-gb.cloud-object-storage.appdomain.cloud or apicup subsys set ptl site-backup-host=s3.cloud-object-storage.appdomain.cloud/eu-gb For sftp type, the SFTP server hostname apicup subsys set ptl site-backup-host=my.sftp.backup.domain.example.com
   site-backup-port	The port for the protocol to connect to the site-backup-host. Defaults to 22 if not explicitly set. The backup port is not required for object storage but if specified, is typically port 443. apicup subsys set ptl site-backup-port=22
   site-backup-auth-user	The username for the host that is specified in site-backup-host. If you are using an object-store, the username is the S3 Secret Key ID. apicup subsys set ptl site-backup-auth-user=<user_name>
   site-backup-auth-pass	The password for the host that is specified in site-backup-host. If you are using an object-store, the password is the S3 Secret Access Key parameter. The password is stored in Base64 encoded format, and must not be edited directly in the apiconnect-up.yml file. apicup subsys set ptl site-backup-auth-pass=password
   site-backup-auth-ssh-key	OpenSSH key for database backups by using SFTP. Important: Use apicup certs to set this value. Do not use apicup subsys. Only OpenSSH keys are supported.1 apicup certs set ptl site-backup-auth-ssh-key=<ssh-key-file-path>
   site-backup-path	The location of the backups on the remote host: S3 - the name of your S3 bucket to store backup data, optionally followed by a / and then any subdirectories inside the bucket. Valid examples: bucket bucket/path bucket/lots/of/paths Example: apicup subsys set ptl site-backup-path=apic-backup SFTP - the full absolute path of the folder on the SFTP server, beginning with /. apicup subsys set ptl site-backup-path=</folder> When you specify a file path in a backup setting, be sure to escape any blank spaces in the path.
   site-backup-protocol	The protocol that is used to communicate with your remote backup endpoint. Specify one of the following values: sftp - for secure file transfer protocol local - for local storage objstore - for S3 compatible object storage Starting with v10.0.3.0, the default protocol is local (earlier releases used sftp as the default). For example: apicup subsys set ptl site-backup-protocol=local
   site-backup-certs	The name of a custom certificate that contains your upstream custom object-store CA certificate. This field accepts the name of the Kubernetes secret that contains your upstream custom S3 CA certificate. The key of the secret must be ca.crt and the value is the base64-encoded value of the CA certificate. If the server certificate that your object-store presents is signed by a well-known CA and includes any intermediate certificates in the chain, then you do not need to provide the CA certificate. If you are not sure what CA certificate your object-store uses, then configure portal database backups without setting site-backup-certs and verify that backups work and no TLS errors are logged. If you do need to provide the CA certificate then you must provide the entire chain in the ca.crt member of the secret, as follows: intermediate-certificate-1 intermediate-certificate-2 . . . intermediate-certificate-n root-certificate Where the first certificate in the ca.crt member (intermediate-certificate-1) is the issuer of the object-store server certificate, and each subsequent certificate in the ca.crt member is the issuer of the preceding certificate. The root certificate in the ca.crt member must be self-signed. If there are no intermediate certificates, then the ca.crt member contains only the root certificate. Follow these steps to create and assign the CA certificate: Log in to your portal VM. If you have a three replica deployment, log in to any of the portal VMs. ssh apicadm@<portal vm hostname> Switch to the root user: sudo -i Copy over the ca.crt file or create it on the VM by creating a file of the same name and pasting in the contents. Create a Kubernetes secret from the ca.crt file: kubectl create secret generic custom-portal-objstore-ca --from-file=ca.crt=/path/to/ca.crt Take a backup of the generated Kubernetes secret: kubectl get secret custom-portal-objstore-ca -o yaml > custom-portal-objstore-ca.yaml Keep the generated custom-portal-objstore-ca.yaml file in your project directory. Exit from the VM, and set the site-backup-certs property to custom-portal-objstore-ca: apicup subsys set ptl site-backup-certs=custom-portal-objstore-ca
   site-backup-s3-uri-style	Applies to object-store only. site-backup-s3-uri-style is an optional property. Indicates whether URIs to your object-store backup should use a host or a path value. When not specified, defaults to host. Valid values: host and path. Some custom object-store providers require the 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 accept only path style client communications. Important: Contact your object-store administrator before you set this property. If not properly configured, an object-store can reject connections from the client.
   site-backup-schedule	The schedule for how often automatic portal backups are run. The format for the schedule is any valid cron string, as follows: * * * * * - - - - - | | | | | | | | | +----- day of week (0 - 6) (Sunday=0) | | | +------- month (1 - 12) | | +--------- day of month (1 - 31) | +----------- hour (0 - 23) +------------- min (0 - 59) For example: 30 22 * * 1 runs backups at 22:00 on Mondays. The default backup schedule is 0 2 * * * (runs every day at 02:00). The time zone for backups is Coordinated Universal Time. apicup subsys set ptl site-backup-schedule="0 2 * * *"
   site-priority-list	Optional list of prioritized sites to restore. Default: empty. apicup subsys set <subsystem name> site-priority-list <comma-separated-list-of-sites> For example: apicup subsys set ptl site-priority-list portal.a1.example.com/e2etest-1/spacecatalog,portal.a1.example.com/e2etest-4/cat3,portal.a1.example.com/e2etest-3/cat1

2. You can review your portal backup settings with the apicup get command:

   apicup subsys get <subsystem name>

   The output from this command lists all of the subsystem settings, including backup, and indicates whether there are any errors. Fix any errors before you continue.

   For SFTP, to view the SSH key, use the apicup certs command:

   apicup certs get ptl site-backup-auth-ssh-key

3. Validate the installation with the new backup parameters by running the following command:

   apicup subsys get <subsystem name> --validate

   Correct any invalid values before you continue.

4. Activate the backup settings by running the following command:

   apicup subsys install <subsystem name>

5. Ensure that the changes were applied successfully:

   apicup subsys health-check <subsystem name>