Configure Backint based backup and recovery for SAP HANA

This guide shows you how to configure Google Cloud's Agent for SAP to perform Backint based backup and recovery for SAP HANA.

For information about this feature, see Backint based backup and recovery for SAP HANA.

For information about performing backup and recovery operations for SAP HANA using Backint, see Performing backup and recovery using Backint.

Before you begin

Validate your installation of version 3.2 (latest) of Google Cloud's Agent for SAP. For instructions, see the installation guide for your scenario.
If you have installed the agent on a Bare Metal Solution server, then make sure that you have completed the required prerequisites and set up a service account. For instructions, see Configure Google Cloud's Agent for SAP on Linux.
If you need to enable this feature for an instance of Google Cloud's Agent for SAP that is running on a host other than a Compute Engine Virtual Machine (VM) instance or a Bare Metal Solution server, then you must create an incident with SAP support in component BC-OP-LNX-GOOGLE so that both SAP and Google Cloud can evaluate your configuration.
Install SAP HANA:
- For information about automating the installation of SAP HANA on Google Cloud using Terraform, see the deployment guide for your scenario.
- For information about installing SAP HANA on Bare Metal Solution, see SAP HANA on Bare Metal Solution planning guide.

Create a Cloud Storage bucket

Before you enable the Backint feature of Google Cloud's Agent for SAP, make sure that there exists a Cloud Storage bucket to store your backups. If you have a Cloud Storage bucket, then you can skip this section.

For information about storing backups in Cloud Storage buckets, see Storing backups in Cloud Storage buckets.

To create a Cloud Storage bucket:

Google Cloud console

In the Google Cloud console, go to the Cloud Storage Buckets page.
Go to Buckets page
Click Create bucket.
On the Create a bucket page, enter your bucket information. To go to the next step, click Continue.
- For Name your bucket, enter a name that meets the bucket naming requirements.
- For Choose where to store your data, do the following:
  - Select a Location type option.
  - Select a Location option.
- For Choose a default storage class for your data, select a storage class.
- For Choose how to control access to objects, select an Access control option.
- For Advanced settings (optional), specify an encryption method, a retention policy, or bucket labels.
Click Create.

Command line

Replace STORAGE_CLASS with your preferred storage class.
Replace LOCATION with your preferred location (ASIA, EU, or US)
Replace BUCKET_NAME with a bucket name that meets the bucket name requirements.

gcloud storage buckets create gs://BUCKET_NAME --default-storage-class STORAGE_CLASS --location LOCATION

Set IAM roles

To allow Google Cloud's Agent for SAP perform backup and recovery operations for SAP HANA, you must ensure that the service account being used by your Compute Engine VM or Bare Metal Solution server includes the IAM role Storage Object Admin (storage.objectAdmin).

To add this role to your service account, follow these steps:

In the Google Cloud console, go to the IAM page.

Go to IAM
Select your Google Cloud project.
Identify the service account to which you want to add the role.
- If the service account isn't already on the principals list, then it doesn't have any roles assigned to it. Click Add and enter the email address of the service account.
- If the service account is already on the principals list, then it has existing roles. Click the Edit button for the service account that you want to edit.
From the list of available roles, select Storage Object Admin.
Click Add or Save to apply the roles to the service account.

Enable access to Cloud APIs and metadata servers

Google Cloud's Agent for SAP requires access to the following Google Cloud IP addresses and hosts during the backup and recovery operations:

For access to Cloud Storage, storage.googleapis.com.
For the Compute Engine VM instance metadata server:
- oauth2.googleapis.com, for authentication
- 169.254.169.254
- metadata.google.internal

If Google Cloud's Agent for SAP and your SAP HANA system are running on a Compute Engine VM that does not have access to the internet, then you need to configure Private Google Access so that the agent can interact with Cloud Storage and, if using a dedicated service account, authenticate itself with Google Cloud. For instructions, see Configuring Private Google Access.

Enable the Backint feature

To enable the Backint feature of Google Cloud's Agent for SAP, complete the following steps:

Connect to your SAP HANA host by using SSH.

If your host is a Compute Engine VM, then from the VM instances page in Google Cloud console, you can click the SSH button for your VM instance, or use your preferred SSH method.
Switch to the SAP HANA system administrator:
```
sudo su - SID_LCadm
```
Replace SID_LC with the SID. Use lowercase for any letters.

