Transferring from the Command Line |
The executable ascp (Aspera secure copy) 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
URIs are supported in paths, but only under the following restrictions:
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. |
-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 . |
-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, in bytes. A read_size of 1M is 1
MB. The maximum block size is 500 MB. The default of 0 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 0 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 | 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 | 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. Assign each participant to an independent UDP port. Large files can also be split using --multi-session-threshold option. (See below.) |
-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 | Set the FASP transfer policy.
Important: If --policy is not set, ascp uses the server-side policy setting (fair by default). |
--file-list=filename | Take the list of sources to transfer from filename. The file list
supports UTF-8 files and input from standard input through "-". The sources
can exist on either the local host or the remote host (in terms of
download), but not on both. Each source must be specified on a separate line:
Use with URIs: The sources listed in the file list cannot be URIs. To use --file-list with cloud storage, you must specify the cloud storage with a URI in either a root, source prefix, or command-line destination parameter, subject to the limitations described above. 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. In addition, you cannot also include file names on the command line when you use --file-list. Only files from the file list will be transferred. |
--file-pair-list=filename | Take the list of sources and corresponding destinations from
filename. Note that there is no command-line
equivalent. Source and destination arguments in the file list cannot be
URIs. Each source and each destination must be specified on a separate line:
Use with URIs: The sources and destinations listed in the file list cannot be URIs. To use --file-pair-list with cloud storage, you must specify the cloud storage with a URI in either a root, source prefix, or command-line destination parameter, subject to the limitations described above. 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. In addition, you cannot also include file names on the command line when you use --file-pair-list. Only files from the file-pair list will be transferred. |
--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. |
--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 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\Bob\Archive C:\Users\Bob\srcdir\file0012 bob@10.0.0.1:/ Result:
Example download: ascp --move-after-transfer=Archive bob@10.0.0.1:/srcdir C:\Users\Bob Result:
As with transfers, by default, no portion of the path above the transferred file or directory is included when the file or directory is moved to the archive (unless --src-base is specified). The --src-base=prefix option preserves paths in the archive directory the same way as it preserves them with transfers. That is, when --src-base=prefix is specified, files are moved to the archivedir including the portion of the path that remains when prefix is removed. Example: ascp --src-base=C:\Users\Bob --move-after-transfer=C:\Users\Bob\Archive C:\Users\Bob\srcdir\file0012 bob@10.0.0.1:/ Result:
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, include the flag --remove-empty-directories on the command line. This removes empty source directories except for those that are specified as the source to transfer. Restrictions:
|
--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 (ascpor 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. |
--precalculate-job-size | Add this option to calculate total size before transfer. Note that the server side aspera.conf 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. |
--save-before-overwrite | If a transfer will overwrite an existing file, move the existing file to file.yyyy.mm.dd.hh.mm.ss.index.ext, where index is set to 1 at the beginning of each new second and incremented for each file saved in this manner during the same second. File attributes are maintained in the renamed file. |
--file-crypt=crypt | Encrypt or decrypt files for client-side encryption-at-rest (EAR). Valid values for crypt are encrypt and decrypt. Set the passphrase (required) with the environment variable ASPERA_SCP_FILEPASS. Encrypted files have the file extension .aspera-env. Note that 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, 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. |
--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 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 not transferred, 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 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). |
--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 creation time: Set the file/directory creation time at the destination to
that of the source. Available on Windows clients only. 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 both --preserve-modification-time and --preserve-access-time. 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 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. |
--multi-session-threshold=threshold | This option augments the existing -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. Files with
sizes less than the threshold will not be split for the multi-session
transfer. If not set, the default is that no files are split. The client
node API can also specify the multi-session-threshold, and this will be
passed to the ascp command line. A default value for the
threshold can be specified in aspera.conf by setting
multi_session_threshold_default. By default, the threshold
default is "unspecified" (NULL). Setting it to 0 (zero) means "do not
split". The command-line setting overrides the
aspera.conf setting. If the client doesn't specify
a value, then the multi_session_threshold_default is taken from the
server. Note: For cloud transfers, file-splitting is currently (3.6.0)
supported for S3 only.
For cloud transfers, the process of
splitting files in a multi-session transfer differs from a regular
(non-cloud) multi-session transfers. For cloud transfers, files are sent in
chunks, and 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> Multi-session uploads to cloud storage with file splitting must have the ascp chunk size and the cloud-storage part size set to equal values. File-splitting needs to respect a minimum split size, which for cloud storage is a part. That is, each ascp call needs to deliver full parts. However, note that if the file size is greater than the multi-session threshold and smaller than the chunk size, then there is no split. Set chunk size and part size as follows:
|
--delete-before-transfer | Delete files that exist at the destination but not at the source, before any files are transferred. Do not use with multiple sources, keepalive, or HTTP fallback. The utility asdelete provides the same capability. |
--preserve-xattrs=mode |
Preserve extended attributes (xattrs) and/or access control lists (ACLs) when
transferring files between different types of file systems.
mode can be one of native,
metafile, or none (default):
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. |
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. |