Skip to main content
Pure Technical Services

Using the Pure Storage SAP HANA Toolkit

Currently viewing public documentation. Please login to access the full scope of documentation.

The SAP HANA toolkit is a set of executables packaged in an rpm for Redhat Enterprise Linux and SUSE Enterprise Linux. 

The following tasks can be accomplished with the toolkit:

  • Check for and apply best practice recommendations for Pure Storage FlashArray when used as persistent storage for SAP HANA deployments.
  • Create application consistent and crash consistent storage snapshots for the following deployment types:
    • Scale Up bare metal 
    • Scale Out bare metal 
    • Scale Up on VMware using vVols 
    • Scale Out on VMware using vVols 
  • Recover from application consistent storage snapshots for the following deployment types:
    • Scale Up bare metal 
    • Scale Up on VMware using vVols.

The toolkit is based on python scripts located on Pure Storage Open-Connect

Python 3 must be available on the system to use any of th tools in the SAP HANA Toolkit. To check what python revision is currently being used execute the following 

python --version

If both Python 2 and Python 3 are on the system then use the following to set the primary python version to 3.x 

update-alternatives --config python

Installing the SAP HANA Toolkit

The latest version of the SAP HANA Toolkit can be downloaded directly from GitHub to the relevant system using the following command:

wget https://github.com/PureStorage-OpenConnect/SAP-HANA-Scripts/raw/master/Python/Build%20Artifacts/ps_saphana_toolkit-0.0.1-1.x86_64.rpm

The package can then be installed using the rpm installer command:

rpm -ivh ps_saphana_toolkit-0.0.1-1.x86_64.rpm 

It is also possible to install the package directly from the repository:

rpm -ivh https://github.com/PureStorage-OpenConnect/SAP-HANA-Scripts/raw/master/Python/Build%20Artifacts/ps_saphana_toolkit-0.0.1-1.x86_64.rpm

The executables and configuration files are created in /opt/purestorage/saphana_toolkit with symbolic links to /usr/local/bin for each executable.

HANA:/hana/shared # ll /opt/purestorage/saphana_toolkit/
total 73428
drwxr--r-- 1 root root       66 Jan 15 03:04 cfg_files
-rwxr--r-- 1 root root 23208232 Jan 15 02:20 create_scaleout_snapshot
-rwxr--r-- 1 root root 23207776 Jan 15 02:20 create_scaleup_snapshot
-rwxr--r-- 1 root root  5555960 Jan 15 02:20 ps_saphana_cfg_check
-rwxr--r-- 1 root root 23208976 Jan 15 02:20 recover_scaleup_snapshot
HANA:/hana/shared # ll /usr/local/bin/
total 16
lrwxrwxrwx 1 root root 57 Jan 15 03:04 create_scaleout_snapshot -> /opt/purestorage/saphana_toolkit/create_scaleout_snapshot
lrwxrwxrwx 1 root root 56 Jan 15 03:04 create_scaleup_snapshot -> /opt/purestorage/saphana_toolkit/create_scaleup_snapshot
lrwxrwxrwx 1 root root 53 Jan 15 03:04 ps_saphana_cfg_check -> /opt/purestorage/saphana_toolkit/ps_saphana_cfg_check
lrwxrwxrwx 1 root root 57 Jan 15 03:04 recover_scaleup_snapshot -> /opt/purestorage/saphana_toolkit/recover_scaleup_snapshot
Sarah:/hana/shared #                                                                                        

Removing the SAP HANA toolkit 

To remove the SAP HANA toolkit use the rpm command with the "-e" qualifier and package name:

rpm -e ps_saphana_toolkit 

 This will remove both the /opt/purestorage/saphana_toolkit directory , including its contents, and the symbolic links to /usr/local/bin.

Checking for and applying best practice recommendations 

To check for and apply the best practice recommendations simply execute the ps_saphana_cfg_check utility as root. 

The ps_saphana_cfg_check utility will identify the operating system vendor, major and minor revision levels in order to apply the appropriate best practices for the platform. Configuration settings for multiple components are taken from the /opt/purestorage/saphana_toolkit/cfg_files/  directory. 

These configuration settings should only be used for SAP HANA based deployments. 

