Ascp Command Reference

The executable ascp (Aspera secure copy) is a command-line FASP transfer program. The tables below describe the complete command usage, including general syntax guidelines, supported environment variables, a synopsis, and command options.

General Syntax Guidelines

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 set the following environment variables for use with the ascp command:

Item Initiation Command
Password ASPERA_SCP_PASS=password
Token ASPERA_SCP_TOKEN=token
Cookie ASPERA_SCP_COOKIE=cookie
Content Protection Password ASPERA_SCP_FILEPASS=password
Proxy Server Password ASPERA_PROXY_PASS=proxy_server_password

Ascp Usage

ascp options [[user@]srcHost:]source_file1[,source_file2,...] [[user@]destHost:]target_path

For examples of ascp commands, see Ascp General Examples.

Important: If you do not specify a username 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 (for example, authenticating Administrator, rather than DOMAIN\Administrator). Thus, you will need to specify a domain explicitly, if applicable to the user.

Special Considerations for URI Paths

URIs are supported in paths, but only under the following restrictions:

Transfer Testing with Minimal Storage Requirements

For ascp transfer testing purposes, you can use a faux:// argument in place of the source file and target path to send random data and not write it to disk at the destination. For more information, see Testing and Optimizing Transfer Performance. For examples, see Ascp General Examples.

Ascp Options

