Configuring HTTP and HTTPS Fallback

HTTP fallback serves as a secondary transfer method when the Internet connectivity required for Aspera FASP transfers (UDP port 33001, by default) is unavailable. When HTTP fallback is enabled and UDP connectivity is lost or cannot be established, the transfer will continue over the HTTP (or HTTPS) protocol. These instructions describe how to enable and configure HTTP/HTTPS fallback.

Prerequisites:

Configure your HST Server web UI, as described in Configuring Your Web UI Settings. For additional information on configuring different modes and testing, see the Aspera KB Article "HTTP fallback configuration, testing and troubleshooting."
Your Aspera HTTP daemon (asperahttpd) is running with sufficient privileges so that it can modify file ownership.

Limitations:

Folders that are symbolic links cannot be downloaded directly by using HTTP fallback. Folders that are symbolic links are processed correctly when their parent folder is the source.
HTTP fallback can only follow symbolic links. Settings in aspera.conf or in the command line are ignored.
HTTP fallback attempts to transfer at the target rate but is limited by TCP.
HTTP fallback does not support pre-post processing or inline validation.

Process:

Enable HTTP/HTTPS fallback for your web server.
1. Open aspera.conf from the following location:
  
  /opt/aspera/etc/aspera.conf/Library/Aspera/etc/aspera.conf
2. Edit the <WEB/> section.
  Confirm the following entries are correct:
```
<WEB
   ...
   HttpFallback = "yes"        
   HttpFallbackPort = "8080"
   HttpsFallbackPort = "8443"   
/>
```
3. Save and close the file.
4. Confirm that aspera.conf is formed correctly.
  Validate the aspera.conf file using the asuserdata utility:
```
$ /opt/aspera/bin/asuserdata -v
```
Configure HTTP/HTTPS fallback settings.
You can configure HTTP/HTTPS fallback from the HST Server GUI or by editing aspera.conf.
Configuring HTTP/HTTPS fallback from the GUI:

Launch the transfer server and go to Configuration > Global > HTTP Fallback.

Review the following settings:
- In the Enable HTTP row, select Override and set to true.
- If you want to allow fallback over HTTPS, in the Enable HTTPS row, select Override and set to true.
- Verify that the value for HTTP Port matches the value in aspera.conf, under the <WEB/> section (default: 8080). Refer to Step 1 for additional information.
- (If applicable) Verify that the value for HTTPS Port matches the value in aspera.conf, under the <WEB/> section (default: 8443). Refer to Step 1 for additional information.
Configuring HTTP/HTTPS fallback by editing aspera.conf:
Run the following commands:
- To view the current HTTP settings in aspera.conf:
```
$ /opt/aspera/bin/asuserdata -b -t
```
- To enable HTTP fallback:
```
$ asconfigurator -x "set_http_server_data;enable_http,true"
```
- To enable HTTPS fallback, if using:
```
$ asconfigurator -x "set_http_server_data;enable_https,true"
```
- To set the HTTP port (default 8080, must match the value in the <WEB> section of aspera.conf):
```
$ asconfigurator -x "set_http_server_data;http_port,8080"
```
- To set the HTTPS port (default 8443, must match the value in the <WEB> section of aspera.conf):
```
$ asconfigurator -x "set_http_server_data;https_port,8443"
```
These commands edit or create the following lines in aspera.conf:
```
<CONF version="2">
  ...
  <http_server>
    ...
    <enable_http>true</enable_http>          
    <enable_https>true</enable_https>        
    <http_port>8080</http_port>              
    <https_port>8443</https_port>            
    ...
  </http_server>
</CONF>
```
To manually inspect and edit aspera.conf, open it from the following directory:

/opt/aspera/etc/aspera.conf/Library/Aspera/etc/aspera.conf

Review additional HTTP fallback settings.

Additional HTTP fallback settings can be set in the HTTP Fallback tab in the HST Server GUI or set in aspera.conf:

