Ascp Command Reference

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.

Important: On Isilon IQ OneFS systems, last access time (atime) is disabled by default (see sysctl efs.bam.atime_enabled). You will see atime is set to be the same as mtime when using -p option. Use the command "sysctl efs.bam.atime_enabled=1" to enable the preservation of atime on your Isilon system.

Note: For Limelight, only the preservation of modification time (mtime) is supported.

• 0 – Always retransfer the entire file.
• 1 – Check file attributes and resume if the current and original attributes match.
• 2 – Check file attributes and do a sparse file checksum; resume if the current and original attributes/checksums match.
• 3 – Check file attributes and do a full file checksum; resume if the current and original attributes/checksums match.

Note that when a complete file exists at the destination (no .aspx), the source file size is compared with the destination file size. When a partial file and a valid .aspx file exist at the destination, the source file size is compared with the file size recorded inside the .aspx file.

Note: As of version 3.3, datagram size can also be enforced by the server using <datagram_size> in aspera.conf. If size is set with both -Z (client side) and <datagram_size> (server side), the <datagram_size> 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".

• * (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.

Important: If you do not specify a user name for the transfer, the local username will be authenticated (by default). 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.

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

Important: If --policy is not set, ascp uses the server-side policy setting (fair by default).

• src
• src2
• ...
• srcN

Use with URIs: The sources listed in the file list cannot be URIs. To use --file-list with cloud storage, you must specify the cloud storage with a URI in either a root, source prefix, or command-line destination parameter, subject to the limitations described above in Special Considerations for URI Paths.

Important: Multiple --file-list and --file-pair-list options are not supported in a single ascp 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.

• src1
• dst1
• src2
• dst2
• ...
• srcN
• dstN

Use with URIs: The sources and destinations listed in the file list cannot be URIs. To use --file-pair-list with cloud storage, you must specify the cloud storage with a URI in either a root, source prefix, or command-line destination parameter, subject to the limitations described above in Special Considerations for URI Paths.

Important: Multiple --file-list and --file-pair-list options are not supported in a single ascp 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-pair-list. Only files from the file-pair list will be transferred.

• follow – Follow symbolic links and transfer the linked files.
• copy – Copy only the alias file. If a file with the same name exists on the destination, the symbolic link will not be copied.
• copy+force – Copy only the alias file. If a file with the same name exists on the destination, the symbolic link will replace the file. If the file of the same name on the destination is a symbolic link to a directory, it will not be replaced.
• skip – Skip the symbolic links.

Move source files and copy source directories to archivedir after they are successfully transferred. Because directories are copied, the original source tree remains in place. 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.

Example upload:

ascp --move-after-transfer=C:\Users\Bob\Archive C:\Users\Bob\srcdir\file0012 bob@10.0.0.1:/

Result:

• file0012 is transferred to bob's docroot on 10.0.0.1
• file0012 is moved (not copied) from its original location to C:\Users\Bob\Archive

Example download:

ascp --move-after-transfer=Archive bob@10.0.0.1:/srcdir C:\Users\Bob

Result:

• srcdir is downloaded to C:\Users\Bob on the current machine.
• srcdir is moved (not copied) from its original location to the archive directory bob@10.0.0.1:/Archive on the server.

As with transfers, by default, no portion of the path above the transferred file or directory is included when the file or directory is moved to the archive (unless --src-base is specified).

The --src-base=prefix option preserves paths in the archive directory the same way as it preserves them with transfers. That is, when --src-base=prefix is specified, files are moved to the archivedir including the portion of the path that remains when prefix is removed.

Example:

ascp --src-base=C:\Users\Bob --move-after-transfer=C:\Users\Bob\Archive C:\Users\Bob\srcdir\file0012 bob@10.0.0.1:/

Result:

• file0012 is transferred to bob's docroot on 10.0.0.1. The file is transferred and includes the path minus the prefix — that is, to srcdir/file0012.
• file0012 is moved to C:\Users\Bob\Archive. The file is moved and includes the path minus the prefix — that is, to C:\Users\Bob\Archive\srcdir\file0012.

Once files have been moved to the archive, the original source directory tree remains intact. To remove empty source directories that remain after files have been moved, include the flag --remove-empty-directories on the command line. This removes empty source directories except for those that are specified as the source to transfer.

Restrictions:

• archivedir must be on the same file system as the source. If the specified archive is on a separate file system, it will be created (if it does not exist), but an error will be generated and files will not be moved to it. For cloud storage, archivedir must be in the same cloud storage account.
• archivedir is subject to the same docroot restrictions as the source.
• --remove-after-transfer and --move-after-transfer are mutually exclusive; including both in the same command generates an error.

Important: File manifests can only be stored locally. Thus, if you are using S3, or other non-local storage, you must specify a local manifest path.

• always – Always overwrite the file.
• never – Never overwrite the file. However, note that if the parent folder is not empty, its access, modify, and change times may still be updated.
• diff – Overwrite if file is different from the source (i.e., if a complete file exists at the destination (no .aspx file) and is the same as the source file, then leave it unmodified (no change on timestamp/attributes either); otherwise re-transfer the whole source file). Note this policy interacts with the resume policy.
• older – Overwrite if file is older than the source.

Important: When --overwrite=diff, you must also consider the resume policy (-k{0|1|2|3}). If -k0 (or no -k specified), the source and destination files are always deemed to be different, thereby implying always overwrite. If -k1, the source and destination files are compared based on file attributes (currently, just file size). If -k2, the source and destination files are compared based on sparse checksum. If -k3, the source and destination files are compared based on full checksum.

Note: This option requires that --partial-file-suffix also be enabled.

With the exception of --overwrite=never, specifying --overwrite with --save-before-overwrite has no affect. If --overwrite=never, any file that would be overwritten remains unchanged. If --overwrite is set to any other value, files that would be overwritten are renamed using the convention described above.

Note: This option only takes effect when it is set on the receiver side.

For example, the "clips" directory 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 within the "outgoing" folder (but not the "outgoing" folder, itself), run the following command:

> ascp -d --src-base=/clips/outgoing/ root@10.0.0.1:/clips/outgoing/ /incoming  

Result: The following folders and files appear in the "incoming" directory 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:

>  ascp -d root@10.0.0.1:/clips/outgoing/ /incoming  

Result:

(docroot)/incoming/outgoing/file1
(docroot)/incoming/outgoing/folderA/file2
(docroot)/incoming/outgoing/folderB/file3

>  ascp -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

For further examples, with and without --src-base, see Ascp File Manipulation Examples

Use with URIs

The --src-base option performs a character-to-character match with the source path specifying a file or directory. Hence for cloud storage, it is necessary that --src-base specify the URI in the same manner the source parameters are specified (for example, if the source includes and embedded passphrase, the source base must also include an embedded passphrase or it will not match the source files/directories).

Specify the address of the Aspera proxy server. proxy_url takes the form of:

dnat[s]://[username]@server:port

The default ports for DNAT and DNATS protocols are 9091 and 9092.

Note: This option requires the transfer user be authenticated as a superuser.

Note: This option requires the transfer user be authenticated as a superuser.