File checksums are useful for trouble-shooting file corruption, allowing you to determine at what point in the transfer file corruption occurred. Aspera servers can report source file checksums that are calculated on-the-fly during transfer and then sent from the source to the destination. To do so, the transfer must meet both of the following requirements:
The user on the destination can calculate a checksum for the received file and compare it (manually or programmatically) to the checksum reported by the sender. The checksum reported by the source can be retrieved in the destination logs, a manifest file, in Aspera Console, or as an environment variable. Instructions for comparing checksums follow the instructions for enabling checksum reporting.
Checksum reporting is disabled by default. You can enable and configure checksum reporting on the server by using the following methods:
Command-line options override the settings in aspera.conf and the GUI.
|Enable checksum reporting and specify the type of checksum to calculate for
Note: The default value for the ascp option is none, in which case the reported checksum is the one configured on the server, if any.
|The file manifest is a file that contains a list of content that was
transferred in a transfer session. The file name of the file manifest is
automatically generated from the transfer session ID.
When set to none, no file manifest is created. (Default)
When set to text, a text file is generated that lists all files in each transfer session.
|The location where manifest files are written. The location can be an
absolute path or a path relative to the transfer user's home directory. If
no path is specified (default), the file is generated under the destination
path at the receiver, and under the first source path at the sender.
Note: File manifests can be stored only locally. Thus, if you are using S3 or other non-local storage, you must specify a local manifest path.
To enable checksum reporting, run the following asconfigurator command:
> asconfigurator -x "set_node_data;file_checksum,checksum"
To enable and configure the file manifest where checksum report data is stored, run 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 following example, where checksum type is md5, file manifest is enabled, and 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>
Click Configuration to open the Server Configuration window. Select the Global, Groups, or Users tab, depending on whether you want to enable 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 any, md5, sha1, sha256, sha384, or sha512.
To enable the file manifest, select the override check box for File Manifest and set the effective value to text. To set the path, select the override check box 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.
To enable checksum reporting on a per-transfer-session basis, run ascp with the --file-checksum=hash option, where hash is sha1, md5, sha-512, sha-384, sha-256, or none (the default).
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.
> ascp --file-checksum=md5 --file-manifest=text --file-manifest-path=C:\Users\Public\reports file email@example.com:/destination_path
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 transferred file is stored in the pre/post environment variable FILE_CSUM, which can be used in pre/post scripts to output 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 pre- and post-processing scripts and environment variables, see File Pre- and Post-Processing (Prepost).
If you open a file that you downloaded with Aspera and find that it is corrupted, you can determine when the corruption occurred by comparing the checksum that is reported by Aspera to the checksums of the files on the destination and on the source.
> CertUtil -hashfile filepath MD5
> CertUtil -hashfile filepath MD5
$ md5 filepath
# md5sum filepath
# csum -h MD5 filepath
# digest -a md5 -v filepath