Node API setup

The Aspera Node API comes with your installation of HSTS. To use it, you must configure your product and create Node API credentials.

About this task

Note: For more information about creating a transfer token, see: Transfer token creation with the Node API.

Procedure

  1. Ensure that the hosts file contains an entry for 127.0.0.1 localhost. The hosts file can be found in /etc/hosts.
  2. Select or create a system user to associate with the Node API credentials.
    Aspera uses a specially configured system user for SSH authentication when transfers are started. To use dynamic SSH keys for authentication, see Configuring SSH dynamic keys.
    Note: If this user uses Node API credentials to create access keys or bearer tokens, either avoid setting a password for the user or create a long password.
    Create a user account, for example aspera_user_1, by running the following command: 
    # useradd aspera_user_1
  3. Restrict the system user's access to the server's file system.
    • If the Node API user authenticates using an access key or bearer token, set up a restriction for the system user.
    • If the Node API user uses Node API credentials to authenticate, set up a docroot for the system user.
    • To configure a restriction:

      Run the following command:

      # asconfigurator -x "set_user_data;user_name,username;file_restriction,|restriction"

      Where username is the system user's username, | is a delimiter, and restriction is specific to the storage type and path:

      Storage Type Format Example
      local storage For Unix-like OS:
      • specific folder: file:////folder/*
      • drive root: file:////*
      For Windows OS:
      • specific folder: file:///c%3A/folder/*
      • drive root: file:///c*
      Amazon S3 and IBM Cloud Object Storage - S3 s3://*
      Azure azu://*
      Azure Files azure-files://*
      Alibaba Cloud oss://*
      Google Cloud gs://*
    • To configure a docroot:

      Run the following command:

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

      Where username is the system user's username and docroot is the absolute path to which the system user has access.

  4. Restrict user permissions with aspshell.

    By default, all system users establish FASP® connections and are restricted only by file permissions. Assign the user to use aspshell to restrict their file operations, allowing 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 or active directory user account so that it uses the aspshell; there might be other ways to do so on your system.

    Run the following command to change the user login shell to aspshell:

    # sudo usermod -s /bin/aspshell username

    Confirm that the user's shell is updated by running the following command and looking for /bin/aspshell at the end of the output:

    # grep username /etc/passwd username:x:501:501:...:/home/username:/bin/aspshell
    Note: If you use OpenSSH, sssd, and Active Directory for authentication: To make aspshell the default shell for all domain users, first set up a local account for server administration because this change affects all domain users. Then, open /etc/sssd/sssd.conf and change default_shell from /bin/bash to /bin/aspshell.
  5. Set the IBM Aspera Connect public SSH key as an authorized key for the transfer user and ensure that they own the file. To use SSH dynamic keys for authentication, see Configuring SSH dynamic keys.
    To restrict users to running only Aspera-based transfers, use the workaround explained in the previous step. Also, note that Aspera Web Applications are preconfigured with the command directive set to aspshell. If it is not present and is needed, you can configure it manually as well.
    1. Create the .ssh directory in the user's home folder. 
      # mkdir /home/aspera_user_1/.ssh/

      Associate the Aspera transfer user with a Node API

    2. Copy the Connect public SSH key into .ssh and rename it authorized_keys (or append the public key to authorized_keys if the file exists). 
      # cp /opt/aspera/var/aspera_tokenauth_id_rsa.pub /home/aspera_user_1/.ssh/authorized_keys
    3. Ensure that .ssh and .ssh/authorized_keys are owned by the user. 
      # chown -R aspera_user_1:aspera_user_1 /home/aspera_user_1/.ssh
 # chmod 600 /home/aspera_user_1/.ssh/authorized_keys
 # chmod 700 /home/aspera_user_1
 # chmod 700 /home/aspera_user_1/.ssh
  6. Associate the Aspera transfer user with a Node API username and password.
    For example, to assign Node API credentials to user aspera_user_1, run the following command: 
    # sudo/opt/aspera/bin/asnodeadmin -a -u node_api_username -p node_api_passwd -x aspera_user_1
  7. Optional: Change HTTPS port or SSL certificate.
    The Aspera Node API provides an HTTPS interface for encrypted communication between node machines, on port 9092, by default. To modify the HTTPS port, see Configuring the Aspera NodeD service. For information about maintaining and generating a new SSL certificate, see Setting up SSL for your nodes.
  8. Configure other Node API settings.
    • If you want to query transfers by using GET /ops/transfers or to retrieve usage data by using GET /usage, enable activity logging on the node by running the following command: 
      # asconfigurator -x "set_server_data;activity_logging,true"

    • If you want to query events by using GET /events, enable activity event logging on the node by running the following command:

      # asconfigurator -x "set_server_data;activity_event_logging,true"

      The activity_event_logging can be configured in individual access keys and overrides the setting on the node. If activity_event_logging is enabled for the access key, any Node API events that are associated with that access key are logged even if the node setting is false. If it is disabled for the access key, events are not logged for the access key even if activity_event_logging is enabled on the node.

    • For a description of other settings, see Configuring the Aspera NodeD service.
  9. Restart asperanoded to activate your changes.
    Run the following commands to restart the Aspera Node Service: 
    > systemctl restart asperanoded
    Or for Linux systems that use init.d: 
    > service asperanoded restart