Ascp Command Reference

The ascp executable is a command-line FASP transfer program. This reference describes ascp syntax, command options, and supported environment variables.

For examples of ascp commands, see the following topics:

Another command-line FASP transfer program, Ascp 4 (ascp4), is optimized for transfers of many small files. It has many of the same capabilities as ascp, as well as its own features. For more information, see Introduction to Ascp 4 and Comparison of Ascp and Ascp 4 Options.

Ascp Syntax

ascp options [[username@]src_host:]source1[ source2 ...] [[username@]dest_host:]dest_path
username
The username of the Aspera transfer user can be specified as part of the source or destination, whichever is the remote server. It can also be specified with the --user option. If you do not specify a username for the transfer, the local username is authenticated by default.
Note: If you are authenticating on a Windows computer as a domain user, the transfer server strips the domain from the username. For example, Administrator is authenticated rather than DOMAIN\Administrator. For this reason, you must specify the domain explicitly.
src_host
The name or IP address of the computer where the files or directories to be transferred reside.
source
The file or directory to be transferred. Separate multiple arguments with spaces.
dest_host
The name or IP address of the computer where the source files or directories are to be transferred.
dest_path
The destination directory where the source files or directories are to be transferred.
  • If the source is a single file, the destination can be a filename. However, if there are multiple source arguments, the destination must be a directory.
  • To transfer to the transfer user's docroot, specify "." as the destination.
  • If the destination is a symbolic link, then the file or directory is written to the target of the symbolic link.

Specifying Files, Directories, and Paths

  • Specify paths on the remote computer relative to the transfer user's docroot. If the user has a restriction instead of a docroot, specify the full path, which must be allowed by the restriction.
  • Avoid the following characters in file and directory names: / \ " : ' ? > < & * |
  • Specify paths with forward-slashes, regardless of the operating system.
  • If directory or file arguments contain special characters, specify arguments with single-quotes (' ') to avoid interpretation by the shell.

URI paths: URI paths are supported, but with the following restrictions:

  • If the source paths are URIs, they must all be in the same cloud storage account. No docroot (download), local docroot (upload), or source prefix can be specified.
  • If a destination path is a URI, no docroot (upload) or local docroot (download) can be specified.
  • The special schemes stdio:// and stdio-tar:// are supported on the client side only. They cannot be used for specifying an upload destination or download source.
  • If required, specify the URI passphrase as part of the URI or set it as an environment variable (ASPERA_SRC_PASS or ASPERA_DST_PASS, depending on the transfer direction).

UNC paths: If the server is Windows and the path on the server is a UNC path (a path that points to a shared directory or file on Windows), it can be specified in an ascp command using one of the following conventions:

  • As an UNC path that uses backslashes ( \ ): If the client side is a Windows computer, the UNC path can be used with no alteration. For example, \\192.168.0.10\temp. If the client is not a Windows computer, every backslash in the UNC path must be replaced with two backslashes. For example, \\\\192.168.0.10\\temp.

  • As an UNC path that uses forward slashes ( / ): Replace each backslash in the UNC path with a forward slash. For example, if the UNC path is \\192.168.0.10\temp, change it to //192.168.0.10/temp. This format can be used with any client-side operating system.

Testing paths: To test ascp transfers, use a faux:// argument in place of the source or target path to send random data without writing it to disk at the destination. For more information, see IBM Aspera High-Speed Transfer Server Admin Guide: Testing and Optimizing Transfer Performance. For examples, see Ascp General Examples.

Required File Access and Permissions

  • Sources (for downloads) or destinations (for uploads) on the server must be in the transfer user's docroot or match one of the transfer user's file restrictions, otherwise the transfer stops and returns an error.
  • The transfer user must have sufficient permissions to the sources or destinations, for example write access for the destination directory, otherwise the transfer stops and returns a permissions error.
  • The transfer user must have authorization to do the transfer (upload or download), otherwise the transfer stops and returns a "management authorization refused" error.
  • Files that are open for write by another process on a Windows source or destination cannot be transferred and return a "sharing violation" error. On Unix-like operating systems, files that are open for write by another process are transferred without reporting an error, but may produce unexpected results depending on what data in the file is changed and when relative to the transfer.

Environment Variables

The following environment variables can be used with the ascp command. The total size for environment variables depends on your operating system and transfer session. Aspera recommends that each environment variable value should not exceed 4096 characters.

