OSS Backint Agent for SAP HANA - Object Storage Service - Alibaba Cloud Documentation Center

Install the agent

Create the configuration directory.
```
mkdir -p /usr/sap/<SID>/SYS/global/hdb/opt/hdbconfig/
```
Replace <SID> with your SAP HANA system ID (SID), for example, HDB.

Download the installation script.

curl -O https://gosspublic.alicdn.com/oss-backint/v1/install.sh

Run the installation script.
```
chmod +x install.sh
./install.sh <SID>
```
Expected output: <version> has successfully installed.
Verify the installation.
```
/usr/sap/HT1/SYS/global/hdb/opt/hdbbackint -v
```
Expected output: #SOFTWAREID "backint 1.06" "ALIBABACLOUD OSS 1.0.4"

Configure the agent

Edit the following configuration file to specify your OSS bucket, region, and access credentials:

/usr/sap/<SID>/SYS/global/hdb/opt/hdbconfig/oss-backint-agent.ini

The following example shows a minimal configuration:

[default]
bucket-name = my-hana-backup
region = cn-hangzhou
source-profile = ak-pair

[profile ak-pair]
access-key-id = LTAI5t****
access-key-secret = ****

Enable Backint backup

Log on to SAP HANA as the <sid>adm user and run the following SQL statements to switch the backup method to Backint:

-- Point the catalog, data, and log backup parameter files to the agent configuration file
ALTER SYSTEM ALTER CONFIGURATION ('global.ini', 'SYSTEM') SET ('backup', 'catalog_backup_parameter_file') = '/usr/sap/<SID>/SYS/global/hdb/opt/hdbconfig/oss-backint-agent.ini';
ALTER SYSTEM ALTER CONFIGURATION ('global.ini', 'SYSTEM') SET ('backup', 'catalog_backup_using_backint') = 'true';
ALTER SYSTEM ALTER CONFIGURATION ('global.ini', 'SYSTEM') SET ('backup', 'data_backup_parameter_file') = '/usr/sap/<SID>/SYS/global/hdb/opt/hdbconfig/oss-backint-agent.ini';
ALTER SYSTEM ALTER CONFIGURATION ('global.ini', 'SYSTEM') SET ('backup', 'log_backup_parameter_file') = '/usr/sap/<SID>/SYS/global/hdb/opt/hdbconfig/oss-backint-agent.ini';
ALTER SYSTEM ALTER CONFIGURATION ('global.ini', 'SYSTEM') SET ('backup', 'log_backup_using_backint') = 'true';

-- Enable continuous log recording for point-in-time recovery
ALTER SYSTEM ALTER CONFIGURATION ('global.ini', 'SYSTEM') SET ('persistence', 'log_mode') = 'normal';

After you modify the parameters, restart the database or run the following command as the <sid>adm user to apply the changes:

hdbnsutil -reconfig

Verify the configuration

Run a test backup to verify that the configuration is correct:

BACKUP DATA USING BACKINT ('oss-backint-agent-test');

If the backup succeeds, the backup data appears in your OSS bucket under the storage-prefix path. The default prefix is SAP-HANA-Backint. For more information about routine backup and recovery operations, see SAP HANA Backup and Recovery.

Additional credential methods

Scenario	Credential method	Description
SAP HANA runs on an ECS instance	ECS RAM role (recommended)	No AccessKey management required. The agent retrieves temporary credentials from instance metadata.
Cross-account backup	RAM role ARN	Uses STS tokens for secure cross-account access.
ACK cluster with RRSA enabled	OIDC	Uses OIDC tokens for pod-level credential isolation.
External key management system	External Process	Retrieves credentials by running a custom command.

ECS RAM role

If SAP HANA runs on an ECS instance, you can use an ECS RAM role to avoid managing AccessKey pairs. Make sure that the ECS instance is attached with a RAM role that has OSS access permissions.

source-profile = ecsramrole

[profile ecsramrole]
mode = EcsRamRole
# Optional. The role name is automatically retrieved if not specified.
# ecs-role-name = EcsRamRoleHana

RAM role ARN

To store backup data in an OSS bucket that belongs to a different Alibaba Cloud account, use a RAM role ARN for cross-account authorization.

source-profile = ramrolearn

[profile ramrolearn]
mode = RamRoleArn
access-key-id = yourAccessKeyID
access-key-secret = yourAccessKeySecret
role-arn = acs:ram::113511544585****:role/testrole
role-session-name = session_name_example

OIDC

If SAP HANA runs in a Container Service for Kubernetes (ACK) cluster with RRSA (RAM Roles for Service Accounts) enabled, you can use OIDC authentication for pod-level credential isolation.

source-profile = oidcrolearn

