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.

The instructions below describe how to enable and configure 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. For additional information on configuring different modes and testing, see the Aspera KB Article "HTTP fallback configuration, testing and troubleshooting."

  1. Turn on HTTP/HTTPS Fallback.
    Edit the <WEB/> section of the aspera.conf file, which can be found in the following location:
    C:\Program Files[ (x86)]\Aspera\Enterprise Server\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. Confirm the following entries are correct:

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

    > asuserdata -v
  2. Configure HTTP/HTTPS fallback settings.
    You can configure HTTP/HTTPS Fallback from either the Connect Server GUI or by editing aspera.conf.

    Configuring HTTP/HTTPS fallback 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:

    • 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.
    HTTP Fallback configuration options.

    Configuring HTTP/HTTPS fallback by editing aspera.conf:

    Run the following commands:

    • To view the current HTTP settings in aspera.conf:
      $ 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:

    C:\Program Files[ (x86)]\Aspera\Enterprise Server\etc\aspera.conf
  3. Review additional HTTP fallback settings.
    Additional HTTP fallback settings can be set in the HTTP Fallback tab in the Connect 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 Enterprise 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 Aspera Enterprise Server will be 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
    • 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
    • false
    false
    Enable HTTPS Enables the HTTPS Fallback server that allows failed UDP transfers to continue over HTTPS.
    • true
    • 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.

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

    Enter a token string

    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 final step in this topic.
  5. Run the following command to validate your updated configuration file:
    $ asuserdata -v
  6. After enabling HTTP fallback and setting a token encryption key, restart the Aspera Central, Aspera NodeD, and Aspera HTTPD services.
    Go to Control Panel > Administrative Tools > Services. For each service, right-click the service and select Restart from the menu.