aspera.conf - File system configuration

The settings in the <file_system> section of aspera.conf include the docroot, file permissions, file handling, filters, checksum reporting, and growing files. The absolute path, or docroot, is the area of the file system that is accessible to an Aspera transfer user. The default empty value allows access to the entire file system. You can set one global docroot and then further restrict access to the file system by group or individual user.

Important configuration notes:

  • The default server configuration gives users full access to the server's file system with read, write, and browse privileges. Set a global docroot that is an empty folder and set the global file permissions to false.
  • Some Aspera features require a docroot in URI format or require a file restriction instead of a docroot. For more information, see Docroot versus file restriction.
Configuration methods: These instructions describe how to manually modify aspera.conf. You can also add and edit these parameters that use asconfigurator commands. For more information on using asconfigurator, see User, group, and default configurations. Run the following command to retrieve a complete default aspera.conf file that includes the asconfigurator syntax for each setting:
> asuserdata -+
  1. Open aspera.conf from the following location:

    C:\Program Files\Aspera\Enterprise Server\etc\aspera.conf

  2. Add or locate the <file_system /> section, as in the following example.
    <file_system>
       <access>
          <paths>
             <path>
                <absolute peer_ip="ip_address">/path/$(name)</absolute>
                                                           <!-- Absolute Path (conditional) -->
                <absolute>/path/$(name)</absolute>            <!-- Absolute Path -->            <!-- Growing files handling can also be specified within the <absolute> section; 
                     for detailed informataion, see the following table -->
                <restrictions>
                    <restriction></restriction>       <!-- File Restriction 1 -->
                    <restriction></restriction>       <!-- File Restriction 2 -->
                </restrictions>
                <read_allowed>true</read_allowed>          <!-- Read Allowed -->
                <write_allowed>true</write_allowed>        <!-- Write Allowed -->
                <dir_allowed>true</dir_allowed>            <!-- Browse Allowed -->
             </path>
          </paths>
       </access>
       <read_block_size>0</read_block_size>                <!-- Read Block Size -->
       <write_block_size>0</write_block_size>              <!-- Write Block Size -->
       <read_threads>0</read_threads>                       <!–- Number of I/O Read Threads -->
       <write_threads>0</write_threads>                     <!–- Number of I/O Write Threads -->
       <scan_threads>0</scan_threads>                       <!-- Number of Dir Scanning Threads -->
       <meta_threads>0</meta_threads>                       <!-- Number of Metadata Threads -->
       <worker_threads>0</worker_threads>
       <sparse_file>false</sparse_file>                     <!-- Sparse File Checking -->
       <fail_on_attr_error>yes</fail_on_attr_error>         <!-- Behavior on Attr Error -->
       <compression_method>lz4</compression_method>         <!-- Compression Method for File Transfer --> 
       <use_file_cache>true</use_file_cache>               <!-- Use File Cache -->
       <max_file_cache_buffer>0</max_file_cache_buffer>    <!-- Max File Cache Buffer-->
       <resume_suffix>.aspx</resume_suffix>                <!-- Resume Suffix -->
       <symbolic_links>follow,create</symbolic_links>      <!-- Symbolic Link Actions -->
       <preserve_attributes> </preserve_attributes>        <!-- Preserve Attributes -->
       <overwrite>allow</overwrite>                        <!-- Overwrite -->
       <file_manifest>disable</file_manifest>              <!-- File Manifest -->
       <file_manifest_path>path</file_manifest_path>        <!-- File Manifest Path -->
       <file_manifest_inprogress_suffix>.aspera-inprogress</file_manifest_inprogress_suffix>
                                                           <!-- File Manifest Suffix -->
       <pre_calculate_job_size>any</pre_calculate_job_size><!-- Pre-Calculate Job Size -->
       <replace_illegal_chars></replace_illegal_chars>     <!-- Convert Restricted Windows Characters -->
     
       <storage_rc>
          <adaptive>true</adaptive>                        <!-- Storage Rate Control -->
       </storage_rc>
       <filters>                                           <!-– File Filter Pattern List -->
          <filter>rule1</filter>
          <filter>rule2</filter>
       </filters>
       <partial_file_suffix>.partial</partial_file_suffix> <!-- Partial File Suffix --> 
       <file_checksum>any</file_checksum>                  <!-– File Checksum Method -->  
    </file_system>
  3. Edit settings as needed.
    File System Settings Reference
    Field Description Values Default
    Absolute Path The absolute path, or docroot, is the area of the file system that is accessible to an Aspera transfer user. The default empty value allows access to the entire file system. You can set one global docroot and then further restrict access to the file system by group or individual user. Docroot paths require specific formatting that depends on where the transfer server's storage is located.
    Format examples:
    • Local storage-absolute path:C:\Users\aspera424\movies

      Or using a placeholder for usernames: C:\Users\$(name)

    • Local storage in URI format: file:///C:\Users\bear\movies

      URI format is required for server-side encryption at rest, but is not supported by the Aspera Watch Service.

    Set a global docroot to an empty folder or a part of the file system specific to each user. If there is a pattern in the docroot of each user, for example, C:\sandbox\username, you can use a substitutional string. Allowing you to assign an independent docroot to each user without setting it individually for each user. For more information, see Setting up users.

    You can also set multiple docroots and make them conditional based on the IP address from which the connection is made by editing aspera.conf. To do so, edit the absolute path setting by adding the IP address by using the following syntax:
    <absolute peer_ip="ip_address">path</absolute>
    Growing files allows you to start transferring files to the target directory while they are still being written to the source directory. To configure aspera.conf for growing files:
    • Edit the <absolute> section.
    • Add your growing files specification using the syntax described in Ascp command reference for the source element.

    See also Ascp general examples.

    file path or URI undefined (total access)
    File Restriction
    Note: A configuration (global, group, or user) can have a docroot or a file restriction; configurations with both are not supported.
    A set of file system filters that use "*" as a wildcard and "!" to indicate "exclude". Paths are in URI format; special characters in a URI must be URL-encoded.

    Access to a file is rejected unless the file matches the restrictions, which are processed in the following order:

    • If a restriction starts with "!", the user is not allowed to access any files that match the rest of the restriction.
    • If a restriction does not start with "!", the user can access any file that matches the filter.
    • If one or more restrictions do not start with "!", the user can access any file that matches any one of the no-"!" restrictions.

    Format examples:

    • For a specific folder:

      file:///c%3A/Documents/*
    • For the drive root:

      file:////*
    • For ICOS-S3 storage:

      s3://my_vault/*
    • To exclude access to key files:

      !*.key
    URI undefined (total access)
    Read Allowed Set to true to allow users to transfer files and folders from their docroot.
    • true
    • false
    true
    Write Allowed Set to true to allow users to transfer files and folders to their docroot.
    • true
    • false
    true
    Browse Allowed Set to true to allow users to browse their docroot.
    • true
    • false
    true
    Read Block Size (bytes) Set the maximum number of bytes that can be stored within a block as the block is being transferred from the source disk drive to the receiver. The default of zero causes the Aspera sender to use its default internal buffer size, which might vary by operating system. This is a performance-tuning parameter for an Aspera sender, which only takes effect if the sender is a server. Positive integer, where 500 MB or 524,288,000 bytes is the maximum block size. 0
    Write Block Size (bytes) Set the maximum bytes within a block that an ascp receiver can write to disk. The default of zero causes the Aspera receiver to use its default internal buffer size, which might vary by operating system. This is a performance-tuning parameter for an Aspera receiver, which only takes effect if the receiver is a server. Positive integer, where 500 MB or 524,288,000 bytes is the maximum block size. 0
    Number of I/O Read Threads Set the number of threads the Aspera sender uses to read file contents from the source disk drive. It takes effect on both client and server, when acting as a sender. The default of zero causes the Aspera sender to use its internal default, which might vary by operating system. This is a performance-tuning parameter for an Aspera sender. Positive integer 0
    Number of I/O Write Threads Set the number of threads the Aspera receiver uses to write the file contents to the destination disk drive. It takes effect on both client and server, when acting as a receiver. The default of zero causes the Aspera receiver to use its internal default, which might vary by operating system. This is a performance-tuning parameter for an Aspera receiver. Positive integer 0
    Number of Dir Scanning Threads Set the number of threads the Aspera sender uses to scan directory contents. It takes effect on both client and server, when acting as a sender. The default of zero causes the Aspera sender to use its internal default. This is a performance-tuning parameter for an Aspera sender. Positive integer 0
    Number of Metadata Threads Set the number of threads the Aspera receiver uses to create directories or 0-byte files. It takes effect on both client and server, when acting as a receiver. The default of zero causes the Aspera receiver to use its internal default, which might vary by operating system. This is a performance-tuning parameter for an Aspera receiver. Positive integer 0
    Number of Worker Threads Set the number of threads the Aspera sender and receiver use to delete files. This is a performance-tuning parameter. Positive integer 0
    Sparse File Checking
    • Set to true to enable sparse file checking, which tells the Aspera receiver to avoid writing zero blocks and save disk space.
    • Set to false to tell the Aspera receiver to write all the blocks. This is a performance-tuning parameter for an Aspera receiver.
    true or false false
    Behavior on Attr Error Set behavior for when operations attempt to set or change file attributes (such as POSIX ownership, ACLs, or modification time) and fail. Setting to yes returns an error and causes the operation to fail. Setting to no logs the error and the operation continues. no or yes yes
    Compression Method for File Transfer Set the compression method to apply to transfers. It applies to both the client and server. lz4, qlz, zlib, or none lz4
    Use File Cache Set to true (default) to enable per-file memory caching at the data receiver. File level memory caching improves data write speed on Windows platforms in particular, but uses more memory. This is a performance-tuning parameter for an Aspera receiver.

    Use a file cache on systems that are transferring data at speeds close to the performance of their storage device, and disable it for system with very high concurrency. Memory utilization grows with the number of concurrent transfers.

    true or false true
    Max File Cache Buffer (bytes) Set the maximum size allocated for per file memory cache in bytes, see Use File Cache. The default of zero causes that the Aspera receiver uses its internal buffer size, which might be different for different operating systems. This is a performance-tuning parameter for an Aspera receiver. Positive integer 0
    Resume Suffix Set the file name extension for temporary metadata of files that are used for resuming incomplete transfers. Each data file in progress has a corresponding metadata file with the same name, plus the resume suffix that was specified by the receiver. Metadata files in the source of a directory transfer are skipped if they end with the sender's resume suffix.
    Note: When you change the resume suffix, you need to restart the Aspera Sync service, in order for Hot Folders to pick up new settings. The Aspera Sync service also manages the Hot Folders transfers. To restart the service, go to Search from the taskbar and type Services, then click IBM Aspera Sync and click Restart.
    Text string .aspx
    Symbolic Link Actions Set how the server handles symbolic links. For more information about the actions and the interaction between the server configuration and the client request, see Symbolic link handling. Combinations of values are logically ORed before use. For example, use none alone to mean skip, and shut out other options; when both follow and follow_wide are set, the latter is recognized.
    To set a combination of actions globally or for individual users, you must edit the configuration file aspera.conf by running the following command:
    > asconfigurator -x "set_node_data;symbolic_links,value"
    > asconfigurator -x "set_user_data;user_name,username;symbolic_links,value"
    none, create, follow, follow_wide, or any combination delimited by commas follow,create
    Preserve Attributes Set the file creation policy.
    • Set to none to not preserve the timestamps of source files.
    • Set to times to preserve the timestamp of the source files at destination.
    Note: For Limelight storage, only the preservation of modification time is supported.
    none or times Blank (use the client setting)
    Overwrite
    • Set to allow to allow Aspera clients to overwrite existing files on the server, when the file permissions allow that action.
    • Set to deny so clients who upload files to the server cannot overwrite existing files, regardless of file permissions.
    allow or deny allow
    File Manifest
    • Set to text to generate a text file receipt of all files within each transfer session.
    • Set to disable to not create a File Manifest.

    The manifest file is a file that contains a list of everything that was transferred in a transfer session. The file name of the File Manifest itself is automatically generated based on the transfer session's unique ID. The location where each manifest is written is specified by the File Manifest Path value. If no File Manifest Path is specified, the file is generated under the destination path at the receiver, and under the first source path at the sender.

    text, disable, or none none
    File Manifest Path Specify the location to store manifest files. Can be an absolute path or a path relative to the transfer user's home.
    Note: File manifests can only be stored locally. Thus, if you are using S3, or other nonlocal storage, you must specify a local manifest path.
    Text string Blank
    File Manifest Suffix Specify the suffix of the manifest file during file transfer. Text string .aspera-inprogress
    Pre-Calculate Job Size
    • Set to yes to enable calculating job size before the transfer.
    • Set to no to disable calculating job size before the transfer.
    • Set to any to follow client configurations.
    yes, no, or any any
    Convert Restricted Windows Characters To enable the replacement of reserved Windows characters in file and directory names with a nonreserved character, set to the single byte, nonrestricted character that is used for the replacement. Only applies to files written to the local Windows file system; to enable on the peer it must be set on the peer's system. Single-byte, nonrestricted character Blank
    File Filter Pattern List Exclude or include files and directories with the specified pattern in the transfer. Add multiple entries for more inclusion or exclusion patterns. To specify an inclusion, start the pattern with + (+ and a white space). To specify an exclusion, start the pattern with - (- and a white space). Two symbols can be used in the setting of patterns:
    • A * (asterisk) represents zero to many characters in a string. For example, *.tmp matches .tmp and abcde.tmp.
    • A ? (question mark) represents a single character. For example, t?p matches tmp but not temp.

    For more information about specifying rules, see Using filters to include and exclude files.

    This option applies only when the server is acting as a client. Servers cannot exclude files or directories that were uploaded or downloaded by remote clients.

    Text entries Blank
    Partial File Name Suffix Set the file name extension on the destination computer while the file is being transferred. When the file is transferred, the file name extension is removed.

    If Hot Folders are upload destinations, the partial file name suffix must be set to some value to prevent partial files from being downloaded from a hot folder.

    Note: When you change the partial file name setting, you need to restart the Aspera Sync service, in order for Hot Folders to pick up new settings. The Aspera Sync service also manages the Hot Folders transfers. To restart the service, go to Search from the taskbar and type Services, then click IBM Aspera Sync and click Restart.
    Note: This option only takes effect when it is set on the receiver side.
    Text string Blank
    File Checksum Method Set the type of checksum to calculate for transferred files. The content of transfers can be verified by comparing the checksum value at the destination with the value that is read at the source. For more information, see Reporting checksums. any, md5, sha1, sha256, sha384, or sha512 any
  4. Save and validate aspera.conf.
    Run the following command to confirm that the XML is correctly formatted and the parameter settings are valid:
    > asuserdata -v