Setting docroot for object storage

Docroot path syntax for object-storage based HSTS is typically a protocol prefix that is followed by URL-encoded storage account access credentials and a path in that storage. Some storage configuration properties can also be set in the docroot.

General docroot syntax

protocol://user:password@object_storage_URL/path/[?storage_configuration]

Docroot paths might be set to cloud or on-premises object storage in the HSTS GUI or by editing aspera.conf using asconfigurator.

To set the docroot for a user with asconfigurator, run the following command:

# asconfigurator -x "set_user_data;user_name,username;absolute,docroot"

The docroot can also be configured manually by adding the following text to /opt/aspera/etc/aspera.conf:

<user>
   <name>username</name>
   ...
   <file_system>
       <access><paths><path>
            <absolute>docroot</absolute>
       </path></paths></access>
   </file_system>
</user>

Note: After editing aspera.conf, you must restart asperanoded:

Run the following commands to restart asperanoded:

# systemctl restart asperanoded

Object storage docroot formats

Docroot formatting requirements:

The protocol prefixes for cloud-based docroot paths are case-sensitive. For example, s3:// is the correct prefix for S3 storage and S3://" does not work.
The variable components of URI docroots must be URL encoded, unless you are entering them in the HSTS GUI. For more information, see URL encoding.

Amazon S3

Using IAM assume roles improve the security, in which case the docroot has the following format:

s3://s3.amazonaws.com/my_bucket/

For more information on the IAM roles required for Aspera®, see IAM role permissions for S3 buckets in https://www.ibm.com/support/pages/iam-role-permissions-s3-buckets.

Without IAM roles, you must specify your access_id and secret_key. You can find these values in the AWS Management Console by clicking your login name and selecting Security Credentials from the drop-down menu. The docroot includes this information with the following format:

s3://s3.amazonaws.com/my_bucket/

The docroot can also be used to set storage configuration properties that include AWS storage class, infrequent access, server encryption, or AWS KMS encryption, by adding the appropriate option:

s3://s3.amazonaws.com/my_bucket/?storage-class=REDUCED_REDUNDANCY
s3://s3.amazonaws.com/my_bucket/?storage-class=INFREQUENT_ACCESS
s3://s3.amazonaws.com/my_bucket/?server-side-encryption=AES256
s3://s3.amazonaws.com/my_bucket/?server-side-encryption=AWS_KMS

These options can be combined as in the following example, where the & that combines the queries must be URI encoded:

s3://s3.amazonaws.com/my_bucket/?storage-class=REDUCED_REDUNDANCY&amp;server-side-encryption=AES256

Azure blob

azu://storage_account:storage_access_key@blob.core.windows.net/path_to_blob

Azure Files

azure-files://storage_account:storage_access_key@file.core.windows.net/share

Google Cloud Storage

If the instance was set up with a Google service account, the docroot is set as:

google-gcs:///my_bucket/my_path

Without a Google service account, obtain the .p12 private key for your storage. For instructions on generating a private key, see the Google Cloud Platform documentation: Cloud Storage authentication

google-gcs:///my_bucket/my_path?aspera.gssession.projectId=project_ID&amp;aspera.gssession.pk12=path_to_private_key_pk12_file</absolute>

Note: The email_address is the service account ID associated with the storage. You must URL encode the @ when entering the email address in the docroot. For example, if the service account ID is test@developer.gserviceaccount.com, then it is entered in the docroot as:

test%40developer.gserviceaccount.com