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).

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.

For information about installing SAP HANA on Bare Metal Solution, see the SAP HANA on Bare Metal Solution planning guide.

If the host VM does not have access to the internet, you need to configure Private Google Access so that Backint agent can access the Google Cloud APIs. To configure Private Google Access, see Configuring Private Google Access.

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 console.

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

Open the Cloud Storage browser in 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 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 allow other principals to access your bucket.

Installing the Backint agent on the SAP HANA host

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 SAP HANA host by using SSH. If your host is a Compute Engine VM, from 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 - SID_LCadm
```
Download and install the Backint agent.
```
curl -O https://storage.googleapis.com/cloudsapdeploy/backint-gcs/install.sh
chmod +x install.sh
./install.sh
```
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 Cloud Customer Care.
- Upon completion, issues a message that instructs you to update the parameters.txt file and to set up authentication. See Configuring the Backint agent and SAP HANA for more details.
If any of the following scenarios apply to you, you need to create a service account for the Backint agent:
- You need the Backint agent to use a different set of resource permissions than your host Compute Engine VM uses.
- SAP HANA is running on Bare Metal Solution.
- SAP HANA is not running on Google Cloud.
To create a service account for the Backint agent:
1. In the console, go to the Service accounts page.
  
  Go to the Service Accounts page
2. Select your Google Cloud project.
3. Click Create Service Account.
4. Specify a name for the service account and, optionally, a description.
5. Click Create and Continue.
6. Click Continue to create the service account without permissions.
7. As appropriate, grant other users access to the service account.
8. Click Done.
9. On the Service accounts page in the console, click the email address of the service account that you just created.
10. Under the service account name, click the Keys tab.
11. Click the Add Key drop-down menu, and then select Create new key to create a service account key.
12. 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 SID_LCadm user can access, such as /usr/sap/SID/home
- Make sure that the SID_LCadm 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 principals.
4. In the New principals field, enter the full email address of the service account. For example:
  
  backint-test@my-project.iam.gserviceaccount.com
5. Click on the Select a role drop down and enter Storage Object Admin.
6. Click Save.

Configuring the Backint agent and SAP HANA

You configure the Backint agent by specifying parameters in a plain text configuration file.

You can use the same single configuration for all backup types (data, log, and catalog), or you can use a different configuration for each backup type by creating a separate configuration file for each.

You specify the path to each Backint agent configuration file in SAP HANA by specifying parameters in the global.ini file.

Configure the Backint agent by specifying parameters in the parameters.txt file. You can rename the file as appropriate.
1. Use your preferred method to edit the parameters.txt file. The file is installed in the following directory.
```
/usr/sap/SID/SYS/global/hdb/opt/backint/backint-gcs/parameters.txt
```
  You can rename the parameters.txt file and use different configuration files for data, log, and catalog backups.
  
  For descriptions of the configuration parameters, as well as performance recommendations, see Configuration options for the Backint agent.
2. Specify 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, specify the path to the JSON key file.
```
#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 /usr/sap/ABC/home/example-project-123456-d591d63bba6f.json
```
Optional: Configure the Backint agent to bypass or use a proxy for backups and recoveries. By default, the Backint agent bypasses HTTP proxies.

Warning: Routing backups through a proxy negatively impacts the performance and reliability of all proxy traffic during the sending or retrieving of backups from Cloud Storage. Google Cloud strongly recommends that the Backint agent bypass HTTP proxies.

Queries to the instance metadata server must always bypass the HTTP proxy server. Use either the http or https proxy parameters as required by your proxy server.

To specify proxy server settings for the Backint agent, edit the file /usr/sap/SID/SYS/global/hdb/opt/backint/backint-gcs/jre/conf/net.properties.

For example, the following configuration specifies an HTTPS proxy server:
```
http.proxyHost=proxy-host
http.proxyPort=proxy-port
http.nonProxyHosts=localhost|127.*|[::1]|169.254.169.254|metadata.google.internal
https.proxyHost=proxy-host
https.proxyPort=proxy-port
```
For more information about using the Backint agent with a proxy, see Proxies and the Backint agent.

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.

If you are using a different configuration file for each different type of backup, specify the different configuration files as shown in the following table. Otherwise, specify the same configuration file for all types.

Parameter	Value
`catalog_backup_parameter_file`	`/usr/sap/SID/SYS/global/hdb/opt/backint/backint-gcs/parameters-catalog.txt`
`catalog_backup_using_backint`	`true`
`data_backup_parameter_file`	`/usr/sap/SID/SYS/global/hdb/opt/backint/backint-gcs/parameters-data.txt`
`log_backup_parameter_file`	`/usr/sap/SID/SYS/global/hdb/opt/backint/backint-gcs/parameters-log.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 a Compute Engine VM, 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 Google Cloud CLI and configure the application-default login by using the gcloud auth application-default login command.

Updating the Backint agent to a new version

Before you update the Backint agent to a new version in your production environment, make sure to test the new version in a non-production environment. For information about what a version of the Backint agent offers, see the release notes for that version.

To update the Backint agent to a new version:

Enable remote HTTP requests from the SAP HANA host to https://www.googleapis.com/.
(Recommended) Stop your SAP HANA database instance.

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

curl -O https://storage.googleapis.com/cloudsapdeploy/backint-gcs/update.sh
chmod +x update.sh
./update.sh

If you had stopped your SAP HANA database instance, then restart it.

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 SID_LCadm, 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

To troubleshoot problems with Backint agent for SAP HANA, see Troubleshooting Backint agent for SAP HANA.

Getting support for the Backint agent

If you need help resolving a problem with Backint agent for SAP HANA, gather the required diagnostic information and contact Cloud Customer Care. For more information, see Backint agent for SAP HANA diagnostic information.