This command also sets several environment variables, including $SAPSYSTEMNAME, which is set with the SID of your SAP HANA database.
Enable the Backint feature for Google Cloud's Agent for SAP:
```
/usr/bin/google_cloud_sap_agent installbackint
```
Alternatively, to install the Backint related files on a host with a different SID, include the sid flag:
```
/usr/bin/google_cloud_sap_agent installbackint -sid=DIFFERENT_SID_LC
```
Replace DIFFERENT_SID_LC with the SID of the required SAP HANA instance. Use lower case for any letters.

After the command is run successfully, all files related to the Backint feature of Google Cloud's Agent for SAP are installed in the directory /usr/sap/SID/SYS/global/hdb/opt/backint/backint-gcs/. This includes files that are necessary for integrating the agent with SAP HANA. It also detects Cloud Storage Backint agent for SAP HANA on your host, disables that agent, and copies its files to a recoverable directory on your host. For more information, see Upgrade from Backint agent.
Configure the Backint feature:
Run command
To configure the agent's Backint feature, run the configurebackint command. We recommend this approach over editing the Backint configuration file.
```
/usr/bin/google_cloud_sap_agent configurebackint \
  -f="PATH_TO_PARAMETERS_FILE" \
  -bucket="BUCKET_NAME"
```
Replace the following:
- PATH_TO_PARAMETERS_FILE: the path to your PARAMETERS.json Backint configuration file
- BUCKET_NAME: specify the name of the Cloud Storage bucket where you want to store your SAP HANA backups
  
  Optionally, you can set more parameters while running this command. For information about these parameters, see Configuration parameters.
Edit configuration file
As an alternative to running the agent's configurebackint command, you edit the Backint configuration file as follows:
1. Open the Backint configuration file:
```
/usr/sap/SID/SYS/global/hdb/opt/backint/backint-gcs/parameters.json
```
  Replace SID with the SID of the SAP system where you installed the Backint related files.
  
  The following is an example of what the configuration file contains:
```
{
 "bucket": "",
 "log_to_cloud": true
}
```
2. To allow Google Cloud's Agent for SAP to perform Backint based backup and recovery operations for your SAP HANA system, edit the configuration file and then specify the following parameters:
  - bucket: specify the name of the Cloud Storage bucket where you want to store your SAP HANA backups
  - service_account_key: if you have created a service account for Google Cloud's Agent for SAP, then specify the absolute path to the directory on your host where you've uploaded the corresponding JSON-encoded service account key
  For more information, see Service account considerations.
3. Optionally, you can modify other configuration parameters. For information about these parameters, see Configuration parameters.
4. Save the configuration file.

Customize the Backint configuration file

Optionally, after you enable the Backint feature of Google Cloud's Agent for SAP, you can perform the following customizations:

Rename the parameters.json file.

To indicate this renaming, this file is referred to as PARAMETERS.json in the Google Cloud's Agent for SAP documentation.
Create a separate configuration file for each of the following: SAP HANA data volume, SAP HANA log volume, and SAP HANA backup catalog.

Make sure to set a unique name for each configuration file.
Move these configuration files to a different directory. For example, in a scale-out deployment, you can store the Backint related configuration files of all your nodes in a shared directory that is accessible to the nodes. This can make it easier for you to manage these files.

If you perform any of these customizations, then make sure to appropriately specify the filename and its path for the parameters in your SAP HANA's global.ini file. For instructions, see Configure SAP HANA for the Backint feature.

Configure SAP HANA for the Backint feature

After you've enabled the Backint feature of Google Cloud's Agent for SAP, you need to configure your SAP HANA system to use this feature:

Use SAP HANA Studio or SAP HANA Cockpit to edit the global.ini configuration file.

In the backup section of the global.ini file, specify values for the following parameters:

