Configuring HTTP and HTTPS Fallback

Configure HTTP/HTTPS Fallback via the Connect Server GUI or aspera.conf.

HTTP Fallback serves as a secondary transfer method when the Internet connectivity required for Aspera accelerated transfers (i.e., 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 protocol (or HTTPS protocol). The instructions below walk through the process of setting up HTTP/HTTPS fallback. For additional information on configuring different modes and testing, please refer to the Aspera KB Article "HTTP fallback configuration, testing and troubleshooting."

Note: Ensure that your HTTP daemon (Aspera HTTPD) is running with sufficient privileges, so that it can modify file ownership.

Turn on HTTP/HTTPS Fallback.
These instructions assume that you have already configured your Connect Server's Web UI, as documented in the topic "Connect Server Web UI Settings." If you have not done so, please review that topic before proceeding. To turn on HTTP/HTTPS Fallback, you must edit the <WEB/> section of aspera.conf. This configuration file can be found in the following directory:
```
/opt/aspera/etc/aspera.conf
```
If you do not see the <WEB/> section, you will need to copy it from the file aspera-web-sample.conf, as described in "Connect Server Web UI Settings." Within the <WEB/> section, locate and confirm the following entries:
```
<WEB
   ...
   HttpFallback = "yes"         
   HttpFallbackPort = "8080"    
   HttpsFallbackPort = "8443"   
/>
```
If you modify aspera.conf, run the following command (from Enterprise Server's bin directory) to validate your updated configuration file:
```
$ /opt/aspera/bin/asuserdata -v
```
Configure HTTP/HTTPS Fallback settings.
You may configure HTTP/HTTPS Fallback in the Aspera Connect Server GUI or modify aspera.conf. To edit your settings within the GUI, launch Connect Server and go to Configuration > Global (tab in left pane) > HTTP Fallback (tab in right pane).

Review the following settings:
- Set Enable HTTP to true.
- If you want to allow fallback over HTTPS, set Enable HTTPS to true.
- Verify that the value shown for HTTP Port matches that which is displayed in the aspera.conf file, under the <WEB/> section (default: 8080). Refer to Step 1 for additional information.
- (If applicable) Verify that the value shown for HTTPS Port matches that which is displayed in the aspera.conf file, under the <WEB/> section (default: 8443). Refer to Step 1 for additional information.
To change your HTTP Fallback settings within aspera.conf, navigate to the following directory:
```
/opt/aspera/etc/aspera.conf
```
Update your HTTP Fallback settings within aspera.conf based on the example shown below. Set enable_http and, if you want to allow HTTPS fallback, enable_https to true, as well as specify port numbers for http_port and https_port. Note that the values for http_port and https_port must match the HttpFallbackPort and HttpsFallbackPort values set within the <WEB/> section of aspera.conf (8080 and 8443, respectively). Refer to Step 1 for additional information.
```
<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>
```
After modifying aspera.conf, run the following command (from Enterprise Server's bin directory) to validate your updated configuration file:
```
$ /opt/aspera/bin/asuserdata -v
```

Review additional HTTP Fallback settings.

The following sample template and description table displays additional HTTP Fallback options within aspera.conf:

<CONF version="2">
 ...
  <http_server>
    <cert_file> </cert_file>                                 <!-- Cert file -->
    <key_file> </key_file>                                   <!-- Key file -->
    <bind_address>0.0.0.0</bind_address>                   <!-- Bind Address -->
    <restartable_transfers>true</restartable_transfers>    <!-- Restartable Transfers -->
    <session_activity_timeout>1</session_activity_timeout> <!-- Session Activity Timeout -->
    <enable_http>true</enable_http>                        <!-- Enable HTTP -->
    <enable_https>true</enable_https>                      <!-- Enable HTTPS -->
    <http_port>8080</http_port>                            <!-- HTTP port -->
    <https_port>8443</https_port>                          <!-- HTTPS port -->
  </http_server>
</CONF>

#	Field	Description	Values	Default
1	Cert File	The absolute path to an SSL certificate file. If left blank, the default certificate file that came with your Aspera Enterprise Server will be used.	file path	blank
2	Key File	The absolute path to an SSL key file. If left blank, the default certificate file that came with your Aspera Enterprise Server will be used.	file path	blank
3	Bind Address	This is the network interface address on which the HTTP Fallback Server listens. The default value 0.0.0.0 allows the Aspera 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
4	Restartable Transfers	Setting this to `true` allows interrupted transfers to resume at the point of interruption.	`true` `false`	`true`
5	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. Notice that this option cannot be left at 0, otherwise interrupted HTTP Fallback sessions will get stuck until server or `asperacentral` is restarted.	positive integer	-
6	HTTP Port	The port on which the HTTP server listens. Valid port numbers range between 1 and 65535.	positive integer	8080
7	HTTPS Port	The port on which the HTTPS server listens. Valid port numbers range between 1 and 65535.	positive integer	8443
8	Enable HTTP	Enables the HTTP Fallback Server that allows failed UDP transfers to continue over HTTP.	`true` `false`	`false`
9	Enable HTTPS	Enables the HTTPS Fallback Server that allows failed UDP transfers to continue over HTTPS.	`true` `false`	`false`

Specify a token encryption key.
The token encryption key is the secret text string that is used to authorize transfers configured to require a token.
Note: 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
```
You can specify a token encryption key from the Aspera Enterprise/Connect Server GUI or in aspera.conf. To configure your token encryption key within the GUI, launch your Enterprise/Connect Server application and click Configuration. Go to Global > Authorization, check the option Token Encryption Key and enter a key string of your choice (in the example below, the string "secret").

To specify the token encryption key in aspera.conf, open the file with a text editor, and add or update the authorization section's encryption_key (the example below uses the string "secret"; however, it can be any string):
```
<CONF version="2">
  ...
  <default>
    <authorization>
    ...
    <token>
      <encryption_key>secret</encryption_key>
    </token>
    </authorization>
  </default>
  ...
</CONF>
```
Important: After changing your Aspera token settings (either via aspera.conf or the GUI), you must restart AsperaHTTPD. For instructions, see the final step in this topic.
(Optional) Utilize asconfigurator to update HTTP Fallback settings.
You may also use the asconfigurator command-line tool to configure HTTP Fallback. Use the option -F and specify the HTTP Fallback configuration with set_http_server_data;. You must append the options with values and enclose them in quotes. The syntax is as follows:
```
asconfigurator -F "set_http_server_data; <option_name>, <value>"
```
For example, to enable HTTP Fallback (e.g. enable_http, true) and use port 8085 (http_port,8085), use the following syntax:
```
$ asconfigurator -F "set_http_server_data; enable_http,true; http_port,8085"
```
To reset the settings, use the AS_NULL value. For example, to reset enable_http, use the following syntax:
```
$ asconfigurator -F "set_http_server_data; enable_http,AS_NULL"
```
To view current settings, use the following command:
```
$ asuserdata -b -t
```
Restart Aspera Central and Aspera HTTPD to apply new settings.
Run the following commands to restart Aspera Central and Aspera HTTPD:
```
$ /etc/init.d/asperacentral restart
$ /etc/init.d/asperahttpd restart
```