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.
| Item | Decription |
|---|---|
| symbols used in the paths | Use single-quote (' ') and forward-slashes (/) on all platforms. |
| Characters to avoid | / \ " : ' ? > < & * | |
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 options [[user@]srcHost:]source_file1[,source_file2,...] [[user@]destHost:]target_path
| Option | Description |
|---|---|
| -h, --help | Display usage. |
| -A, --version | 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 file timestamps for source modification time (mtime) and
last access time (atime). Important: On Windows, mtime and atime 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. Important: On Isilon IQ OneFS systems, last access time (atime) is disabled by default (see sysctl efs.bam.atime_enabled). You will see atime is set to be the same as mtime when using -p option. Use the command "sysctl efs.bam.atime_enabled=1" to enable the preservation of atime on your Isilon system. |
| -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 private key file. Typically, the private key file is in the directory $HOME/.ssh/id_[algorithm]. |
| -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 at the specified resume
level (default: 0). Note that this must be specified for your first
transfer; otherwise, it will not work for subsequent transfers. Resume levels:
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. |
| -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, 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. |
| -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. |
| -S remote_ascp | Specify the name of the remote ascp binary (if different). |
| -e prepost | Specify an alternate pre/post command. Be sure to 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: 33001) |
| -C nid:ncount | 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.
|
| -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 between positions 3000 to 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. |
| --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. |
| --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, see 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." |
| --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.
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.
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. |
| ----source-prefix=prefix | Add prefix to the beginning of each source path. |
| --symbolic-links=method | Specify rule to handle symbolic links. This option takes following
values: (Default: follow)
|
| --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 (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. |
| --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):
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=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. 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 Files outside of the source base (for example, /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/file3If --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 |
| --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. |
| --ignore-host-key | If you're prompted to accept a host key when connecting to a remote host, ascp ignores the request. |
| --check-sshfp=fingerprint | Check against the server SSH host key fingerprint (for example, f74e5de9ed0d62feaf0616ed1e851133c42a0082). |
| --apply-local-docroot | Apply the local docroot. This option is equivalent to setting the environment variable ASPERA_SCP_DOCROOT. |
| 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. |