ASPERA_DST_PASS=password
The password to authenticate a URI destination.
ASPERA_LOCAL_TOKEN=token
A token that authenticates the user to the client (in place of SSH authentication).
Note: If the local token is a basic or bearer token, the access key settings for cipher and preserve_time are not respected and the server settings are used. To set the cipher and timestamp preservation options as a client, set them in the command line.
ASPERA_PROXY_PASS=proxy_server_password
The password for an Aspera Proxy server.
ASPERA_SCP_COOKIE=cookie
A cookie string that you want associated with transfers.
ASPERA_SCP_DOCROOT=docroot
The transfer user docroot. Equivalent to using --apply-local-docroot when a docroot is set in aspera.conf.
ASPERA_SCP_FILEPASS=password
The passphrase to be used to encrypt or decrypt files. For use with --file-crypt.
ASPERA_SCP_KEY="-----BEGIN RSA PRIVATE KEY..."
The transfer user private key. Use instead of the -i option.
ASPERA_SCP_PASS=password
The password for the transfer user.
ASPERA_SCP_TOKEN=token
The transfer user authorization token. Overridden by -W.
ASPERA_SRC_PASS=password
The password to authenticate to a URI source.

Ascp Options

-6
Enable IPv6 address support. When specifying an IPv6 numeric host for src_host or dest_host, write it in brackets. For example, username@[2001:0:4137:9e50:201b:63d3:ba92:da]:/path or --host=[fe80::21b:21ff:fe1c:5072%eth1].
-@ range_start:range_end
Transfer only part of a file: range_start is the first byte to send, and range_end is the last. If either position is unspecified, the file's first and last bytes (respectively) are assumed. This option only works for downloads of a single file and does not support transfer resume.
-A, --version
Display version and license information.
--apply-local-docroot
Apply the local docroot that is set in aspera.conf for the transfer user. Use to avoid entering object storage access credentials in the command line. This option is equivalent to setting the environment variable ASPERA_SCP_DOCROOT.
-C nodeid:nodecount
Enable multi-session transfers (also known as parallel transfers) on a multi-node/multi-core system. A node ID (nodeid) and count (nodecount) are required for each session. nodeid and nodecount can be 1-128, but nodeid must be less than or equal to nodecount, such as 1:2, 2:2. Each session must use a different UDP port specified with the -O option. Large files can be split across sessions, see --multi-session-threshold. For more information, see the IBM Aspera High-Speed Transfer Server Admin Guide: Configuring Multi-Session Transfers.
-c cipher
Encrypt in-transit file data using the specified cipher. Aspera supports three sizes of AES cipher keys (128, 192, and 256 bits) and supports two encryption modes, cipher feedback mode (CFB) and Galois/counter mode (GCM). The GCM mode encrypts data faster and increases transfer speeds compared to the CFB mode, but the server must support and permit it.

Cipher rules

The encryption cipher that you are allowed to use depends on the server configuration and the version of the client and server:

  • When you request a cipher key that is shorter than the cipher key that is configured on the server, the transfer is automatically upgraded to the server configuration. For example, when the server setting is AES-192 and you request AES-128, the server enforces AES-192.
  • When the server requires GCM, you must use GCM (requires version 3.9.0 or newer) or the transfer fails.
  • When you request GCM and the server is older than 3.8.1 or explicity requires CFB, the transfer fails.
  • When the server setting is "any", you can use any encryption cipher. The only exception is when the server is 3.8.1 or older and does not support GCM mode; in this case, you cannot request GCM mode encryption.
  • When the server setting is "none", you must use "none". Transfer requests that specify an encryption cipher are refused by the server.

Cipher Values

Value Description Support

aes128
aes192
aes256

 Use the GCM or CFB encryption mode, depending on the server configuration and version (see cipher negotiation matrix). All client and server versions.

aes128cfb
aes192cfb
aes256cfb

 Use the CFB encryption mode. Clients version 3.9.0 and newer, all server versions.

aes128gcm
aes192gcm
aes256gcm

 Use the GCM encryption mode. Clients and servers version 3.9.0 and newer.
none Do not encrypt data in transit. Aspera strongly recommends against using this setting. All client and server versions.

Client-Server Cipher Negotiation

The following table shows which encryption mode is used depending on the server and client versions and settings:

  Server, v3.9.0+

AES-XXX-GCM

 Server, v3.9.0+

AES-XXX-CFB

 Server, v3.9.0+

AES-XXX

 Server, v3.8.1 or older

AES-XXX
Client, v3.9.0+

AES-XXX-GCM

 GCM server refuses transfer GCM server refuses transfer
Client, v3.9.0+

AES-XXX-CFB

 server refuses transfer CFB CFB CFB
Client, v3.9.0+

