Configuring HTTP and HTTPS Fallback

HTTP fallback serves as a secondary transfer method when the Internet connectivity required for Aspera accelerated 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. The instructions below walk through the process of setting up HTTP/HTTPS fallback. For additional information on configuring different modes and testing, see 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.
  1. Turn on HTTP/HTTPS Fallback.

    These instructions assume that you have already configured your Connect Server's Web UI, as described in Configuring Your Web UI Settings. If you have not already done so, be sure to 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 location:

    /opt/aspera/etc/aspera.conf

    If you do not see the <WEB/> section, copy it from the file aspera-web-sample.conf, as described in Configuring Your Web UI Settings. In the <WEB/> section, confirm the following entries:

    <WEB
       ...
       HttpFallback = "yes"         <!-- Yes to turn on; No to turn off -->
       HttpFallbackPort = "8080"    <!-- Default: 8080 -->
       HttpsFallbackPort = "8443"   <!-- Default: 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
  2. Configure HTTP/HTTPS fallback settings.

    You can configure HTTP/HTTPS Fallback from either the Connect Server GUI or aspera.conf.

    From the GUI

    To edit your settings from the GUI, launch the transfer server and go to Configuration > Global (tab in left pane) > HTTP Fallback (tab in right pane).

    Open the Server Configuration window

    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.

    HTTP Fallback configuration options.

    From aspera.conf

    To change your HTTP fallback settings from aspera.conf, go to the following directory:

    /opt/aspera/etc/aspera.conf

    Update your HTTP fallback settings in 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). For additional information, see Step 1.

    <CONF version="2">
      ...
      <http_server>
        ...
        <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>
  3. After modifying aspera.conf, restart the Aspera Central, Aspera NodeD, and Aspera HTTPD services:
    # service asperacentral restart
    # service asperanoded restart
    # /etc/init.d/asperahttpd restart
  4. Run the following command (from Enterprise Server's bin directory) to validate your updated configuration file:
    $ /opt/aspera/bin/asuserdata -v
  5. Review additional HTTP fallback settings.

    The following sample template and description table displays additional HTTP fallback options in 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 Enterprise Server is 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 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

  6. Specify a token encryption key.

    The token encryption key is the secret text string used for authorizing 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 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").

    Enter a token string

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

    <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 final step in this topic.
  7. Use asconfigurator to update HTTP fallback settings. (Optional)

    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 (for example, 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
  8. 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