Configuration Files 

/opt/purestorage/saphana_toolkit/cfg_files/configurations.json

This file contains the preset configuration recommendations for each of the operating systems which support SAP HANA. Present configurations are formatted as follows:

clipboard_e336cce8880d72db86cf8df1b2dba9d46.png

vendor The operating system vendor , either "suse" or "redhat"
distribution  the operating system distribution typically "sles" or "enterprise_linux" 
major The major revision of the distribution 
minor The minor revision of the distribution 
dm_blk_mq Should the blk_mq elevator be turned on for multipath devices, or if it is already on by default.
scsi_blk_mq Should the blk_mq elevator be turned on for scsi devices, or if it is already on by default.
scheduler What ths the recommended IO scheduler to use for Pure Storage FlashArray volumes
mpathconf What device-mapper configuration settings to use. References existing files.  

/opt/purestorage/saphana_toolkit/cfg_files/rh7

The recommended multipath.conf entries for Pure Storage FlashArray  and Redhat Enterprise Linux 7.x. 

/opt/purestorage/saphana_toolkit/cfg_files/rh8

The recommended multipath.conf entries for Pure Storage FlashArray  and Redhat Enterprise Linux 8.x. 

/opt/purestorage/saphana_toolkit/cfg_files/sl12

The recommended multipath.conf entries for Pure Storage FlashArray  and SUSE Enterprise Linux 12.x

/opt/purestorage/saphana_toolkit/cfg_files/sl15

The recommended multipath.conf entries for Pure Storage FlashArray  and SUSE Enterprise Linux 15.x

Applying best practice recommendations

Depending on if the system is identified to be a virtual machine or a bare metal server – different settings are applied. 

  • If the system is a virtual machine , then device-mapper and udev rules are not set – instead the IO scheduler and global elevator is set for the bootloader (reboot required).
  • If the system is bare metal then the appropriate device-mapper configuration and udev settings are applied , along with the IO scheduler (IO scheduler changes require a reboot).
  • It also checks if the required settings are present so as to avoid unnecessary changes.

To run the configuration check execute the following:

ps_saphana_cfg_check

This is an example of the configuration check being run on a system. The following changes are checked for , prompted for and changed:

  • IO Scheduler changed for SCSI devices.
  • IO scheduler changes for Device-Mapper devies.
  • Multipath and udev (device rules) configurations applied.
  • Due to an IO scheduler change the bootloader is rebuilt and the user prompted for a reboot. 

 clipboard_e787cb81e71dbe48e2eb6647a7cbcec35.png

For device-mapper configuration changes only the section pertaining to Pure Storrage FlashArray is changed. 