Field	Description	Values	Default
Cert File	The absolute path to an SSL certificate file. If left blank, the default certificate file that came with HST Server is used.	file path	blank
Key File	The absolute path to an SSL key file. If left blank, the default certificate file that came with your HST Server is used.	file path	blank
Bind Address	The network interface address on which the HTTP fallback server listens. The default value 0.0.0.0 allows the HTTP fallback server to accept transfer requests on all network interfaces for this node. Alternatively, a specific network interface address may be specified.	valid IPv4 address	0.0.0.0
Restartable Transfers	Set to `true` to allow interrupted transfers to resume from the point of interruption.	`true` or `false`	`true`
Session Activity Timeout	Any value greater than 0 sets the amount of time, in seconds, that the HTTP fallback server will wait without any transfer activity before canceling the transfer. This option cannot be set to 0, otherwise interrupted HTTP fallback sessions will get stuck until server or `asperacentral` is restarted.	positive integer	20
HTTP Port	The port on which the HTTP server listens. Valid port numbers range between 1 and 65535.	positive integer	8080
HTTPS Port	The port on which the HTTPS server listens. Valid port numbers range between 1 and 65535.	positive integer	8443
Enable HTTP	Enables the HTTP fallback server that allows failed UDP transfers to continue over HTTP.	`true` or `false`	`false`
Enable HTTPS	Enables the HTTPS fallback server that allows failed UDP transfers to continue over HTTPS.	`true` or `false`	`false`

<CONF version="2">
 ...
  <http_server>
    <cert_file> </cert_file>
    <key_file> </key_file>
    <bind_address>0.0.0.0</bind_address>
    <restartable_transfers>true</restartable_transfers>
    <session_activity_timeout>1</session_activity_timeout>
    <enable_http>true</enable_http>
    <enable_https>true</enable_https>
    <http_port>8080</http_port>
    <https_port>8443</https_port>
  </http_server>
</CONF>

Set a token encryption key.
If HTTP/HTTPS fallback is enabled, a token encryption key is required. If HTTP/HTTPS is configured without the encryption key, initiating a transfer with the download button generates the following error:
```
Error: internal error - unable to start token generation
```
The token encryption key is the secret text string used for authorizing transfers configured to require a token. Aspera recommends setting a key string at least 20 random characters long.
You can specify a token encryption key from the Connect Server GUI or by editing aspera.conf.

Set a token key from the GUI:

Launch Connect Server and click Configuration. Click Global > Authorization, select the option Token Encryption Key and enter a key string of random characters (at least 20 recommended).

Set a token key in aspera.conf:
To set the token encryption key in aspera.conf, run the following command:
```
$ asconfigurator -x "set_node_data;token_encryption_key,secret_string"
```
The key should be a string of random characters, at least 20 recommended. This adds or updates the <encryption_key> value in the <authorization> section:
```
<CONF version="2">
  ...
  <default>
    <authorization>
    ...
    <token>
      <encryption_key>secret_string</encryption_key>
    </token>
    </authorization>
  </default>
  ...
</CONF>
```
Important: After changing your Aspera token settings—either in aspera.conf or the GUI—you must restart asperahttpd. For instructions, see the last step in these instructions.
If you manually edited aspera.conf, validate your updated configuration file:
```
$ /opt/aspera/bin/asuserdata -v
```
After enabling HTTP fallback and setting a token encryption key, restart asperacentral, asperanoded, and asperahttpd.
Run the following command in a Terminal window to restart asperacentral:
```
$ sudo launchctl stop com.aspera.asperacentral
$ sudo launchctl start com.aspera.asperacentral
```
Run the following commands to restart asperanoded:
```
$ sudo launchctl stop com.aspera.asperanoded
$ sudo launchctl start com.aspera.asperanoded
```
Run the following commands to restart asperahttpd:
```
$ sudo launchctl stop com.aspera.asperahttpd
$ sudo launchctl start com.aspera.asperahttpd
```