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:

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:

  1. Enable HTTP/HTTPS fallback for your web server.
    1. Open aspera.conf from the following location:
    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.
  2. Configure HTTP/HTTPS fallback settings.

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

    To manually inspect and edit aspera.conf, open it from the following directory:

  3. Review additional HTTP fallback settings.
    Additional HTTP fallback settings can be 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>
  4. 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.

    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.
  5. If you manually edited aspera.conf, validate your updated configuration file:
    $ /opt/aspera/bin/asuserdata -v
  6. 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:
    # /etc/init.d/asperacentral stop
    # /etc/init.d/asperacentral start
    Run the following commands to restart asperanoded:
    # /etc/init.d/asperanoded restart
    Run the following commands to restart asperahttpd:
    # /etc/init.d/asperahttpd stop
    # /etc/init.d/asperahttpd start