Cloud Storage Backint agent for SAP HANA installation guide

These instructions show you how to install and configure the Cloud Storage Backint agent for SAP HANA (Backint agent) on a Compute Engine VM that has SAP HANA installed.

For information about the configuration options of the Backint agent, see Cloud Storage Backint agent for SAP HANA overview.

Prerequisites

Before you can install the Backint agent, you first need to install SAP HANA. To install SAP HANA on Google Cloud, see SAP HANA Deployment Guide.

Creating a Cloud Storage bucket for backups

Before you can configure the Backint agent, you need to create a Cloud Storage bucket to hold the backups.

To create a Cloud Storage bucket, use the Cloud Console.

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

Open the Cloud Storage browser in Cloud Console.

Open the Cloud Storage browser
Click CREATE BUCKET.
Name your bucket and then click Continue.
Follow the prompts to select your bucket options.

Note: The encryption options presented in the Cloud Console during bucket creation apply generally to objects at rest in the bucket. The Backint agent provides additional encryption options for your backups that are independent of the bucket encryption options.
Click Create.
To configure bucket permissions, click the permissions tab. By default, as owner of the bucket, you have read-write access to the bucket. You can also give other members in your group or individual users to access your bucket.

Installing the Backint agent on your SAP HANA VM

The Backint agent is installed in the same shared file system as the SAP HANA database.

In an SAP HANA scale-out deployment, install the Backint agent on each node of the SAP HANA system. To simplify administration, you can store your configuration files in a shared location that is accessible to all of the nodes in your deployment, such as /hana/shared.

Connect to your VM by using SSH. From the Compute Engine VM instances page, you can click the SSH button for your VM instance, or you can use your preferred SSH method.
Switch to the SAP HANA system administrator.
```
sudo su - sidadm
```
Download and install the Backint agent.
```
curl https://storage.googleapis.com/cloudsapdeploy/backint-gcs/install.sh | bash
```
Note: if you are updating an existing instance of the Backint agent to a new version, follow the instructions in Updating the Backint agent to a new version.

The install.sh script takes the following actions:
- Installs the Backint agent as a JAR file in /usr/sap/SID/SYS/global/hdb/opt/backint/backint-gcs.
- Downloads a compatible version of the Java Runtime Environment.
- Sets up the backint script that invokes the Backint agent. Do not modify the backint script unless instructed to do so by Google Cloud support.
- Upon completion, issues a message that instructs you to update the parameters.txt file and to set up authentication.
If SAP HANA is not running on Google Cloud or if you need the Backint agent to use a different set of resource permissions than the host VM uses, create a service account for the Backint agent.
1. Open the IAM & admin Service accounts page in Google Cloud Console.
  
  Go to the Service Accounts page
2. Click + CREATE SERVICE ACCOUNT.
3. Specify a name for the service account and, optionally, a description.
4. Click CREATE.
5. On the Service account permissions panel, click Continue to create the service account without permissions.
6. As appropriate, grant users access to the service account.
7. Click Done.
8. On the Service accounts page in the Cloud Console, click on the service account that you just created.
9. On the Service account details page under Keys, click on ADD KEY > Create new key to create a service account key.
10. Accept JSON as the key type and click CREATE. A private key is saved to your computer.
Upload the JSON key file to the SAP HANA host.
- Store the .json file in a directory that the sidadm user can access, such as /usr/sap/SID/home
- Make sure that the sidadm user is authorized to read the file.
Update your Cloud Storage bucket to grant the service account permission to use the bucket:
1. Click on your bucket name in the Cloud Storage browser.
  
  Open Cloud Storage browser
2. Click the Permissions tab.
3. Click Add members.
4. In the New members field, enter the full email address of the service account. For example:
  
  backint-test@my-project.iam.gserviceaccount.com

Configuring the Backint agent and SAP HANA

You configure the Backint agent by editing the parameters.txt file. SAP HANA is configured by updating the global.ini file.

Configure the Backint agent.
1. Use your preferred method to edit the parameters.txt file, which is installed in the following directory:
```
/usr/sap/SID/SYS/global/hdb/opt/backint/backint-gcs/parameters.txt
```
  For descriptions of the configuration parameters, as well as performance recommendations, see Configuration options for the Backint agent.