AES-XXX

 GCM CFB CFB CFB
Client, v3.8.1 or older

AES-XXX

 server refuses transfer CFB CFB CFB
--check-sshfp=fingerprint
Compare fingerprint to the server SSH host key fingerprint that is set with <ssh_host_key_fingerprint> in aspera.conf. Aspera fingerprint convention is to use a hex string without the colons; for example, f74e5de9ed0d62feaf0616ed1e851133c42a0082. For more information on SSH host key fingerprints, see the IBM Aspera High-Speed Transfer Server Admin Guide: Securing your SSH Server.

Note: If HTTP fallback is enabled and the transfer "falls back" to HTTP, this option enforces server SSL certificate validation (HTTPS). Validation fails if the server has a self-signed certificate; a properly signed certificate is required.

-D | -DD | -DDD
Log at the specified debug level. With each D, an additional level of debugging information is written to the log.
-d
Create the destination directory if it does not already exist. This option is automatically applied to uploads to object storage.
--delete-before-transfer
Before transfer, delete any files that exist at the destination but not also at the source. The source and destination arguments must be directories that have matching names. Do not use with multiple sources, keepalive, URI storage, or HTTP fallback. The asdelete tool provides the same capability.
--dest64
Indicate that the destination path or URI is base64 encoded.
-E 'pattern'
Exclude files or directories from the transfer based on matching the specified pattern to file names and paths (to exclude files by modification time, use --exclude-newer-than or --exclude-older-than). Use the -N option (include) to specify exceptions to -E rules. Rules are applied in the order in which they are encountered, from left to right. The following symbols can be used in the pattern:
  • * (asterisk) represents zero or more characters in a string, for example *.tmp matches .tmp and abcde.tmp.
  • ? (question mark) represents a single character, for example t?p matches tmp but not temp.

For details and examples, see Using Filters to Include and Exclude Files.

Note: When filtering rules are found in aspera.conf, they are applied before rules given on the command line (-E and -N).
-e prepost_script
Run the specified pre-post script as an alternate to the default aspera-prepost script. Specify the full path to the pre-post script. Use pre-post scripts to run custom commands such as shell scripts, Perl scripts, Windows batch files, and executable binaries that can invoke a variety of environment variables. For instructions, see the IBM Aspera High-Speed Transfer Server Admin guide.
--exclude-newer-than=mtime, --exclude-older-than=mtime
Exclude files (but not directories) from the transfer, based on when the file was last modified. Positive mtime values are used to express time, in seconds, since the original system time (usually 1970-01-01 00:00:00). Negative mtime values (prefixed with "-") are used to express the number of seconds prior to the current time.
-f config_file
Read Aspera configuration settings from config_file rather than aspera.conf(the default).
--file-checksum=hash
Enable checksum reporting for transferred files, where hash is the type of checksum to calculate: sha1, md5, sha-512, sha-384, sha-256, or none (the default). When the value is none, the checksum that is configured on the server, if any, is used. For more information about checksum reporting, see Reporting Checksums .
Important: When checksum reporting is enabled, transfers of very large files (>TB) take a long time to resume because the entire file must be reread.
--file-crypt={encrypt|decrypt}
Encrypt files (when sending) or decrypt files (when receiving) for client-side encryption-at-rest (EAR). Encrypted files have the file extension .aspera-env. This option requires the encryption/decryption passphrase to be set with the environment variable ASPERA_SCP_FILEPASS. If a client-side encrypted file is downloaded with an incorrect password, the download is successful, but the file remains encrypted and still has the file extension .aspera-env. For more information, see Client-Side Encryption-at-Rest (EAR).
--file-list=file
Transfer all source files and directories listed in file. Each source item is specified on a separate line. UTF-8 file format is supported. Only the files and directories are transferred. Path information is not preserved at the destination. To read a file list from standard input, use "-" in place of file.

For example, if list.txt contains the following list of sources: 

/tmp/code/compute.php 
doc_dir
images/iris.png 
images/rose.png

and the following command is run: 

# ascp --file-list=list.txt --mode=send --user=username --host=ip_addr .

then the destination, in this case the transfer user's docroot, will contain the following:

compute.php 
doc_dir (and its contents)
iris.png
rose.png

Restrictions:

  • The command line cannot use the user@host:source syntax. Instead, specify this information with the options --mode, --host, and --user.
  • Paths specified in the file list cannot use the user@host:source syntax.
  • Because multiple sources are being transferred, the destination must be a directory.
  • Only one --file-list or --file-pair-list option is allowed per ascp session. If multiple lists are specified, only the last one is used.
  • Only files and directories specified in the file list are transferred; any sources specified on the command line are ignored.
  • If the source paths are URIs, the size of the file list cannot exceed 24 KB.

