async Command-Line Options

This topic covers async command-line options, including definitions, allowable values, and defaults. Text shown in BOLD indicates a parameter that is required when using the corresponding async option. async can be run as a direct replacement for uni-directional, rsync-style replications (push or pull directions), or for bi-directional synchronization. Basic usage is as follows:

> async [INSTANCE-OPTIONS] -N [SESSION-OPTIONS] ...  
> async [INSTANCE-OPTIONS] -N PAIRNAME -d LDIR -r [user@host:PATH] [SESSION_OPTIONS] ...
> async -N TestBackup -d c:/tmp/dir -r user@server:d:/tmp/dir -w passwd -K bidi -a fair -l 30000  <!-- Windows to Windows -->
> async -N TestBackup -d c:/tmp/dir -r user@server:/tmp/dir -w passwd -K bidi -a fair -l 30000    <!-- Windows to Linux -->

Note: Always include the drive letter in Windows paths. If no drive letter is included when syncing with a Windows machine, async displays the error message: "Failed. Peer error: Remote directory is not absolute."

The session option -N is required. -N must follow any instance options and must precede all session arguments. For example:

async -L c:/mylogs  -N session1 -d c:/data -r root@paris:d:/data

Note: You can synchronize between a Windows endpoint and a Windows server, as well as between a Windows endpoint and a Linux server. With async, the path separator "/" works equally well on Windows and other platforms. The path separator "\" is platform-agnostic only for the options -d/r/L/R/B/b and --keep-dir-local/remote. In filtering rules, however, "\" is exclusively a quoting operator and "/" is the only path separator recognized. The examples below use "/" uniformly.

The required PAIRNAME parameter names the synchronization session, which appears in Aspera Console, while the LDIR parameter specifies the local directory to be synchronized. These options are followed by the user's login credentials at the remote endpoint, as well as the PATH that specifies the remote directory to be synchronized. If the mode of synchronization is push, then the contents of LDIR will be synchronized to PATH, with the LDIR content overwriting the PATH content, by default (unless the overwrite options are specified otherwise, e.g. to only overwrite if newer, or never overwrite). If the synchronization mode is pull, then the contents of PATH will be synchronized to LDIR. If the mode is bidi (bi-directional), then the contents of LDIR will be synchronized to PATH, with the newer versions of files and directories overwriting older versions, by default. As demonstrated by the example above, async has a variety of session options that enable you to control synchronization performance, as well as for indicating FASP transfer parameters. The following table is a complete command-line options reference. You can also display an abbreviated version from the command line by entering async -h.

Table Legend
BOLD TEXT = Required parameter

Note: Transfers started by async can be controlled from the Enterprise Server (ES) or Connect Server (CS) GUI. Canceling an async transfer from ES or CS shuts down async.

Instance Options

Short-form Option	Long-form Option	Description	Default Parameter
-h	--help	Display help for command-line options.
-A	--version	Display the async version information.
-D[D..]		Debug level	0
-q	--quiet	Disable progress display.
-L LOCAL-LOG-DIR	--alt-logdir =LOCAL-LOG-DIR	Specify a logging directory on the local host. If the directory doesn't exist, async creates it for you.
	--cooloff=SECS	Number of seconds to delay the start of the transfer. For example, if --cooloff=5, async waits 5 seconds before copying a file. If --cooloff=0 transfers start immediately. Note that both peers get the same cooloff period. --cooloff is an instance option and therefore must appear before -N. The permitted value for SECS is any integer from 0 to 60.	3
	watchd=CON(HOST:PORT)	Connection string to the data storage.
	remote-watchd=CON	Connection string to the remote data storage.

Session Options

Short-form Option	Long-form Option	Description	Default Parameter
-N PAIRNAME	--name=PAIRNAME	Name for the synchronization pair, which can be any string used to identify the connection. This value is also be stored within the session cookie and can be used in Aspera Console to identify the transfer session's name. PAIRNAME can contain only ASCII alphanumeric, hyphen, and underscore characters. Note: -N must precede any combination of the options below.
-n ACTION	--symbolic-links=ACTION	Treat symbolic links per the specified ACTION. Permitted values are: copy - create (or update) the link at the destination. (Not valid for Windows source or destination.) skip - ignore the link altogether. follow - treat the link as if it were the file (or directory) it points to, so that at the destination, what was a link will now be a copy of the file (or directory). (Skip, if source is Windows.) Refer to Configuring Symbolic Links for more information on using symbolic links.	skip
-d LDIR	--local-dir=LDIR	Set the local sync directory to LDIR. Note that you can use the --create-dir option (described below) to create the remote directory if it does not already exist.
-r RDIR	--remote-dir=RDIR	Set the remote sync directory to RDIR. Note that you can use the --create-dir option (described below) to create the remote directory if it does not already exist. RDIR=[[USER@]HOST:]PATH CAUTION: For a local synchronization, do not specify a remote (destination) directory that is located inside your source directory.
	--host=HOST	The name of the remote host. When HOST is specified with this option, the characters "@" and ":" are no longer treated specially in the argument to -r, so may appear in any such name. Note that if --host=HOST is specified, the remote-user name cannot be extracted from the argument to --remote-dir, and therefore must be supplied by a --user=NAME option or in the environment variable $USER (on Windows, %USER%). Thus, allowed forms are as follows: --remote-dir USER@HOST:/ROOTDIR # (old method) --user USER --remote-dir HOST:/ROOTDIR --host HOST --user USER --remote-dir /ROOTDIR --remote-dir HOST:/ROOTDIR # (uses $USER) --host HOST --remote-dir /ROOTDIR # (uses $USER) The following means the same as the first three lines above: `-r /ROOTDIR --user=USER --host=HOST` For backward compatibility, -r A:/ROOTDIR for any single letter A is still taken as a Windows path, not as --host A -r /ROOTDIR. To specify a one-letter host name A, use an explicit --host=A.
	--user=USER	The name of the remote user. When --user=USER is specified, the character "@" is no longer treated specially in the argument to -r, so may appear in any such name.
