Configuring the IBM Aspera NodeD Service

The IBM Aspera NodeD Service handles HTTP/HTTPS requests to HSTS. You can configure server settings that include the hostname, HTTP/HTTPS ports, the address and port of the Redis database, and SSL certificates.

Configuration Methods

The server can be configured for the Node API by using the asconfigurator command line tool or by editing the <server> section of aspera.conf:

  • Asconfigurator: Use the following syntax, substituting option with the option from the following table and value with the wanted value:
    # /opt/aspera/bin/asconfigurator -x "set_server_data;option,value"

    To view the current settings, run the following command:

    # /opt/aspera/bin/ asuserdata -a
  • Aspera.conf: Open it in a text editor with administrative privileges from the following location:
    /opt/aspera/etc/aspera.conf

    See the sample aspera.conf following the table.

    After manually editing aspera.conf, validate your XML by running the following command:

    # /opt/aspera/bin/asuserdata -v

Node API Configuration Options

Important configuration considerations:

  • Certain services must be restarted for changes in the settings to take effect, as described in the To Activate Changes column. The commands to restart these services are given following the table.
  • In addition to the Aspera server configuration, if you plan to transfer many small files with the Node API, you might need to increase the number of file descriptors available on your system. If too few descriptors are available, the Redis database and the transfer fail. For instructions, see Node API transfers of many small files fails.
asconfigurator option
aspera.conf setting
Description and Values To Activate Changes...
server_name
<server_name>
Hostname or IP address.

Default: hostname

Restart asperanoded.
http_port
<http_port>
HTTP service port. Value is an integer 1 - 65535, default 9091. This setting is overridden by <listen>. Restart asperanoded.
https_port
<https_port>
HTTPS service port. Value is an integer 1 - 65535, default 9092. This setting is overridden by <listen>. Restart asperanoded.
enable_http
<enable_http>
Enable HTTP for the Node API services by setting to true. Default: false. This setting is overridden by <listen>. Restart asperanoded.
enable_https
<enable_https>
Enable HTTPS for the Node API services by setting to true (default). This setting is overridden by <listen>. Restart asperanoded.
workers
<workers>
Number of worker threads. Default: 20. Restart asperanoded.
transfers_multi_session_default
<transfers_multi_session_default>
Number of ascp workers per transfer. Default: 1. Restart asperanoded.
transfers_retry_duration
<transfers_retry_duration>
If a transfer fails, node tries to restart it for the specified time, default 20 m. If a transfer restarts and makes progress, then the retry timer is reset and the next time if fails, it will again try to restart it for retry_duration'. The backoff interval for retrying within this duration is internal to the application, and the number of retries might vary depending on the transfer queue. Restart asperanoded.
transfers_retry_all_failures
<transfers_retry_all_failures>
Setting to true retries all transfers, including transfers otherwise considered unretryable. Default: false. Restart asperanoded.
listen
<listen>
To bind asperanoded on a specific address (or addresses), specify a comma-delimited list of listening ports. Ports have the format [ip_address:]port[s]. To specify a secure port, add 's' to the end of the port number, for example 127.0.0.1:9092s.

The IP address is optional; however, if no IP address is specified then the port binds to all network interfaces on the server, rather than to the single address.

Setting this option overrides <http_port>, <https_port>, <enable_http>, and <enable_https>.

Restart asperanoded.
cert_file
<cert_file>
Full path name of the SSL certificate, which must be in .pem format.

Default: /opt/aspera/etc/aspera_server_cert.pem

Restart asperanoded.
max_response_entries
<max_response_entries>
Maximum number of entries to return in a response. Default: 1000. Reload node configuration.
max_response_time
<max_response_time>
Maximum amount of time to wait for a long-running operation. Default: 10. Reload node configuration.
db_dir
<db_dir>
Path to the directory where the database file is saved. Before changing this value, you must back up your database. See Backing up and restoring the node user database records.

Default:

Restart asperanoded and the Redis database.
db_port
<db_port>
Database service port. Value is an integer 1 - 65535, default: 31415. Before changing this value, you must back up your database. See Backing up and restoring the node user database records. Restart asperanoded and the Redis database.
ssl_ciphers
<ssl_ciphers>
The SSL encryption ciphers that the server allows, each separated by a colon (:). Default: all of the following values:
TLS_ECDHE_RSA_WITH_AES_128_CBC_SHA
TLS_ECDHE_RSA_WITH_AES_256_CBC_SHA
TLS_ECDHE_RSA_WITH_3DES_EDE_CBC_SHA
DHE-RSA-AES256-SHA
DHE-DSS-AES256-SHA
AES256-SHA
AES128-SHA256
DHE-RSA-AES128-SHA
DHE-DSS-AES128-SHA
RC2-CBC-MD5