Parameter	Value
`data_backup_parameter_file`	`/usr/sap/SID/SYS/global/hdb/opt/backint/backint-gcs/PARAMETERS_DATA.json`.
`parallel_data_backup_backint_channels`	For multistreaming data backups, specify the number of channels considering the type of Cloud Storage bucket you're using, the required performance, and the disk throughput.
`log_backup_using_backint`	If you're using a separate configuration file for the SAP HANA backup log volume, then specify the value `true`.
`log_backup_parameter_file`	If you're using a separate configuration file for the SAP HANA backup log volume, then specify the following value: `/usr/sap/SID/SYS/global/hdb/opt/backint/backint-gcs/PARAMETERS_LOG.json`. Replace `PARAMETERS_LOG` with the name of the configuration file that you're using for the backups of the SAP HANA log volume.
`catalog_backup_using_backint`	If you're using a separate configuration file for the SAP HANA backup catalog, then specify the value `true`.
`catalog_backup_parameter_file`	If you're using a separate configuration file for the SAP HANA backup catalog, then specify the following value: `/usr/sap/SID/SYS/global/hdb/opt/backint/backint-gcs/PARAMETERS_CATALOG.json`. Replace `PARAMETERS_CATALOG` with the name of the configuration file that you're using for the backups of the SAP HANA backup catalog.

The following is an example of a global.ini file that is configured to use the Backint feature of Google Cloud's Agent for SAP:

[backup]
log_backup_using_backint = true
catalog_backup_using_backint = true
parallel_data_backup_backint_channels = 16
catalog_backup_parameter_file = /usr/sap/SID/SYS/global/hdb/opt/backint/backint-gcs/parameters-catalog.json
data_backup_parameter_file = /usr/sap/SID/SYS/global/hdb/opt/backint/backint-gcs/parameters-data.json
log_backup_parameter_file = /usr/sap/SID/SYS/global/hdb/opt/backint/backint-gcs/parameters-log.json

In the persistence section of the global.ini file, specify values for the following parameters:
- basepath_logbackup: specify the directory in your file system where SAP HANA can store log backups when it is not able to connect to your Cloud Storage bucket; make sure that this directory has enough space to store backups.
- basepath_catalogbackup: specify the directory in your file system where SAP HANA can store backups of the SAP HANA backup catalog when it is not able to connect to your Cloud Storage bucket; make sure that this directory has enough space to store backups.

Validate backup and recovery

After you enable the Backint feature of Google Cloud's Agent for SAP, make sure to validate it by creating and restoring a backup in a test system.

For testing, you can use the built-in self diagnostics tool of the agent. To use this built-in tool to validate backup and recovery, run the following command:

sudo /usr/bin/google_cloud_sap_agent backint -u=IDENTIFIER -p=PATH_TO_PARAMETERS_FILE -f=diagnose

Replace the following:

IDENTIFIER: a value that identifies the execution of the command. This identifier is used to name the temporary folder that is created in the Cloud Storage bucket while performing the diagnostics.
PATH_TO_PARAMETERS_FILE: the path to your PARAMETERS.json file

If you had installed the Backint agent on your host, then the first time you use Google Cloud's Agent for SAP to perform a backup operation, Google Cloud's Agent for SAP creates JSON versions of the text configuration files. For more information, see Upgrade from Backint agent.

Example configuration file

The following is a completed PARAMETERS.json configuration file of the Backint feature of Google Cloud's Agent for SAP:

{
  "bucket": "example-bucket-backup",
  "recovery_bucket": "example-bucket-recovery",
  "parallel_streams": 8,
  "service_account_key": "path/to/key/file.json",
  "rate_limit_mb": 100,
  "log_to_cloud": true,
  "log_level": "DEBUG"
}

Configuration parameters

The following table explains the configuration parameters of Google Cloud's Agent for SAP that are specific to the Backint feature.

For information about the mapping between the configuration parameters of the Backint agent and Google Cloud's Agent for SAP, see Mapping of configuration parameters.

For information about the configuration parameters of Google Cloud's Agent for SAP, including the parameters related to metrics collection, see the installation guide for your scenario.