-w PASS	--pass=PASS	Set the passphrase string to PASS.
-i FILE	--private-key-path=FILE	The SSH private key file. For information on creating a key pair, see Creating SSH Keys (Terminal).
-K DIRECTION	--direction=DIRECTION	Set the transfer direction. DIRECTION can be push, pull, or bidi (bi-directional).	push
-k CKSUMTYPE	--checksum=CKSUMTYPE	Set the checksum type. CKSUMTYPE can be sha1, md5, sha1-sparse, md5-sparse, or none. A value of none is equivalent to a size and modification-time check only.	sha1-sparse
-P PORT	--tcp-port=PORT	Set the TCP port for SSH. PORT must be valid numeric IP port.	22
-O PORT	--udp-port=PORT	Set the UDP port used by FASP for data transfer.	33001
-a POLICY	--rate-policy=POLICY	Set the transfer rate policy. POLICYcan be fixed, fair, high, or low.	fair
`-l` RATE	--target-rate=RATE	Set the maximum transfer rate. RATE=integer G/g, M/m, K/k, or bps.	10,000 Kbps or 10 Mbps
-m RATE	--min-rate=RATE	Set min transfer rate. RATE=integer G/g, M/m, K/k, or just bps.	200 Kbps
-g SIZE	--read-block-size=SIZE	Set block size for reading. SIZE=integer K, M, or just bytes.	64 MB
-G SIZE	--write-block-size=SIZE	Set block size using for writing. SIZE=integer K, M, or just bytes.	64 MB
-H VAL	--scan-intensity=VAL	Set the intensity for scanning work. VAL can be one of vlow, low, medium, high, or vhigh. vlow minimizes system activity. vhigh maximizes system activity by continuously scanning files without rest.	medium
	--scan-dir-rename	Enable renamed-directory detection on the initial scan.
-o POLICY	--overwrite=POLICY	Set the overwrite policy. POLICY can be always, older, or conflict. Use with -K push and pull. Note: You can easily resolve CONFLICT and ERROR situations in a uni-directional sync by “touching” the problem files on the source and running async with --overwrite=always. This is designed to clear all CONFLICT and ERROR states as the problem files are synced. Note: --overwrite=older is only accurate if the user also specifies --preserve-time (preserve timestamps).	always for -K push and pull. conflict for -K bidi.
-R REMDIR	--remote-logdir=REMDIR	Specify a logging directory on the remote host.
-Z MTU	--datagram-size=MTU	Specify the datagram size (MTU) as an integer.	By default, FASP uses the detected-path MTU.
-X SIZE	--rexmsg-size=SIZE	Adjust the SIZE (in bytes) of a retransmission request (Maximum: 1440).
-c CIPHER	--cipher=CIPHER	Set encryption algorithm. CIPHER can be none, AES128	AES128
-C	--continuous	Run continuous synchronization. If you receive an inotify error when attempting to run continuous synchronization, see Error Troubleshooting.	one-time
-t	--preserve-time	Preserve file timestamps.	off
	--preserve-access-time	Set the access time of the destination file to the same value as that of the source file.	off
	--preserve-modification-time	Set the modification time of the destination file to the same value as that of the source file.	off
	--preserve-creation-time	Set the creation time of the destination file to the same value as that of the source file. (Valid only on Windows.)	off
-u	--preserve-uid	Preserve file owner's UID. This preserve option requires that async is running as root (for Linux) or Administrator (for Windows).	off
-j	--preserve-gid	Preserve file owner's GID. This preserve option requires that async is running as root (for Linux) or Administrator (for Windows).	off
	--write-uid=UID	Write files as the user UID. UID may be numeric, or by name. If by name, the name is looked up on the host actually performing the write. Failure to set the UID is logged, but is not an error. The UID is set after ascp completes and before moving the file from the staging directory to the final location. This option conflicts with --preserve-uid.
	--write-gid=GID	Write files as the group GID. GID may be numeric, or by name. If by name, name is looked up on host actually performing the write. Failure to set the GID is logged, but is not an error. GID is set after ascp completes and before moving the file from the staging directory to the final location. This option conflicts with --preserve-gid.