This option might also be set in the <client> section, in which case, when this machine functions as a client, the specified ciphers are requests to the server. If any of the ciphers in the server's allowlist coincide with those in the client's request list, communication is allowed; otherwise, it is denied.

If you override this setting, the override is always used. However, if you do not override it, the default setting depends on the settings for <ssl_protocol>. If <ssl_protocol> is set to sslv23, then a large, relatively weak selection of suites is allowed. If the protocol is anything else, then a smaller, stronger selection of suites is allowed. Many older web browsers cannot handle the stronger set of suites, in which case you might encounter compatibility issues.

Restart asperanoded.
ssl_protocol
<ssl_protocol>
The SSL protocol versions that the server allows. This option might also be set in the <client> section, in which case, when this machine is a client, the specified protocols function as requests to the server. If any of the protocols in the server's allowlist coincide with those in the client's request list, communication is allowed; otherwise, it is denied.

Supported values: tlsv1, tlsv1.1, and tlsv1.2. Default: tlsv1.

Restart asperanoded.
activity_logging
<activity_logging>
If true, enable querying transfers by using GET /ops/transfers or to retrieve usage data by using GET /usage. Default is false. Restart asperanoded.
activity_event_logging
<activity_event_logging>
If true, allow the Node API to query transfers that are associated with this access key through the /events endpoint. The server configuration can be overridden by the access key configuration. This option must be enabled for event reporting to IBM Aspera on Cloud. Default is false. Restart asperanoded.
files_recursive_counts_enabled
<files_recursive_counts_enabled>
If true, enable recursive counts. This option must be enabled for event reporting to IBM Aspera on Cloud. The server configuration can be overridden by the access key configuration. Default is false. Restart asperanoded.
aej_logging
<aej_logging>
If true, enable reporting to the IBM Aspera on Cloud Activity app. The server configuration can be overridden by the access key configuration. Default is false. Restart asperanoded.

Example Node API configuration in aspera.conf

<server>
   <server_name>your_hostname</server_name>  
   <http_port>9091</http_port>
   <https_port>9092</https_port>
   <enable_http>false</enable_http>
   <enable_https>true</enable_https>
   <workers>20</workers>
   <transfers_multi_session_default>1</transfers_multi_session_default>
   <transfers_retry_all_failures>false</transfers_retry_all_failures>
   <transfers_retry_duration>20m</transfers_retry_duration>
   <listen> </listen>
   <cert_file>/opt/aspera/etc/aspera_server_cert.pem</cert_file>
   <max_response_entries>1000</max_response_entries> 
   <max_response_time_sec>10</max_response_time_sec> 
   <db_dir>/opt/aspera/var</db_dir>
   <db_port>31415</db_port>
   <ssl_ciphers>TLS_ECDHE_RSA_WITH_AES_128_CBC_SHA:…:RC2-CBC-MD5</ssl_ciphers>
   <ssl_protocol>tlsv1</ssl_protocol>
   <activity_logging>true</activity_logging>
   <activity_event_logging>true</activity_event_logging>
   <files_recursive_counts_enabled>true</files_recursive_counts_enabled>
   <aej_logging>true</aej_logging>
</server>

Restarting and reloading services

Note: Running the commands requires root privileges.

Restart asperanoded:

Run the following commands to restart asperanoded:
# systemctl restart asperanoded
Or for Linux systems that use init.d:
# service asperanoded restart

Reload the node configuration:

# sudo /opt/aspera/bin/asnodeadmin --reload

Restart asperanoded and the Redis database:

  1. Stop asperanoded:
    # systemctl stop asperanoded
    Or for Linux systems that use init.d:
    # service asperanoded stop
  2. Shut down the database:
    # /opt/aspera/bin/asnodeadmin --db-shutdown
  3. Start asperanoded:
    # systemctl start asperanoded
    Or for Linux systems that use init.d:
    # service asperanoded start
Note: The database service is started automatically when you restart the node service.