Using the Pure Storage SAP HANA Toolkit
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:
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.
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:
In the FlashArray web user interface it can now be seen that the storage snapshot is present with the appended Snapshot ID.
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:
In the FlashArray web user interface it can now be seen that the storage snapshot is present with the appended Snapshot ID:
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.
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.
Each SAP HANA data volume should also be shown to have a storage snapshot with the SAP HANA Backup ID appended to it.
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.
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).
Once a catalog ID is selected the relevant FlashArray is queried to check if the storage snapshot is present.
If recovery is selected to proceed the SAP HANA instance is shut down and the relevant recovery method is performed.
Once the new volume has been attached to the host, the SystemDB and tenant databases are recovered.
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.