To create a file list that also specifies destination paths, use --file-pair-list.

--file-manifest={none|text}
Generate a list of all transferred files when set to text. Requires --file-manifest-path to specify the location of the list. (Default: none)
--file-manifest-path=directory
Save the file manifest to the specified location when using --file-manifest=text. File manifests must be stored locally. For cloud or other non-local storage, specify a local manifest path.
--file-manifest-inprogress-suffix=suffix
Apply the specified suffix to the file manifest's temporary file. For use with --file-manifest=text. (Default suffix: .aspera-inprogress)
--file-pair-list=file
Transfer files and directories listed in file to their corresponding destinations. Each source is specified on a separate line, with its destination on the line following it.

Specify destinations relative to the transfer user's docroot. Even if a destination is specified as an absolute path, the path at the destination is still relative to the docroot. Destination paths specified in the list are created automatically if they do not already exist.

For example, if the file pairlist.txt contains the following list of sources and destinations: 

Dir1
Dir2
my_images/iris.png
project_images/iris.png
/tmp/code/compute.php
/tmp/code/compute.php
/tmp/tests/testfile
testfile2

and the following command is run: 

# ascp --file-pair-list=pairlist.txt --mode=send --user=username --host=ip_addr .

then the destination, in this case the transfer user's docroot, now contains the following:

Dir2  (and its contents)
project_images/iris.png
tmp/code/compute.php
testfile2

Restrictions:

  • The command line cannot use the user@host:source syntax. Instead, specify this information with the options --mode, --host, and --user.
  • The user@host:source syntax cannot be used with paths specified in the file list.
  • Because multiple sources are being transferred, the destination specified on the command line must be a directory.
  • Only one --file-pair-list or --file-list option is allowed per ascp session. If multiple lists are specified, only the last one is used.
  • Only files from the file pair list are transferred; any additional source files specified on the command line are ignored.
  • If the source paths are URIs, the file list cannot exceed 24 KB.

For additional examples, see Ascp General Examples.

-G write_size
If the transfer destination is a server, use the specified write-block size, which is the maximum number of bytes that the receiver can write to disk at a time. Default: 256 KB, Range: up to 500 MB. This option accepts suffixes "M" or "m" for mega and "K" or "k" for kilo, such that a write_size of 1M is one MB.

This is a performance-tuning option that overrides the write_block_size set in the client's aspera.conf. However, the -G setting is overridden by the write_block_size set in the server's aspera.conf. The receiving server never uses the write_block_size set in the client's aspera.conf.

-g read_size
If the transfer source is a server, use the specified read-block size, which is the maximum number of bytes that the sender reads from the source disk at a time. Default: 256 KB, Range: up to 500 MB. This option accepts suffixes "M" or "m" for mega and "K" or "k" for kilo, such that a read_size of 1M is one MB.

This is a performance-tuning option that overrides the read_block_size set in the client's aspera.conf. However, the -g setting is overridden by the read_block_size set in the server's aspera.conf. When set to the default value, the read size is the default internal buffer size of the server, which might vary by operating system. The sending server never uses the read_block_size set in the client's aspera.conf.

-h, --help
Display the help text.
--host=hostname
Transfer to the specified host name or address. Requires --mode. This option can be used instead of specifying the host with the hostname:file syntax.
-i private_key_file
Authenticate the transfer using public key authentication with the specified SSH private key file. The argument can be just the filename if the private key is located in user_home_dir/.ssh/, because ascp automatically searches for key files there. Multiple private key files can be specified by repeating the -i option. The keys are tried in order and the process ends when a key passes authentication or when all keys have been tried without success, at which point authentication fails.
-K probe_rate
Measure bottleneck bandwidth at the specified probing rate (Kbps). (Default: 100Kbps)
-k {0|1|2|3}
Enable the resuming of partially transferred files at the specified resume level. (Default: 0)

Specify this option for the first transfer or it will not work for subsequent transfers. Resume levels:

  • -k 0 – Always re-transfer the entire file.
  • -k 1 – Compare file attributes and resume if they match, and re-transfer if they do not.
  • -k 2 – Compare file attributes and the sparse file checksums; resume if they match, and re-transfer if they do not.
  • -k 3 – Compare file attributes and the full file checksums; resume if they match, and re-transfer if they do not.

