|Transferring with A4|
Supported environment variables, the general syntax, and command options for A4 are described below. ascp4 exits with a 0 on success or a 1 if there is an error. The error code is logged in the ascp4 log file.
If needed, you can set the following environment variables for use with the ascp4 command.
ascp4 options [[user@]srcHost:]source_file1[,source_file2,...] [[user@]destHost:]target_path
If you do not specify a username for the transfer, the local username will be authenticated by default.
If there are multiple source arguments, the target path must be a directory.
To describe filepaths, use single-quote (' ') and forward-slashes (/) on all platforms. Avoid the following characters in filenames: / \ " : ' ? > < & * |.
URIs are supported in paths, but only under the following restrictions:
|-h, --help||Display usage summary, then exit.|
|-A, --version||Display version and license information, then exit.|
|-T||Disable encryption for maximum throughput.|
|-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.
|-q||Quiet mode (to disable progress display).|
|-l max_rate||Set the target transfer rate. (Default: 10 Mbps) This option accepts suffixes "G/g" for Giga, "M/m" for Mega, "K/k" for Kilo, and "P/p/%" for percentage, and decimals are allowed. If the ascp client does not specify a target rate, the server target rate (set in aspera.conf) is used. If local or server rate caps are specified, the "starting" (default) rates will not exceed the cap.|
|-m min_rate||Set the minimum transfer rate in Kbps. (Default: 0) If the ascp client does not specify a minimum rate, the server-side minimum rate (set in aspera.conf) is used. If local or server rate caps are specified, the "starting" (default) rates will not exceed the cap.|
|-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 - 10000 bytes)
Note: As of version 3.3, datagram size can also be enforced by setting <datagram_size> in aspera.conf on the server. If size is set with both -Z (client side) and <datagram_size> (server side), the server 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".
|-X rexmsg_size||Adjust the maximum size in bytes of a retransmission request. (Max: 1440).|
|-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.|
|-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)|
|Exclude (-E) or include (-N) files or directories with the specified pattern from the
transfer. This option can be used multiple times to exclude many patterns.
Up to 16 -E and -N patterns can be used.
Two symbols can be used in the pattern, as shown below.
Rules are applied in the order they are encountered, with the first rule taking precedence.
|--mode=mode||Specify the transfer direction, where mode is either send or recv. Requires --host.|
|--host=host||The server's hostname or address. If a value is not provided, either the source files or the target path must specify a prepended host name as "host:filename". Requires --mode.|
|--policy=xfer_policy||Set the transfer policy, which can be any of the following:
If --policy is set on the command line, it will be reflected in the GUI. If no related options are specified on the command line, ascp4 uses the server-side policy setting (fair by default).
|--user=username||The username to be authenticated by the transfer server. If you do not specify a
username for the transfer, the local username will be authenticated (by
Note: 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.
|symbolic-links=method||Specify the rule to handle symbolic links. This option takes following values
Important: On Windows, the only option is skip.
|--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. This feature is
available in send mode only (--mode=send).
For example, the directory /clips 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 in /clips/outgoing (but not /outgoing itself) to the /incoming directory at the destination, run the following command:
> ascp4 -d --src-base=/clips/outgoing/ email@example.com:/clips/outgoing/ /incoming
Result: The following folders and files appear in /incoming 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.
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:
> ascp4 -d firstname.lastname@example.org:/clips/outgoing/ /incoming
(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:
> ascp4 -d email@example.com:/clips/outgoing/file1 firstname.lastname@example.org:/clips/outgoing/folderA/file2 /incoming
|--file-list=filename||Specify a file with a list of files to transfer. 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:
Important: Multiple --file-list options are not supported in a single ascp4 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.
|--faspmgr-io||Run the program in API mode using FASP manager I/O. In this mode, the program reads FASPMGR4 commands from management and executes the commands. The FASPMGR4 commands are PUT/WRITE/STOP to open/write/close on a file on a peer (server) machine.|
|--preserve-file-owner-uid||Preserve transferred files' owner information (uid).
Note: This option requires the transfer user be authenticated as a superuser.
|--preserve-file-owner-gid||Preserve transferred files' group information (gid).
Note: This option requires the transfer user be authenticated as a superuser.
|--preserve-access-time||Currently has the same effect as -p.|
|--preserve-source-access-time||Currently has the same effect as -p.|
|--preserve-modification-time||Currently has the same effect as -p.|
|--preserve-creation-time||Currently has the same effect as -p. This feature is supported on Windows only.|
|--chunk-size=bytes||Buffer size used for storage read/write operations as well as an internal transmission and compression "unit". The value must be at least 4kb but not more than 128Mb.|
|--read-threads=num||Number of storage "read" threads (sender only). Default: 2.|
|--write-threads=num||Number of storage "write" threads (receiver only). Default: 2.|
|--scan-threads=num||Number of directory "scan" threads (sender only). Default: 2.|
|--meta-threads=num||Number of directory "creation" threads (receiver only). Default: 2.|
|--compression=method||Compress file data inline. The method can be one of: none, zlib, or lz4. Default is lz4.|
|--compression-hint=num||For compression algorithms that offer configuration of compression levels. Currently this is only used by zlib. A lower number compresses the data less but executes more quickly (0 = no compression). A higher number offers higher compression at the cost of higher compression time. Acceptable values are -1 to 9, where -1 is a "balanced" selection of the tradeoff between compression and performance. Default: -1.|
|--compare=method||The compare method can be size, size+mtime, md5, md5-sparse, sha1, or sha1-sparse. If the --overwrite method is diff or diff+older, the default compare method is size.|
|--overwrite=method||Overwrite files at the destination with source files of the same name. (Default:
always) This option can use the following methods:
|--resume||Resume a copy rather than retransfer if partial files are present at the destination and they do not differ from the source file based on the compare method. If the files no longer match then the source file is retransferred.|
|-k resume_level||Enable resumption of partial transfers. The resume_level can be 0
(default), 1, 2, or 3.
|--sparse-file||Enable writing of sparse files to disk. This mode indicates the file is sparsed and A4 must avoid writing zero content of the file to disk. In this mode, A4 writes a block to disk if even one bit is set in that block, otherwise it avoids writing the block (by default A4 blocks are 64K).|
|--no-read||Test mode: don't actually read the contents of source files.|
|--no-write||Test mode: don't actually write the contents of destination files.|
|--no-open||Test mode: don't actually open/write the contents of destination files.|
|--memory=bytes||Maximum memory that the ascp4 process is allowed to use. Default 256MB.|
|--remote-memory=bytes||Maximum memory that the remote ascp4 process is allowed to use. Default 256MB.|
|Exclude files from the transfer based on when the file was last changed. This option does not consider directories.|