ascp Usage

The ascp command reference.

Print this page

ascp is a command-line fasp transfer program. This topic covers the complete command usage, including the general syntax guideline, supported environment variables, synopsis, and the options.

General Syntax Guideline
Item Decription
symbols used in the paths Use single-quote (' ') and forward-slashes (/) on all platforms.
Characters to avoid / \ " : ' ? > < & * |
Environment Variables

If needed, you can use the command to set the password, token, and cookie in the environment variables. Replace the highlighted text with your own values:

Item Initiation Command
Password set ASPERA_SCP_PASS=the-password
Token set ASPERA_SCP_TOKEN=the-token
Cookie set ASPERA_SCP_COOKIE=the-cookie
Content Protection Password set ASPERA_SCP_FILEPASS=content-protect-password
ascp Usage
ascp <options> [[user@]srcHost:]source-file1[,source-file2,...] [[user@]destHost:]target-path

IMPORTANT NOTE: If you do not specify a user name for the transfer, the local username will be authenticated (by default). In the case of a Windows machine and a domain user, the transfer server will strip the domain from the username (e.g. authenticating "Administrator," rather than "DOMAIN\Administrator). Thus, you will need to explicitly specify a domain, if applicable to the user.

ascp Options
Option Description
-A Display version and license information; then exit.
-T Disable encryption for maximum throughput.
-d Create target directory if it doesn't already exist.
-p Preserve source modification time (mtime) and last access time (atime).

IMPORTANT NOTE: On Windows, mtime and atime may be effected when the system automatically adjusts for Daylight Savings Time (DST). Please refer to the Microsoft KB article, http://support.microsoft.com/kb/129574, for details.

-q Quiet flag (to disable progress display).
-v Verbose mode (print connection and authentication debug messages in the log file).
-{Q|QQ} (Deprecated as of 3.0+ by --policy) Enable fair (-Q) or trickle (-QQ) transfer policy. Use the -l and -m to set the target and minimum rates.
-U{1|2} (Deprecated as of 3.0+ by --policy) Priority when sharing physical or virtual bandwidth cap. 1 for higher priority, 2 for regular. (Default: 2)
-l target_rate Set the target transfer rate in Kbps (Default: 10000 Kbps). If the ascp client does not specify a target rate, it will be acquired from aspera.conf (server-side, as the local aspera.conf target rate setting doesn't apply). If local or server aspera.conf rate caps are specified, the "starting" (default) rates will be not higher than the cap.
-m min-rate Set the minimum transfer rate in Kbps (Default: 0. If the ascp client does not specify a minimum rate, it will be acquired from aspera.conf (server-side, as the local aspera.conf minimum rate setting doesn't apply). If local or server aspera.conf rate caps are specified, the "starting" (default) rates will be not higher than the cap.
-w{r|f} Test bandwidth from server to client (r) or client to server (f). Currently a beta option.
-K probe-rate Set probing rate (Kbps) when measuring bottleneck bandwidth.
-k{0|1|2|3} Enable resuming partially transferred files. (Default: 0). Please note that this must be specified for your first transfer; otherwise, it will not work for subsequent transfers.
  • 0 Always retransfer the entire file.
  • 1 Check file attributes and resume if the current and original attributes match.
  • 2 Check file attributes and do a sparse file checksum; resume if the current and original attributes/checksums match.
  • 3 Check file attributes and do a full file checksum; resume if the current and original attributes/checksums match.

Note that when a complete file exists at the destination (no .aspx), the source file size is compared with the destination file size. When a partial file and a valid .aspx file exist at the destination, the source file size is compared with the file size recorded inside the .aspx file.

-i private-key-file Use public key authentication and specify the private key file. Typically, the private key file is in the directory $HOME/.ssh/id_[algorithm].
-Z dgram-size Specify the datagram size (MTU) for fasp. By default, the detected path MTU is used.
-u user-string Apply a user string, such as variables for pre- and post-processing.
-X rexmsg-size Adjust the size in bytes of a retransmission request. (Max: 1440).
-g read-size Set the read-block size, a performance-tuning parameter for an Aspera sender (which only takes effect if the sender is a server). It represents the maximum number of bytes that can be stored within a block as the block is being transferred from the source disk drive to the receiver. The default of 0 will cause the Aspera sender to use its default internal buffer size, which may be different for different operating systems. Note that 500M (524,288,000 bytes) is the maximum block size.
-G write-size This is a performance-tuning parameter for an Aspera receiver (which only takes effect if the receiver is a server). It represents the maximum bytes within a block that an ascp receiver can write to disk. The default of 0 will cause the Aspera receiver to use its default internal buffer size, which may be different for different operating systems. Note that 500M (524,288,000 bytes) is the maximum block size.
-S remote-ascp Specify the name of the remote ascp binary (if different).
-L local-log-dir Specify a logging directory in the local host, instead of using the default directory.
-R remote-log-dir Specify a logging directory in the remote host, instead of using the default directory.
-e prepost Specify an alternate pre/post command. Be sure to use the complete path and file name.
-f config-file Specify an alternate Aspera configuration file (default is aspera.conf).
-C n-id:n-count Use parallel transfer on a multi-node/core system. Specify the node id (nid) and count (ncount) in the format 1:2, 2:2. Assign each participant to an independent UDP port.
-E pattern Exclude files or directories with the specified pattern from the transfer. This option can be used multiple times to exclude many patterns. Up to 16 patterns can be used by using -E. Two symbols can be used in the pattern, as shown below.
  • * (asterisk) represents zero to many characters in a string, for example "*.tmp" matches ".tmp" and "abcde.tmp".
  • ? (question mark) represents one character, for example "t?p" matches "tmp" but not "temp".
-O fasp-port Set the UDP port to be used by fasp for data transfer. (Default: 33001)
-P ssh-port Set the TCP port to be used for fasp session initiation. (Default: 33001)
-W token-string Specify the token string for the transfer.
-@[range-low:range-high] Transfer only part of a file. This option only works when downloading a single file and does not support resuming. The argument to "-@" may omit either or both numbers, and the ":" delimiter. For example, -@3000:6000 transfers bytes between positions 3000 to 6000; -@1000: transfers from 1000 to the end of the file; and -@:1000 transfers from beginning to 1000.
-6 Enable IPv6 address support. When using IPv6, the numeric host can be written inside brackets. For example, [2001:0:4137:9e50:201b:63d3:ba92:da] or [fe80::21b:21ff:fe1c:5072%eth1].
-D | -DD | -DDD Specify the debug level, where each D is an additional level of debugging.
--mode=MODE Specify the transfer direction. Replace MODE with send or recv.
--policy=fixed | high | fair | low

The long option of the transfer policy, which overrides deprecated options -Q(QQ) and -U. For a description of policies, please refer to the topic fasp Transfer Policies.

IMPORTANT NOTE: If --policy is set on the command line, it will be reflected in ascp. If --policy is not set, -Q(QQ) and -U will determine the transfer policy and priority. If no related options are specified on the command line, ascp will use the server-side policy setting, which--by default--is "fair."

--user=USERNAME The user name to be authenticated by the transfer server.

IMPORTANT NOTE: If you do not specify a user name for the transfer, the local username will be authenticated (by default). In the case of a Windows machine and a domain user, the transfer server will strip the domain from the username (e.g. authenticating "Administrator," rather than "DOMAIN\Administrator). Thus, you will need to explicitly specify a domain, if applicable to the user.
--host=HOSTNAME The server's address.
--args-list=FILENAME The name of the command file. If you are storing command options in a file, use this option to call the file. Refer to Creating Command Files for additional details.
--file-list=FILENAME The file list. If you list all files to transfer in a file, use this option to call the list.
--remove-after-transfer Add this option to remove all source files (excluding the source directory) once the transfer has completed.
--remove-empty-directories Add this option to remove an empty source directory once the transfer has completed.
--skip-special-files Add this option to skip special files (e.g. devices and pipes).
--file-manifest=OUTPUT Generate a list of all transferred files. Replace OUTPUT with none or text (Default: none)
--file-manifest-path=DIRECTORY

Specify the path to store the manifested file.

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

--file-manifest-inprogress-suffix=SUFFIX Specify the file manifest's temporary-file suffix.
--precalculate-job-size Add this option to calculate total size before transfer. Please note that the server side conf file setting overrides the ascp command line option.
--overwrite=METHOD Overwrite files with the same name. This option takes following values (Default: diff):
  • always - Always overwrite the file.
  • never - Never overwrite the file.
  • diff - Overwrite if file is different from the source (i.e., if a complete file exists at the destination (no .aspx file) and is the same as the source file, then leave it unmodified (no change on timestamp/attributes either); otherwise re-transfer the whole source file). Note this policy interacts with the resume policy.
  • older - Overwrite if file is older than the source.

IMPORTANT NOTE: When --overwrite=diff, you must also consider the resume policy (-k{0|1|2|3}). If -k0 (or no -k specified), the source and destination files are always deemed to be different, thereby implying always overwrite. If -k1, the source and destination files are compared based on file attributes (currently, just file size). If -k2, the source and destination files are compared based on sparse checksum. If -k3, the source and destination files are compared based on full checksum.

--file-crypt=CRYPT Encrypt or decrypt files. Replace CRYPT with encrypt or decrypt. Passphrase is required.
--retry-timeout=SECS For retry attempts, specify the timeout duration in seconds.
--keepalive

This option enables a persistent session that doesn't require a predefined source file set and a destination at execution. Instead of reading source/destination paths from the command line, a persistent session reads source and destination paths through mgmt commands. In addition, persistent session supports canceling of individual files and directories. In a persistent session, you can also specify the transfer mode with the --mode=MODE option.

IMPORTANT NOTE: Persistent sessions for S3-direct connections (i.e., transfers to S3 through a relay user) are not supported at this time.

--partial-file-suffix=SUFFIX Filename extension on the destination computer while the file is being transferred. Once the file has been completely transferred, this filename extension will be removed. (Default: blank)

NOTE: This option only takes effect when it is set on the receiver side.
--src-base=NAME If this option is utilized, ascp will strip the srcbase path, while preserving the rest of the directory structure.

NOTE: If the target directory does not exist, the "-d" option is required when specifying the "--src-base" option.

For example, the "clips" directory on the remote computer contains the following folders and files: 

/clips/outgoing/file1
/clips/outgoing/folderA/file2
/clips/outgoing/folderB/file3

In this case, we want to transfer all folders and files within the "outgoing" folder (but not the "outgoing" folder, itself). Upon executing the following command (where -d creates the target directory if it doesn't already exist): 

> ascp -d  --src-base=/clips/outgoing/ root@10.0.0.1:/clips/outgoing/ /incoming

The following folders and files will appear in the "incoming" directory on the destination computer: 

(docroot)/incoming/file1
(docroot)/incoming/folderA/file2
(docroot)/incoming/folderB/file3

Note that files outside of the source base (e.g. /temp/file4 and /temp/file5) are skipped from transmission and warnings will be generated.

Alternatively, if the --src-base option is not specified (as shown in the following command): 

>  ascp -d root@10.0.0.1:/clips/outgoing/ /incoming

Then the contents of the "outgoing" folder will be transferred, along with the "outgoing" folder itself: 

(docroot)/incoming/outgoing/file1
(docroot)/incoming/outgoing/folderA/file2
(docroot)/incoming/outgoing/folderB/file3
--ignore-host-key With this option specified, when connecting to a remote host and you are prompted to accept a host key, ascp ignores the request.
--preserve-creation-time Preserve file creation time (available for Windows only). Note that this option must be used in conjunction with the -p option, which preserves the file's mtime and atime (modification and access time). Please refer to example below. 

ascp -p --preserve-creation-time foo aspera_test@10.0.22.204:
ascp HTTP Fallback Options
Option Description
-y {0|1} Enable HTTP Fallback transfer server when UDP connection fails. Set 1 to enable.
-j {0|1} Encode all HTTP transfers as JPEG files. Set 1 to enable. 0 / 1. (Default: 0)
-Y key-file The HTTPS transfer's key file name.
-I certif-file The HTTPS certificate's file name.
-t port Specify the port for HTTP Fallback Server.
-x proxy-server Specify the proxy server address used by HTTP Fallback.