This topic covers async command-line options, including definitions, allowable values and defaults. Text shown in GREEN below 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 as a 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 -->
WARNING: If you do not include a drive letter in your path when syncing with a Windows machine, async will report the following error message: "Failed. Peer error: Remote directory is not absolute." Thus, remember to always include a drive letter in your Windows path(s).
The required session option -N must precede session arguments, whereas instance options must precede -N. For example, async -L c:/mylogs -N session1 -d c:/data -r root@paris:d:/data.
IMPORTANT NOTE: You can synchronize between a Windows endpoint and a Windows server, as well as between a Windows endpoint and a Linux server. In 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. Please refer to the following table for the complete command-line options reference.
| Table Legend |
|---|
| GREEN TEXT = Required parameter |
IMPORTANT NOTE: Transfers started by async v1.3+ can be controlled from within the Enterprise Server (ES) / Connect Server (CS) GUI. Canceling an async transfer within ES or CS will shut down async.
Instance Options
| Short-form Option | Long-form Option | Description | Default Parameter |
|---|---|---|---|
| -h | --help | async command-line option help | |
| -A | --version | async version | |
| -D[D..] | Debug level | 0 | |
| -q | --quiet | Disable progress display | |
| -L LOCAL-LOG-DIR | --alt-logdir =LOG-DIR | Specify a logging directory on the local host. Note that you can specify a directory that doesn't exist and async will create it for you. | |
| --cooloff=SECS | Number of seconds to delay the start of the transfer. For example, when "--cooloff=5," async waits 5 seconds before copying a file. When "--cooloff=0" cool off is disabled; thus, transfers start immediately. Note that both peers get the same cooloff period. --cooloff is an instance option (i.e. it must appear before "-N"), where a permitted value is an integer between 0 and 60 seconds. | 3 | |
| watch-db=DB(HOST:PORT) | External DB used for input during continuous mode. | ||
| remote-watch-db=DB | DB used by the remote host. |
Session Options
| Short-form Option | Long-form Option | Description | Default Parameter | |
|---|---|---|---|---|
| -N PAIRNAME | --name=PAIRNAME | Synchronization pair name (which can be any string used to identify the
connection). This value will also be stored within the session cookie and can be
used in Aspera Console to identify the transfer session's name. IMPORTANT NOTE #1: "-N" must precede any combination of the options below. IMPORTANT NOTE #2: This option's argument can contain only ASCII alphanumeric, hyphen and underscore characters. |
||
| -n ACTION | --symbolic-links=ACTION |
Skip symbolic links. ACTION=skip IMPORTANT NOTE: When performing a sync from Linux to Windows, you must specify -n skip or --symbolic-links=skip; otherwise, you will receive an error. |
skip | |
| -d LDIR | --local-dir=LDIR | Set local file path. 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 remote file path. 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 IMPORTANT NOTE: DO NOT specify a remote (destination) directory that is located inside your source directory for a local synchronization. |
||
| --host=HOST |
Remote host's name. When option --host=HOST is given, the characters '@' and ':' are no longer treated specially in the argument to -r, so may appear in any such name. Note that if option --host=HOST is given, the remote-user name cannot be extracted from the argument to "--remote-dir", so must be supplied by a --user=NAME option or in the environment variable $USER (on Windows, %USER%). Thus, allowed forms are shown below. --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 | Remote user's name. When option --user=USER is given, the character '@' is no longer treated specially in the argument to -r, so may appear in any such name. | |||
| -w PASS | --pass=PASS | Set passphrase string | ||
| -i FILE | --private-key-path=FILE | SSH private key file. For information on creating a key pair, please refer to the topic Creating SSH Keys (Terminal). | ||
| -K DIRECTION | --direction=DIRECTION | Set transfer direction. DIRECTION=push, pull, bidi. | push | |
| -k CKSUMTYPE | --checksum=CKSUMTYPE | Set checksum type. CKSUMTYPE=sha1, md5, sha1-sparse, md5-sparse, none. CKSUMTYPE of none is equivalent to a size and modification-time check only. | sha1-sparse | |
| -P PORT | --tcp-port=PORT | Set the TCP port used 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 transfer rate policy. POLICY=fixed, fair, high, low | fair | |
| -l RATE | --target-rate=RATE | Set max transfer rate. RATE=integer G/g, M/m, K/k, bps. | 10,000 Kbps or 10 Mbps | |
| -m RATE | --min-rate=RATE | Set min transfer rate. RATE=integer G/g, M/m, K/k, bps. | 200 Kbps | |
| -g SIZE | --read-block-size=SIZE | Set block size for reading. SIZE=integer K, M, bytes. | 64 MB | |
| -G SIZE | --write-block-size=SIZE | Set block size using for writing. SIZE=integer K, M, bytes. | 64 MB | |
| -H VAL | --scan-intensity=VAL | VAL can be one of vlow, low, medium, high, vhigh. Sets intensity for scanning work. vlow minimizes system activity. vhigh maximizes system activity by continuously scanning files without rest. | medium | |
| -M | --no-scan-dir-rename | No directory rename detection on initial scan to prevent spurious conflicts on certain file system types. | ||
| -o RULE | --overwrite=RULE |
RULE= always, older, conflict.
IMPORTANT NOTE #1: You can easily resolve CONFLICT and ERROR situations in 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. IMPORTANT NOTE #2: -o/--overwrite=older will only be accurate if the user also specifies "preserve timestamps"(-t/--preserve-time) |
Conflict for -K bidi, otherwise always. | |
| -R R-LOG-DIR | --remote-logdir=R-LOG-DIR | 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=none, AES128 | aes128 | |
| -C | --continuous | Run continuous synchronization. If you encounter an inotify error when attempting to run continuous synchronization, please refer to the topic Error Troubleshooting. | one-time | |
| -t | --preserve-time | Preserve file timestamp. | 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. | off | ||
| -u | --preserve-uid | Preserve file owner's UID. Note that 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. Note that this preserve option requires that async is running as root (for Linux) or Administrator (for Windows). | off | |
| --write-uid=UID | Write files as User ID (UID). UID may be numeric, or by name. If by name, name is looked up on host actually performing the write. Failing to set the UID is logged, but is not an error. UID is set after ascp completes, and before moving the file from the staging directory to final location. Conflicts with --preserve-uid. | |||
| --write-gid=GID | Write files as Group ID (GID). GID may be numeric, or by name. If by name, name is looked up on host actually performing the write. Failing 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 final location. Conflicts with --preserve-gid. | |||
| -x | --reset | Clears the async snapshot database and re-scans the synchronized directories/files to create a fresh snapshot. | off | |
| -b PATH | --local-db-dir=PATH | Local database directory. Note that you may relocate the snapshot database to a different location than the default one under LDIR specified via -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 which does not support database locking reliably. Refer to the topic Multiple Databases (Snap DB) for usage. | Default snapshot directory is ~private-asp at the root level of the synchronized directory. | |
| -B PATH | --remote-db-dir=PATH | Remote database directory. Similar to -b above, but for the remote database. Refer to the topic Multiple Databases (Snap DB) for usage. | Default snapshot directory is ~private-asp at the root level of the synchronized directory. | |
| -I FILE | --include-from=FILE | Scan paths based on filter file. | ||
| -E FILE | --exclude-from=FILE | Skip paths based on filter file. | ||
| --include=PATTERN | Include paths that match the pattern. | |||
| --exclude=PATTERN | Exclude paths that match the 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 mostly used with uni-directional sync. In bi-directional sync, a deletion on one side will be "ignored," but the next time async is run, the file will be re-copied from the other end. In continuous mode, the file will not be re-copied until either async is restarted or the file is changed (i.e., "touched"). | |||
| --keep-dir-local=DIR | Move deleted files under DIR. Note that keep-dir-local must exist (i.e., it is not created by --create-dir), and must be outside of the synchronization directory, but on the same file system. | |||
| --keep-dir-remote=DIR | Move server's deleted files under DIR. Note that keep-dir-remote must exist (i.e., it is not created by --create-dir), and must be outside of the synchronization directory, but on the same file system. | |||
| --create-dir | Creates the remote directory if it does not exist. This option is used with the -d and -r options (async will create directories if they do not exist, rather than report an error and quit). | |||
| --inode-format=hash | Enables the SHA-1 virtual inode. | |||
| --dedup | Hardlinks are created on duplicate files (i.e., file deduplication) | |||
| --no-scan | Skip inital scanning |
IMPORTANT NOTE: When scanning or monitoring a file system for changes, async will now skip over files with names that end in one of the special suffixes specified in the configuration file, <resume_suffix> and <partial_file_suffix>. To disable this behavior, you may 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".