If a complete file exists at the destination (no .aspx), the source and destination file sizes are compared. If a partial file and a valid .aspx file exist at the destination, the source file size and the file size recorded in the .aspx file are compared.

Note: If the destination is a URI path, then the only valid options are -k 0 and -k 1 and no .aspx file is created.
-L local_log_dir[:size]
Log to the specified directory on the client computer rather than the default directory. Optionally, set the size of the log file (Default: 10 MB). See also -R for setting the log directory on the server.
-l max_rate
Transfer at rates up to the specified target rate. (Default: 10000 Kbps) This option accepts suffixes "G" or "g" for giga, "M" or "m" for mega, "K" or "k" for kilo, and "P", "p", or "%" for percentage. Decimals are allowed. If this option is not set by the client, the setting in the server's aspera.conf is used. If a rate cap is set in the local or server aspera.conf, the rate does not exceed the cap.
-m min_rate
Attempt to transfer no slower than the specified minimum transfer rate. (Default: 0) If this option is not set by the client, then the server's aspera.conf setting is used. If a rate cap is set in the local or server aspera.conf, then the rate does not exceed the cap.
--mode={send|recv}
Transfer in the specified direction: send or recv (receive). Requires --host.
--move-after-transfer=archivedir
Move source files and copy source directories to archivedir after they are successfully transferred. Because directories are copied, the original source tree remains in place. The transfer user must have write permissions to the archivedir. The archivedir is created if it does not already exist. If the archive directory cannot be created, the transfer proceeds and the source files remain in their original location.

To preserve portions of the file path above the transferred file or directory, use this option with --src-base. For an example, see Ascp File Manipulation Examples.

To remove empty source directories (except those specified as the source to transfer), use this option with --remove-empty-directories .

Restrictions:

  • archivedir must be on the same file system as the source. If the specified archive is on a separate file system, it is created (if it does not exist), but an error is generated and files are not moved to it.
  • For cloud storage, archivedir must be in the same cloud storage account as the source and must not already contain files with the same name (the existing files cannot be overwritten and the archiving fails).
  • If the source is on a remote system (ascp is run in receive mode), archivedir is subject to the same docroot restrictions as the remote user.
  • --remove-after-transfer and --move-after-transfer are mutually exclusive. Using both in the same session generates an error.
  • Empty directories are not saved to archivedir.
  • When used with --remove-empty-directories and --src-base, scanning for empty directories starts at the specified source base and proceeds down any subdirectories. If no source base is specified and a file path (as opposed to a directory path) is specified, then only the immediate parent directory is removed (if empty) after the source files have been moved.
--multi-session-threshold=threshold
Split files across multiple ascp sessions if their size is greater than or equal to threshold. Use with -C, which enables multi-session transfers.

Files whose sizes are less than threshold are not split. If threshold is set to 0 (the default), no files are split.

If --multi-session-threshold is not used, the threshold value is taken from the setting for <multi_session_threshold_default> in the aspera.conf file on the client. If not found in aspera.conf on the client, the setting is taken from aspera.conf on the server. The command-line setting overrides any aspera.conf settings, including when the command-line setting is 0 (zero).

Multi-session uploads to cloud storage are supported for S3 only and require additional configuration. For more information, see the IBM Aspera High-Speed Transfer Server Admin Guide: Configuring Multi-Session Transfers.

-N 'pattern'
Include files or directories in the transfer based on matching the specified pattern to file names and paths. Rules are applied in the order in which they are encountered, from left to right, such that -N rules protect files from -E rules that follow them.
Note: An include rule must be followed by at least one exclude rule, otherwise all files are transferred because none are excluded. To exclude all files that do not match the include rule, use -N '/**/' -E '/**' at the end of your filter arguments.

The following symbols can be used in the pattern:

  • * (asterisk) represents zero or more characters in a string, for example *.tmp matches .tmp and abcde.tmp.
  • ? (question mark) represents any single character, for example t?p matches tmp but not temp.

For details on specifying patterns and rules, including examples, see Using Filters to Include and Exclude Files.

Note: Filtering rules can also be specified in aspera.conf. Rules found in aspera.conf are applied before any -E and -N rules specified on the command line.
-O fasp_port
Use the specified UDP port for FASP transfers. (Default: 33001)
--overwrite={never|always|diff|diff+older|older}
Overwrite destination files with source files of the same name. Default: diff. This option takes the following values:
  • never - Never overwrite the file. However, if the parent folder is not empty, its access, modify, and change times may still be updated.
  • always - Always overwrite the file.
  • diff - Overwrite the file if different from the source. If a complete file at the destination is the same as a file on the source, it is not overwritten. Partial files are overwritten or resumed depending on the resume policy.
  • diff+older - Overwrite the file if older and also different than the source. For example, if the destination file is the same as the source, but with a different timestamp, it will not be overwritten. Plus, if the destination file is different than the source, but newer, it will not be overwritten.
  • older - Overwrite the file if its timestamp is older than the source timestamp.

