Getting Started with Data Lake Files HDLFSCLI

The HDLFSCLI is included in the HANA Data Lake Client download from the SAP software center. The first step is to download and install the latest version of the HANA Data Lake client.

The latest HANA Data Lake Client package can by identified by the most recent release date.

Once you’ve identified the correct package for your operating system, download it.

To connect the HDLFSCLI to an SAP HANA, data lake Files container, a certificate will need to be generated to make a secure connection. Below are the steps required to create a self-signed certificate to get started using the HDLFSCLI. You will require an installation of OpenSSL. Use your preferred Linux package installer to install OpenSSL if it is not already installed. If you’re using a Windows machine, then Windows Subsystem for Linux (WSL) will have OpenSSL installed. Alternatively, OpenSSL can be installed for Windows from here.

Then, follow these steps to creating your self-signed certificate.

Make sure the certificate fields are not all exactly the same between the Certificate Authority (CA) and client certificates. Otherwise, it is assumed to be a self-signed cert and the cert validation below will fail.

Create a folder.

mkdir %HOMEPATH%\certs
cd %HOMEPATH%\certs

mkdir -p $HOME/certs
cd $HOME/certs

Create a private key for the CA (2048 bits).

openssl genrsa -out ca.key 2048

Create the CA’s public certificate (valid for 200 days). Provide at least a common name and fill other fields as desired. Fields can be skipped; it is not necessary to fill out every field.

openssl req -x509 -new -key ca.key -days 200 -out ca.crt

Create a signing request for the client certificate.

Provide at least a common name and fill other fields as desired. Leave the email-Id field blank. The Common Name must be different from the one used for the CA public certificate.

openssl req -new -nodes -newkey rsa:2048 -out client.csr -keyout client.key

Create the client certificate (valid for 100 days)

openssl x509 -days 100 -req -in client.csr -CA ca.crt -CAkey ca.key -CAcreateserial -out client.crt

Verify the certificate was signed by the CA.

openssl verify -CAfile ca.crt client.crt

To obtain the subject string of a certificate in the RFC2253 format used in HDL Files authorizations (omit the “subject=” prefix).

Note: You will need this later when you configure authentication for HDL Files.

openssl x509 -in client.crt -nameopt RFC2253 -subject -noout

Navigate to SAP HANA Cloud Central and select “Manage Configuration” on the HDL instance.

Select the “Data Lake Files” button at the top of the page.

Here is a full view of the screen showing the location of “Trusts” and “Authorizations”. You may need to scroll down to find these.

Click on “Add” under Trusts configuration and hit on “Upload” file button and browse to the location where your ca.crt is located and upload that file and click on apply.

The alias can be anything, but the certificate should be exactly what is in the generated ca.crt.

Click on “Add” under Authorizations and select the roles as “Admin” or “User” and then click on “Generate pattern” from the output of the following command. (exclude the “subject=” prefix):

openssl x509 -in client.crt -nameopt RFC2253 -subject -noout

Alternatively, you can use the “Generate Pattern” option and similarly upload the client.crt file after clicking on the “Upload” file option. It will automatically generate a pattern like above.

Now click “Review and Save” at the bottom of the page.

Click “Save Changes” on the modal to confirm changes.

Next, we will verify that the configuration we did in Steps 5 & 6 work.

The <Instance ID> and <REST API Endpoint> can be copied by clicking on the ellipses in SAP HANA Cloud Central.

<PATH> is the path to the corresponding certificate. The following command lists out files in the root folder of the HDL files instance. Thus if the instance has no files, the command will not return anything.

hdlfscli -cert <PATH>\client.crt -key <PATH>\client.key -cacert <PATH>\ca.crt -k -s https://<REST API Endpoint> -filecontainer <Instance ID> ls

[Optional]: Configure a configuration file to make using the CLI simpler.

Note: The configuration will be placed in the user’s root directory. It is saved as a JSON file that can be modified in any text editor.

hdlfscli -cert <PATH>\client.crt -key <PATH>\client.key -k -s <REST API Endpoint> -config myconfig -dump-config ls

Test the configuration that was just created.

hdlfscli -config myconfig ls

Upload a file to the SAP HANA, data lake Files storage instance. Ensure you know the path to the TPCH data files that were downloaded in the prerequisites.

hdlfscli -config myconfig upload <Your Local Path>\TPCH <Target File Path>\TPCH

Verify that the files has been uploaded.

hdlfscli -config myconfig lsr

Now that the TPCH data files are in the data lake Files container, we can use SQL on Files to query the data. Learn how to do this in the tutorial Explore SAP HANA Cloud, SAP HANA Database SQL on Files.

[Troubleshoot]: If you get this error while verifying the configuration, follow the steps below:

Copy the content of the Client field inside [ ] brackets. Then go to your Data Lake instance, click on Manage Configuration, and scroll down to Authorizations. Delete the entire value from the existing “Pattern” field and paste in the Client field value.

Now, re-verify the configuration and it should work.

For more information on HDLFSCLI, check the SAP Help Portal documentation.