Before After
devices {
       device {
               vendor                "PURE"
               product               "FlashArray"
               path_selector         "queue-length 0"
               path_grouping_policy  group_by_prio
               path_checker          tur
               fast_io_fail_tmo      10
               dev_loss_tmo          60
               no_path_retry         0
               hardware_handler      "1 alua"
               prio                  alua
               failback              immediate
        }
}
blacklist {
        wwid    INTEL_SSDSC2BB300G4T_PHWL451300NZ300PGN
}
devices {
  device {
        vendor                "PURE"
        product               "FlashArray"
        fast_io_fail_tmo      10
        path_grouping_policy  "group_by_prio"
        failback              "immediate"
        prio                  "alua"
        hardware_handler      "1 alua"
        max_sectors_kb        1024
    }
blacklist {
        wwid    INTEL_SSDSC2BB300G4T_PHWL451300NZ300PGN
}

Creating storage snapshots for Scale Up deployments

Using the create_scaleup_snapshot utility application consistent and crash consistent storage snapshots can be created. The following behaviors should be noted when using this process.

  • Application consistent storage snapshots are created for only the SAP HANA data volume. 
  • The storage snapshot will have the SAP HANA Backup ID appended to its name for recovery purposes.
  • Crash consistent storage snapshots will add the data and log volume to a protection group with the instance system identifier (SID) appended for traceability purposes. If two systems with the same SID exist in the same landscape on the same FlashArray then Crash consistent storage snapshots should only be created of one of them. 
  • It is possible to create storage snapshots of SAP HANA virtual machines on VMware but only if the data and log volumes are located on a vVol datastore. 

Only SAP HANA 2.0 deployments are supported for use with this utility. The utility will exclusively try to connect to the SystemDB. 

The following arguments are used with the create_scaleup_snapshot utility 

Argument Purpose Requirement
-h, --help  Show help message text. Optional
-ha HOSTADDRESS, --hostaddress HOSTADDRESS Host address(IP) or hostname of the SAP HANA Scale Up  System. Defaults to localhost if not provided. Optional
-i INSTANCENUMBER, --instancenumber INSTANCENUMBER SAP HANA instance number , typically in the form 00. defaults to 00 if not provided.  Optional
 -du DATABASEUSER, --databaseuser DATABASEUSER  SAP HANA system database user with the correct permissions to create a storage snapshot.  Required
-dp DATABASEPASSWORD, --databasepassword DATABASEPASSWORD SAP HANA system database password with the correct permissions to create a storage snapshot. Will prompt for a password if not provided.  Optional
-osu OPERATINGSYSTEMUSER, --operatingsystemuser OPERATINGSYSTEMUSER  A user with the permissions to freeze the SAP HANA data volume and view volume information.  Required
-osp OPERATINGSYSTEMPASSWORD, --operatingsystempassword OPERATINGSYSTEMPASSWORD  Password for the user with permissions to freeze the SAP HANA data volume and view volume information. Will prompt for the password if not provided.  Optional
-fa FLASHARRAY, --flasharray FLASHARRAY  The IP address or hostname of a Pure Storage FlashArray with the SAP HANA systems volumes on it. Required
-fau FLASHARRAYUSER, --flasharrayuser FLASHARRAYUSER  A user on the FlashArray with permissions to create a volume snapshot. Required
 -fap FLASHARRAYPASSWORD, --flasharraypassword FLASHARRAYPASSWORD Password for the user with permissions to create a volume snapshot on FlashArray. Will prompt for the password if not provided.  Optional
  -cc, --crashconsistent Create a crash consistent snapshot in a protection group.  Optional
 -ff, --freezefilesystem Freeze the filesystem to avoid any IO going to the volume. Will unfreeze as apart of the process.  Optional
 -vca VCENTERADDRESS, --vcenteraddress VCENTERADDRESS The IP address or hostname of a vCenter Server managing the SAP HANA VM. Optional
  -vcu VCENTERUSER, --vcenteruser VCENTERUSER  The Username of a user for the vCenter Server managing the SAP HANA VM. Optional
-vcp VCENTERPASSWORD, --vcenterpassword VCENTERPASSWORD The Password of a user for the vCenter Server managing the SAP HANA VM. Will prompt for the password if not provided.  Optional
--version Show program's version number and exit Optional

Example creating an application consistent storage snapshot on the local scale up instance

No password arguments are provided which then causes a prompt to show for each required.

HANA:~ # create_scaleup_snapshot --databaseuser SYSTEM --operatingsystemuser root --flasharray 10.21.227.53 --flasharrayuser pureuser
Database Password:
Operating System Password:
FlashArray Password:
vCenter Password (Leave blank if not required):
Volume Snapshot serial number : 723EC7B5B427453E000134CD
Confirming storage snapshot with SAP HANA Backup ID : 1610720058079

The Storage snapshot is created and visible within SAP HANA Studio: 

clipboard_eeae588edaa52650d9070b0dd6753ad82.png

In the FlashArray web user interface it can now be seen that the storage snapshot is present with the appended Snapshot ID.

clipboard_e0b3b4899c00bfefa49e42c35c7f8a76f.png

Example creating an application consistent storage snapshot on a remote virtualized vVol scale up instance

No password arguments are provided which then causes a prompt to show for each required.

If the vCenter Credentials are not provided then the snapshot will be abandoned in a similar fashion to the below output :

HANA:~ # create_scaleup_snapshot --hostaddress vhana05.soln.local --databaseuser SYSTEM --operatingsystemuser root --flasharray 10.21.227.50 --flasharrayuser pureuser
Database Password:
Operating System Password:
FlashArray Password:
vCenter Password (Leave blank if not required):
The volume has been detected to be a virtual disk but no vCenter credentials have been supplied to further parse the request
Abandoning storage snapshot with SAP HANA Backup ID : 1610719220924
HANA:~ # create_scaleup_snapshot --hostaddress vhana05.soln.local --databaseuser SYSTEM --operatingsystemuser root --flasharray 10.21.227.50 --flasharrayuser pureuser --vcenteraddress erebus.soln.local --vcenteruser Administrator@vsphere.local
Database Password:
Operating System Password:
FlashArray Password:
vCenter Password (Leave blank if not required):
Volume Snapshot serial number : 8488B6DAC70F42A20001A482
Confirming storage snapshot with SAP HANA Backup ID : 1610719444661

The Storage snapshot is created and visible within SAP HANA Studio:

clipboard_e0eae7e02a4fd1b1d770e375dd89cebb3.png

 

In the FlashArray web user interface it can now be seen that the storage snapshot is present with the appended Snapshot ID:

clipboard_e57b3e501cf3d3319313f168afed1201f.png

Example creating a crash consistent storage snapshot on the local scale up instance

HANA:/hana/shared # create_scaleup_snapshot --databaseuser SYSTEM --operatingsystemuser root --flasharray 10.21.227.53 --flasharrayuser pureuser --crashconsistent
Database Password:
Operating System Password:
FlashArray Password:
vCenter Password (Leave blank if not required):
Crash consistent storage snapshot SAPHANA-SH1-CrashConsistency.1 created

As the snapshot is created without any application awareness, there is no entry in the SAP HANA catalog for it. 

As seen in the FlashArray web user interface a Protection Group is created for the instance and the relevant volumes are added to it before being a snapshot is created. 

clipboard_ea8f1a3d34426de89830fcfb2ff10a048.png

Creating storage snapshots for Scale Out deployments 

Using the create_scaleout_snapshot utility application consistent and crash consistent storage snapshots can be created. The following behaviors should be noted when using this process.

  • Application consistent storage snapshots are created for only the SAP HANA data volumes attached to the relevant worker host at that point in time. 
  • The storage snapshot for each data volume will have the SAP HANA Backup ID and worker host name appended to its name for recovery purposes.
  • Crash consistent storage snapshots will add the data and log volumes to a protection group with the instance system identifier (SID) appended for traceability purposes. If two systems with the same SID exist in the same landscape on the same FlashArray then Crash consistent storage snapshots should only be created of one of them. 
  • It is possible to create storage snapshots of SAP HANA virtual machines on VMware but only if the data and log volumes are located on a vVol datastore. 

Only SAP HANA 2.0 deployments are supported for use with this utility. The utility will exclusively try to connect to the SystemDB. 

For Scale Out deployments the SystemDB is located on the Nameserver host. To find the nameserver host execute the following SQL command 

SELECTHOST FROMM_LANDSCAPE_HOST_CONFIGURATION WHERE NAMESERVER_ACTUAL_ROLE = 'MASTER'

The following arguments are used with the create_scaleup_snapshot utility 

Argument Purpose Requirement
-h, --help  Show help message text. Optional
-ha HOSTADDRESS, --hostaddress HOSTADDRESS Host address (hostname) of an SAP HANA Scale Out worker  System. Defaults to localhost if not provided. Optional
-d DOMAINNAME, --domainname DOMAINNAME  Domain name of domain where SAP HANA scale out nodes are located.  Required
-i INSTANCENUMBER, --instancenumber INSTANCENUMBER SAP HANA instance number , typically in the form 00. defaults to 00 if not provided.  Optional
 -du DATABASEUSER, --databaseuser DATABASEUSER  SAP HANA system database user with the correct permissions to create a storage snapshot.  Required
-dp DATABASEPASSWORD, --databasepassword DATABASEPASSWORD SAP HANA system database password with the correct permissions to create a storage snapshot. Will prompt for a password if not provided.  Optional
-osu OPERATINGSYSTEMUSER, --operatingsystemuser OPERATINGSYSTEMUSER  A user with the permissions to freeze the SAP HANA data volume and view volume information.  Required
-osp OPERATINGSYSTEMPASSWORD, --operatingsystempassword OPERATINGSYSTEMPASSWORD  Password for the user with permissions to freeze the SAP HANA data volume and view volume information. Will prompt for the password if not provided.  Optional
-fa FLASHARRAY, --flasharray FLASHARRAY  The IP address or hostname of a Pure Storage FlashArray with the SAP HANA systems volumes on it. Required
-fau FLASHARRAYUSER, --flasharrayuser FLASHARRAYUSER  A user on the FlashArray with permissions to create a volume snapshot. Required
 -fap FLASHARRAYPASSWORD, --flasharraypassword FLASHARRAYPASSWORD Password for the user with permissions to create a volume snapshot on FlashArray. Will prompt for the password if not provided.  Optional
  -cc, --crashconsistent Create a crash consistent snapshot in a protection group.  Optional
 -ff, --freezefilesystem Freeze the filesystem to avoid any IO going to the volume.Will unfreeze as apart of the process.  Optional
 -vca VCENTERADDRESS, --vcenteraddress VCENTERADDRESS The IP address or hostname of a vCenter Server managing the SAP HANA VM. Optional
  -vcu VCENTERUSER, --vcenteruser VCENTERUSER  The Username of a user for the vCenter Server managing  the SAP HANA VM. Optional
-vcp VCENTERPASSWORD, --vcenterpassword VCENTERPASSWORD The Password of a user for the vCenter Server managing the SAP HANA VM. Will prompt for the password if not provided.  Optional
--version Show program's version number and exit. Optional

Example creating an application consistent storage snapshot on a Scale Out instance using vVols

The only difference between a vVol based scale out instance and a bare metal deployment is the presence of the vcenter credentials

vHANA01:~ # create_scaleout_snapshot --hostaddress vhana01.soln.local --domainname soln.local --databaseuser SYSTEM --operatingsystemuser root --flasharray 10.21.227.50 --flasharrayuser pureuser --vcenteraddress erebus.soln.local --vcenteruser Administrator@vsphere.local
Database Password:
Operating System Password:
FlashArray Password:
vCenter Password (Leave blank if not required):
Creating storage snapshot for mount point : hanadataVHAmnt00001 on host : vhana01.soln.local
Creating storage snapshot for mount point : hanadataVHAmnt00004 on host : vhana02.soln.local
Creating storage snapshot for mount point : hanadataVHAmnt00003 on host : vhana03.soln.local
Creating storage snapshot for mount point : hanadataVHAmnt00002 on host : vhana04.soln.local
Confirming storage snapshot with SAP HANA Backup ID : 1610723655368

The storage snapshot will be visible in SAP HANA studio as shown below. 

clipboard_e8f4457e5d66dd4d2632fe893865372df.png

Each SAP HANA data volume should also be shown to have a storage snapshot with the SAP HANA Backup ID appended to it.

clipboard_e447c742e28a15e8bf597c057c0436c73.png

Example creating a crash consistent storage snapshot on a Scale Out instance using vVols

vHANA01:~ # create_scaleout_snapshot --hostaddress vhana01.soln.local --domainname soln.local --databaseuser SYSTEM --operatingsystemuser root --flasharray 10.21.227.50 --flasharrayuser pureuser --vcenteraddress erebus.soln.local --vcenteruser Administrator@vsphere.local --crashconsistent
Database Password:
Operating System Password:
FlashArray Password:
vCenter Password (Leave blank if not required):
Crash consistent storage snapshot SAPHANA-VHA-CrashConsistency.1 created

All of the log and data volumes will be added to a new protection group and a snapshot created of it. 

clipboard_ef64f2176957f228a3fe4c20eafb3e7f4.png

Recovering from a data snapshot for a Scale Up deployment 

Using the recover_scaleup_snapshot utility application consistent and crash consistent storage snapshots can be created. The following behaviors should be noted when using this process:

  • Only application consistent storage snapshots for Scale Up instances can be recovered.
  • Recovery can be performed by copying the snapshot to a new volume or overwriting an existing volume with the storage snapshot.
  • If recovery is performed by copying the snapshot to a new volume then the existing data volume is detached from the host and the new volume is attached. 
  • All tenants and the SystemDB are recovered as apart of this process.
  • The SAP HANA database must be running to perform recovery. This is a recovery in place scenario , recovery cannot be redirected. 

If the SAP HANA instance is not running then the standard recovery process needs to be used through SAP HANA Studio or SAP HANA Cockpit. 

The following arguments are used with the recover_scaleup_snapshot utility 

Argument Purpose Requirement
-h, --help  Show help message text. Optional
-ha HOSTADDRESS, --hostaddress HOSTADDRESS Host address (hostname) of an SAP HANA Scale Out worker  System. Defaults to localhost if not provided. Optional
-i INSTANCENUMBER, --instancenumber INSTANCENUMBER SAP HANA instance number, typically in the form 00. Defaults to 00 if not provided.  Optional
 -du DATABASEUSER, --databaseuser DATABASEUSER  SAP HANA system database user with the correct permissions to create a storage snapshot.  Required
-dp DATABASEPASSWORD, --databasepassword DATABASEPASSWORD SAP HANA system database password with the correct permissions to create a storage snapshot. Will prompt for a password if not provided.  Optional
-osu OPERATINGSYSTEMUSER, --operatingsystemuser OPERATINGSYSTEMUSER  A user with the permissions to freeze the SAP HANA data volume and view volume information.  Required
-osp OPERATINGSYSTEMPASSWORD, --operatingsystempassword OPERATINGSYSTEMPASSWORD  Password for the user with permissions to freeze the SAP HANA data volume and view volume information. Will prompt for the password if not provided.  Optional
-fa FLASHARRAY, --flasharray FLASHARRAY  The IP address or hostname of a Pure Storage FlashArray with the SAP HANA systems volumes on it. Required
-fau FLASHARRAYUSER, --flasharrayuser FLASHARRAYUSER  A user on the FlashArray with permissions to create a volume snapshot. Required
 -fap FLASHARRAYPASSWORD, --flasharraypassword FLASHARRAYPASSWORD Password for the user with permissions to create a volume snapshot on FlashArray. Will prompt for the password if not provided.  Optional
-sp SIDADMPASSWORD, --sidadmpassword SIDADMPASSWORD <sid>adm password for the <sid>adm user Required
-ov, --overwritevolume Overwrite the original SAP HANA volume with the snapshot. The default behaviour without this argument is to copy the snapshot to a new volume and attach that to the host operating system. Optional
 -vca VCENTERADDRESS, --vcenteraddress VCENTERADDRESS The IP address or hostname of a vCenter Server managing the SAP HANA VM. Optional
  -vcu VCENTERUSER, --vcenteruser VCENTERUSER  The Username of a user for the vCenter Server managing  the SAP HANA VM. Optional
-vcp VCENTERPASSWORD, --vcenterpassword VCENTERPASSWORD The Password of a user for the vCenter Server managing the SAP HANA VM. Will prompt for the password if not provided.  Optional
--version Show program's version number and exit. Optional
Example Recovering local SAP HANA Scale Up Instance 
HANA:~ # recover_scaleup_snapshot --databaseuser SYSTEM --operatingsystemuser root --flasharray 10.21.227.53 --flasharrayuser pureuser --sidadmpassword Osmium76
Database Password:
Operating System Password:
FlashArray Password:
vCenter Password (Leave blank if not required): 

This recovery method is possible with both vVols and bear metal deployments.

The SAP HANA Catalog is queried for all of the recovery points it is aware of (only for data snapshots).

clipboard_e2a0a2253d6985b292669bbbd7af5f3ef.png

Once a catalog ID is selected the relevant FlashArray is queried to check if the storage snapshot is present. 

clipboard_e98b8b95fed5a5f3cfd9165f9d56e27ec.png

If recovery is selected to proceed the SAP HANA instance is shut down and the relevant recovery method is performed.

clipboard_e973a0d947e5cd36d04f9c701f79e439a.png

Once the new volume has been attached to the host, the SystemDB and tenant databases are recovered. 

clipboard_e218109c3821b48fe8038fb4a26de3e15.png

Its important to note than when using the default recovery method a new volume is created , which alters the world wide identifier of the SAP HANA data volume will be different. The original volume is preserved and the new data volume will have the SAP HANA Backup ID appended to the volume name. 

clipboard_e13c8718b0ac37a215162c80470e05f5c.png