2. In parameters.txt, add the name of the Cloud Storage bucket to use for the backups.
```
#BUCKET bucket-name
```
3. If you created a service account and private key for the Backint agent, add the path to the JSON key file to parameters.txt.
```
#SERVICE_ACCOUNT /path/key-file-name.json
```
The following example shows the contents of a valid parameters.txt file:
```
#BUCKET hana-backups
#DISABLE_COMPRESSION
#SERVICE_ACCOUNT #SERVICE_ACCOUNT /usr/sap/ABC/home/example-project-123456-d591d63bba6f.json
```

Configure SAP HANA to use the Backint agent.

Use SAP HANA Studio or SAP HANA Cockpit to set the following parameters in the backup section of the global.ini configuration file to the values shown in the table. You do not need to restart SAP HANA after making these changes.

Parameter	Value
`catalog_backup_parameter_file`	`/usr/sap/SID/SYS/global/hdb/opt/backint/backint-gcs/parameters.txt`
`catalog_backup_using_backint`	`true`
`data_backup_parameter_file`	`/usr/sap/SID/SYS/global/hdb/opt/backint/backint-gcs/parameters.txt`
`log_backup_parameter_file`	`/usr/sap/SID/SYS/global/hdb/opt/backint/backint-gcs/parameters.txt`
`log_backup_using_backint`	`true`

Use SAP HANA Studio to specify the same value for both basepath_catalogbackup and basepath_logbackup in the persistence section of the global.ini file. For example:

Test the installation by creating a backup in the Cloud Storage bucket and restoring from the backup.
To support the Backint agent automatic update function, enable remote HTTP requests from the SAP HANA VM to https://www.googleapis.com/.
Optionally, enable Cloud Logging.
- If SAP HANA is running on Google Cloud, add the com.google.cloud.logging.LoggingHandler handler to the com.google.cloud.partners.handlers property in the /usr/sap/SID/SYS/global/hdb/opt/backint/backint-gcs/logging.properties file.
- If SAP HANA is running outside of Google Cloud, install Cloud SDK and configure the application-default login by using the gcloud auth application-default login command.

Updating the Backint agent to a new version

To update the Backint agent to a new version:

Enable remote HTTP requests from the SAP HANA host to https://www.googleapis.com/.

As sidadm on the SAP HANA host, install the new version:

curl https://storage.googleapis.com/cloudsapdeploy/backint-gcs/update.sh | bash

The update.sh script takes the following actions:

Installs the new version of the Backint agent in /usr/sap/SID/SYS/global/hdb/opt/backint/backint-gcs.
Updates the backint script to invoke the new Backint agent version.
Updates the version number in VERSION.txt.
Stores the update.sh script locally in /usr/sap/SID/SYS/global/hdb/opt/backint/backint-gcs.
Issues a message when it's done.

The update process does not modify or replace your existing parameters.txt file. To use any new options introduced in the new version, you need to add the corresponding parameters to your existing parameters.txt file.

The update process leaves the old version of the Backint agent in the /usr/sap/SID/SYS/global/hdb/opt/backint/backint-gcs directory, so that you can fall back to the old version if needed.

Falling back to a previous version

If you encounter problems with a new version of the Backint agent and Google Cloud or SAP support advises you to fall back to your previous version, you can do so by editing the backint script file.

You do not need to remove any parameters that you might have added for the new version in the parameters.txt file. The previous version of the Backint agent ignores the parameters from the newer version.

To fallback to a previous version:

As sidadm, open the backint script for editing. For example:

vi /usr/sap/SID/SYS/global/hdb/opt/backint/backint-gcs/backint

Change the name of the Backint agent JAR file to the name of the JAR file of the previous version.

For example, if you are falling back from version 1.0.6 to version 1.0.4, you would change:
```
-jar /usr/sap/ABC/SYS/global/hdb/opt/backint/backint-gcs/sap-backint-gcs-1.0.6.jar
```
to:
```
-jar /usr/sap/ABC/SYS/global/hdb/opt/backint/backint-gcs/sap-backint-gcs-1.0.4.jar
```
Open the VERSION.txt file for editing and specify the previous version number. You need to do this so that the update mechanism knows which version you are running.
```
vi /usr/sap/SID/SYS/global/hdb/opt/backint/backint-gcs/VERSION.txt
```
Test the Backint agent by triggering a backup.

Troubleshooting

If errors occur during the execution of a backup or a recovery, error messages are displayed in SAP HANA Studio or SAP HANA Cockpit, so check there first for information about the cause of an error. This information might be displayed in the backup.log and backint.log trace files. Be sure to select the relevant database name when multitenant database containers (MDC) are used.

