Configuring for the Node API

The Node API can be configured using the asconfigurator tool from the command line or by editing the server section of aspera.conf. To configure your node for the Node API using asconfigurator, use this general syntax:

# /opt/aspera/bin/asconfigurator -x "set_server_data;option,value"

Possible options and values are described in the table below.

To view the current settings, run the following command:

# /opt/aspera/bin/ asuserdata -a

To manually edit aspera.conf, open it in a text editor with administrative privileges from the following location:

/opt/aspera/etc/aspera.conf

For an example of the Node API configuration in aspera.conf, see the example below. Possible options and values are described in the table below.

Remember to validate aspera.conf after any editing to confirm your configuration is correct. Run the following command:

# /opt/aspera/bin/asuserdata -v

Node API Configuration Options

Note: Each of the settings below requires certain services to be restarted in order for any changes to take effect; see the To Activate Changes column in the table below. The commands to restart these services are given below the table.

asconfigurator option
aspera.conf setting

Description and Values To Activate Changes...

server_name
<server_name>

Hostname or IP address.

Default: hostname

Restart node service

http_port
<http_port>

HTTP service port. Value is an integer 1 - 65535, default 9091. This setting is overridden by <listen>. Restart node service

https_port
<https_port>

HTTPS service port. Value is an integer 1 - 65535, default 9092. This setting is overridden by <listen>. Restart node service

enable_http
<enable_http>

Enable HTTP for the Node API services by setting to true. Default: false. This setting is overridden by <listen>. Restart node service

enable_https
<enable_https>

Enable HTTPS for the Node API services by setting to true (default). This setting is overridden by <listen>. Restart node service

workers
<workers>

Number of worker threads. Default: 20. Restart node service

transfers_multi_session_default
<transfers_multi_session_default>

Number of ascp workers per transfer. Default: 1. Restart node service

transfers_retry_duration
<transfers_retry_duration>

If a transfer fails, node will try to restart it for the specified time, default 20m. If a transfer restarts and makes some 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 may vary depending on the transfer queue. Restart node service.

transfers_retry_all_failures
<transfers_retry_all_failures>

Setting to true will retry all transfers, including transfers otherwise considered unretriable. Default: false. Restart node service.

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 node service

cert_file
<cert_file>

Full pathname of SSL certificate (.pem and existing support for .chain).

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

Restart node service

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 should back up your database. See Redis DB Backup/Restore.

Default: /opt/aspera/var

Restart the node and DB services.

db_port
<db_port>

Database service port. Value is an integer 1 - 65535, default: 31415. Before changing this value, you should back up your database. See Redis DB Backup/Restore. Restart the node and DB services.

ssl_ciphers
<ssl_ciphers>

The SSL encryption ciphers that the server will allow, each separated by a colon (:). Default: all of the following:

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 may 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 allow list 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 may encounter compatibility issues.

Restart node service.

ssl_protocol
<ssl_protocol>

The SSL protocol versions that the server will allow. This option may 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 allow list 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 node service.

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>   <proxy>
      ...
   </proxy>
   <ssl_ciphers>TLS_ECDHE_RSA_WITH_AES_128_CBC_SHA:…:RC2-CBC-MD5</ssl_ciphers>
   <ssl_protocol>tlsv1</ssl_protocol>
</server>

Restarting and Reloading Services

Note: Running the commands below requires root privileges.

Restart the Node Service:

$ sudo /etc/init.d/asperanoded restart

Reload the Node Configuration:

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

Restart the Node and DB Services:

$ sudo /etc/init.d/asperanoded stop 
$ sudo /opt/aspera/bin/asnodeadmin --db-shutdown
$ sudo /etc/init.d/asperanoded start
Note: The DB service is started automatically when you restart the node service.