Option Description
-h, --help Display usage.
-A, --version Display version and license information; then exit.
-T Disable encryption for maximum throughput.
-c Specify the encryption cipher for file data. Options are aes128, aes192, aes256, or none. This overrides the setting for transport_cipher in aspera.conf.
-d Create target directory if it doesn't already exist.
-q Quiet mode (to disable progress display).
-v Verbose mode (prints connection and authentication debug messages in the log file). For information on log files, see Log Files .
-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.
-l max_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 (efault: 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.
-u user_string Apply a user string, such as variables for pre- and post-processing.
-i private_key_file Use public key authentication and specify the SSH private key file. Typically, the private key file is in the directory $HOME/.ssh/id_algorithm. Multiple private key files can be specified using multiple -i arguments. The keys are tried in order and the process ends when a key passes authentication or when all keys have been tried and authentication fails.
-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. (Default: 100Kbps)
-k {0|1|2|3} Enable resuming partially transferred files at the specified resume level (default: 0). This must be specified for your first transfer; otherwise, it will not work for subsequent transfers. Resume levels:
  • -k 0 – Always retransfer the entire file.
  • -k 1 – Check file attributes and resume if the current and original attributes match.
  • -k 2 – Check file attributes and do a sparse file checksum; resume if the current and original attributes/checksums match.
  • -k 3 – Check file attributes and do a full file checksum; resume if the current and original attributes/checksums match.

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.

-Z dgram_size Specify the datagram size (MTU) for FASP. By default, the detected path MTU is used. (Range: 296 - 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".

-g read_size Set the read-block size, in bytes. A read_size of 1M is 1 MB. The maximum block size is 500 MB. The default of 256K causes the Aspera sender to use its default internal buffer size.

This is a performance-tuning parameter for an Aspera sender, which takes effect only if the sender is a server. It specifies the maximum number of bytes that can be stored within a block as the block is transferred from the source disk to the receiver. This option overrides the client's configuration file setting for this feature if set. The server uses its configuration file setting for this feature if it's set, otherwise it uses read_size if set; however, it does not use settings in the client configuration file.

-G write_size Set the write-block size, in bytes. A write_size of 1M is 1 MB. The maximum block size is 500 MB. The default of 256K causes the Aspera receiver to use its default internal buffer size.

This is a performance-tuning parameter for an Aspera receiver, which takes effect only if the receiver is a server. It specifies the maximum number of bytes within a block that an ascp receiver can write to disk. This option overrides the client's configuration file setting for this feature if set. The server uses its configuration file setting for this feature if it's set, otherwise it uses write_size if set; however, it does not use settings in the client configuration file.

-L local_log_dir[:size] Specify a logging directory in the local host, instead of using the default directory. Optionally set the size of the log file (default 10 MB).
-R remote_log_dir Specify a logging directory in the remote host, instead of using the default directory.
-S remote_ascp Specify the name of the remote ascp binary (if different).
-e prepost Specify an alternate pre/post command. Use the complete path and file name.
-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: 22)
-C nid:ncount Enable multi-session transfers (also known as parallel transfers) on a multi-node/multi-core system. Specify the node ID (nid) and count (ncount) in the format 1:2, 2:2. The valid range of values for nid and ncount is 1-128, and nid must be less than or equal to ncount. Assign each participant to an independent UDP port. Large files can be split across sessions, see --multi-session-threshold.
-E pattern

-N pattern

Exclude (-E) or include (-N) files or directories from the transfer using the specified pattern. This option can be used multiple times to exclude/include many patterns. Up to 16 -E and -N patterns can be used. The following two symbols can be used in specifying the pattern:
  • A "*" (asterisk) represents zero or more characters in a string. For example *.tmp matches .tmp and abcde.tmp.
  • A "?" (question mark) represents a single character. For example t?p matches tmp but not temp.

Rules are applied in the order in which they are encountered, with the first rule taking precedence. For details on specifying rules, see Applying Filters to Include and Exclude Files.

--exclude-newer-than=mtime

--exclude-older-than=mtime

Exclude files from the transfer based on when the file was last changed. This feature does not include directories.
-f config_file Specify an alternate Aspera configuration file (default is aspera.conf).
-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 from position 3000 to position 6000; -@1000: transfers from 1000 to the end of the file; and -@:1000 transfers from beginning to 1000.
-X rexmsg_size Adjust the maximum size in bytes of a retransmission request. (Max: 1440).
--mode=mode Specify the transfer direction, where mode is either send or recv. Requires --host.
--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. Requires --mode.
--keepalive Run ascp in persistent mode. Requires --mode and --host.
--save-before-overwrite Saves a copy of an existing file if a transfer would overwrite the file. If the filename is filename.ext, the file is saved as filename.yyyy.mm.dd.hh.mm.ss.index.ext (where index is set to 1 at the beginning of each second and incremented for each file saved during the same second) in the same directory before the new file is written. File attributes are maintained in the renamed file.
--policy=fixed | high | fair | low Set the FASP transfer policy.
  • fixed – Attempts to transfer at the specified target rate, regardless of the actual network capacity. This policy transfers at a constant rate and finishes in a guaranteed time. This policy typically occupies most of the network's bandwidth, and is not recommended in most file transfer scenarios. In fixed mode, a maximum (target) rate value is required.
  • high – Monitors the network and adjusts the transfer rate to fully utilize the available bandwidth up to the maximum rate. When congestion occurs, a it transfers at a rate twice of a session with fair policy. In this mode, both the maximum (target) and the minimum transfer rates are required.
  • fair – Monitors the network and adjusts the transfer rate to fully utilize the available bandwidth up to the maximum rate. When other types of traffic build up and congestion occurs, it shares bandwidth fairly by transferring at an even rate. In this mode, both the maximum (target) and the minimum transfer rates are required.
  • low – Similar to fair mode, the low policy uses the available bandwidth up to the maximum rate, but is much less aggressive when sharing bandwidth with other network traffic. When congestion builds up, the transfer rate is reduced to the minimum rate until other traffic retreats.

Important: If --policy is not set, ascp uses the server-side policy setting (fair by default).

--source-prefix=prefix Add prefix to the beginning of each source path. This can be either a conventional path or a URI; however, it can only be a URI if there is no root defined.
--src-base=prefix Specify the prefix to be stripped off from each source object. The remaining portion of the source path is kept intact at the destination. Special care must be taken when using this option with cloud storage.

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 

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. Files outside of the source base (for example, /temp/file4) are not transferred, and warnings are generated.

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

If the same transfer is run without --src-base=/clips/outgoing/, then the following folders and files appear at the destination:

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

For further examples, with and without --src-base, see Ascp File Manipulation Examples

Use with URIs

The --src-base option performs a character-to-character match with the source path specifying a file or directory. Hence for cloud storage, it is necessary that --src-base specify the URI in the same manner the source parameters are specified (for example, if the source includes and embedded passphrase, the source base must also include an embedded passphrase or it will not match the source files/directories).

--file-list=filename Extract a list of sources to transfer from filename. The file list supports UTF-8 files and input from standard input through "-". If the sources are URIs, the list file should not exceed 24kb. The sources can exist on either the local host or the remote host (for download), but not on both. Each source must be specified on a separate line, for example:
  • src
  • src2
  • ...
  • srcN

Important: Multiple --file-list and --file-pair-list options are not supported in a single ascp command. If multiple file lists are specified, all but the last will be ignored. If --file-list or --file-pair-list is used, you cannot also include file names on the command line; only files from the file list will be transferred.

--file-pair-list=filename Extract a list of sources and corresponding destinations from filename. There is no command-line equivalent for specifying file pairs. If the sources or destination are URIs, the list file should not exceed 24kb. Each source and each destination must be specified on a separate line:
  • src1
  • dst1
  • src2
  • dst2
  • ...
  • srcN
  • dstN

Important: Multiple --file-list and --file-pair-list options are not supported in a single ascp command. If multiple file lists are specified, all but the last will be ignored. If --file-list or --file-pair-list is used, you cannot also include file names on the command line; only files from the file list will be transferred.

--dest64 Indicate that the destination is base64 encoded.
--source-prefix64=prefix Indicate that the specified source prefix is base64 encoded. If a non-encoded source prefix is also specified on the command line, the later argument takes precedence.
--remove-after-transfer Remove all source files (excluding the source directory) after they are successfully transferred. Requires write permissions on the source.
--move-after-transfer=archivedir Move source files and copy source directories to archivedir after they are successfully transferred. Requires write permissions on the source and the archivedir. Because directories are copied, the original source tree remains in place. 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.

Example upload:

# ascp --move-after-transfer=C:\Users\Pat\Archive C:\Users\Pat\srcdir\file0012 Pat@10.0.0.1:/

Results:

  • file0012 is uploaded to Pat's docroot on 10.0.0.1, the server (destination).
  • On the current machine (source), file0012 is moved (not copied) to C:\Users\Pat\Archive

Example download:

# ascp --move-after-transfer=Archive Pat@10.0.0.1:/srcdir C:\Users\Pat

Results:

  • srcdir is downloaded to C:\Users\Pat on the current machine (destination).
  • On the server (source), srcdir is moved (not copied) to the archive directory Pat@10.0.0.1:/Archive.

When the file or directory is moved to the archive, no portion of the path above the transferred file or directory is included, unless the --src-base option is specified.

The --src-base=prefix option preserves paths in the archive directory the same way it preserves them with transfers. That is, when --src-base=prefix is specified, files are moved to the archivedir and they include the portion of the path that remains when prefix is removed.

Example:

# ascp --src-base=C:\Users\Pat --move-after-transfer=C:\Users\Pat\Archive C:\Users\Pat\srcdir\file0012 Pat@10.0.0.1:/

Results:

  • file0012 is uploaded to Pat's docroot on 10.0.0.1. The file includes the path minus the prefix C:\Users\Pat — that is, srcdir/file0012.
  • On the current machine (source), file0012 is moved to C:\Users\Pat\Archive. The file includes the path minus the prefix C:\Users\Pat — that is, C:\Users\Pat\Archive\srcdir\file0012.

Once files have been moved to the archive, the original source directory tree remains intact. To remove empty source directories that remain after files have been moved, add the flag --remove-empty-directories to the ascp command. This removes empty source directories, except for those that are specified as the source to transfer.

Restrictions:

  • archivedir must be on the same file system as the source. If the specified archive is on a separate file system, it will be created (if it does not exist), but an error will be generated and files will not be moved to it. For cloud storage, archivedir must be in the same cloud storage account.
  • archivedir is subject to the same docroot restrictions as the source.
  • --remove-after-transfer and --move-after-transfer are mutually exclusive. Including both in the same command generates an error.
  • Empty directories are not saved to archivedir.
--remove-empty-directories Remove empty source directories once the transfer has completed (not including a directory specified as the source to transfer). Do not use if multiple processes (ascp or other) might access the source directory at the same time.
--remove-empty-source-directory Remove the source directory argument itself (for use with --remove-empty-directories).
--skip-special-files Skip special files (for example, devices and pipes).
--file-manifest=output Generate a list of all transferred files, where output is none or text (Default: none)
--file-manifest-path=directory Specify the path to the file manifest.

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 suffix of the file manifest's temporary file. (Default: .aspera-inprogress)
--precalculate-job-size Calculate total size before transfer. The server side aspera.conf setting overrides the ascp command-line option.
--overwrite=method Overwrite destination files with source files of the same name. This option takes the following values (Default: diff):
  • 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 it is different from the source. If a complete file at the destination is the same as the source then it will not be overwritten. Partial files will be overwritten or resumed depending on the resume policy.
  • diff+older – Overwrite the file if it is older and different than the source.
  • older – Overwrite the file if its timestamp is older than the source timestamp.

Important: 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.

--file-crypt=crypt Encrypt or decrypt files for client-side encryption-at-rest (EAR). Valid values are encrypt and decrypt. Set the passphrase (required) with the environment variable ASPERA_SCP_FILEPASS. Encrypted files have the file extension .aspera-env. If a client-side encrypted file is downloaded with an incorrect password, the download is successful but the file is still encrypted and still has the file extension .aspera-env.
--file-checksum=hash Report checksums for transferred files, where hash is sha1, md5, sha-512, sha-384, sha-256 or none. (Default: none)
--retry-timeout=secs Specify the timeout duration in seconds for a retry attempt.
--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.

--proxy=proxy_url Specify the address of the Aspera proxy server. proxy_url takes the form of:
dnat[s]://[username]@server:port

The default ports for DNAT and DNATS protocols are 9091 and 9092.

--preserve-file-owner-uid (OS X and Linux/UNIX systems only.) Preserve transferred files' owner information (uid).

Note: This option requires the transfer user be authenticated as a superuser.

--preserve-file-owner-gid (OS X and Linux/UNIX systems only.) Preserve transferred files' group information (gid).

Note: This option requires the transfer user be authenticated as a superuser.

--preserve-creation-time
--preserve-modification-time
--preserve-access-time
--preserve-source-access-time
-p

Preserve creation time [Windows only]: Set the file/directory creation time at the destination to that of the source. If the destination is a non-Windows host, this option is ignored. (Note: Do not confuse this with UNIX ctime, which represents "change time", indicating the time when metadata was last updated.)

Preserve modification time: Set the file/directory modification time at the destination to that of the source.

Preserve access time: Set the file/directory access time (the last time the file was read or written) at the destination to that of the source. This results in the destination file having the access time that the source file had prior to the copy operation. The act of copying the source file to the destination results in an update to the source file's access time.

Preserve source access time: Restore the access time of the file at the source once the copy operation is complete (because the file system at the source regards the transfer operation as an access).

-p is equivalent to setting --preserve-modification-time and --preserve-access-time (and --preserve-creation-time, on Windows).

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.

Cloud storage support for timestamp settings depends on the cloud storage implementation. See the documentation for your cloud storage option to determine which of these settings are supported.

For Limelight, only the preservation of modification time (mtime) is supported.

--ignore-host-key If you are prompted to accept a host key when connecting to a remote host, ascp ignores the request.
--check-sshfp=fingerprint Check whether fingerprint matches the server SSH host key fingerprint specified in the server's aspera.conf. Aspera fingerprint convention is to use a hex string without the colons; for example, f74e5de9ed0d62feaf0616ed1e851133c42a0082.

Note: When the HTTP fallback feature is enabled and the client "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.

--apply-local-docroot Apply the local docroot. This option is equivalent to setting the environment variable ASPERA_SCP_DOCROOT.
--multi-session-threshold=threshold This option augments the -C option, which enables multi-session transfers (also known as parallel transfers). With the threshold option, if the size of the files to be transferred is greater than or equal to threshold, files will be split across multiple sessions. If the total file size is less than the threshold or no threshold is set (default), files are not split. The client node API can specify the multi-session-threshold, and this will be passed to the ascp command line. If the client doesn't specify a value, then the multi_session_threshold_default is taken from the server. A default value for the threshold can be specified in aspera.conf by setting multi_session_threshold_default. Setting it to 0 (zero) means "do not split". The command-line setting overrides the aspera.conf setting.
Note: For cloud transfers, file-splitting is currently (3.6.0) supported for S3 only.

Multi-session uploads to cloud storage:Currently only supported for S3. Unlike non-cloud file splitting, files for transfer to cloud storage are sent in chunks, with the chunk size is specified by <chunk_size> in aspera.conf:

<central_server>
    . . .
    <transfer>
        <protocol_options>
            <transfer>
                <chunk_size>0</chunk_size>
            </transfer>
        </protocol_options>
    </transfer>
</central_server>

File-splitting needs to respect a minimum split size, which for cloud storage is a part, such that each ascp call must deliver full parts. Thus, the chunk size must be equal to the cloud-storage part size. If the file size is greater than the multi-session threshold but smaller than the chunk size, then the file is not split. Set chunk size and part size as follows:

  1. In aspera.conf set the chunk size to some value greater than 5 MB (the minimum part size), for example:
    <chunk_size>67108864</chunk_size>   <!-- 64 MB -->
  2. In /opt/aspera/etc/trapd/s3.properties set the upload part size (default 64 MB) to the same value as the chunk size and set a ONE_TO_ONE gathering policy:
    aspera.transfer.upload.part-size=64MB
    aspera.transfer.gathering-policy=ONE_TO_ONE
--delete-before-transfer Delete files that exist at the destination but not at the source, before any files are transferred. Requires write permissions on the destination. Do not use with multiple sources, keepalive, URI storage, or HTTP fallback. The utility asdelete provides the same capability.

--preserve-xattrs=mode
--remote-preserve-xattrs=mode
--preserve-acls=mode
--remote-preserve-acls=mode

Preserve extended attributes (xattrs) and/or access control lists (ACLs) when transferring files between different types of file systems. mode can be native, metafile, or none (default):
native
xattrs and ACLs are preserved using native capabilities of the file system. However, this storage mode is not supported on all file systems.
metafile
xattrs and ACLs for a file (say, readme.txt) are preserved in a second file, whose name is composed of the name of the primary file with .aspera-meta appended to it; for example, readme.txt.aspera-meta. The Aspera metafiles are platform independent and can be copied between hosts without loss of information. This storage mode is supported on all file systems.
none
xattrs and ACLs are not preserved. This storage mode is supported on all file systems.

The modes of preserving xattrs and ACLs on each side of the transfer will end up being the same, even if specified differently. In this case, the metafile mode takes precedence, silently.

The options with the remote- prefix specify the storage mode used on the remote file system. If not specified, the default behavior is to use the same storage mode specified for the local file system. A remote option with mode set to native may be overridden by the remote ascp if that mode is not supported there.

Older versions of ascp do not support this feature. Thus, these options may be overridden by the peer, to none, and ascp will abort and indicate the problem is incompatible FASP protocol versions.

The amount of xattr/ACL data per file that can be transferred successfully is subject to ascp's internal PDPU size limitation.

Ascp Options for HTTP Fallback

Option Description
-y {0|1} Enable HTTP Fallback transfer server when UDP connection fails. Set to 1 to enable (default: 0).
-j {0|1} Encode all HTTP transfers as JPEG files. Set to 1 to enable (default: 0).
-Y key_file The HTTPS transfer's key file name.
-I cert_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.