Ensure that you installed the Backint agent as the sidadm user.

Log files

If errors occur, review the following logs:

SAP HANA backup.log, which contains information about the SAP HANA backup and recovery operations.
SAP HANA backint.log, which contains the calls to the backup interface that is used by the Backint agent and other external backup tools.
Backint agent log files, which contain Backint agent installation and operational events. The Backint agent log files are located in /usr/sap/SID/SYS/global/hdb/opt/backint/backint-gcs/logs. The Backint agent logs can include indications of communication errors with Cloud Storage and related configuration or permissions issues.
The Google Cloud logs, which can contain errors related to the service account that is used by the Backint agent. To review the Google Cloud logs, see the Logs Viewer page in Cloud Console.

Also check the disk and network I/O information on the host VM to verify activity.

For more information about Backint agent logging, see Logging for the Backint agent.

Connectivity issues

If the Backint agent can't connect to the Cloud Storage bucket, review the configuration steps. In particular, check the following items:

Retry the failed backup or restore to make sure that the error wasn't just a momentary connectivity issue.
If you are using the service account of the host VM with the Backint agent, the access scope for Storage is listed as Read Write under Cloud API access scopes on the VM instance details page in the Cloud Console. If it is not, stop the instance and edit the access scope.
If you created a service account for the Backint agent:
- On the Permissions tab of the Bucket details page in the Cloud Console, confirm that the Backint agent service account is listed and that it has the Storage Object Admin role.
- Confirm that you created a private key, stored it on the SAP HANA VM, and correctly specified the path to the JSON key file in the Backint agent configuration file, /usr/sap/SID/SYS/global/hdb/opt/backint/backint-gcs/parameters.txt.
All parameters are specified correctly in both the parameters.txt Backint agent configuration file and the SAP HANA global.ini file.

You can test access to the Cloud Storage bucket from the SAP HANA host by using the Cloud Storage gsutil tool that is included with the Cloud SDK. Using the gsutil tool, save and access a text file on the Cloud Storage bucket:

If you are not using the default service account, authenticate with Google Cloud either as a user that is authorized to the Cloud Storage bucket or the Backint agent service account:
```
gcloud auth login user-account
```
Or:
```
gcloud auth activate-service-account --key-file=/path/key-file-name.json
```
For more information about Cloud Storage authentication of a service account, see gsutil authentication.
Confirm that you can list the objects that are stored in the bucket:
```
gsutil ls gs://bucket/
```
Create a test file:
```
touch test.txt
```
Confirm that you can write the test file to the bucket:
```
gsutil cp test.txt gs://bucket/test.txt
```
Confirm that you can read the test file in the bucket:
```
gsutil cp gs://bucket/test.txt
```

Low throughput

If your throughput is lower than expected, verify that compression is disabled.

To disable compression, add the #DISABLE_COMPRESSION flag to the Backint agent parameters.txt file.

Also, note that multi-stream backups apply only to data backups that are greater than 128 GB.

Multistreaming errors

If you get errors while multistreaming, change the number of streams to one (1) to see if the error is related to the number of streams.

For more information about Backint agent logging, see Multistreaming data backups with the Backint agent.

Getting support for the Backint agent

If you need help resolving a problem with SAP HANA backups that use the Backint agent, create an incident in the SAP incident processing system, using component HAN-DB-BAC, as indicated by SAP Note 2705632.

If SAP determines that the root cause is in the Google Cloud software, SAP development support transfers the incident to the BC-OP-LNX-GOOGLE component, which Google Cloud monitors at all times.

In addition to the diagnostic information requested in SAP Note 2705632, gather the following additional diagnostic information:

Relevant extracts of the /var/log/messages on the HANA system affected from around the time of the issue.
The SAP HANA backup.log and backint.log files. Unless the issue also occurs with the SYSTEM database, you need the files only for the tenant database.
The Backint agent parameters.txt file and the log files in the backint-gcs directory, or an export of Cloud Logging logs, if you have activated Logging.
The global.ini entries for backup:
- backint_response_timeout
- data_backup_buffer_size
- parallel_data_backup_backint_channels
The software versions of SAP HANA, the operating system, and the Backint agent that you are using. The version of Backint agent is listed in the installation.log file.
The size of your backup.
Information about the IAM service account that the Backint agent is using to access Cloud Storage.
Information about whether previous backup or restore attempts from this host VM were successful.

For more information from SAP about getting support for SAP HANA, see the "Getting Support" section in the SAP HANA Administration Guide.