Ascp4 command reference
Supported environment variables, the general syntax, and command options for
ascp4 are described in the following sections. ascp4 exits with a
0
on success or a 1
on error. The error code is logged in the
ascp4 log file.
ascp4 syntax
ascp4 options [[user@]srcHost:]source_file1[,source_file2,...] [[user@]destHost:]dest_path
User
The username of the Aspera transfer user can be specified as part of the as part of
the source or destination, whichever is the remote server or with the
--user
option. If you do not specify a username for the
transfer, the local username is authenticated by default.
Administrator
is authenticated rather than
DOMAIN\Administrator
. Thus, you must specify the domain
explicitly.Source and destination paths
- If there are multiple source arguments, then the target path must be a directory.
- To describe file paths, use single quotation marks (
' '
) and forward slashes (/
) on all platforms. - To transfer to the transfer user's docroot, specify "
.
" as the destination. - Avoid the following characters in file names:
/ \ " : ' ? > < & * |
. - If the destination is a symbolic link, then the file is written to the target of the symbolic link. However, if the symbolic link path is a relative path to a file (not a directory) and a partial file name suffix is configured on the receiver, then the destination path is relative to the user's home directory. Files within directories that are sent to symbolic links that use relative paths are not affected.
URI paths: URI paths are supported, but only with the following restrictions:
- If the source paths are URIs, they must all be in the same cloud storage account. No docroot (download), local docroot (upload), or source prefix can be specified.
- If a destination path is a URI, no docroot (upload) or local docroot (download) can be specified.
- The special schemes stdio:// and stdio-tar:// are supported only on the client side. They cannot be used as an upload destination or download source.
- If required, specify the URI passphrase as part of the URI or set it as an
environment variable (
ASPERA_SRC_PASS
orASPERA_DST_PASS
, depending on the direction of transfer).
UNC paths: If the server is Windows and the path on the server is a UNC path (a path that points to a shared directory or file on Windows operating systems) then it can be specified in an ascp4 command by using one of the following conventions:
- UNC path that uses backslashes (
\
)If the client side is a Windows machine, the UNC path can be used with no alteration. For example, \\192.168.0.10\temp. If the client is not a Windows machine, every backslash in the UNC path must be replaced with two backslashes. For example, \\\\192.168.0.10\\temp.
- UNC path that uses forward slashes (
/
)Replace each backslash in the UNC path with a forward slash. For example, if the UNC path is \\192.168.0.10\temp, change it to //192.168.0.10/temp. This format can be used with any client-side operating system.
Required file access and permissions
- Sources (for downloads) or destinations (for uploads) on the server must be in the transfer user's docroot or match one of the transfer user's file restrictions, otherwise the transfer stops and returns an error.
- The transfer user must have sufficient permissions to the sources or destinations, for example write access for the destination directory, otherwise the transfer stops and returns a permissions error.
- The transfer user must have authorization to do the transfer (upload or download), otherwise the transfer stops and returns a "management authorization refused" error.
- Files that are open for write by another process on a Windows source or destination cannot be transferred and return a "sharing violation" error. On Unix-like operating systems, files that are open for write by another process are transferred without reporting an error, but might produce unexpected results that depend on what data in the file is changed and when relative to the transfer.
Environment variables
If needed, you can set the following environment variables for use with an ascp4 session. The total size for environment variables depends on your operating system and transfer session. Each environment variable value must not exceed 4096 characters.
ASPERA_SCP_PASS=
password- The password that is used for SSH authentication of the transfer user.
ASPERA_SCP_TOKEN=
token- Set the transfer user authorization token. Ascp4 currently supports transfer tokens, which
must be created by using astokengen with the --full-paths
option. For more information, see
Transfer Token Generation (astokengen)
in the IBM Aspera High-Speed Admin Guide
ASPERA_SCP_COOKIE=
cookie- A cookie string that is passed to monitoring services.
ASPERA_SRC_PASS=
password- The password that is used to authenticate to a URI source.
ASPERA_DST_PASS=
password- Set the password that is used to authenticate to a URI destination.
ASPERA_LOCAL_TOKEN=
token- A token that authenticates the user to the client (in place of SSH
authentication). Note: If the local token is a basic or bearer token, the access key settings for cipher and preserve_time are not respected and the server settings are used. To set the cipher and timestamp preservation options as a client, set them in the command line.
Ascp4 options
ascp4 -h
.-A, --version
- Display version and license information.
- -c {aes128|aes192|aes256|none}
- Encrypt in-transit file data by using the specified cipher. This option overrides the
<encryption_cipher>
setting in aspera.conf. - --check-sshfp=fingerprint
- Compare fingerprint to the server SSH host key fingerprint that is set with
<ssh_host_key_fingerprint>
in aspera.conf. Aspera fingerprint convention is to use a hex string without the colons; for example, f74e5de9ed0d62feaf0616ed1e851133c42a0082. For more information on SSH host key fingerprints, see .IBM Aspera High-Speed Admin Guide. --chunk-size=
bytes- Perform storage read and write operations with the specified buffer size. Also, use the buffer
size as an internal transmission and compression block. Valid range: 4 KB - 128 MB. For transfers
with object storage, use
--chunk-size=1048576
if chunk size is not configured on the server to ensure that the chunk size of ascp4 and Trapd match. --compare={size|size+mtime|md5|md5-sparse|sha1|sha1-sparse}
method- When using
--overwrite
and--resume
, compare files with the specified method. If the--overwrite
method isdiff
ordiff+older
, the default--compare
method issize
. --compression={none|zlib|lz4}
- Compress file data inline. Default:
lz4
. If set tozlib
,--compression-hint
can be used to set the compression level. --compression-hint=
num- Compress file data to the specified level when
--compression
is set to an option that accepts compression level settings (currently only zlib). A lower value results in less, but faster, data compression (0 = no compression). A higher value results in greater, slower compression. Valid values are -1 to 9, where -1 is "balanced". Default: -1. - -D | -DD | -DDD
- Log at the specified debug level. With each D, an additional level of debugging information is written to the log. This option is not supported if the transfer user is restricted to aspshell.
--delete-before
,--delete-before-transfer
- Before transfer, delete files that exist at the destination but not at the source. The source
and destination arguments must be directories that have matching names. Objects on the destination
that have the same name but different type or size as objects on the source are not deleted. Do not
use with multiple sources or
--keepalive
. - --dest64
- Indicate that the destination path or URI is base64 encoded.
- -E pattern
- Exclude files or directories from the transfer based on the specified pattern. Use
the
-N
option (include) to specify exceptions to-E
rules. Rules are applied in the order in which they are encountered, from left to right. The following symbols can be used in the pattern:*
(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
matchestmp
but nottemp
.
Note: When filtering rules are found in aspera.conf, they are applied before rules that are given on the command line (-E
and-N
). --exclude-newer-than=mtime
--exclude-older-than=mtime
- Exclude files (but not directories) from the transfer based on when the file was last changed.
Positive mtime values are used to express time, in seconds, since the original
system time (usually 1970-01-01 00:00:00). Negative
mtime values (prefixed with "
-
") are used to express the number of seconds before the current time. - -f config_file
- Read Aspera configuration settings from config_file rather than aspera.conf(the default).
--faspmgr-io
- Run ascp4 in API mode by using FASP manager I/O. Ascp4 reads FASPMGR4 commands from management and runs them. The FASPMGR4 commands are PUT/WRITE/STOP to open/write/close on a file on the server.
- --file-crypt={encrypt|decrypt}
- Encrypt files (when sending) or decrypt files (when receiving) for client-side
encryption-at-rest (EAR). Encrypted files have the file extension .aspera-env.
This option requires the encryption and decryption passphrase to be set with the environment
variable
ASPERA_SCP_FILEPASS
. If a client-side encrypted file is downloaded with an incorrect password, the download is successful, but the file remains encrypted and still has the file extension .aspera-env. For more information, see Client-Side Encryption-at-Rest (EAR). --file-list=
filepath- Transfer the files and directories that are listed in filepath. Only the
files and directories are transferred. The path information is not preserved at the destination.
Each source must be specified on a separate line, for example:
src src2 ... srcN
To read a file list from standard input, use "
-
" in place of filepath (as ascp4 --file-list=- …). UTF-8 file format is supported. Use with-d
if the destination folder does not exist.Restrictions:
- Paths in file lists cannot use
user@host:filepath
syntax. You must use--user
with--file-list
. - Only one
--file-list
option is allowed per ascp4 session. If multiple file lists are specified, all but the last are ignored. - Only files and directories from the file list are transferred, and any additional source files or directories that are specified on the command line are ignored.
- If more than one read thread is specified (default is 2) for a transfer that uses
--file-list
, the files in the file list must be unique. Duplicates can produce unexpected results on the destination. - Because multiple sources are being transferred, the destination must be a directory.
- If the source paths are URIs, the size of the file list cannot exceed 24 KB.
For large file lists (~100 MB+), use with
--memory
to increase available buffer space. - Paths in file lists cannot use
- --file-manifest={none|text}
- Generate a list of all transferred files when set to
text
. Requires --file-manifest-path to specify the location of the list. (Default:none
) - --file-manifest-path=directory
- Save the file manifest to the specified location when using --file-manifest=text. File manifests must be stored locally. For cloud or other nonlocal storage, specify a local manifest path.
- --file-manifest-inprogress-suffix=suffix
- Apply the specified suffix to the file manifest's temporary file. For use with
--file-manifest=text. (Default suffix:
.aspera-inprogress
) -h, --help
- Display the usage summary.
--host=
host- Transfer to the specified hostname or address. Requires
--mode
. This option can be used instead of specifying the host as part of the file name (as hostname:filepath). -i
private_key_file- Authenticate the transfer by using public key authentication with the specified SSH private key
file (specified with a full or relative path). The private key file is typically in the directory
$HOME/.ssh/. If multiple
-i
options are specified, only the last one is used. - -k {0|1|2|3}
- Enable the resumption of partially transferred files at the specified resume level. Default: 0.
This option must be specified for your first transfer or it does not work for subsequent transfers.
Resume levels:
- -k 0: Always retransfer the entire file (same as
--overwrite=always
). - -k 1: Compare file modification time and size and resume if they match (same
as
--overwrite=diff --compare=size --resume
). - -k 2: Compare-sparse checksum and resume if they match (same as
--overwrite=diff --compare=md5-sparse --resume
). - -k 3: Compare-full checksum and resume if they match (same as
--overwrite=diff --compare=md5 --resume
).
- -k 0: Always retransfer the entire file (same as
--keepalive
- Enable ascp4 to run in persistent mode. This option enables a persistent session that does not
require that source content and its destination are specified at execution. Instead, the persistent
session reads source and destination paths through mgmt commands. Requires
--mode
and--host
. -L
local_log_dir[:size]- Log to the specified directory on the client machine rather than the default directory. Optionally, set the size of the log file (default 10 MB).
-l
max_rate- Transfer at rates up to the specified target rate. Default: 10 Mbps. This option accepts
suffixes
G/g
for Giga,M/m
for Mega,K/k
for Kilo, andP/p/%
for percentage. Decimals are allowed. If this option is not set by the client, the server target rate is used. If a rate cap is set in the local or server aspera.conf, then the rate does not exceed the cap. -m
min_rate- Attempt to transfer no slower than the specified minimum transfer rate. Default: 0. If this option is not set by the client, then the server's aspera.conf setting is used. If a rate cap is set in the local or server aspera.conf, then the rate does not exceed the cap.
--memory=
bytes- Allow the local ascp4 process to use no more than the specified memory. Default: 256 MB. See
also
--remote-memory
. --meta-threads=
num- Use the specified number of directory
creation
threads (receiver only). Default: 2. - --mode={send|recv}
- Transfer in the specified direction:
send
orrecv
(receive). Requires --host. --move-after-transfer=
archivedir- Move source files and copy source directories to archiver after they are successfully
transferred. Because directories are copied, the original source tree remains in place. The transfer
user must have write permissions to the archivedir. 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.
To preserve portions of the file path above the transferred file or directory, use this option with
--src-base
.To remove empty source directories (except those specified as the source to transfer), use this option with --remove-empty-directories .
Restrictions:
- archivedir must be on the same file system as the source. If the specified archive is on a separate file system, it is created (if it does not exist), but an error is generated and files are not moved to it.
- For cloud storage, archivedir must be in the same cloud storage account as the source and must not already contain files with the same name (the existing files cannot be overwritten and the archiving fails).
- If the source is on a remote system (ascp is run in receive mode), archivedir is subject to the same docroot restrictions as the remote user.
- --remove-after-transfer and --move-after-transfer are mutually exclusive. Using both in the same session generates an error.
- Empty directories are not saved to archivedir.
- When used with --remove-empty-directories and --src-base, scanning for empty directories starts at the specified source base and proceeds down any subdirectories. If no source base is specified and a file path (as opposed to a directory path) is specified, then only the immediate parent directory is removed (if empty) after the source files were moved.
- -N pattern
- Protect (
include
) files or directories from exclusion by any -E (exclude) options that follow it. Files and directories are specified by using pattern. Each option-plus pattern is a rule. Rules are applied in the order (left to right) in which they're encountered. Thus, -N rules protect files only from -E rules that follow them. Create patterns by using standard globbing wildcards and special characters such as:*
(asterisk) represents zero or more characters in a string, for example, *.tmp matches .tmp and abcde.tmp.?
(question mark) represents any single character, for example,t?p
matches tmp but not temp.
Note: Filtering rules can also be specified in aspera.conf. Rules that are found in aspera.conf are applied before any -E and -N rules that are specified on the command line. --no-open
- In test mode, do not open or write the contents of destination files.
--no-read
- In test mode, do not read the contents of source files.
--no-write
- In test mode, do not write the contents of destination files.
-O
fasp_port- Use the specified UDP port for FASP transfers. Default: 33001.
- --overwrite={always|never|diff|diff+older|older}
- Overwrite files at the destination with source files of the same name based on the
method. Default:
always
. Use with--compare
and--resume
. method can be the following: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 the file if it is different from the source, depending on thecompare
method (default issize
). If the destination is object storage,diff
has the same effect asalways
.If
resume
is not enabled, partial files are overwritten if they are different from the source, otherwise they are skipped. Ifresume
is enabled, only partial files with different sizes or checksums from the source are overwritten; otherwise, files resume.diff+older
– Overwrite the file if it is older and different from the source, depending on thecompare
method (default issize
). Ifresume
is not enabled, partial files are overwritten if they are older and different from the source, otherwise they are skipped. Ifresume
is enabled, only partial files that are different and older than the source are overwritten, otherwise they are resumed.older
– Overwrite the file if its timestamp is older than the source timestamp.
-P
ssh-port- Use the specified TCP port to initiate the FASP session. (Default: 22).
-p
- Preserve file timestamps for access and modification time. Equivalent to setting
--preserve-modification-time, --preserve-access-time, and
--preserve-creation-time. Timestamp support in object storage varies by provider;
consult your object storage documentation to determine which settings are supported.
On Windows, modification time might be affected when the system automatically adjusts for Daylight Savings Time (DST). For more information, see Daylight saving time help and support.
- --partial-file-suffix=suffix
- Enable the use of partial files for files that are in transit, and set the suffix to add to
names of partial files. (The suffix does not include a "
.
", as for a file extension, unless explicitly specified as part of the suffix). This option takes effect only when set on the receiver side. When the transfer is complete, the suffix is removed. (Default: suffix is null; use of partial files is disabled). - --policy={fixed|high|fair|low}
- Transfer according to the specified policy:
fixed
– Attempt to transfer at the specified target rate, regardless of network capacity. Content is transferred at a constant rate and the transfer finishes in a guaranteed time. Thefixed
policy can consume most of the network's bandwidth and is not recommended for most types of file transfers. This option requires a maximum (target) rate value (-l
).high
– Adjust the transfer rate to fully utilize the available bandwidth up to the maximum rate. When congestion occurs, the transfer rate is twice as fast as transfer with a fair policy. This option requires maximum (target) and minimum transfer rates (-l
and-m
).fair
– Adjust the transfer rate to fully utilize the available bandwidth up to the maximum rate. When congestion occurs, bandwidth is shared fairly by transferring at an even rate. This option requires maximum (target) and minimum transfer rates (-l
and-m
).low
– Adjust the transfer rate to use the available bandwidth up to the maximum rate. Similar to fair mode, but less aggressive when sharing bandwidth with other network traffic. When congestion occurs, the transfer rate is reduced to the minimum rate until other traffic decreases.
If
--policy
is not set, ascp4 uses the server-side policy setting (fair
by default). --precalculate-job-size
-
Calculate the total size before starting the transfer. The server-side
pre_calculate_job_size
setting in aspera.conf overrides this option. --preserve-access-time
- Preserve the file timestamps (currently the same as
-p
). --preserve-creation-time
- Preserve the file timestamps (currently the same as
-p
). --preserve-file-owner-gid
--preserve-file-owner-uid
- (Linux, UNIX, and macOS only) Preserve the group information (
gid
) or owner information (uid
) of the transferred files. These options require that the transfer user is authenticated as a superuser. --preserve-modification-time
- Preserve the file timestamps (currently the same as
-p
). --preserve-source-access-time
- Preserve the file timestamps (currently the same as
-p
). -q
- Run ascp4 in quiet mode. This option disables the progress display.
-R
remote_log_dir- Log to the specified directory on the remote host rather than the default directory.
Note: Client users that are restricted to
aspshell
are not allowed to use this option. --read-threads=
num- Use the specified number of storage
read
threads (sender only). Default: 2. To setwrite
threads on the receiver, use--write-threads
.Note: If more than one read thread is specified for a transfer that uses--file-list
, the files in the file list must be unique. Duplicates can produce unexpected results on the destination. --remote-memory=
bytes- Allow the remote ascp4 process to use no more than the specified memory. Default: 256 MB.
- --remove-empty-directories
- Remove empty source directories once the transfer is completed successfully, but do not remove a
directory that is specified as the source argument. To also remove the specified source directory,
use --remove-empty-source-directory. Directories can be emptied by using
--move-after-transfer or --remove-after-transfer. Scanning for
empty directories starts at the src-base and proceeds down any subdirectories. If no source base is
specified and a file path (as opposed to a directory path) is specified, then only the immediate
parent directory is scanned and removed if it's empty following the move of the source file.
Note: Do not use this option if multiple processes (ascp4 or other) might access the source directory at the same time.
--resume
- Resume a transfer rather than retransferring the content if partial files are present at the
destination and they do not differ from the source file based on the
--compare
method. If the source and destination files do not match, then the source file is retransferred. See-k
for another way to enable resume. --scan-threads=
num- Use the specified number of directory
scan
threads (sender only). Default: 2. - -SSH
- Use an external SSH program instead of the built-in libssh2 implementation to establish the
connection with the remote host. The wanted SSH program must be defined in the environment's PATH
variable. To enable debugging of the SSH process, use the
-DD
and--ssh-arg=-vv
options with ascp4. - --ssh-arg=ARG
- Add ARG to the command line arguments passed to the external SSH program
(implies that you use
-SSH
). This option might be repeated as needed to supply multiple separate SSH arguments. The order is preserved. The ARG elements are inserted before any key files supplied to ascp4, and before the user and host argument.
--sparse-file
- Enable ascp4 to write sparse files to disk. This option prevents ascp4 from writing zero content to disk for sparse files; ascp4 writes a block to disk if even 1 bit is set in that block. If no bits are set in the block, ascp4 does not write the block (ascp4 blocks are 64 KB by default).
--src-base=
prefix- Strip the specified prefix from each source path. The remaining portion of the source path is
kept intact at the destination. Available only in send mode.
Use with URIs: The --src-base option performs a character-to-character match with the source path. For object storage source paths, the prefix must specify the URI in the same manner as the source paths. For example, if a source path includes an embedded passphrase, the prefix must also include the embedded passphrase otherwise it does not match.
- --symbolic-links={follow|copy|skip}
- Handle symbolic links by using the specified method. On Windows, the only
option is
skip
. On other operating systems, this option takes following values:follow
– Follow symbolic links and transfer the linked files. (Default)copy
– Copy only the alias file. If a file with the same name exists on the destination, the symbolic link is not copied.skip
– Skip symbolic links. Do not copy the link or the file it points to.
-T
- Disable in-transit encryption for maximum throughput.
-u
user_string- Define a user string for Lua scripts that can be run with transfer events.
--user=
username- Authenticate the transfer by using the specified username. Use this option instead of specifying
the username as part of the destination path (as
user@host:file). Note: If you are authenticating on a Windows machine as a domain user, the transfer server strips the domain from the username. For example,
Administrator
is authenticated rather thanDOMAIN\Administrator
. Thus, you must specify the domain explicitly. --worker-threads=
num- Use the specified number of worker threads for deleting files. On the receiver, each thread deletes one file or directory at a time. On the sender, each thread checks for the presences of one file or directory at a time. Default: 1.
--write-threads=
num- Use the specified number of storage
write
threads (receiver only). Default: 2. To setread
threads on the sender, use--read-threads
.For transfers to object storage, write threads cannot exceed the maximum number of jobs that are configured for Trapd. Default: 15. To use more threads, open /opt/aspera/etc/trapd/trap.properties on the server and setaspera.session.upload.max-jobs
to a number larger than the number of write threads. For example,# Number of jobs allowed to run in parallel for uploads. # Default is 15 aspera.session.upload.max-jobs=50
-X
rexmsg_size- Limit the size of retransmission requests to no larger than the specified size, in bytes. Max: 1440.
-Z
dgram_size- Use the specified datagram size (MTU) for FASP transfers. Range: 296 - 65535 bytes. Default: the
detected path MTU.
As of version 3.3, datagram size can be specified on the server by setting
<datagram_size>
in aspera.conf. The server setting overrides the client setting, unless the client uses a version of ascp that is older than 3.3, in which case the client setting is used. If the pre-3.3 client does not set -Z, the datagram size is the discovered MTU and the server logs the message "LOG Peer client doesn't support alternative datagram size
".