This guide shows you how to configure Google Cloud's Agent for SAP to perform Backint based backup and recovery for SAP HANA.
For conceptual information about this feature, which can help in planning your implementation, see Backup and recovery for SAP HANA by using Backint.
For information about how to create Backint based backups and recover your SAP HANA by using them, see Back up and recover SAP HANA by using Backint.
Before you begin
- Validate your installation of version 3.6 (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 your SAP HANA database is running in an on-premises environment, then make sure to set up a service account and its key. For information about how to do this, 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 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.
- 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
-
Create a Cloud Storage bucket and configure it as follows:
-
Replace
STORAGE_CLASS
with your preferred storage class. -
Replace
LOCATION
with your preferred location (ASIA
,EU
, orUS
) -
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 instance 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.
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.
For a granular level of access, you can set the following IAM permissions to your custom role for your service account on a project level:
storage.objects.list
storage.objects.create
You must also set IAM Policies on your bucket by granting your principal the following IAM permissions:
storage.objects.get
storage.objects.update
storage.objects.delete
Add the following permissions if you want to perform multipart uploads:
storage.multipartUploads.create
storage.multipartUploads.abort
For more information about how to create a custom role, see Create and manage custom roles. For more information on granting a principal a custom role for bucket-level access, see Add a principal to a bucket-level policy.
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 instance metadata server:
oauth2.googleapis.com
, for authentication169.254.169.254
metadata.google.internal
If Google Cloud's Agent for SAP and your SAP HANA system are running on a Compute Engine instance 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 instance, then from the VM instances page in Google Cloud console, you can click the SSH button for your 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
If your SAP HANA database is running on a Compute Engine instance or a Bare Metal Solution server, then to configure the agent's Backint feature, run the
configurebackint
command. We recommend this approach over editing the agent's Backint configuration file./usr/bin/google_cloud_sap_agent configurebackint \ -f="PATH_TO_PARAMETERS_FILE" \ -bucket="BUCKET_NAME"
If your SAP HANA database is running in an on-premises environment, then configure the agent's Backint feature by running the following command:
/usr/bin/google_cloud_sap_agent configurebackint \ -f="PATH_TO_PARAMETERS_FILE" \ -bucket="BUCKET_NAME" \ -service_account_key="PATH_TO_KEY" \ -log_to_cloud=false \ -send_metrics_to_monitoring=false
Replace the following:
PATH_TO_PARAMETERS_FILE
: the path to yourPARAMETERS.json
Backint configuration fileBUCKET_NAME
: the name of the Cloud Storage bucket where you want to store your SAP HANA backupsPATH_TO_KEY
: the fully-qualified path to the JSON-encoded Google Cloud service account key that you set up
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: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 }
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 backupsservice_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.
If your SAP HANA database is running in an on-premises environment, then make sure to also set the following:
"log_to_cloud": false
"send_metrics_to_monitoring": false
Optionally, you can modify other configuration parameters. For information about these parameters, see Configuration parameters.
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 theglobal.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 theglobal.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. You need at least 18 GB of available disk space on your file system to run this built-in tool. 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 yourPARAMETERS.json
file
While using this tool, you can use the optional parameters
diagnose_file_max_size_gb
and diagnose_tmp_directory
. For more
information about these parameters, see their descriptions in
Configuration parameters.
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 |
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 |
Optional. Specify the name of the Cloud Storage bucket that the
agent reads during
While we recommend using this parameter to simplify configuration management for system
copy and system refresh operations, it's incompatible with the
|
log_to_cloud |
Optional. To redirect the Backint related logs of Google Cloud's Agent for SAP,
to Cloud Logging, specify
If your SAP HANA database is running in an on-premises environment, then
you must set this parameter's value to For information about the Backint related log file, see Logging. |
log_level |
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:
The default value is |
compress |
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 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 |
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 |
kms_key |
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
If your SAP HANA system is running on a Compute Engine instance, then the key must be accessible to that instance. If your SAP HANA system is running on a host other than a Compute Engine instance, then the Cloud KMS key must be accessible to the service account used by Google Cloud's Agent for SAP. For more information, see Service accounts. You cannot specify the |
folder_prefix |
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 This prefix is inserted as a folder between the
This parameter is available from version 3.1 of the agent. |
recovery_folder_prefix |
Optional. Specify to set a prefix for the folders in the
Cloud Storage bucket that the agent reads during
This parameter is available from version 3.1 of the agent.
While we recommend using this parameter to simplify configuration management for system
copy and system refresh operations, it's incompatible with the
|
shorten_folder_path |
Optional. Specify to shorten the object path in the Cloud Storage bucket that the agent reads and writes during all Backint operations. For more information, see Supported customizations. This parameter is available from version 3.3 of the agent. |
retries |
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 |
parallel_streams |
Optional. Specify this parameter to enable parallel upload of backups to your Cloud Storage bucket. The value you specify for this parameter is the maximum number of parallel upload streams that Google Cloud's Agent for SAP can use. The maximum value is 32. Any value exceeding this is capped to 32. The default value is 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 Don't enable parallel upload if any of the following apply:
If any of the preceding conditions are met, then the agent exits with a
status of |
xml_multipart_upload |
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 This parameter is available from version 3.2 of the agent. To use the XML API multipart upload method, We recommend using For information about how to create separate parameter files for log and
data backups, or how to set value for
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 |
Optional. Specify the storage class used when writing backups to the Cloud Storage bucket. The available storage classes are as follows:
The default value is This parameter is available from version 3.2 of the agent. |
metadata |
Optional. Specify key:value fields to store as metadata for objects when writing backups to the Cloud Storage bucket. This parameter is available from version 3.3 of the agent. The format in an example { "bucket": "example-bucket-backup", "metadata": {"key1": "value1", "key2": "value2"}, "log_to_cloud": true } The default metadata written is |
custom_time |
Otional. Specify a date and time that you want to set for the
This parameter is available from version 3.4 of the agent. You can set this parameter with the value From version 3.6 of the agent, you can set a future date for the
{ "bucket": "example-bucket-backup", "custom_time": "UTCNow+30d", "log_to_cloud": true } The following is an example of how you can specify this parameter with a
date-time value in your { "bucket": "example-bucket-backup", "custom_time": "2024-06-25T13:25:00Z", "log_to_cloud": true } |
rate_limit_mb |
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 |
If Google Cloud's Agent for SAP is not running on a Compute Engine instance, 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 instance, 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. |
diagnose_file_max_size_gb |
Optional. Specify the upper limit for the size of the temporary file, in GB, that the agent's self diagnostics tool creates and deletes. The default value is 16 GB. This parameter is available from version 3.3 of the agent. For the successful operation of the self diagnostics tool, you must
ensure that the available storage in your file system is at least 2-3 GB
more than the value of |
diagnose_tmp_directory |
Optional. Specify the directory used to read and write temporary files
for the self diagnostics tool
of the agent. The default value is This parameter is available from version 3.3 of the agent. |
send_metrics_to_monitoring |
Optional. Specifies whether or not the agent can collect metrics related to the status and throughput of files that are uploaded or downloaded during Backint operations. The agent sends the collected metrics to Cloud Monitoring. This parameter is available from version 3.3 of the agent. The default value is |
threads |
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 |
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
|
buffer_size_mb |
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 buffer size is 100 MB, which means that a single HTTPS request stream to or from Cloud Storage is kept open until 100 MB of data is transferred. The maximum buffer size is 250 MB. Because Google Cloud's Agent for SAP retries failed HTTPS 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. If you're using the |
retry_backoff_initial |
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
|
retry_backoff_max |
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
|
retry_backoff_multiplier |
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 |
log_delay_sec |
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 |
client_endpoint |
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 |
Troubleshooting
To troubleshoot problems with version 3.6 (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.
What's next
- To learn how to create Backint based backups and recover your SAP HANA database by using them, see back up and recover SAP HANA by using Backint.