aspera.conf - Transfer

This topic describes how to manually modify the <transfer> section of aspera.conf (this section includes parameters for inline validation; see Inline File Validation (Overview) for more information). You can also add and edit these parameters using asconfigurator commands. For more information on using asconfigurator, see User, Group and Default Configurations.

  1. Open aspera.conf.

    You can find the aspera.conf configuration file at:

    /opt/aspera/etc/aspera.conf

  2. Add or locate the <transfer/> section, as in the example below.
    <transfer>
     <in>
        <bandwidth>
           <aggregate>
              <trunk_id>109</trunk_id>        <!-- Incoming VLink ID -->
           </aggregate>
           <flow>
              <target_rate>
                 <cap></cap>                  <!-- Incoming Target Rate Cap -->
                 <default>10000</default>     <!-- Incoming Target Rate Default -->
                 <lock>false</lock>           <!-- Incoming Target Rate Lock -->
              </target_rate> 
              <min_rate>
                 <cap></cap>                  <!-- Incoming Minimum Rate Cap -->
                 <default></default>          <!-- Incoming Minimum Rate Default -->
                 <lock>false</lock>           <!-- Incoming Minimum Rate Lock -->
              </min_rate>
              <policy>
                 <cap></cap>                  <!-- Incoming Policy Allowed -->
                 <default></default>          <!-- Incoming Policy Default -->
                 <lock>false</lock>           <!-- Incoming Policy Lock -->
              </policy>
              <priority>
                 <cap></cap>                  <!-- Incoming Priority Allowed -->
                 <default></default>          <!-- Incoming Priority Default -->
                 <lock>false</lock>           <!-- Incoming Priority Lock -->
              </priority>
              <network_rc>
                 <module></module>              <!-- Incoming Rate Control Module -->
                 <tcp_friendly>no</tcp_friendly>    <!-- Incoming TCP Friendly Mode -->
              </network_rc>  
           </flow>
        </bandwidth>
     </in>
     <out>
        <bandwidth>
           <aggregate>
              <trunk_id>109</trunk_id>        <!-- Outgoing VLink ID -->
           </aggregate>
           <flow>
              <target_rate>
                 <cap></cap>                  <!-- Outgoing Target Rate Cap -->
                 <default>10000</default>     <!-- Outgoing Target Rate Default -->
                 <lock>false</lock>           <!-- Outgoing Target Rate Lock -->
              </target_rate> 
              <min_rate>
                 <cap></cap>                  <!-- Outgoing Minimum Rate Cap -->
                 <default>0</default>         <!-- Outgoing Minimum Rate Default -->
                 <lock>false</lock>           <!-- Outgoing Minimum Rate Lock -->
              </min_rate>
              <policy>
                 <cap></cap>                  <!-- Outgoing Policy Allowed -->
                 <default></default>          <!-- Outgoing Policy Default -->
                 <lock>false</lock>           <!-- Outgoing Policy Lock -->
              </policy>
              <priority>
                 <cap></cap>                  <!-- Outgoing Priority Allowed -->
                 <default></default>          <!-- Outgoing Priority Default -->
                 <lock>false</lock>           <!-- Outgoing Priority Lock -->
              </priority>
              <network_rc>
                 <module></module>              <!-- Outgoing Rate Control Module -->
                 <tcp_friendly>no</tcp_friendly>    <!-- Outgoing TCP Friendly Mode -->
              </network_rc>  
           </flow>
        </bandwidth>
     </out>
    <protocol_options>
        <bind_ip_address></bind_ip_address>            <!–- Bind IP Address -->
        <bind_udp_port>33001</bind_udp_port>           <!-- Bind UDP Port -->
        <disable_batching>false</disable_batching>     <!-- Disable Packet Batching -->
        <batch_size>1</batch_size>                     <!-- Batch Size -->		
        <datagram_size>1000</datagram_size>            <!-- Datagram Size -->
        <max_sock_buffer>0</max_sock_buffer>           <!-- Maximum Socket Buffer (bytes)-->   
        <min_sock_buffer>0</min_sock_buffer>           <!-- Minimum Socket Buffer (bytes)-->   
        <rtt_autocorrect>false</rtt_autocorrect>       <!-- RTT auto correction -->   
        <rtt_reverse_infer>false</rtt_reverse_infer>   <!-- Reverse path congestion inference -->   
     </protocol_options>
    <encryption>
        <content_protection_strong_pass_required>false
        </content_protection_strong_pass_required>
                                              <!-- Strong Password Required for Content Protection -->
        <content_protection_required>false
        </content_protection_required>
                                              <!-- Content Protection Required -->
        <allowed_cipher>any</allowed_cipher>  <!-- Encryption Allowed -->
        <fips_mode>false</fips_mode>          <!-- Transfer in FIPS-140-2-certified encryption mode -->
     </encryption>
     <validation_file_start>AS_NULL</validation_file_start>               
                                                   <!-- Validation File Start -->
     <validation_file_stop>AS_NULL</validation_file_stop> 	  
                                                   <!-- Validation File Stop -->
     <validation_session_start>AS_NULL</validation_session_start> 
                                                   <!-- Validation Session Start -->
     <validation_session_stop>AS_NULL</validation_session_stop>   
                                                   <!-- Validation Session Stop -->
     <validation_threshold>AS_NULL</validation_threshold>         
                                                   <!-- Validation Threshold -->
     <validation_uri>AS_NULL</validation_uri> 			 
                                                   <!-- Validation URI -->
     <validation_threshold_kb>0</validation_threshold_kb> 	  
                                                   <!-- Validation Threshold KB -->
     <validation_threads>5</validation_threads>    <!-- Validation Threads -->
     <validation_lua_script_base64></validation_lua_script_base64>
                                                    <!-- Validation Lua Script Base64 -->
     <validation_lua_script_path></validation_lua_script_path>     
                                                   <!-- Validation Lua Script Path -->
    </transfer>
  3. Configuration options reference.
    Field Description Values Default
    Incoming Vlink ID Set the Vlink ID for incoming transfers. Vlinks are a mechanism to define aggregate transfer policies. The default setting of 0 disables Vlinks. One Vlink—the virtual equivalent of a network trunk—represents a bandwidth allowance that may be allocated to a node , a group, or a user. Vlink ID is defined in each Vlink created in Aspera Console. Vlink ID is a unique numeric identifier. predefined value 0
    Incoming Target Rate Cap (Kbps) Set the Target Rate Cap for incoming transfers. The Target Rate Cap is the maximum target rate that a transfer can request, in kilobits per second. No transfer may be adjusted above this setting, at any time. The default setting of unlimited signifies no Target Rate Cap. Clients requesting transfers with initial rates above the Target Rate Cap will be denied. positive integer unlimited
    Incoming Target Rate Default (Kbps) Set the initial rate for incoming transfers, in kilobits per second. Users may be able to modify this rate in real time, if allowed. This setting is not relevant to transfers with a Policy of fixed. positive integer 10000
    Incoming Target Rate Lock Set to false to allow users to adjust the transfer rate once an incoming transfer is started. Set to true to prevent real-time modification of the transfer rate. true or false false
    Incoming Minimum Rate Cap (Kbps) Set the Minimum Rate Cap for incoming transfers. The Minimum Rate Cap is a level, specified in kilobits per second, below which an incoming transfer will not slow, despite network congestion or physical network availability. The default value of unlimited effectively turns off the Minimum Rate Cap. positive integer or unlimited unlimited
    Incoming Minimum Rate Default (Kbps) Set the initial minimum rate for incoming transfers, in kilobits per second. Users may be able to modify this rate in real time, if allowed. This setting is not relevant to transfers with a Policy of fixed. positive integer 0
    Incoming Minimum Rate Lock Set to false (default) to allow users to adjust the minimum transfer rate once an incoming transfer is started. Set to true to prevent real-time modification of the minimum transfer rate. This setting is not relevant to transfers with a Policy of Fixed. true or false false
    Incoming Bandwidth Policy Allowed Set the allowed Bandwidth Policy for incoming transfers. Aspera transfers use fixed, high, fair and low policies to accommodate network-sharing requirements. When set to any, the server will not deny any transfer based on policy setting. When set to high, transfers with a Policy of high and less aggressive transfer policies (e.g. fair or low) will be permitted. When set to fair, transfers of fair and low will be permitted, while fixed transfers will be denied. When set to low, only transfers with a Bandwidth Policy of low will be allowed. fixed, high, fair / regular, low, or any any
    Incoming Bandwidth Policy Default Set the default Bandwidth Policy for incoming transfers. The default policy value may be overridden by client applications initiating transfers.
    • fixed – Attempts to transfer at the specified target rate, regardless of the actual network capacity. This policy transfers at a constant rate and finishes in a guaranteed time. This policy typically occupies most of the network's bandwidth, and is not recommended in most file transfer scenarios. In fixed mode, a maximum (target) rate value is required.
    • high – Monitors the network and adjusts the transfer rate to fully utilize the available bandwidth up to the maximum rate. When congestion occurs, a it transfers at a rate twice of a session with fair policy. In this mode, both the maximum (target) and the minimum transfer rates are required.
    • fair – Monitors the network and adjusts the transfer rate to fully utilize the available bandwidth up to the maximum rate. When other types of traffic build up and congestion occurs, it shares bandwidth fairly by transferring at an even rate. In this mode, both the maximum (target) and the minimum transfer rates are required.
    • low – Similar to fair mode, the low policy uses the available bandwidth up to the maximum rate, but is much less aggressive when sharing bandwidth with other network traffic. When congestion builds up, the transfer rate is reduced to the minimum rate until other traffic retreats.
    fixed, high, fair / regular, low, or any fair
    Incoming Bandwidth Policy Lock Set to false (default) to allow users to adjust the Bandwidth Policy once an incoming transfer is started. Set to true to prevent real-time modification of the Bandwidth Policy. true or false false
    Incoming Priority Allowed The highest priority your client can request. Use the value 0 to unset this option; 1 to allow high priority, 2 to enforce normal priority. 0, 1, or 2 1
    Incoming Priority Default The initial priority setting. Use the value 0 to unset this option, 1 to allow high priority; 2 to enforce normal priority 0, 1, or 2 2
    Incoming Priority Lock To disallow your clients change the priority, set the value to true true or false false
    Module (for incoming rate control) Located within the incoming </network_rc> stanza, this hidden setting is meant for advanced users to select an incoming rate control module (which will only be applied at the local "receiver" side). It should only be used with special instructions for debugging. Options include:
    • delay-odp: queue scaling controller
    • delay-adv: advanced rate controller
    • air: FASP air
    delay-odp, delay-adv, or air blank
    TCP Friendly (for incoming rate control) Located within the incoming </network_rc> stanza, this hidden setting is meant for advanced users to turn TCP-friendly mode on or off (which will only be applied at the local "receiver" side when the transfer policy is set to fair). It should only be used with special instructions for debugging. If turned on ("yes"), this mode allows an incoming FASP transfer to maintain relative fair bandwidth share with a TCP flow under congestion. yes or no no
    Outgoing Vlink ID Set the Vlink ID for outgoing transfers. Vlinks are a mechanism to define aggregate transfer policies. The default setting of 0 disables Vlinks. One Vlink—the virtual equivalent of a network trunk—represents a bandwidth allowance that may be allocated to a node , a group, or a user. Vlink ID is defined in each Vlink created in Aspera Console. The Vlink ID is a unique numeric identifier. predefined value 0
    Outgoing Target Rate Cap (Kbps) Set the Target Rate Cap for outgoing transfers. The Target Rate Cap is the maximum target rate that a transfer can request, in kilobits per second. No transfer may be adjusted above this setting, at any time. The default setting of unlimited signifies no Target Rate Cap. Clients requesting transfers with initial rates above the Target Rate Cap will be denied. positive integer unlimited
    Outgoing Target Rate Default (Kbps) Set the initial rate for outgoing transfers, in kilobits per second. Users may be able to modify this rate in real time, if allowed. This setting is not relevant to transfers with a Policy of Fixed. positive integer 10000
    Outgoing Target Rate Lock Set to false (default) to allow users to adjust the transfer rate once an outgoing transfer is started. Set to true to prevent real-time modification of the transfer rate. true or false false
    Outgoing Minimum Rate Cap (Kbps) Set the Minimum Rate Cap for outgoing transfers. The Minimum Rate Cap is a level specified in kilobits per second, below which an outgoing transfer will not slow, despite network congestion or physical network availability. The default value of Unlimited effectively turns off the Minimum Rate Cap. positive integer unlimited
    Outgoing Minimum Rate Default Set the initial minimum rate for outgoing transfers, in kilobits per second. Users may be able to modify this rate in real time, if allowed. This setting is not relevant to transfers with a Policy of Fixed. positive integer 0
    Outgoing Minimum Rate Lock Set to false (default) to allow users to adjust the minimum transfer rate once an outgoing transfer is started. Set to true to prevent real-time modification of the minimum transfer rate. This setting is not relevant to transfers with a Policy of Fixed. true or false false
    Outgoing Bandwidth Policy Allowed Set the allowed Bandwidth Policy for outgoing transfers. Aspera transfers use fixed, high, fair and low policies to accommodate network-sharing requirements. When set to any, the server will not deny any transfer based on policy setting. When set to high, transfers with a Policy of high and less aggressive transfer policies (e.g. fair or low) will be permitted. When set to fair, transfers of fair and low will be permitted, while fixed transfers will be denied. When set to low, only transfers with a Bandwidth Policy of low will be allowed. fixed, high, fair (regular), low, or any any
    Outgoing Bandwidth Policy Default Set the default Bandwidth Policy for outgoing transfers. The default policy value may be overridden by client applications initiating transfers.
    • fixed – Attempts to transfer at the specified target rate, regardless of the actual network capacity. This policy transfers at a constant rate and finishes in a guaranteed time. This policy typically occupies most of the network's bandwidth, and is not recommended in most file transfer scenarios. In fixed mode, a maximum (target) rate value is required.
    • high – Monitors the network and adjusts the transfer rate to fully utilize the available bandwidth up to the maximum rate. When congestion occurs, a it transfers at a rate twice of a session with fair policy. In this mode, both the maximum (target) and the minimum transfer rates are required.
    • fair – Monitors the network and adjusts the transfer rate to fully utilize the available bandwidth up to the maximum rate. When other types of traffic build up and congestion occurs, it shares bandwidth fairly by transferring at an even rate. In this mode, both the maximum (target) and the minimum transfer rates are required.
    • low – Similar to fair mode, the low policy uses the available bandwidth up to the maximum rate, but is much less aggressive when sharing bandwidth with other network traffic. When congestion builds up, the transfer rate is reduced to the minimum rate until other traffic retreats.
    fixed, high, fair, low fair
    Outgoing Bandwidth Policy Lock Set to false (default) to allow users to adjust the Bandwidth Policy once an outgoing transfer is started. Set to true to prevent real-time modification of the Bandwidth Policy. true or false false
    Outgoing Priority Allowed The highest priority your client can request. Use the value 0 to unset this option; 1 to allow high priority, 2 to enforce normal priority. 0, 1, or 2 1
    Outgoing Priority Default The initial priority setting. Use the value 0 to unset this option, 1 to allow high priority; 2 to enforce normal priority. 0, 1, or 2 2
    Outgoing Priority Lock To prevent your clients from changing the priority, set the value to true. true or false false
    Module (for outgoing rate control) Located within the outgoing <network_rc> stanza, this hidden setting is meant for advanced users to select an outgoing rate control module (which will only be applied at the local "receiver" side). It should only be used with special instructions for debugging. Options include:
    • delay-odp: queue scaling controller
    • delay-adv: advanced rate controller
    • air: FASP air
    delay-odp, delay-adv, or air blank
    TCP Friendly (for outgoing rate control) Located within the outgoing <network_rc> stanza, this hidden setting is meant for advanced users to turn TCP-friendly mode on or off (which will only be applied at the local "receiver" side when the transfer policy is set to fair). It should only be used with special instructions for debugging. If turned on ("yes"), this mode allows an outgoing FASP transfer to maintain relative fair bandwidth share with a TCP flow under congestion. yes or no no
    Bind IP Address Specify an IP address for server-side ascp to bind its UDP connection. If a valid IP address is given, ascp sends and receives UDP packets only on the interface corresponding to that IP address.
    Important: The bind address should only be modified (changed to an address other than 127.0.0.1) if you, as the System Administrator, understand the security ramifications of doing so, and have undertaken precautions to secure the SOAP service.
    valid IPv4 address blank
    Bind UDP Port Prevent the client-side ascp process from using the specified UDP port. integer between 1 and 65535 33001
    Disable Packet Batching Set to true to send data packets back-to-back (no sending a batch of packets). This results in smoother data traffic at a cost of higher CPU usage. true or false false
    Batch Size When set to "0" (default), the system uses a pre-computed batch size. Set this to "1" for high concurrency servers (senders) in order to reduce CPU utilization in aggregate. Integer 0
    Datagram Size Sets the datagram size on the server side. If size is set with both -Z (client side) and <datagram_size> (server side), the <datagram_size> setting is used. In cases where the client-side is pre-3.3, datagram size is determined by the -Z setting, regardless of the server-side setting for <datagram_size>. In such cases, if there is no -Z setting, datagram size is based on the discovered MTU and the server logs the message "LOG Peer client doesn't support alternative datagram size". Integer 1492
    Maximum Socket Buffer (bytes) Set the upper bound of the UDP socket buffer of an ascp session below the input value. The default of 0 will cause the Aspera sender to use its default internal buffer size, which may be different for different operating systems. positive integer 0
    Minimum Socket Buffer (bytes) Set the minimum UDP socket buffer size for an ascp session. positive integer 0
    RTT auto correction Set to true to enable auto correction of the base (minimum) RTT measurement. This feature is helpful for maintaining accurate transfer rates in hypervisor-based virtual environments. true or false false
    Reverse path congestion inference Set to true to prevent the transfer speed of a session from being adversely affected by congestion in the reverse (non data-sending) transfer direction. This feature is useful for boosting speed in bi-directional transfers. true or false true
    Strong Password Required for Content Encryption Set to true to require the password for content encryption to contain at least 6 characters, of which at least 1 is non-alphanumeric, at least 1 is a letter, and at least 1 is a digit. true or false false
    Content Protection Required Set to true to require that content be left encrypted at the destination.
    • Users are required to enter a password during upload to encrypt the files on the server.
    • Users will be given the option when downloading to decrypt during transfer.
    true or false false
    Encryption Allowed Set the type of transfer encryption accepted by this computer. Set to any to allow both encrypted and non-encrypted transfers to this computer. Set to none to allow only non-encrypted transfers. Set to aes-128 to allow only encrypted transfers. any, noneaes-128, aes-192, or aes-256 any
    Do encrypted transfers in FIPS-140-2-certified encryption mode Set to true for ascp to use a FIPS 140-2-certified encryption module. When enabled, transfer start is delayed while the FIPS module is verified.

    When you run ascp in FIPS mode (that is, <fips_enabled> is set to true in aspera.conf), and you use passphrase-protected SSH keys, you must use keys generated by running ssh-keygen in a FIPS-enabled system, or convert existing keys to a FIPS-compatible format using a command such as the following:

    openssl pkcs8 -topk8 -v2 aes128 -in id_rsa -out new-id_rsa
    Important: When set to true, all ciphers and hash algorithms that are not FIPS compliant will abort transfers.
    true or false false
    Run at File Start Enables validation when starting a file. This happens before file transfer starts. For more information on inline file validation, see Inline File Validation (Overview). uri, lua_script, or none none
    Run at File Stop Enables validation when reporting file transfer end. This happens after file transfer is complete and file is closed. For more information on inline file validation, see Inline File Validation (Overview). uri, lua_script, or none none
    Run at Session Start Enables validation when an ascp session starts. For more information on inline file validation, see Inline File Validation (Overview). uri, lua_script, or none none
    Run at Session Stop Enables validation when an ascp session ends. For more information on inline file validation, see Inline File Validation (Overview). uri, lua_script, or none none
    Run when Crossing File Threshold Enables validation when a set threshold in the file transfer is reached. For more information on inline file validation, see Inline File Validation (Overview).

    Note: For threshold validation, it is possible for the file transfer to complete before the file threshold validation response comes back (because ascp doesn't pause file transfers during file threshold validation); therefore, a complete file transfer could happen even with validation failure.

    uri, lua_script, or none none
    Validation Threshold KB Threshold validation occurs- after the threshold value defined in this option is met during file download (when at least the threshold KB of the file is downloaded). Since threshold validation can only be triggered periodically (every second in the worst case), the file must be large enough to trigger this validation.

    The Validation Threshold option must also be specified (uri or lua) if this option is to be recognized by the system.

    If Validation Threshold is also enabled, and this value is not specified (or set to 0), the ascp session will exit with an error.
    Positive integer 0
    Validation Threads Setting a value enables multiple validations to happen in parallel in validator threads.

    Note: If the number of validation threads is not set to 1, then muliple threads may perform different types of validations for different (or the same) files at the same time. In such a situation, the response of a validation_file_stop at the end of a file download might come before the response of a validation_threshold for the same file.

    Positive integer 5
    Validation URI External URL used for validation calls. When this parameter is defined, at least two validations, validation_file_start and validation_file_stop will happen for every file.

    The entry should define a URL, port, and URL handler for validation. For example, http://127.0.0.1:8080/SimpleValidator

    This value must be defined if any of the following values are set to uri:
    • validation_file_start
    • validation_file_stop
    • validation_ session_start
    • validation_session_stop
    • validation_threshold
    URL none
    Base64-Encoded Lua Action Script For Lua API validation, enter the base64-encoded value. If both this option and File Path to Lua Action Script option are defined, this value is ignored. For more information on inline file validation, see Inline File Validation (Overview).

    This value must be defined if any of the following values are set to lua_script: Run at File Start, Run at File Stop, Run at Session Start, Run at Session Stop, Run when Crossing File Threshold.

    Base64-encoded string blank
    File Path to Lua Action Script For Lua API validation, enter a file path. If both this option and the Base64-Encoded Lua Action Script option are defined, this value is the one recognized by the system.
    This value must be defined if any of the following values are set to lua_script:
    • validation_file_start
    • validation_file_stop
    • validation_ session_start
    • validation_session_stop
    • validation_threshold

    For more information on inline file validation, see Inline File Validation (Overview).

    Filepath blank
  4. Save and validate aspera.conf.
    Run the following command to confirm that the XML is correctly formatted and the parameter settings are valid:
    # /opt/aspera/bin/asuserdata -v