Interaction with resume policy (-k): If the overwrite method is diff or diff+older, difference is determined by the resume policy (-k {0|1|2|3}). If -k 0 or no -k is specified, the source and destination files are always considered different and the destination file is always overwritten. If -k 1, the source and destination files are compared based on file attributes (currently file size). If -k 2, the source and destination files are compared based on sparse checksums. If -k 3, the source and destination files are compared based on full checksums.

-P ssh-port
Use the specified TCP port to initiate the FASP session. (Default: 22)
-p
Preserve file timestamps for access and modification time. Equivalent to setting --preserve-modification-time and --preserve-access-time (and --preserve-creation-time on Windows). Timestamp support in object storage varies by provider; consult your object storage documentation to determine which settings are supported.

On Windows, modification time may be affected when the system automatically adjusts for Daylight Savings Time (DST). For details, see the Microsoft KB article, http://support.microsoft.com/kb/129574.

On Isilon IQ OneFS systems, access time (atime) is disabled by default. In this case, atime is the same as mtime. To enable the preservation of atime, run the following command: 
# sysctl efs.bam.atime_enabled=1
--partial-file-suffix=suffix
Enable the use of partial files for files that are in transit, and set the suffix to add to names of partial files. (The suffix does not include a " . ", as for a file extension, unless explicitly specified as part of the suffix.) This option only takes effect when set on the receiver side. When the transfer is complete, the suffix is removed. (Default: suffix is null; use of partial files is disabled.)
--policy={high|fair|low|fixed}
Set the FASP transfer policy.
  • high - Adjust the transfer rate to fully utilize the available bandwidth up to the maximum rate. When congestion occurs, the transfer rate is twice as fast as a fair-policy transfer. The high policy requires maximum (target) and minimum transfer rates.
  • fair - Adjust the transfer rate to fully utilize the available bandwidth up to the maximum rate. When congestion occurs, bandwidth is shared fairly by transferring at an even rate. The fair policy requires maximum (target) and minimum transfer rates.
  • low - Adjust the transfer rate to use the available bandwidth up to the maximum rate. Similar to fair mode, but less aggressive when sharing bandwidth with other network traffic. When congestion occurs, the transfer rate is reduced to the minimum rate until other traffic decreases.
  • fixed - Attempt to transfer at the specified target rate, regardless of network or storage capacity. This can decrease transfer performance and cause problems on the target storage. Aspera discourages using the fixed policy except in specific contexts, such as bandwidth testing. The fixed policy requires a maximum (target) rate.

If --policy is not set, ascp uses the server-side policy setting (fair by default). If the server does not allow the selected policy, the transfer fails.

--precalculate-job-size
Calculate the total size before starting the transfer. The server-side pre_calculate_job_size setting in aspera.conf overrides this option.
--preserve-access-time
Preserve the source-file access timestamps at the destination. Because source access times are updated by the transfer operation, the timestamp preserved is the one just prior to the transfer. (To prevent access times at the source from being updated by the transfer operation, use the --preserve-source-access-time option.)

For IBM Spectrum Scale clusters, use to preserve the expiration time of immutable files.

On Isilon IQ OneFS systems, access time (atime) is disabled by default. In this case, atime is the same as mtime. To enable the preservation of atime, run the following command: 
# sysctl efs.bam.atime_enabled=1
--preserve-acls={native|metafile|none}
Preserve Access Control Lists (ACL) data for macOS, Windows, and AIX files. To preserve ACL data for other operating systems, use --preserve-xattrs. See also --remote-preserve-acls. Default: none.
  • native - Preserve attributes using the native capabilities of the file system. This mode is only supported for Windows, macOS, and AIX. If the destination and source do not support the same native ACL format, async reports and error and exits.
  • metafile- Preserve file attributes in a separate file, named filename.aspera-meta. For example, attributes for readme.txt are preserved in a second file named readme.txt.aspera-meta. These metafiles are platform independent and can be copied between hosts without loss of information. This mode is supported on all file systems.
  • none - Do not preserve attributes. This mode is supported on all file systems.

