Requirements for Integration via REST API
-----------------------------------------

Any operation or management request must be authenticated with a signed request via Signature Version 2 or 4 of the Amazon S3 protocol of the corresponding S3 system user. You can create system users on any storage node in the cluster with the ``ostor-s3-admin create-user -S`` command and parameter ``-e`` specifying the user email address:

::

   # ostor-s3-admin create-user -S -e user@example.com
   UserEmail:user@example.com
   UserId:a14040e0b2ef8b28
   KeyPair[0]:S3AccessKeyId:a14040e0b2ef8b28FZZ8
   KeyPair[0]:S3SecretAccessKey:dbwTnQTW602aAAdq8DQVFzB6yrTCFTNiGB8C8RFA
   Flags:system

With this user you will authenticate further REST API requests managing the S3 cluster. You can create multiple system accounts for different management operations.

Configuration
~~~~~~~~~~~~~

The examples will use cURL for authentication as well as ``GET``, ``PUT``, ``POST``, and ``DELETE`` operations run in Bash. You can simplify signature creation if you create a sane environment first. Create a file ``~/.s3_environment`` replacing ``s3_key`` with your ``S3AcessKeyId`` and ``s3_secret`` with your ``S3SecretAccessKey`` and the following content:

::

   # s3 login variables.
   s3_key="a14040e0b2ef8b28FZZ8"
   s3_secret="dbwTnQTW602aAAdq8DQVFzB6yrTCFTNiGB8C8RFA"
   
   # Sign s3 requests and run curl.
   function s3_curl() {
   
       # Parse command line.
       [ -z "${2}" ] && {
           echo "Usage: ${FUNCNAME[0]} <request_type> <s3_url>"
           return 1
       }
   
       # Prepare signature.
       s3_url="${2%/*}"
       s3_host="${s3_url##*://}"
       s3_query="${2##*/}"
       s3_date="$(date -R)"
   
       # Generate signature.
       s3_signature="$(echo -en "${1}\n\n\n${s3_date}\n/${s3_query%%&*}" |\
           openssl sha1 -hmac ${s3_secret} -binary | base64)"
   
       # Call.
       curl -H "Host: ${s3_host}" \
            -H "Date: ${s3_date}" \
            -H "Authorization: AWS ${s3_key}:${s3_signature}" \
            -X "${1}" \
            "${s3_url}/${s3_query}"
   }

You need to load the file into your default environment to make the ``s3_curl`` function available. Once the file is loaded, you can use it for all further S3 requests. Load the file with the following command:

::

   # source ~/.s3_environment

Statistics
~~~~~~~~~~

You need to have statistics collection enabled on your S3 gateway. The S3 gateway will save the statistics as regular storage objects. On each S3 storage node, create a file ``/var/lib/ostor/local/gw.conf`` with the following contents:

::

   # Enable usage statistics collection.
   S3_GW_COLLECT_STAT=1

Restart the S3 storage service to apply the configuration changes. Run the following command on all S3 storage nodes:

::

   # systemctl restart ostor-agentd.service