Adding a Node to Aspera Files

Aspera Connect Server (the transfer server) provides the "Node API", which is required to connect standalone, on-premise systems to Aspera Files. Basic principles:

Important: To complete this procedure successfully, both the Files application and the browser must be able to verify the node SSL certificate. For details, see Verifying the Certificate below.

Prerequisites

Creating a Node User

On the transfer node, create a node user and associate it with the system user xfer. The asnodeadmin command requires root or administrator permissions.

  1. List the current node users:
    > asnodeadmin -l
  2. Create a node user by running asnodeadmin as follows:
    > asnodeadmin  -a -u node_user -p node_user_passwd -x xfer

    For example:

    > asnodeadmin  -a -u nuser-001 -p !472830x4n -x xfer
  3. List node users again to verify that step 2 configuration was successful:
    > asnodeadmin -l

    You have now created node user nuser-001 with password !472830x4n and associated it with the system user xfer.

    Note: Before deploying Files in a production environment, be sure to create a node-user password that is secure.

Verifying the Certificate

Both the Files application and the browser in use must be able to validate the SSL certificate of the node you are adding, including any and all intermediate certificates.

Because an intermediate certificate may be known to your browser but not to the Files application, it is possible for an add-node procedure to seem successful at first, but for workspace operations (for example, create.workspace, create.membership) to fail; in this case, Files displays a warning symbol in the Operations tab of a workspace you attempt to create on this node.

Best practices require that you provide a bundle of chained certificates, typically provided by the certificate authority, concatenated to the signed server certificate. Note that you must list the server certificate before the chained certificates. For example:

> type www.example.com.crt bundle.crt > www.example.com.chained.crt

This ensures that both the Files application and the browser can verify the node certificates. Use the concatenated file in the ssl_certificate directive. For example:

server {
   listen              443 ssl;
   server_name         www.example.com;
   ssl_certificate     www.example.com.chained.crt;
   ssl_certificate_key www.example.com.key;
   ...
}
For procedures to verify the SSL certificates, see Installing SSL Certificates.

Creating a New Access Key

On the transfer node, create a new user access key with access to the local directory /data by running the following curl command:

> curl -X POST -ki -u 'node_user:node_user_passwd' https://node_host:port/access_keys
-d json_data

To list existing access keys:

> curl -X GET -ki -u 'node_user:node_user_passwd' https://node_host:port/access_keys

To delete an existing access key:

> curl -X DELETE -ki -u 'node_user:node_user_passwd' https://node_host:port/access_keys/access_key_id

Examples of the curl command are shown below for local storage, Swift storage, and AWS storage. For examples of other storage types, see Access Key Authentication.

Using Local Storage

Example of creating a new access key with access to the local directory /data:

> curl -ki -u 'nuser-001:!472830x4n' https://localhost:9092/access_keys -d '{"secret":
"873826c61fffeeb0f5a1746af8808cb823651458", "storage":{"type":"local", "path":"/data"}}'

Example response:

{
    "id": "xwXhChBJBkVppSCgn-o_hoSudXNZHLMQJqFFHGg01iUA",
    "uri": "file:////data",
    "file_id": "1",
    "system_user": "xfer",
    "license": null,
    "storage": {
        "type": "local",
        "path": "/data"
    }

Using Swift Storage

This example uses a file (swift_tenant.json) because the required data is extensive compared to the data required for local storage.

Example request:

> curl -ki -u 'node_user:node_user_passwd' https://node_host:port/access_keys
-d @swift_tenant.json

Example JSON payload file swift_tenant.json:

{
  "secret": "873826c61fffeeb0f5a1746af8808cb823651458",
  "storage": {
     "type": "softlayer_swift",
     "path": "/data",
     "container": "wallball",
     "credentials": {
        "authentication_endpoint": "https://sjc01.objectstorage.softlayer.net/auth/v1.0",
        "username": "RMCOS303446-2%3Aascoopdev",
        "api_key": "42f977c63d4a177b381ef6be42d6e3469a99ffeb32a85b3e55e4298c7fe593afb714"
      }
   }
}

Example response:

{
     "id": "i9ckg14RHEEolpFp2PHFq3lC1aE20XZUWgAXL48cl94A",
     "uri": "swift://sjc01.objectstorage.softlayer.net/wallball/",
     "file_id": "1",
     "system_user": "xfer",
     "license": null,
     "storage": {
          "type": "softlayer_swift",
          "path": "/",
          "container": "wallball",
     }
}

Using AWS Storage

Use either of the following methods to create an access key:

Example response for both methods:

HTTP/1.1 200 OK
Cache: no-cache
Connection: close
Content-Type: application/json; charset=utf-8
{
  "id" : "xCIOPKlpfw9ok78uKIOH0Mn_-N98KGFHc234OPNjR5AdPAA",
  "root_file_id" : "1",
  "license" : null,
  "storage" : {
  "type" : "aws_s3",
  "path" : "/test",
  "endpoint" : "s3.amazonaws.com",
  "bucket" : "aspera",
  "storage_class" : "STANDARD"
 }
}

Testing the Access Key

Test the access key by browsing the top-level directory:

> curl -ki -u 'access_key_id:secret' https://node_host:port/files/1/files a=""

For example:

> curl -ki -u 'xwXhCh...g01iUA:873826c...651458' https://localhost:9092/files/1/files

Test by writing to storage:

> curl -ki -u 'access_key_id:secret' https://node_host:port/files/1/files 
-d json_commands

For example:

> curl -ki -u 'xwXhCh...g01iUA:873826c...651458' https://localhost:9092/files/1/files 
-d {"type":"folder", "name", "TEST-001"}

Changing the Access Key Secret

Given an access key (my_access_key) and a secret (my_secret), change the secret to my_new_secret by running the following command:

> curl -ki -u 'my_access_key:my_secret' hostname:port/access_keys/my_access_key -X PUT -d '{"secret":"my_new_secret"}'