Parameters
`bucket`	`String` Specify the name of the Cloud Storage bucket that the Google Cloud's Agent for SAP writes to and reads from. The agent creates backup objects with the storage class of the bucket and supports all storage classes. The agent uses the Compute Engine default encryption to encrypt data at rest.
`recovery_bucket`	`String` Optional. Specify the name of the Cloud Storage bucket that the agent reads during `RESTORE` operations. If you don't specify this parameter, then the agent uses the bucket specified for the `bucket` parameter for all operations: `BACKUP`, `RESTORE`, `INQUIRE`, `DELETE`, and `DIAGNOSE` operations.
`log_to_cloud`	`Boolean` Optional. To redirect the Backint related logs of Google Cloud's Agent for SAP, to Cloud Logging, specify `true`. The default value is `true`. For information about the Backint related log file, see Logging.
`log_level`	`String` Optional. Specify the logging level for the Backint feature of Google Cloud's Agent for SAP, set the required value. The available log levels are as follows: `DEBUG` `INFO` `WARNING` `ERROR` The default value is `INFO`. Don't change the logging level unless you are directed by Cloud Customer Care.
`compress`	`Boolean` Optional. Specify whether or not Google Cloud's Agent for SAP is to enable compression while writing backups to the Cloud Storage bucket. The default value is `false`. We recommend that you don't enable compression. Although compression reduces the cost of storage for backups in Cloud Storage, it requires more CPU processing during backup operations and slows down the effective backup throughput. Regardless of this parameter, Google Cloud's Agent for SAP supports both compressed and uncompressed backup files during a restore operation.
`encryption_key`	`String` Optional. Specify the path to the customer-supplied encryption key that you've configured your Cloud Storage bucket to use to encrypt backups. Make sure to specify a fully-qualified path to a base64-encoded AES-256 key. You cannot specify the `encryption_key` parameter with the `kms_key` or `parallel_streams` parameters.
`kms_key`	`String` Optional. Specify the path to the customer-managed encryption key that you've configured your Cloud Storage bucket to use to encrypt backups. Specify the path by using the format `projects/KMS_PROJECT_ID/locations/LOCATION/keyRings/KEY_RING_NAME/cryptoKeys/KMS_KEY_NAME`, where: `KMS_PROJECT_ID`: the ID of the Google Cloud project where the KMS key exists `LOCATION`: the Cloud KMS location where your KMS key exists `KEY_RING_NAME`: the name of the key ring that contains the KMS key `KMS_KEY_NAME`: the name of the KMS key If your SAP HANA system is running on a Compute Engine VM, then the key must be accessible to the VM. If your SAP HANA system is running on a host other than a Compute Engine VM, then the Cloud KMS key must be accessible the service account used by Google Cloud's Agent for SAP. For more information, see Service accounts. You cannot specify the `kms_key` parameter with the `encryption_key` or `parallel_streams` parameters.
`folder_prefix`	`String` Optional. Specify to set a prefix for the folders in the Cloud Storage bucket that the Google Cloud's Agent for SAP writes to and reads from. You can use this parameter to organize backups of different SAP HANA instances in the same Cloud Storage bucket. You can specify a single folder, like `folder1` or a multi-level path of folders, like `folder1/folder2/folder3`. This prefix is inserted as a folder between the `BUCKET_NAME` and `SID` values in the path for your SAP HANA backups in Cloud Storage. For more information, see Backup organization in the bucket.
`recovery_folder_prefix`	`String` Optional. Specify to set a prefix for the folders in the Cloud Storage bucket that the agent reads during `RESTORE` operations. You can use this parameter to organize backups of different SAP HANA instances in the same Cloud Storage bucket. You can specify a single folder, like `folder1` or a multi-level path of folders, like `folder1/folder2/folder3`.
`retries`	`Int` Specifies the maximum number of times that Google Cloud's Agent for SAP retries a failed attempt to read or write to Cloud Storage. The default value is `5`, which is also the recommended value.
`parallel_streams`	`Int` Optional. Specify to enable parallel upload and specifies the maximum number of parallel upload streams that Google Cloud's Agent for SAP can use. The default value of `1` disables parallel uploads. The maximum value is 32. Any value exceeding this is capped to 32. If you want to enable parallel upload for streaming data, or if your Cloud Storage bucket has a retention policy, then you must also set `xml_multipart_upload` to `true`. Don't enable parallel upload if any of the following apply: The target Cloud Storage bucket uses a retention policy. You have specified the `encryption_key` or `kms_key` parameters. If any of the preceding conditions are met, then the agent exits with a status of `1`. For information about parallel uploads, see Parallel uploads.
`xml_multipart_upload`	`Boolean` Optional. Specifies whether or not the XML API multipart upload method is used when writing backups to the Cloud Storage bucket. The default value is `false`. To use the XML API multipart upload method, `parallel_streams` must have a value greater than `1`. We recommend using `xml_multipart_upload` only to parallelize log or catalog backups. To parallelize data backups, we recommend setting `parallel_data_backup_backint_channels` in the `backup` section of your `global.ini` file. For information about how to create separate parameter files for log and data backups, or how to set value for `parallel_data_backup_backint_channels`, see Configure SAP HANA for the Backint feature. In case of any failure, the XML multipart uploads are aborted automatically and the data being uploaded is deleted. We also recommend setting lifecycle conditions for AbortIncompleteMultipartUpload to ensure that data is deleted if the upload operation fails.
`storage_class`	`String` Optional. Specify the storage class used when writing backups to the Cloud Storage bucket. The available storage classes are as follows: `STANDARD` `NEARLINE` `COLDLINE` `ARCHIVE` The default value is `STANDARD`.
`rate_limit_mb`	`Int` Optional. Specify the upper limit, in MB, for the outbound network bandwidth of Compute Engine during backup or restore operations. By default, Google Cloud does not limit the network bandwidth for Google Cloud's Agent for SAP. When you set this parameter, the throughput might vary, but won't exceed the specified limit.
`service_account_key`	`String` If Google Cloud's Agent for SAP is not running on a Compute Engine VM, then specify the fully-qualified path to the JSON-encoded Google Cloud service account. If Google Cloud's Agent for SAP is running on a Compute Engine VM, then we recommend that you don't specify this parameter and instead use the Compute Engine default authentication. Specifying this parameter directs Google Cloud's Agent for SAP to use the service account key when authenticating to Cloud Storage.
`threads`	`Int` This is an optional advanced tuning parameter. Don't modify this parameter unless instructed to do so by Customer Care. Its default value rarely needs to be modified. Specify the number of worker threads. The default value is the number of processors in the host.
`file_read_timeout_ms`	`Int` This is an optional advanced tuning parameter. Don't modify this parameter unless instructed to do so by Customer Care. Its default value rarely needs to be modified. Specify the maximum amount of time, in milliseconds, that Google Cloud's Agent for SAP waits to open the backup file. The default value is `60000` (60 seconds).
`buffer_size_mb`	`Int` This is an optional advanced tuning parameter. Don't modify this parameter unless instructed to do so by Customer Care. Its default value rarely needs to be modified. Specify this parameter to control the size of HTTPS requests to Cloud Storage during backup or restore operations. The default chunk size is 100 MB, which means that a single HTTP request stream to or from Cloud Storage is kept open until 100 MB of data is transferred. Because Google Cloud's Agent for SAP retries failed HTTP requests multiple times before failing an operation, buffer sizes smaller than 100 MB result in less data that needs to be retransmitted if a request fails. Larger buffer sizes can improve throughput, but require more memory usage and more time to resend data in the event of a request failure.
`retry_backoff_initial`	`Int` This is an optional advanced tuning parameter. Don't modify this parameter unless instructed to do so by Customer Care. Its default value rarely needs to be modified. Specify the initial value, in seconds, for the retry period used in the exponential backoff network retries. The default value is `10`.
`retry_backoff_max`	`Int` This is an optional advanced tuning parameter. Don't modify this parameter unless instructed to do so by Customer Care. Its default value rarely needs to be modified. Specify the maximum value, in seconds, for the retry period used in the exponential backoff network retries. The default value is `300`.
`retry_backoff_multiplier`	`Float` This is an optional advanced tuning parameter. Don't modify this parameter unless instructed to do so by Customer Care. Its default value rarely needs to be modified. Specify the multiplier for the retry period used in the exponential backoff network retries. The multiplier must be greater than `1` and the default value is `2`.
`log_delay_sec`	`Int` This is an optional advanced tuning parameter. Don't modify this parameter unless instructed to do so by Customer Care. Its default value rarely needs to be modified. Specify the logging delay, in seconds, for progress updates during reads and writes to the Cloud Storage bucket. The default value is `60`.
`client_endpoint`	`String` This is an optional advanced tuning parameter. Don't modify this parameter unless instructed to do so by Customer Care. Its default value rarely needs to be modified. Specify the endpoint of the Cloud Storage client. The default value is `storage.googleapis.com`.

Troubleshooting

To troubleshoot problems with version 3.2 (latest) of Google Cloud's Agent for SAP, see Google Cloud's Agent for SAP troubleshooting guide.

Get support

If you need help resolving a problem with Google Cloud's Agent for SAP, then gather the required diagnostic information and contact Cloud Customer Care. For more information, see Google Cloud's Agent for SAP for SAP HANA diagnostic information.