Ascp command reference

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.

The growing files feature can be used with the source option to start transferring files to the target directory while they are still being written to the source directory.

Note: To use the growing files feature, the source file must be on a native file system. Growing files cannot be larger than 8 exabytes - 1 (9,223,372,036,854,775,807 bytes). However, the maximum file size of the file system overrides a setting that is larger.

Growing files use can also be configured statically with aspera.conf. See also Ascp general examples.

To use the growing files feature with ascp, the source parameter can be used with the following syntax:

source?grow=wait_time[&wait_start=[mtime | null_read]][[&confirm_stop=[ true | false ]]

A file transfer is deemed to be complete when the time since last update to the source file reaches the wait_time value (in seconds). However, the time is only sampled when all currently available source data was transferred. In other words, if more data arrives after the wait time has elapsed, but the transfer is still in progress, the additional data is still transferred.

grow

Enables the growing file feature and is used to set the wait time in seconds. The wait time is the amount of time that is allowed to pass before a file that is not changing is treated as complete. The grow element must be set to a nonnegative integer to define wait time. If it is set to a nonnumeric string, the default wait time of 10 seconds is used.

wait_start

Can be used to specify how time is calculated to determine whether a file is complete. If mtime is used, then the file modification time is used to calculate the wait time. If null_read is used, then the time of a file read that returns zero bytes is used. The default is mtime.

confirm_stop

Can be used to indicate when all the data was added to the source file and to prevent any additional wait time followed by a read of EOF.

Note that confirm_stop is ignored if wait_start is set to null_read.

To use confirm_stop, set it to true (the default value is false). Then, use an external program to adjust the source file mtime upon completion of writing data to the source file, by using the following criteria:

mtime < current_system_time - wait_time, mtime != 0

Any value for mtime that meets this criteria is acceptable to flag this condition except mtime = 0, which is used to flag a file error. You can, for example, use touch 1. If mtime is not adjusted before the timeout is reached, an error is generated.

An alternative method for defining the wait_time value is to use modifiers for powers of 1,024. However, the value must be less than 8 * 2^60. The modifier must consist of an integer, and a unit specifier. The unit specifiers are:

• k or K for 1 * 1024
• m or M for 1 * 1024 * 1024
• g or G for 1 * 1024 * 1024 * 1024

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 file name. 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 quotation marks (' ') 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 by 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 . For examples, see Ascp general examples.

WebSocket protocol

The WebSocket protocol can be used instead of SSH or HTTPS for client connections with the transfer server. To use it, you must configure aspera.conf specifically for WebSocket use. Then, for transfers, you must use ascp --ws-connect option to enable WebSocket and the -P option to specify the WebSocket port (9093).

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 might produce unexpected results that depend 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. Each environment variable value must 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 use --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 you specify 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 and 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 that is specified with the -O option. Large files can be split across sessions, see --multi-session-threshold. For more information, see IBM Aspera High-Speed Transfer Server.

-c cipher

Encrypt in-transit file data by 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 or the transfer fails.
• When you request GCM and the server is older than 3.8.1 or explicitly 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 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 CFB encryption mode.	Clients version 4.0.0 and newer, all server versions.
aes128gcm aes192gcm aes256gcm	Use GCM encryption mode.	Clients and servers.
none	Do not encrypt data in transit. For security and to keep the file integrity, avoid the use of 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 AES-XXX-GCM	Server AES-XXX-CFB	Server AES-XXX	Server AES-XXX
Client AES-XXX-GCM	GCM	Server refuses transfer	GCM	Server refuses transfer
Client AES-XXX-CFB	Server refuses transfer	CFB	CFB	CFB
Client AES-XXX	GCM	CFB	CFB	CFB
Client 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. The Aspera fingerprint convention is to use a hex string without the colons; for example, f74e5de9ed0d62feaf0616ed1e851133c42a0082. For more information on SSH host key fingerprints, see IBM Aspera High-Speed Transfer 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 exists. 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

(V4.0 or higher) The -e option is not valid anymore. The support for pre-post scripts was removed with version 4.0 or higher.

Run the specified pre-post script as an alternative to the default aspera-prepost.bat 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 various environment variables. IBM Aspera High-Speed Transfer Server product [] .

--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 before 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 and 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 that are 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, contains:

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 that are 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 that are specified in the file list are transferred. Any sources that are 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 manifest file to the specified location when you use --file-manifest=text. Manifests file must be stored locally. For cloud or other nonlocal storage, specify a local manifest file 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 that are listed in file to their corresponding destinations. Each source is specified on a separate line, with its destination on the line that follows 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 that are specified in the list are created automatically if they do not 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 that are specified in the file list.
• Because multiple sources are being transferred, the destination that is 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 that are 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 1 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 1 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 hostname or address. Requires --mode. This option can be used instead of specifying the host with the hostname:file syntax.

-i private_key_file | cert_file

The -i option can be used to specify either:

• An SSH private key file, for authenticating a transfer by using public key authentication with the specified SSH private key file. The argument can be just the file name 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 were tried without success, at which point authentication fails.
• A Certificate Authority certificate, for use with fallback transfers or with WebSocket use, when you do not want to use the system default certificate.

-K probe_rate

Measure bottleneck bandwidth at the specified probing rate (Kbps). (Default: 100 Kbps).

-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 doesn’t work for subsequent transfers. Resume levels:

• -k 0 – Always retransfer the entire file.
• -k 1 – Compare file attributes and resume if they match, and retransfer if they do not.
• -k 2 – Compare file attributes and the sparse file checksum; resume if they match, and retransfer if they do not.
• -k 3 – Compare file attributes and the full file checksum; resume if they match, and retransfer 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 that is 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 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 were 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.

-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 more information see Using filters to include and exclude files.

Note: Filtering rules can also be specified in aspera.conf. Rules that are found in aspera.conf are applied before any -E and -N rules that are specified on the command line.

-O fasp_port

Use the specified UDP port for FASP transfers. (Default: 33001).

--output-file-progress

Can be used to write the individual file transfer progress to the stdout file descriptor.

--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 might 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 is not overwritten. Plus, if the destination file is different than the source, but newer, it is 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 checksum. If -k 3, the source and destination files are compared based on full checksum.

-P ssh-port | websockets-port

Use the specified TCP port to initiate the FASP transfer session, by using the port number that is appropriate for your use of either SSH or WebSocket.

-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 might be affected when the system automatically adjusts for Daylight Savings Time (DST). For more information, see Daylight saving time help and support.

--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 use 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 use 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 the bandwidth is shared 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. Use the fixed policy only for specific contexts, such as bandwidth testing, otherwise, avoid the use of this policy. The fixed policy requires a maximum target rate.
• aggressiveness - The aggressiveness of transfers that are authorized by this access key in claiming available bandwidth. Value can be 0.00-1.00. For example, these values correspond to the policy option where a policy of high approximates to aggressiveness of 0.75, fair to 0.50 and low to 0.25. Aggressiveness can be used if you need to fine-tune the transfer policy.

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 a transfer starts. 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 that is preserved is the one just before 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.

--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 by 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:

• 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.
• Old versions of ascp do not support values other than none, and transfers that use 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 might be affected when the system automatically adjusts for Daylight Savings Time (DST). For details, see Daylight saving time help and support.

--preserve-object-lock-legal-hold

(V4.4.2) Preserve legal hold status of source files and directories when created at the destination.

--preserve-object-lock-retention

(V4.4.2) Preserve retention information of source files and directories when created at the destination.

--preserve-source-access-time

Preserve the access times of the original sources to the last access times before to transfer. This prevents access times at the source from being updated by the transfer operation. Typically used 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 by 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-preserve-acls={native|metafile|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.
• Old versions of Ascp do not support values other than none, and transfers that use native or metafile fail with an error that reports incompatible FASP protocol versions.

--proxy=proxy_url

Use the proxy server at the specified address. proxy_url must 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 is completed successfully. Requires write permissions on the source.

--remove-empty-directories

Remove empty source directories once the transfer is completed successfully, but do not remove a directory that is specified as the source argument. To also remove the specified source directory, use --remove-empty-source-directory. Directories can be emptied by using --move-after-transfer or --remove-after-transfer. Scanning for empty directories starts at the src-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 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 that are 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 that is saved during that second. The saved copies retain the attributes of the original. Not supported for URI path destinations.

-SSH

Use an external SSH program instead of the built-in libssh2 implementation to establish the connection with the remote host. The wanted SSH program must be defined in the environment's PATH variable. To enable debugging of the SSH process, use the -DD and --ssh-arg=-vv options with ascp.

--ssh-arg=ARG

Add ARG to the command line arguments passed to the external SSH program (implies that you use -SSH). This option might be repeated as needed to supply multiple separate SSH arguments. The order is preserved. The ARG elements are inserted before any key files supplied to ascp, and before the user and host argument.

--skip-special-files

Skip special files, such as devices and pipes, without reporting errors for them.

--source-prefix=prefix

Add a 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

Add a 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 that are 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 does not match.

For examples, see Ascp file manipulation examples.

--src-base64=<base64-encoded src-base>

An alternative to --src-base, with the same value except base64-encoded to help avoid character conversion issues for nonascii character sets. If both --src-base and --src-base64 are specified, then the last argument on the command line is used.

--symbolic-links={follow|copy|copy+force|skip}

Handle-symbolic links that use the specified method, as allowed by the server. For more information, 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 is 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 for Lua scripts that can be run with transfer events.

--user=username

Authenticate the transfer by 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 more information, see Log files.

-W {token_string|@token_file}

Authenticate by 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.

--ws-connect

Use WebSocket instead of SSH for client connections with the transfer server.

-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 continues 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 automated execution of Lua scripts

Options:

-i cert_file

By default ascp uses the system certificates. However, the -i option can be used to use the specified Certificate Authority certificate for fallback transfers, and for WebSocket.

-t port

Transfer through 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 by 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).