-x	--reset	Clear the async snapshot database and rescan the synchronized directories and files to create a fresh snapshot.	off
-b LDBDIR	--local-db-dir=LDBDIR	Local database directory. Note that you may relocate the snapshot database to a different location than the default one under the LDIR specified with -d. This allows placing the database away from the main data files. This is useful for performance tuning. It is also useful when -d LDIR is located on a network share volume that does not reliably support database locking. For further usage information, see Multiple Databases (Snap DB).	Default snapshot directory is ~private-asp at the root level of the synchronized directory.
-B RDBDIR	--remote-db-dir=RDBDIR	Remote database directory. Similar to -b above, but for the remote database. For further usage information, see Multiple Databases (Snap DB).	Default snapshot directory is ~private-asp at the root level of the synchronized directory.
-I FILE	--include-from=FILE	Scan paths identified in the filter FILE.
-E FILE	--exclude-from=FILE	Skip paths identified in the filter FILE.
	--include=PATTERN	Scan paths that match PATTERN.
	--exclude=PATTERN	Exclude paths that match PATTERN.
	--assume-no-mods	Only propagate create/delete/move. In other words, when running async in non-continuous mode, it does not scan a directory if the modification time is unchanged (compared to the current snapshot).
	--ignore-delete	Do not copy removals to the peer. This option is used mostly with uni-directional syncs. In bi-directional sync, a deletion on one side is "ignored," but the next time async is run, the file is recopied from the other end. In continuous mode, the file is not recopied until either async is restarted or the file is changed (i.e., "touched").
	--keep-dir-local=DIR	Move deleted files under DIR. Note that DIR must exist (it is not created by --create-dir), and must be outside the synchronization directory, but on the same file system.
	--keep-dir-remote=DIR	Move the server's deleted files under DIR. Note that DIR must exist (it is not created by --create-dir), and must be outside the synchronization directory, but on the same file system.
	--create-dir	Create the remote directory if it does not exist. This option is used with the -d and -r options (async creates directories if they do not exist, rather than reporting an error and quitting).
	--dedup[=MODE]	If duplicate files are encountered, take the action specified by MODE, which can be hardlink or copy. In either mode, only a single copy of duplicate files is transferred. With --dedup=hardlink, the files are then replicated at the destination by means of hardlinks. With --dedup=copy, the files are replicated at the destination by copying.	create hardlinks
	--no-scan	Skip initial scanning.
	--preserve-acls=MODE	Preserve the ACL access data from Windows or OSX files if the preservation MODE is native or metafile. If MODE is native, async expects that the destination supports the same native ACL format as the source; if not, it generates an error and exits. If MODE is metafile, async writes the access data to a separate file in the same location; the file has same name but with the added extension .aspera-meta. Metafile data is in a generic format that can reside on any platform and also be reconverted to native form if the file is again synced with a system that supports it. If MODE is none, no ACL data is preserved at all. This feature is only meaningful if both hosts are in a common security domain. If a SID (security ID) in a source file does not exist at a destination, the sync proceeds but no ACL data is saved and the log records that the ACL could not be applied.	No ACL data is preserved.
	--remote-preserve-acls=MODE	Like --preserve-acls but used when ACLs are stored in a different format on the remote host. Defaults to the value of --preserve-acls.	No ACL data is preserved.
	--preserve-xattrs=MODE	Preserve OSX extended attributes data (xattr) if preservation MODE is native or metafile. If the sync is run by a regular user, only user-level attributes are preserved. If run as superuser, all attributes are preserved. If MODE is native, async expects that the destination supports the same native xattr format as the source; if not, it generates an error and exits. If MODE is metafile, async writes the xattr data to a separate file in the same location; the file has the same name with the added extension .aspera-meta. The aspera-meta files are platform-independent and can be copied between hosts without loss of data. They can be reconverted to the native form if the file is again synced with an OSX system. If MODE is none, no xattr data is preserved at all.	No xattr data is preserved.
	--remote-preserve-xattrs=MODE	Like --preserve-xattrs but used attributes are stored in a different format on the remote systgem. Defaults to the value of --preserve-xattrs.	No xattr data is preserved.
	--scan-dir-rename	Look for renames and moves of directories when scanning. Results are only relevant if the inodes for your file system are stable.	No scan for directory renames and moves
	--scan-file-rename	Look for renames and moves of files when scanning. Results are only relevant if the inodes for your file system are stable.	No scan for file renames and moves
	--check-sshfp=VALUE	Specify the expected fingerprint of the server.
	--delete-delay	Postpone actual deletion of files or directories until the end of the sync session.
	--sharing-retry-max=N	Maximum number of times to retry after a sharing violation. The interval between retries is the number of seconds specified by --cooloff.	3

Note: When scanning or monitoring a file system for changes, async skips over files with names that end in one of the special suffixes specified in the configuration file with <resume_suffix> and <partial_file_suffix>. To disable this behavior, you can set these values to the empty string. <resume_suffix> defaults to .aspx. <partial_file_suffix> defaults to the empty string, but is often set to .partial.