ascp Command Reference

The ascp (Aspera secure copy) executable is a command-line fasp transfer program. This topic covers the complete command usage, including general syntax guidelines, supported environment variables, a synopsis, and command 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: 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: 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). For information about log files, see Log Files.
`-{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. (Range: 296 to 10000 bytes) Note: As of version 3.3, datagram size can also be enforced by the server using <datagram_size> in aspera.conf. If size is set with both -Z (client side) and <datagram_size> (server side), the <datagram_size> setting is used. If the client-side is pre-3.3, datagram size is determined by the -Z setting, regardless of the server-side setting for <datagram_size>. In this case, if there is no -Z setting, datagram size is based on the discovered MTU and the server logs the message "LOG Peer client doesn't support alternative datagram size".
`-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: 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: 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.
`--file-list=`FILENAME	Sources in the file-list are inserted as if they appear on the command-line (right after the `--file-list=FILENAME` option). The file list supports UTF-8 files and input from the stdin through "-". The sources can exist on either local host or the remote host (in terms of download), but not on both. src src2 ... srcN Important: Multiple `file-lists` and `file-pair-lists` are not supported in a single ascp command. If multiple files are specified, all but the last one will be ignored. In addition, you cannot use the `file-list` option while also listing file names on the command-line. Only files within the file-list will succeed.
`--file-pair-list=`FILENAME	Specify source-destination pairs in a file using the `--file-pair-list=FILENAME` option. Note that there is no command-line equivalent. In the case of file pair list files, each source and each destination must be separarated by line endings. src1 dst1 src2 dst2 ... srcN dstN Important: Multiple `file-lists` and `file-pair-lists` are not supported in a single ascp command. If mutiple files are specified, all but the the last one will be ignored. In addition, you cannot use the `file-pair-list` option while also listing file names on the command-line. Only files within the file-list will succeed.
`--symbolic-links=`METHOD	Specify rule to handle symbolic links. This option takes following values: (Default: follow) follow Follow symbolic links and transfer the linked files. copy Copy only the alias file. If a file with the same name exists on the destination, the symbolic link will not be copied. copy+force Copy only the alias file. If a file with the same name exists on the destination, the symbolic link will replace the file. If the file of the same name on the destination is a symbolic link to a directory, it will not be replaced. skip Skip the symbolic links.
`--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: 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. However, note that if the parent folder is not empty, its access, modify, and change times may still be updated. 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: 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.
`--file-checksum=`HASH	Report checksums for transferred files, where HASH is sha1, md5, or none.
`--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	Strips the specified source-base path, while preserving the rest of the directory structure. 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, to transfer all folders and files within the "outgoing" folder (but not the "outgoing" folder, itself), run the following command: `>` ascp -d --src-base=/clips/outgoing/ root@10.0.0.1:/clips/outgoing/ /incoming Result: The following folders and files appear in the "incoming" directory at the destination: (docroot)/incoming/file1 (docroot)/incoming/folderA/file2 (docroot)/incoming/folderB/file3 Note: Files outside of the source base (e.g. "/temp/file4") are skipped from transmission and warnings are generated. Without --src-base If `--src-base` is not used, and the source item is a folder, the contents of the folder are transferred, along with the folder itself. For example: `>` ascp -d root@10.0.0.1:/clips/outgoing/ /incoming Result: (docroot)/incoming/outgoing/file1 (docroot)/incoming/outgoing/folderA/file2 (docroot)/incoming/outgoing/folderB/file3 If `--src-base` is not used, and the source item is a file, only the file is transferred, not the folders in the file's path. For example: `>` ascp -d root@10.0.0.1:/clips/outgoing/file1 root@10.0.0.1:/clips/outgoing/folderA/file2 /incoming Result: (docroot)/incoming/file1 (docroot)/incoming/file2 For further examples, with and without `--src-base`, see ascp File Manipulation Examples
`--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.