[profile oidcrolearn]
mode = OidcRoleArn
oidc-provider-arn = acs:ram::113511544585****:oidc-provider/TestOidcProvider
oidc-token-file-path = OIDCTokenFilePath
role-arn = acs:ram::113511544585****:role/testoidc
role-session-name = TestOidcAssumedRoleSession

External Process

If your organization uses an external key management system, you can configure the agent to retrieve credentials by running a custom command. The command must return a JSON object in one of the following formats:

Long-term credentials:

{
  "AccessKeyId": "yourAccessKeyID",
  "AccessKeySecret": "yourAccessKeySecret"
}

Temporary credentials:

{
  "AccessKeyId": "yourAccessKeyID",
  "AccessKeySecret": "yourAccessKeySecret",
  "Expiration": "2023-12-29T07:45:02Z",
  "SecurityToken": "yourSecurityToken"
}

Configuration example:

source-profile = process

[profile process]
mode = Process
credential-process = /path/to/your/credential-script

Configuration reference

The following table lists all parameters supported in the agent configuration file (oss-backint-agent.ini).

Parameter	Description
`bucket-name`	(Required) The name of the OSS bucket.
`region`	(Required) The region where the bucket is located, for example, `cn-hangzhou`.
`source-profile`	(Required) The name of the credential profile. For more information, see Additional credential methods.
`hana-sid`	(Required) The SAP HANA system ID, automatically set by the installation script.
`endpoint`	The OSS endpoint. If not specified, the public endpoint is automatically generated based on the `region` value. To use an internal endpoint, specify it manually, for example, `https://oss-cn-hangzhou-internal.aliyuncs.com`.
`storage-prefix`	The object prefix in the bucket. Default value: `SAP-HANA-Backint`.
`object-acl`	The access control list (ACL) for backup objects. Valid values: `default`, `private`, `public-read`, and `public-read-write`.
`object-tagging`	The tags for backup objects, in key-value pair format. Example: `Project=SAP&Environment=Production`.
`object-storage-class`	The storage class for backup objects. Valid values: `Standard`, `IA`, `Archive`, `ColdArchive`, and `DeepColdArchive`. If you use Archive or a colder storage class, you must restore the objects before you can recover data from them.
`server-side-encryption`	The server-side encryption method. Valid values: `AES256`, `KMS`, and `SM4`. If you use KMS, you must also set `server-side-encryption-key-id`.
`server-side-data-encryption`	The data encryption algorithm.
`server-side-encryption-key-id`	The ID of the customer master key (CMK) managed by KMS.
`addressing-style`	The endpoint addressing style. Valid values: `virtual`, `path`, and `cname`. Default value: `virtual`.
`sign-version`	The signature algorithm version. Valid values: `v1` and `v4`. Default value: `v4`.
`read-timeout`	The read timeout period, in seconds. Default value: `20`.
`connect-timeout`	The connection timeout period, in seconds. Default value: `10`.
`retry-times`	The maximum number of retries after a failure. Default value: `10`.
`skip-verify-cert`	Specifies whether to skip TLS certificate verification. Default value: `false`.
`proxy`	The address of the proxy server.
`bind-address`	The local address to bind for outbound connections.
`page-size`	The number of results per page for list operations. Default value: `100`.
`job`	The number of concurrent jobs across files. Default value: `5`.
`big-file-threshold`	The file size threshold for multipart upload and parallel download, in bytes. Default value: `67108864` (64 MiB).
`pipe-parallel`	The number of concurrent threads in pipe mode. Default value: `3`.
`pipe-part-size`	The part size in pipe mode, in bytes. The maximum backup file size per pipe is this value multiplied by 10,000. Default value: `6291456` (6 MiB), which supports a maximum of approximately 60 GB. Increase this value if you need to back up larger databases. Peak memory usage formula: job × pipe-parallel × pipe-part-size. For example, with default settings: 5 × 3 × 6 MiB = 90 MiB.
`file-parallel`	The number of concurrent threads in file mode. This value is automatically calculated, with a maximum of 12. SAP HANA uses pipe mode, so this parameter does not take effect.
`file-part-size`	The part size in file mode, in bytes. This value is automatically calculated. SAP HANA uses pipe mode, so this parameter does not take effect.
`shorten-backup-destination-enabled`	Specifies whether to use a shortened OSS backup path. Default value: `false`. When set to `true`, the backup path changes from: `oss://<bucket>/<storage-prefix>/<sid>/DB_<user_id>/usr/sap/<sid>/SYS/global/hdb/backint/` to: `oss://<bucket>/<storage-prefix>/<sid>/DB_<user_id>/`
`log-level`	The log level. Valid values: `off`, `info`, and `debug`. Default value: `off`.
`log-file`	The path of the log output file. Set to `-` to output to stdout.