Important Usage Information:

  • ACLs are not preserved for directories.
  • Both --preserve-acls and --remote-preserve-acls must be specified in order for the target side of a pull (Ascp with --mode=recv) to apply the ACLs.
  • Very old versions of ascp do not support values other than none, and transfers using native or metafile fail with an error that reports incompatible FASP protocol versions.
--preserve-creation-time
(Windows only) Preserve source-file creation timestamps at the destination. Only Windows systems retain information about creation time. If the destination is not a Windows computer, this option is ignored.
--preserve-file-owner-gid, --preserve-file-owner-uid
(Linux, UNIX, and macOS only) Preserve the group information (gid) or owner information (uid) of the transferred files. These options require the transfer user to be authenticated as a superuser.
--preserve-modification-time
Set the modification time, the last time a file or directory was modified (written), of a transferred file to the modification of the source file or directory. Preserve source-file modification timestamps at the destination.

On Windows, modification time may be affected when the system automatically adjusts for Daylight Savings Time (DST). For details, see the Microsoft KB article, http://support.microsoft.com/kb/129574.

--preserve-source-access-time
Preserve the access times of the original sources to the last access times prior to transfer. This prevents access times at the source from being updated by the transfer operation. Typically used in conjunction with the --preserve-access-time option.
--preserve-xattrs={native|metafile|none}
Preserve extended file attributes data (xattr). Default: none. See also --remote-preserve-xattrs.
  • native - Preserve attributes using the native capabilities of the file system. This mode is supported only on macOS and Linux. If the destination and source do not support the same native xattr format, async reports and error and exits. If the Linux user is not root, some attributes such as system group might not be preserved.
  • metafile- Preserve file attributes in a separate file, named filename.aspera-meta. For example, attributes for readme.txt are preserved in a second file named readme.txt.aspera-meta. These metafiles are platform independent and can be copied between hosts without loss of information. This mode is supported on all file systems.
  • none - Do not preserve attributes. This mode is supported on all file systems.

Important Usage Information:

  • Extended attributes are not preserved for directories.
  • If Ascp is run by a regular user, only user-level attributes are preserved. If run as superuser, all attributes are preserved.
  • The amount of attribute data per file that can be transferred successfully is subject to ascp's internal PDPU size limitation.
  • Very old versions of Ascp do not support values other than none, and transfers using native or metafile fail with an error that reports incompatible FASP protocol versions.
  • Use --preserve-xattrs=native to preserve IBM Spectrum Scale ACLs between clusters. For more information, see IBM Aspera High-Speed Transfer Server Admin Guide for Linux.
--proxy=proxy_url
Use the proxy server at the specified address. proxy_url should be specified with the following syntax:

dnat[s]://proxy_username:proxy_password@server_ip_address:port

The default ports for DNAT and DNATS protocols are 9091 and 9092. For a usage example, see Ascp General Examples.

-q
Run ascp in quiet mode (disables the progress display).
-R remote_log_dir
Log to the specified directory on the server rather than the default directory. Note: Client users restricted to aspshell are not allowed to use this option. To specify the location of the local log, use -L.
--remote-preserve-acls={native|metafile|none}
Like --preserve-acls but used when ACLs are stored in a different format on the remote computer. Defaults to the value of --preserve-acls.
Note: Both --preserve-acls and --remote-preserve-acls must be specified in order for the target side of a pull (Ascp with --mode=recv) to apply the ACLs.
--remote-preserve-xattrs={native|metafile|none}
Like --preserve-xattrs but used when attributes are stored in a different format on the remote computer. Defaults to the value of --preserve-xattrs.
--remove-after-transfer
Remove all source files, but not the source directories, once the transfer has completed successfully. Requires write permissions on the source.
--remove-empty-directories
Remove empty source directories once the transfer has completed successfully, but do not remove a directory specified as the source argument. To also remove the specified source directory, use --remove-empty-source-directory. Directories can be emptied using --move-after-transfer or --remove-after-transfer. Scanning for empty directories starts at the srcbase and proceeds down any subdirectories. If no source base is specified and a file path (as opposed to a directory path) is specified, then only the immediate parent directory is scanned and removed if it's empty following the move of the source file. Note: Do not use this option if multiple processes (ascp or other) might access the source directory at the same time.
--remove-empty-source-directory
Remove directories specified as the source arguments. For use with --remove-empty-directories.
-S remote_ascp
Use the specified remote ascp binary, if different than ascp.
--save-before-overwrite
Save a copy of a file before it is overwritten by the transfer. A copy of filename.ext is saved as filename.yyyy.mm.dd.hh.mm.ss.index.ext in the same directory. index is set to 1 at the start of each second and incremented for each additional file saved during that second. The saved copies retain the attributes of the original. Not supported for URI path destinations.
--skip-special-files
Skip special files, such as devices and pipes, without reporting errors for them.
--source-prefix=prefix
Prepend prefix to each source path. The prefix can be a conventional path or a URI; however, URI paths can be used only if no docroot is defined.
--source-prefix64=prefix
Prepend the base64-encoded prefix to each source path. If --source-prefix=prefix is also used, the last option takes precedence.
--src-base=prefix
Strip the specified path prefix from the source path of each transferred file or directory. The remaining portion of the path remains intact at the destination.

