Configuring for Aspera Files

Aspera Connect Server, or Enterprise Server with a Connect-enabled license, must be configured to use the Aspera Node API, which is required to connect these standalone, on-premise systems to Aspera Files. The server accesses the Node API using a node API username and password, that is associated with a local system account called xfer. All transfers and system operations on the computer are run under xfer. Thus, to add a server as a Files node, on the server you must create the system user, configure it as an Aspera transfer user, associate the transfer user with a node username and password, and configure the server to work with Files. Files users access the Node API and Files nodes using access keys, which can be created on the server or in the Files UI.

System Requirements:

  • Connect Server or Enterprise Server with a Connect-enabled license version 3.6.0 or later.
  • The public DNS name of the system must be accessible from all internal and external clients, as well as the computer itself.

Set Up and Configure a Transfer User

  1. Create a system user named xfer. Files requires this name.
  2. Restrict user permissions with aspshell.
    By default, all system users can establish a FASP connection and are only restricted by file permissions. You can restrict the user's file operations through the aspshell, which permits only the following operations:
    • Running Aspera uploads and downloads to or from this computer.
    • Establishing connections in the application.
    • Browsing, listing, creating, renaming, or deleting contents.

    These instructions explain one way to change a user account so that it uses the aspshell; there may be other ways to do so on your system.

    Modify the passwd file to update user accounts to the aspshell.


    Add or replace the user's shell with aspshell. For example, to apply aspshell to the user aspera_user_1, use the following settings in this file:

  3. Ensure that the user has read and write privileges to the local directories or mounts that Aspera must access.
  4. Set a docroot restriction, rather than a docroot.
    The docroot restriction allows access only to the specified storage. To set a docroot restriction, run the following command:
    # asconfigurator -x "set_user_data;user_name,username;file_restriction,path"

    The restriction path syntax depends on the storage:

    Local storage:  <restriction>file:////*</restriction>
    S3 storage:  <restriction>s3://*</restriction>
    Swift storage: <restriction>swift//*</restriction>
    Azure storage: <restriction>azu://*</restriction>

    For example, to set a docroot restriction for xfer to S3 storage, the command is as follows:

    # asconfigurator -x "set_user_data;user_name,xfer;file_restriction,s3://*"
  5. Configure the transfer user for token authorization.
    # asconfigurator -x "set_user_data;user_name,xfer;authorization_transfer_in_value,token;authorization_transfer_out_value,token;token_encryption_key,key"

    Aspera recommends that the key be a random string of at least 20 characters.

  6. Assign the SSH public key associated with the IBM Aspera Connect Browser Plug-in to xfer.
    The Connect Plug-in uses the default Aspera key pair. Run the following commands to create the .ssh directory, copy the default public key into that directory and rename it authorized_keys, and set permissions on the file, run the following commands:
    $ mkdir /home/xfer/.ssh
    $ cp /opt/aspera/var/ /home/xfer/.ssh/authorized_keys
    $ chmod 700 /home/xfer/.ssh
    $ chmod 600 /home/xfer/.ssh/authorized_keys
    $ chown -R xfer:xfer /home/xfer/.ssh
  7. Create a node username and associate it with the system user xfer.
    Run the following command with root or administrator permissions:
    # /opt/aspera/bin/asnodeadmin  -a -u node_user -p node_user_passwd -x xfer

    For example:

    # /opt/aspera/bin/asnodeadmin  -a -u nuser-001 -p !472830x4n -x xfer
    Note: The node username password must meet the password requirements set in Files.
  8. List the node usernames to confirm that your command was successful.
    # /opt/aspera/bin/asnodeadmin -l

Configure the Server as a Files Node

  1. Ensure SSHD is running on port 33001.
    For information on configuring TCP ports, see Securing Your SSH Server. You must also manually configure the <WEB> section of aspera.conf; see the Aspera Connect Server Admin Guide: Configuring Your Web UI Settings.
  2. Configure a file extenstion to identify files that are still being transferred.
    To set an extension for files that are partially transferred, such as .partial, run the following command:
    # asconfigurator -x "set_node_data;partial_file_suffix,.partial"

    The extension is removed once the file transfer is complete.

  3. Enable activity logging by running the following command:
    # asconfigurator -x "set_server_data;activity_logging,true"
  4. Configure the HTTPS service to use port 443 by running the following command:
    # asconfigurator -x "set_server_data;https_port,443"
  5. Enable recursive counts by running the following command:
    # asconfigurator -x "set_server_data;files_recursive_counts_workers,value"

    For value, enter a number from one to eight. Lower values (one or two) result in slower updates but less load on Redis. Higher values (4 to 8) increase the load on Redis and the machine should have twice as many cores. If your Redis database is very large and you set a high number of recursive counts workers, you may encounter out-of-memory problems. To offset this issue, you can increase the time between background Redis save events and number of key changes by running the following command:

    # asconfigurator -x "set_server_data;db_config_save,time key_changes"

    The default value is 900 1, which sets the background save schedule for every 15 minutes (900 seconds) if at least one key changes. To set this change, you must shut down the Redis database (it is restarted in the next step) by running the following command with root or Administrator privileges:

    # /opt/aspera/bin/asnodeadmin --db-shutdown
  6. Restart the Aspera Central, Aspera NodeD, and Aspera HTTPD services.
    Run the following command in a Terminal window to restart asperacentral:
    # /etc/init.d/asperacentral stop
    # /etc/init.d/asperacentral start
    Run the following commands to restart asperanoded:
    # /etc/init.d/asperanoded restart
    Run the following commands to restart asperahttpd:
    # /etc/init.d/asperahttpd stop
    # /etc/init.d/asperahttpd start

Configure Server Certificates

Both the Files application and the browser in use must be able to validate the SSL certificate of the node you are adding, including all intermediate certificates. Because an intermediate certificate may be known to your browser but not to the Files application, an add-node procedure may seem successful in the browser, but workspace operations (for example, create.workspace, create.membership) fail. In this case, Files displays a warning symbol in the Operations tab of a workspace you attempt to create on this node.

To correct or avoid this problem, 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:

$ cat bundle.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;
For procedures to verify the SSL certificates, see Installing SSL Certificates.

Adding the Node to Files

Once you have created a system user on the server, configured the user for Aspera, associated it with a node username, configured the server, and verified your SSL certificates, you may add it as a node in the Files UI. In the process you are asked for an existing access key and secret, or you can create a new one. If you prefer to manually create an access key on the server, see the instructions in Access Key Authentication.