Installing and setting up the REST API

Edit online

How to install and set up the REST API for IBM Storage Archive Enterprise Edition.

About this task

The REST server software for IBM Storage Archive Enterprise Edition software is provided in an rpm file that is contained within the IBM Storage Archive Enterprise Edition software package. You can locate the REST API rpm file after you extract the IBM Storage Archive Enterprise Edition installation image (ltfsee-1.3.5.[fixlevel]-[buildlevel]-{product|upgrade}.bin). Use the following instructions to install and set up the REST server for IBM Storage Archive Enterprise Edition.

Procedure

  1. Verify that the prerequisite software is installed, see REST API software requirements.
  2. The filename structure for the REST API rpm file for IBM Storage Archive Enterprise Edition is [name]-[version]-[buildlevel]-[platform].rpm. Use the following command to install the REST API rpm file: 
    yum localinstall ibmsa-rest-1.3.5.[fixlevel]-[buildlevel]-[platform].rpm
    1. If you intend to use a python3 version that is not set as the default one (e.g. a python virtual environment), you can set the environment variable PYTHON_BIN to the path of the python3 binary file you intend to use, if not set, the REST API will be installed for the system's default python3.
  3. To set up the REST server edit /etc/httpd/conf.d/ibmsa-rest.conf, if needed. The ibmsa-rest-httpd.conf file contains the following defaults:
    • The default port is 7100.
    • The default protocol is http. If you need SSL/TLS, make the following changes:
      • Add the comment: SSLEngine on.
      • Comment in two lines to specify SSL certificate and private key.
      • For this to work, the mod_ssl package is needed. For more information, see REST API software requirements
    • The default language and locale is en_US.UTF-8.
  4. For the REST API to work correctly some permissions need to be granted to the user running httpd (default is apache), a script to facilitate this process is provided with the installation and can be found in /opt/ibm/ltfsee/rest/conf/apache-config.sh, this script grants sudo permissions to run the following:
    • eeadm commands
    • REST API's authorization module
    • ssh-keygen to check the validity of the keys used
    • sudo -l -U * to check if the user being authenticated has access to run eeadm commands
    • stdbuf to parse the output of the eeadm commands being run in the background
  5. There are certain options that can be configured by the user by modifying the /opt/ibm/ltfsee/rest/conf/config.ini file, these are:
    • General settings:
    • Token expiration
      • Default is 8 hours, can be set to False to never expire but this is dangerous and should be avoided.
      • Needs to restart httpd to take effect
    • CSRF Protection
      • Default is True, when enabled, a CSRF Token will be generated along with the Access Token and both Tokens are needed to access the endpoints, to send the CSRF Token in the requests add the X-CSRF-TOKEN header to the request with the Token.
      • For more information about CSRF attacks see https://owasp.org/www-community/attacks/csrf
    • Log level
      • Default is INFO, can be changed to:
        • INFO
        • DEBUG
        • WARNING
        • ERROR
        • CRITICAL
      • Does not need to restart httpd to take effect
    • Key settings:
      • Secret
        • Secret key only for symmetric key (when no asymmetric keys are configured). Adds a layer of security to the encoding and decoding of the access tokens without being as secure as using asymmetric keys.

      These next options have to be set together, if one of them is not found or set incorrectly, they will both be ignored.

    • Private and Public keys
      • Disabled by default, can be set to the path of a public and private key pair to generate more secure access tokens. Must be readable by apache user.
        • If set, the private key will be used to encode the access tokens and the public key will be used to decode them.
    • Key algorithm
      • Disabled by default, Specify the algorithm of the private and public keys, can be set to:
        • HS256 - HMAC using SHA-256 hash algorithm
        • HS384 - HMAC using SHA-384 hash algorithm
        • HS512 - HMAC using SHA-512 hash algorithm
        • ES256 - ECDSA signature algorithm using SHA-256 hash algorithm
        • ES256K - ECDSA signature algorithm with secp256k1 curve using SHA-256 hash algorithm
        • ES384 - ECDSA signature algorithm using SHA-384 hash algorithm
        • ES512 - ECDSA signature algorithm using SHA-512 hash algorithm
        • RS256 - RSASSA-PKCS1-v1_5 signature algorithm using SHA-256 hash algorithm
        • RS384 - RSASSA-PKCS1-v1_5 signature algorithm using SHA-384 hash algorithm
        • RS512 - RSASSA-PKCS1-v1_5 signature algorithm using SHA-512 hash algorithm
        • PS256 - RSASSA-PSS signature using SHA-256 and MGF1 padding with SHA-256
        • PS384 - RSASSA-PSS signature using SHA-384 and MGF1 padding with SHA-384
        • PS512 - RSASSA-PSS signature using SHA-512 and MGF1 padding with SHA-512
        • EdDSA - Both Ed25519 signature using SHA-512 and Ed448 signature using SHA-3
      • For more information about these algorithms, see https://pyjwt.readthedocs.io/en/latest/algorithms.html

    For the assymetric key settings to work, the cryptography package is needed. For more information, see REST API software requirements