Without --src-base, source files and directories are transferred without their source path. (However, directories do include their contents.)

Note: Sources located outside the source base are not transferred. No errors or warnings are issued, but the skipped files are logged.

Use with URIs: The --src-base option performs a character-to-character match with the source path. For object storage source paths, the prefix must specify the URI in the same manner as the source paths. For example, if a source path includes an embedded passphrase, the prefix must also include the embedded passphrase otherwise it will not match.

For examples, see Ascp File Manipulation Examples.

--symbolic-links={follow|copy|copy+force|skip}
Handle symbolic links using the specified method, as allowed by the server. For more information on symbolic link handling, see Symbolic Link Handling. On Windows, the only method is skip. On other operating systems, any of the following methods can be used:
  • follow - Follow symbolic links and transfer the linked files. (Default)
  • copy - Copy only the alias file. If a file with the same name is found at the destination, the symbolic link is not copied.
  • copy+force - Copy only the alias file. If a file (not a directory) with the same name is found at the destination, the alias replaces the file. If the destination is a symbolic link to a directory, it's not replaced.
  • skip - Skip symbolic links. Do not copy the link or the file it points to.
-T
Disable in-transit encryption for maximum throughput.
--tags string
Metatags in JSON format. The value is limited to 4 Kb.
--tags64 string
Metatags in JSON format and base64 encoded. The value is limited to 4 Kb.
-u user_string
Define a user string, such as variables, for pre- and post-processing. This string is passed to the pre- and -post-processing scripts as the environment variable $USERSTR.
--user=username
Authenticate the transfer using the specified username. Use this option instead of specifying the username as part of the destination path (as user@host:file).
Note: If you are authenticating on a Windows computer as a domain user, the transfer server strips the domain from the username. For example, Administrator is authenticated rather than DOMAIN\Administrator. For this reason, you must specify the domain explicitly.
-v
Run ascp in verbose mode. This option prints connection and authentication debug messages in the log file. For information on log files, see IBM Aspera High-Speed Transfer Server Admin Guide: Log Files.
-W {token_string|@token_file}
Authenticate using the authorization token string for the transfer, either as the string itself or when preceded with an @, the full path to the token file. This option takes precedence over the setting for the ASPERA_SCP_TOKEN environment variable.
-wr, -wf
Measure and report bandwidth from server to client (-wr) or client to server (-wf) before the transfer.
-X rexmsg_size
Limit the size of retransmission requests to no larger than the specified size, in bytes. (Max: 1440)
-Z dgram_size
Use the specified datagram size (MTU) for FASP transfers. Range: 296-65535 bytes. (Default: the detected path MTU)

As of version 3.3, datagram size can be specified on the server by setting <datagram_size> in aspera.conf. The server setting overrides the client setting, unless the client is using a version of ascp that is older than 3.3, in which case the client setting is used. If the pre-3.3 client does not set -Z, the datagram size is the discovered MTU and the server logs the message "LOG Peer client does not support alternative datagram size".

Ascp Options for HTTP 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/S protocol.

Limitations:

  • HTTP fallback must be enabled on the server.
  • Folders that are symbolic links cannot be downloaded directly by using HTTP fallback. Folders that are symbolic links are processed correctly when their parent folder is the source.
  • HTTP fallback can only follow symbolic links. Settings in aspera.conf or in the command line are ignored.
  • HTTP fallback attempts to transfer at the target rate but is limited by TCP.
  • HTTP fallback does not support pre-post processing or inline validation.

Options:

-I cert_file
Certify fallback transfers with the specified HTTPS certificate file.
-j {0|1}
Encode all HTTP transfers as JPEG files when set to 1. (Default: 0)
-t port
Transfer via the specified server port for HTTP fallback.
-x proxy_server
Transfer to the specified proxy server address for HTTP fallback.
-Y key_file
Certify HTTPS fallback transfers using the specified HTTPS transfer key.
-y {0|1}
If set to "1", use the HTTP fallback transfer server when a UDP connection fails. (Default: 0)