Configuring the Server for the Node API

The server can be configured for the Node API by 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"

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

/opt/aspera/etc/aspera.conf

Configuration options and values are described in the following table and example aspera.conf. To view the current settings, run the following command:

# /opt/aspera/bin/ asuserdata -a

Validate aspera.conf after manually editing it to confirm your configuration is correct by running the following command:

# /opt/aspera/bin/asuserdata -v

Note: 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.

Node API Configuration Options

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.

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 the SSL certificate, which must be in .pem format. 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 Backing up and Restoring the Node User Database Records. 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 Backing up and Restoring the Node User Database Records.	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:

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 the Node and database Services:

Stop the Node Service:
```
# systemctl stop asperanoded
```
or for Linux systems that use init.d:
```
# service asperanoded stop
```

Shutdown the database:

# /opt/aspera/bin/asnodeadmin --db-shutdown

Start the Node service:
```
# 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.