Reporting Checksums

Enterprise Server determines the success of transfers by using checksums to verify that file contents at a destination match what was read at the source. Enterprise Server can be configured to report these checksums to users.

Note: Checksum reporting requires that both the server and client nodes be running Enterprise Server, Connect Server, or Point-to-Point Client version 3.4.2 or higher.

By default, checksum reporting is turned off. The feature can be enabled and configured on the server using any of the following methods:

The command-line option overrides settings in aspera.conf and the GUI.

Additional options in aspera.conf and the GUI allow you to configure where checksum reports should be saved, described in the table below.

aspera.conf Option
GUI Setting

Description Default

<file_checksum>
File checksum method

Enable checksum reporting, specifying the type of checksum to calculate for transferred files.
  • md5 - Calculate and report an MD5 checksum.
  • sha1 - Calculate and report an SHA-1 checksum.
  • any - Allow the checksum format to be whichever format the client requests.
Note: The none option is no longer supported as of version 3.4.2. If your aspera.conf file has a <file_checksum> setting of none, transfers will fail with the error "Server aborted Session: Invalid configuration file".
any

<file_manifest>
File Manifest

The file manifest is a file containing a list of everything that was transferred in a given transfer session. The filename of the file manifest itself is automatically generated based on the transfer session's unique ID.

When set to disable, no file manifest is created.

When set to text a text file "receipt" of all files within each transfer session is generated.

disable

<file_manifest_path>
File Manifest Path

The location where manifest files are to be written. The location can be an absolute path or a path relative to the transfer user's home.

If no path is specified, the file will be generated under the destination path at the receiver, and under the first source path at the sender.

Note: File manifests can only be stored locally. Thus, if you are using S3, or other non-local storage, you must specify a local manifest path.
blank

Enabling checksum reporting by editing aspera.conf

To enable checksum reporting, run the following command to set the <file_checksum> option in the <file_system> section of the aspera.conf file on your server.

> asconfigurator -x "set_node_data;file_checksum,checksum"

To enable and configure the file manifest where checksum report data is stored, add settings for <file_manifest> and <file_manifest_path> by running the following commands:

> asconfigurator -x "set_node_data;file_manifest,text"
> asconfigurator -x "set_node_data;file_manifest_path,filepath"

These commands create lines in aspera.conf as shown in the example below, in which the path is C:\Users\Public\reports.

<file_system>
    ...
    <file_checksum>md5</file_checksum>
    <file_manifest>text</file_manifest>
    <file_manifest_path>C:\Users\Public\reports</file_manifest_path>
    ...
</file_system>

Enabling checksum reporting from the GUI

Click Configuration to open the Server Configuration window. Select the Global, Groups, or Users tab, depending on whether you want to configure checksum reporting for all users, or for a particular group or user.

Under the File Handling tab, locate the setting for File checksum method. Check the override box and for the effective value, select md5, sha1, or any.

To enable the file manifest from the GUI, select the override checkbox for File Manifest and set the effective value to text. To set the path, select the override checkbox for File Manifest Path and set the effective value to the folder in which you want the manifest files saved.

In the examples above, the manifest is generated when files are transferred and saved as a text file called aspera-transfer-transfer_id-manifest.txt in the directory C:\Users\Public\reports.

Enabling checksum reporting from the ascp Command Line

To enable checksum reporting on a per-transfer-session basis, run ascp with the --file-checksum=hash option, where hash is sha1, md5, or any.

Enable the manifest with the option --file-manifest=output where output is either text or none. You can set the path to the manifest file with the option --file-manifest-path=path.

For example:

> ascp --file-checksum=md5 --file-manifest=text --file-manifest-path=C:\Users\Public\reports file aspera_user_1@189.0.202.39:/destination_path

Setting up a Pre/Post-processing Script

An alternative to enabling and configuring the file manifest to collect checksum reporting is to set up a pre/post-processing script to report the values.

The checksum of a successfully transferred file is stored in the pre/post environment variable FILE_CSUM. This environment variable can be used in pre/post scripts to capture file checksums. For example, the following script outputs the checksum to the file C:\Users\Public\reports\cksum.log:

if "%TYPE%"=="File" (
    if "%STARTSTOP%"=="Stop" (
        echo "The file is: %FILE%" >> C:\Users\Public\reports\cksum.log
        echo "The file checksum is: %FILE_CSUM%" >> C:\Users\Public\reports\cksum.log
    )
)

For information on how to set up pre- and post-processing scripts such as the above and how to use built-in pre/post environment variables, see Pre- and Post-Processing (Prepost).