A4 Command Reference

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.

Important: Not all standard ascp options are available with ascp4.

Environment Variables

If needed, you can set the following environment variables for use with the ascp4 command.

Item Setting
Password ASPERA_SCP_PASS=password
Token ASPERA_SCP_TOKEN=token
Cookie ASPERA_SCP_COOKIE=cookie

ascp4 Syntax

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

User

If you do not specify a username for the transfer, the local username will be authenticated by default.

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

Target_path

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:

Ascp4 Options

Option Description
-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)
-E pattern

-N pattern

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.
  • * (asterisk) represents zero or more characters in a string, for example *.tmp matches .tmp and abcde.tmp.
  • ? (question mark) represents a single character, for example t?p matches tmp but not temp.

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

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 default).
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.
--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/ root@10.0.0.1:/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.

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:

> ascp4 -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:
> ascp4 -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
--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:
  • src
  • src2
  • ...
  • srcN

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-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:
  • always – Always overwrite the file.
  • never – Never overwrite the file. If the destination contains partial files that are older or the same as the source files and resume is enabled, the partial files resume transfer. Partial files with checksums or sizes that differ from the source files are not overwritten.
  • diff – Overwrite if the file is different from the source, depending on the compare method (default is size). If resume is not enabled, partial files are overwritten if they are different from the source, otherwise they are skipped. If resume is enabled, only partial files with different sizes or checksums from the source are overwritten. otherwise they are resumed.
  • diff+older – Overwrite if the destination is older and different from the source, depending on the compare method (default is size). If resume is not enabled, partial files are overwritten if they are older and different from the source, otherwise they are skipped. If resume is enabled, only partial files that are different and older than the source are overwritten, otherwise they are resumed.
  • older – Overwrite if the destination timestamp is older than the source timestamp.
--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.
  • -k 0: Always retransfer the entire file (same as --overwrite=always).
  • -k 1: Check file modification time and size and resume if they match (same as --overwrite=diff --compare=size --resume).
  • -k 2: Check sparse checksum and resume if they match (same as --overwrite=diff --compare=md5-sparse --resume).
  • -k 3: Check full checksum and resume if they match (same as --overwrite=diff --compare=md5 --resume).
--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-newer-than=mtime

--exclude-older-than=mtime

Exclude files from the transfer based on when the file was last changed. This option does not consider directories.