Aspera Command-Line Interface Guide 3.7.2

Mac OS X Revision: 3.7.2.138504 Generated: 01/24/2017 15:19 | Contents | 2

Contents

Introduction...... 3

System Requirements...... 4

Installation...... 5 Installing the Aspera CLI...... 5 Uninstalling...... 5

aspera: The Command-Line Transfer Client...... 6 About the Command-Line Client...... 6 Prerequisites...... 6 Configuring for Faspex...... 6 aspera Command Reference...... 7 faspex Command Reference...... 8 shares Command Reference...... 13 Faspex Examples...... 17 Shares Examples...... 18

ascp: Transferring from the Command Line...... 19 Ascp Command Reference...... 19 Ascp General Examples...... 30 Ascp File Manipulation Examples...... 31 Ascp Transfers to Cloud Storage...... 32 Applying Filters to Include and Exclude Files...... 34 Token Generation...... 36 Creating SSH Keys (Command Line)...... 38 Ascp FAQs...... 39

Transferring with ascp4...... 42 Introduction to A4...... 42 A4 Command Reference...... 42

Technical Support...... 49

Legal Notice...... 50 | Introduction | 3

Introduction

IBM Aspera Command-Line Interface (the Aspera CLI) is a collection of Aspera tools for performing high-speed, secure data transfers from the command line. The Aspera CLI is for users and organizations who want to automate their transfer workflows. The Aspera CLI is comprised of three command-line programs:

aspera The aspera executable is a command-line client for performing transfers with Aspera Faspex and Aspera Shares transfer servers. For further information on the aspera program, see aspera: The Command-Line Transfer Client on page 6

ascp The ascp executable is a command-line FASP transfer program. For information on the ascp program, see ascp: Transferring from the Command Line on page 19

ascp4 ascp4, or A4, is a FASP transfer program similar to ascp that has been optimized for sending large sets of individual files and can support UDP multicast through Aspera FASPStream. For information on A4, see Transferring with ascp4 on page 42. | System Requirements | 4

System Requirements

Mac OS X 10.7, 10.8, 10.9, 10.10, or 10.11.

Required Aspera Licenses • The Aspera CLI requires a Connect-enabled license on the transfer server. For detailed information on your transfer server's license file, see the Aspera Connect Server Admin Guide . • The Aspera CLI package includes a free client license. It or another valid aspera-license file must be present in the Aspera CLI installation directory. | Installation | 5

Installation

Installing the Aspera CLI

1. Download the Aspera CLI package from the Aspera website. 2. Run the installation script: aspera-cli-x.x.x.xxx.xxxxxxx-mac-xx.x-64-release.sh The script places the Aspera CLI in the $HOME/Library/Aspera directory. Note: If you have a previous installation of the aspera command-line client, note that the default installation directory has changed. 3. [Optional] To install the Aspera CLI in your PATH, run the following command:

$ export PATH=~/Applications/Aspera\ CLI/bin:$PATH 4. [Optional] To install the man pages, run the following command:

$ export MANPATH=~/Applications/Aspera\ CLI/share/man:$MANPATH 5. [Optional] To set an environment variable with the value of your password, to be used with all aspera client commands, run the following command:

$ export ASPERA_PASS=mypassword

Uninstalling

You can uninstall the Aspera CLI by deleting the installation directory with the following command:

$ rm -rf ~/Applications/Aspera \ CLI/ | aspera: The Command-Line Transfer Client | 6 aspera: The Command-Line Transfer Client

About the Command-Line Client

The aspera program is a client application that allows you to interact with Aspera Faspex and Aspera Shares transfer servers from the command line. The client provides the same data-transfer functionality as Faspex and Shares, in convenient commands that allow you to automate operations. For example, with the aspera client, you can automate the following: • Listing the contents of your Faspex inbox or Shares share. • Uploading to and downloading from your Shares server. • Sending Faspex packages using files from your local directories. • Sending files from remote storage sources, such as clusters or S3. • Downloading packages that are sent to you, to a local storage location.

Prerequisites

Certificates All aspera client operations perform certificate validation. The included certs directory (or your own certificate authority keys) must be located either in the parent directory of the aspera executable, or in a location that you specify through the -b command-line argument. If a transfer server does not have a valid certificate to allow the operation, you must specify the --insecure option.

Required Aspera Software The machine that runs the aspera client must have either an Aspera server or ascp (which is provided with this package) installed, in the same directory as the aspera executable -- in the PATH or in standard Aspera installation locations.

Configuring for Faspex

If you will use the command-line client to browse the contents of a remote directory through Faspex, you must configure the client after installation. The settings that affect the client with faspex browse reside in the following file:

.aspera_cli_conf In a text editor, edit the .aspera_cli_conf file to set the following: • server name • port • username • password • base directory | aspera: The Command-Line Transfer Client | 7

Configuration File Syntax The Aspera CLI package installs a .aspera_cli_conf file with sample configurations that you can use to see the correct syntax for this file.

Credentials in Your Configuration File The username and password credentials you set in the .aspera_cli_conf file should be the same as the credentials for the Node API user on your Faspex server (not host system credentials).

Defining Multiple Servers You can define multiple servers in the .aspera_cli_conf file, and multiple sources for each server. Then at the command line, you can specify which one to use, with the uid or name value that you defined in the configuration file. aspera Command Reference

Syntax All command sequences begin with the program name, aspera. The aspera program uses the following command syntax:

$ aspera command subcommand [arguments]

Commands The aspera program offers the following commands:

faspex use the Faspex application shares use the Shares application help view help information for a command version print the version number of this program

Faspex Subcommands The faspex command offers the following subcommands:

browse view the contents of a source directory dropbox show information about a dropbox get download package list show information about an inbox send send a package

For details on the Faspex subcommands, see faspex Command Reference on page 8

Shares Subcommands The shares command offers the following subcommands:

upload upload files or directories to a Shares server | aspera: The Command-Line Transfer Client | 8

download download files or directories from a Shares server browse browse a directory of a Shares server delete delete a file or directory rename rename a file or directory

For details on the Shares subcommands, see shares Command Reference on page 13

Getting Help The aspera program also offers a help command that can explain any command in more detail, and provide you with sample use cases. To view the help, type the following:

$ aspera help [faspex|shares] To view the help for a particular subcommand, the syntax is as follows:

$ aspera [faspex|shares] help subcommand For example, to see the options for the Faspex send command, type the following:

$ aspera faspex help send

Finding the Software Version Number To see the version of the aspera client that is installed, type the following:

$ aspera version faspex Command Reference

Faspex Subcommands The faspex command offers the following subcommands:

browse view the contents of a source directory dropbox show information about a dropbox get download a package list show information about an inbox send send a package

For examples of Faspex subcommands in use, see Faspex Examples on page 17

The browse Subcommand Use the browse subcommand to browse a remote source that is defined in the .aspera_cli_conf file. The syntax for browse is as follows:

$ aspera faspex browse [args] | aspera: The Command-Line Transfer Client | 9

The arguments you give to the browse subcommand specify the remote source by source ID name, and the directory you want to browse. The output shows a list of the directories and files, in human-readable format. If you prefer to retrieve the output in JSON format for integration into your automation workflow, use the -j parameter.

-cnum List only up to num items. --count=num

-j Output raw JSON. --json

-ppath The path to the source you want to view. This path is relative to the path you specified in .aspera_cli_conf. --path=path

-knum Skip the first num items. --skip=num

-oorder Sort by order (required). The options for order are as follows: --sort=order • type = sort directories first, then files • size_a = sort by file size (ascending) • size_d = sort by file size (descending) • mtime_a = sort by file modification time (ascending) • mtime_d = sort by file modification time (descending)

-sid/name The ID or name of the source server (a matching ID takes precedence over a matching name), as defined in the .aspera_cli_conf configuration file. --source=id/name

-v Show more verbose output, for debugging. --verbose

-bpath The base path for your CA certificates. If your certificates are in the default location, this argument is not required. The default path is ~/.aspera/cli/certs. --base-ca-path=path

The dropbox Subcommand Use the dropbox subcommand to show information about dropboxes. The syntax for dropbox is as follows:

$ aspera faspex dropbox [args] Arguments for the dropbox subcommand:

-i Accept the certificate, even if it's invalid. ---insecure

-j Output raw JSON. --json

-ldropbox-id Show info for this dropbox only. --list=dropbox-id The dropbox-id is defined in the Faspex application.

-a Show info for all dropboxes. --list-all | aspera: The Command-Line Transfer Client | 10

-p[password] The Faspex user password. --password=[password] If you specify -p but omit the password value, the system assumes an empty string for this value. If you do not specify -p, the Aspera CLI prompts you for a non-echoing password. Alternatively, you can set the ASPERA_PASS environment variable.

-uusername The Faspex username. --user=username

-v Show more verbose output, for debugging. --verbose

-bpath The base path for your CA certificates. If your certificates are in the default location, this argument is not required. The default path is ~/.aspera/cli/certs. --base-ca-path=path

The get Subcommand Use the get subcommand to download a Faspex package. The syntax for get is as follows:

$ aspera faspex get [args] Arguments for the get subcommand:

-f path The file path to download to. ---file path

-i Accept the certificate, even if it's invalid. ---insecure

--url="URL" The FASP URL from which to download. To find the FASP URL for a package, use the list subcommand.

-p[password] The Faspex user password. --password=[password] If you specify -p but omit the password value, the Aspera CLI assumes an empty string for this value. If you do not specify -p, the Aspera CLI prompts you for a non-echoing password. Alternatively, you can set the ASPERA_PASS environment variable.

-uusername The Faspex username. --user=username

-v Show more verbose output, for debugging. --verbose

--target-rate newRate Attempt to revise the target rate (if server settings allow) to a new throughput value, in kbps. --min-rate newRate Attempt to revise the minimum rate (if server settings allow) to a new throughput value, in kbps. | aspera: The Command-Line Transfer Client | 11

--rate-policy policy Attempt to revise the rate policy (if server settings allow). The options for policy are fixed, high, fair, or low. --cipher cipher Attempt to set the encryption cipher (if server settings allow). The options for cipher are aes-128, aes-192, aes-256, and none. -bpath The base path for your CA certificates. If your certificates are in the default location, this argument is not required. The default path is ~/.aspera/cli/certs. --base-ca-path=path

The Faspex list Subcommand Use the list subcommand to see the contents of a user's inbox. The syntax for list is as follows:

$ aspera faspex list [args] Arguments for the list subcommand:

-a List archived packages. ---archived

-n List the packages in the inbox. ---inbox

-i Accept the certificate, even if it's invalid. ---insecure

-p[password] The Faspex user password. --password=[password] If you specify -p but omit the password value, the Aspera CLI assumes an empty string for this value. If you do not specify -p, the Aspera CLI prompts you for a non-echoing password. Alternatively, you can set the ASPERA_PASS environment variable.

-s List sent packages. ---sent

-uusername The Faspex username. --user=username

-v Show more verbose output, for debugging. --verbose

-x Get raw XML RSS atom for this inbox. --xml Note: As the format returned with this option is XML, if you want to download a package referenced in a link tag, make sure that you un-escape the returned XML value in the href= attribute.

-bpath The base path for your CA certificates. If your certificates are in the default location, this argument is not required. The default path is ~/.aspera/cli/certs. --base-ca-path=path | aspera: The Command-Line Transfer Client | 12

The send Subcommand Use the send subcommand to send a Faspex package. The syntax for send is as follows:

$ aspera faspex send [args] Arguments for the send subcommand:

-f path The file to send. You can specify this option multiple times, to indicate multiple files. ---file path

-i Accept the certificate, even if it's invalid. ---insecure

-m metadata Send metadata (JSON object text) with the package. ---metadata metadata

-n "bodyText" A note for the body of the email message. ---note "bodyText"

-p[password] The Faspex user password. --password=[password] If you specify -p but omit the password value, the Aspera CLI assumes an empty string for this value. If you do not specify -p, the Aspera CLI prompts you for a non-echoing password. Alternatively, you can set the ASPERA_PASS environment variable.

-rrecipient Recipient(s) of the package. You can specify this option multiple times, to indicate multiple recipients. The recipient can be a valid email address, a --recipient=recipient Faspex user account name, a Faspex dropbox name, or a workgroup. -sID Send a file from a source ID (as defined in the Faspex application). --source-id=ID

-ttitleText A title (subject line) for the email message. --title=titleText

-uusername The Faspex username. --user=username

-v Show more verbose output, for debugging. --verbose

--target-rate newRate Attempt to revise the target rate (if server settings allow) to a new throughput value, in kbps. --min-rate newRate Attempt to revise the minimum rate (if server settings allow) to a new throughput value, in kbps. --rate-policy policy Attempt to revise the rate policy (if server settings allow). The options for policy are fixed, high, fair, or low. --cipher cipher Attempt to set the encryption cipher (if server settings allow). The options for cipher are aes-128, aes-192, aes-256, and none. | aspera: The Command-Line Transfer Client | 13

-bpath The base path for your CA certificates. If your certificates are in the default location, this argument is not required. The default path is ~/.aspera/cli/ --base-ca-path=path certs. shares Command Reference

Shares Subcommands The shares command offers the following subcommands:

upload upload files or directories to a Shares server download download files or directories from a Shares server browse browse a directory of a Shares server delete delete a file, directory, or share rename rename a file or directory

For examples of Shares subcommands in use, see Shares Examples on page 18

The upload Subcommand Use the upload subcommand to upload content to a Shares server. The syntax for upload is as follows:

$ aspera shares upload [args] Arguments for the upload subcommand:

-i Accept the certificate, even if it's invalid. ---insecure

-Hhost The Shares host name. --host=host

-spath File path to the source of the content you are uploading. --source=path

-dpath Destination directory path (with the format /shareName/relativePathTo/fileOrFolder). --destination=path

-ccookieString Cookie, if one is required. --cookie=cookieString

-p[password] The Shares user password. --password=[password] If you specify -p but omit the password value, the Aspera CLI assumes an empty string for this value. If you do not specify -p, the Aspera CLI prompts you for a non-echoing password. Alternatively, you can set the ASPERA_PASS environment variable.

-uusername The Shares username. | aspera: The Command-Line Transfer Client | 14

--user=username

-v Show more verbose output, for debugging. --verbose

-bpath The base path for your CA certificates. If your certificates are in the default location, this argument is not required. The default path is ~/.aspera/cli/certs. --base-ca-path=path

The download Subcommand Use the download subcommand to download content from a Shares server. The syntax for download is as follows:

$ aspera shares download [args] Arguments for the download subcommand:

-i Accept the certificate, even if it's invalid. ---insecure

-Hhost The Shares host name. --host=host

-spath File path to the source of the content you are downloading (with the format /shareName/relativePathTo/fileOrFolder). --source=path

-dpath Destination directory path (the default is ./). --destination=path

-ccookieString Cookie, if one is required. --cookie=cookieString

-p[password] The Shares user password. --password=[password] If you specify -p but omit the password value, the Aspera CLI assumes an empty string for this value. If you do not specify -p, the Aspera CLI prompts you for a non-echoing password. Alternatively, you can set the ASPERA_PASS environment variable.

-uusername The Shares username. --user=username

-v Show more verbose output, for debugging. --verbose

-bpath The base path for your CA certificates. If your certificates are in the default location, this argument is not required. The default path is ~/.aspera/cli/certs. --base-ca-path=path | aspera: The Command-Line Transfer Client | 15

The browse Subcommand Use the browse subcommand to see what content is on a Shares server. The syntax for browse is as follows:

$ aspera shares browse [args] Arguments for the browse subcommand:

-cnum List only up to num items. --count=num

-i Accept the certificate, even if it's invalid. ---insecure

-j Output raw JSON. --json

-Hhost The Shares host name. --host=host

-Ppath The Shares remote path (the default is /; or use the format /shareName/relativePathTo/fileOrFolder). --path=path

-knum Skip the first num items. --skip=num

-oorder Sort by order. The options for order are as follows: --sort=order • type = sort directories first, then files • size_a = sort by file size (ascending) • size_d = sort by file size (descending) • mtime_a = sort by file modification time (ascending) • mtime_d = sort by file modification time (descending)

-p[password] The Shares user password. --password=[password] If you specify -p but omit the password value, the Aspera CLI assumes an empty string for this value. If you do not specify -p, the Aspera CLI prompts you for a non-echoing password. Alternatively, you can set the ASPERA_PASS environment variable.

-uusername The Shares username. --user=username

-v Show more verbose output, for debugging. --verbose

-bpath The base path for your CA certificates. If your certificates are in the default location, this argument is not required. The default path is ~/.aspera/cli/certs. --base-ca-path=path | aspera: The Command-Line Transfer Client | 16

The delete Subcommand Use the delete subcommand to delete content from a Shares server. The syntax for delete is as follows:

$ aspera shares delete [args] Arguments for the delete subcommand:

-i Accept the certificate, even if it's invalid. ---insecure

-j Output raw JSON. --json

-Hhost The Shares host name. --host=host

-Ppath The path to the remote file or directory to be deleted (with the format /shareName/relativePathTo/fileOrFolder). --path=path

-p[password] The Shares user password. --password=[password] If you specify -p but omit the password value, the Aspera CLI assumes an empty string for this value. If you do not specify -p, the Aspera CLI prompts you for a non-echoing password. Alternatively, you can set the ASPERA_PASS environment variable.

-uusername The Shares username. --user=username

-v Show more verbose output, for debugging. --verbose

-bpath The base path for your CA certificates. If your certificates are in the default location, this argument is not required. The default path is ~/.aspera/cli/certs. --base-ca-path=path

The rename Subcommand Use the rename subcommand to rename content on a Shares server. The syntax for rename is as follows:

$ aspera shares rename [args] Arguments for the rename subcommand:

-i Accept the certificate, even if it's invalid. ---insecure

-j Output raw JSON. --json

-Hhost The Shares host name. --host=host | aspera: The Command-Line Transfer Client | 17

-Ppath The remote path to the content you are renaming (with the format /shareName/relativePathTo/fileOrFolder). --path=path

-spath The remote file or directory you are renaming. --source=path

-dpath The new name for the file or directory. --destination=path

-p[password] The Shares user password. --password=[password] If you specify -p but omit the password value, the Aspera CLI assumes an empty string for this value. If you do not specify -p, the Aspera CLI prompts you for a non-echoing password. Alternatively, you can set the ASPERA_PASS environment variable.

-uusername The Shares username. --user=username

-v Show more verbose output, for debugging. --verbose

-bpath The base path for your CA certificates. If your certificates are in the default location, this argument is not required. The default path is ~/.aspera/cli/certs. --base-ca-path=path

Faspex Examples

List the contents of a remote source (in this example, 22). You can then use the results to send packages with contents from that remote source.

$ aspera faspex browse --sort=type --source=22 -p/Datasheets Send a Faspex package containing a file named test_file in the current directory to recipient at host.com. This command contacts the Faspex server at https://host.com and logs in as the user myusername with the password mypassword. When the recipient receives the email, the subject line "File 4 U" will identify this package.

$ aspera faspex send -f test_file -n"This is a note for a Faspex package sent with the command-line client" -t"File 4 U" -r"recipient" -H"host.com" -umyusername -pmypassword Send a Faspex package containing a file called test_file from a remote source. This command contacts the Faspex server at https://host.com and logs in as the user myusername with the password mypassword. When the recipient receives the email, the subject line "File 4 U" will identify this package.

$ aspera faspex send -f test_file --source=22 -n"This is a note for a Faspex package sent with the command-line client" -t"File 4 U" -r"recipient" - H"host.com" -umyusername -pmypassword Download the specified package based on the faspe:// URL that the Faspex list commmand returns.

$ aspera faspex get -umyusername -H"myhost.com" -pmypassword -- url="faspe://..." | aspera: The Command-Line Transfer Client | 18

List the packages in a user's inbox, in short format.

$ aspera faspex list -umyusername -H"myhost.com" -pmypassword -n List the packages in a user's inbox, in XML (RSS) format. Note: As the format returned with the -x option is XML, if you want to download a package referenced in a link tag, make sure that you un-escape the returned XML value in the href= attribute.

$ aspera faspex list -umyusername -H"myhost.com" -pmypassword -n -x

Shares Examples

Uploading a File Upload local_file to the destination directory using the user with a username of username and a password of password and host 123.45.67.89.

$ aspera shares upload -i --host=123.45.67.89 -uusername -ppassword -- source=./local_file --destination=/upload_share/incoming

Downloading a File Download Bytestream-Sender-Receiver.mov to the local destination local_dir using the user with a username of username and a password of password and host 123.45.67.89.

$ aspera shares download -i --host=123.45.67.89 -uusername -ppassword --source=/download_share/outgoing/Bytestream-Sender-Receiver.mov -- destination=./local_dir

Browsing a Server Browse the test_share on the server 123.45.67.89 using the user with a username of username and a password of password to authenticate.

$ aspera shares browse -i --host=123.45.67.89 -uusername -ppassword --path=/ test_share

Renaming a File Rename the file oldName.mov to newName.mov on the host 123.45.67.89 using the user with a username of username and a password of password to authenticate.

$ aspera shares rename -i --host=123.45.67.89 -uusername -ppassword --path=/ test --source=/outgoing/oldName.mov --destination=/outgoing/newName.mov

Deleting a File Delete the file /test/file on the host 123.45.67.89 using the user with a username of username and a password of password to authenticate.

$ aspera shares delete -i --host=123.45.67.89 -uusername -ppassword --path=/ test/file | ascp: Transferring from the Command Line | 19 ascp: Transferring from the Command Line

Ascp Command Reference

The executable ascp (Aspera secure copy) is a command-line FASP transfer program. The tables below describe the complete command usage, including general syntax guidelines, supported environment variables, a synopsis, and command options.

General Syntax Guidelines

Item Decription symbols used in the paths Use single-quote (' ') and forward-slashes (/) on all platforms.

Characters to avoid / \ " : ' ? > < & * |

Environment Variables

If needed, you can set the following environment variables for use with the ascp command: Item Initiation Command

Password ASPERA_SCP_PASS=password Token ASPERA_SCP_TOKEN=token Cookie ASPERA_SCP_COOKIE=cookie Content Protection Password ASPERA_SCP_FILEPASS=password Proxy Server Password ASPERA_PROXY_PASS=proxy_server_password

Ascp Usage

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

For examples of ascp commands, see Ascp General Examples on page 30. Important: If you do not specify a username 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 (for example, authenticating Administrator, rather than DOMAIN\Administrator). Thus, you will need to specify a domain explicitly, if applicable to the user.

Special Considerations for URI Paths URIs are supported in paths, but only under the following restrictions: • URIs can only be specified on the command line. • If source paths are specified with a URI, all source paths specified on the command line must be from the same cloud storage account, and all must include URIs. • If source paths are specified with a URI, no docroot (download), local docroot (upload), or source prefix can be specified. • If a destination path is specified with a URI, no docroot (upload) or local docroot (download) can be specified. • The special schemes stdio:// and stdio-tar:// are supported on the client only. Usage as a destination (upload) or source (download) is undefined. | ascp: Transferring from the Command Line | 20

• If required, URI passphrases can either be embedded in the URI or specified with the applicable environment variable ASPERA_SRC_PASS or ASPERA_DST_PASS.

Transfer Testing with Minimal Storage Requirements

For ascp transfer testing purposes, you can use a faux:// argument in place of the source file and target path to send random data and not write it to disk at the destination. For more information, see IBM Aspera Enterprise Server Admin Guide: Testing and Optimizing Transfer Performance. For examples, see Ascp General Examples on page 30.

Ascp Options

Option Description

-h, --help Display usage. -A, --version Display version and license information; then exit. -T Disable encryption for maximum throughput. -c Specify the encryption cipher for file data. Options are aes128, aes192, aes256, or none. This overrides the setting for transport_cipher in aspera.conf. -d Create target directory if it doesn't already exist. -q Quiet mode (to disable progress display). -v Verbose mode (prints connection and authentication debug messages in the log file). For information on log files, see IBM Aspera Enterprise Server Admin Guide: Log Files.

-6 Enable IPv6 address support. When using IPv6, the numeric host can be written inside brackets. For example, [2001:0:4137:9e50:201b:63d3:ba92:da] or [fe80::21b:21ff:fe1c:5072%eth1]. -D | -DD | -DDD Specify the debug level, where each D is an additional level of debugging. -l max_rate Set the target transfer rate in Kbps (default: 10000 Kbps). If the ascp client does not specify a target rate, it will be acquired from aspera.conf (server-side, as the local aspera.conf target rate setting doesn't apply). If local or server aspera.conf rate caps are specified, the "starting" (default) rates will be not higher than the cap.

-m min_rate Set the minimum transfer rate in Kbps (efault: 0. If the ascp client does not specify a minimum rate, it will be acquired from aspera.conf (server-side, as the local aspera.conf minimum rate setting doesn't apply). If local or server aspera.conf rate caps are specified, the "starting" (default) rates will be not higher than the cap.

-u user_string Apply a user string, such as variables for pre- and post-processing. -i private_key_file Use public key authentication and specify the SSH private key file. Typically, the private key file is in the directory $HOME/.ssh/id_algorithm. Multiple private key files can be specified using multiple -i arguments. The keys are tried in order and the process ends when a key passes authentication or when all keys have been tried and authentication fails.

-w{r|f} Test bandwidth from server to client (r) or client to server (f). Currently a beta option. -K probe_rate Set probing rate (Kbps) when measuring bottleneck bandwidth. (Default: 100Kbps) -k {0|1|2|3} Enable resuming partially transferred files at the specified resume level (default: 0). This must be specified for your first transfer; otherwise, it will not work for subsequent transfers. Resume levels: | ascp: Transferring from the Command Line | 21

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

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.

-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 the server using in aspera.conf. If size is set with both -Z (client side) and (server side), the 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 . 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".

-g read_size Set the read-block size, in bytes. A read_size of 1M is 1 MB. The maximum block size is 500 MB. The default of 256K causes the Aspera sender to use its default internal buffer size. This is a performance-tuning parameter for an Aspera sender, which takes effect only if the sender is a server. It specifies the maximum number of bytes that can be stored within a block as the block is transferred from the source disk to the receiver. This option overrides the client's configuration file setting for this feature if set. The server uses its configuration file setting for this feature if it's set, otherwise it uses read_size if set; however, it does not use settings in the client configuration file.

-G write_size Set the write-block size, in bytes. A write_size of 1M is 1 MB. The maximum block size is 500 MB. The default of 256K causes the Aspera receiver to use its default internal buffer size. This is a performance-tuning parameter for an Aspera receiver, which takes effect only if the receiver is a server. It specifies the maximum number of bytes within a block that an ascp receiver can write to disk. This option overrides the client's configuration file setting for this feature if set. The server uses its configuration file setting for this feature if it's set, otherwise it uses write_size if set; however, it does not use settings in the client configuration file.

-L local_log_dir[:size] Specify a logging directory in the local host, instead of using the default directory. Optionally set the size of the log file (default 10 MB).

-R remote_log_dir Specify a logging directory in the remote host, instead of using the default directory. -S remote_ascp Specify the name of the remote ascp binary (if different). -e prepost Specify an alternate pre/post command. Use the complete path and file name. -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) | ascp: Transferring from the Command Line | 22

Option Description

-C nid:ncount Enable multi-session transfers (also known as parallel transfers) on a multi-node/ multi-core system. Specify the node ID (nid) and count (ncount) in the format 1:2, 2:2. The valid range of values for nid and ncount is 1-128, and nid must be less than or equal to ncount. Assign each participant to an independent UDP port. Large files can be split across sessions, see --multi-session-threshold.

-E pattern Exclude (-E) or include (-N) files or directories from the transfer using the specified pattern. This option can be used multiple times to exclude/include many patterns. -N pattern Up to 16 -E and -N patterns can be used. The following two symbols can be used in specifying the pattern:

• A "*" (asterisk) represents zero or more characters in a string. For example *.tmp matches .tmp and abcde.tmp. • A "?" (question mark) represents a single character. For example t?p matches tmp but not temp. Rules are applied in the order in which they are encountered, with the first rule taking precedence. For details on specifying rules, see Applying Filters to Include and Exclude Files on page 34.

--exclude-newer- Exclude files from the transfer based on when the file was last changed. This feature than=mtime does not include directories. --exclude-older- than=mtime

-f config_file Specify an alternate Aspera configuration file (default is aspera.conf). -W token_string Specify the token string for the transfer. - Transfer only part of a file. This option only works when downloading a single @[range_low:range_high] file and does not support resuming. The argument to "-@" may omit either or both numbers, and the ":" delimiter. For example, -@3000:6000 transfers bytes from position 3000 to position 6000; -@1000: transfers from 1000 to the end of the file; and -@:1000 transfers from beginning to 1000. -X rexmsg_size Adjust the maximum size in bytes of a retransmission request. (Max: 1440). --mode=mode Specify the transfer direction, where mode is either send or recv. Requires -- host. --user=username The user name to be authenticated by the transfer server. 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.

--host=hostname The server's address. Requires --mode. --keepalive Run ascp in persistent mode. Requires --mode and --host. --save-before- Saves a copy of an existing file if a transfer would overwrite overwrite the file. If the filename is filename.ext, the file is saved as filename.yyyy.mm.dd.hh.mm.ss.index.ext (where index is set to 1 at the beginning of each second and incremented for each file saved during the same second) in the same directory before the new file is written. File attributes are maintained in the renamed file. | ascp: Transferring from the Command Line | 23

Option Description

--policy=fixed | Set the FASP transfer policy. high | fair | low • 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).

--source- Add prefix to the beginning of each source path. This can be either a conventional path prefix=prefix or a URI; however, it can only be a URI if there is no root defined. --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. Special care must be taken when using this option with cloud storage. 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 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/ [email protected]:/ clips/outgoing/ /incoming Result: The following folders and files appear in the "incoming" directory at the destination. Files outside of the source base (for example, /temp/file4) are not transferred, and warnings are generated.

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

If the same transfer is run without --src-base=/clips/outgoing/, then the following folders and files appear at the destination:

(docroot)/incoming/outgoing/file1 (docroot)/incoming/outgoing/folderA/file2 (docroot)/incoming/outgoing/folderB/file3 | ascp: Transferring from the Command Line | 24

Option Description 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).

--file-list=filename Extract a list of sources to transfer from filename. The file list supports UTF-8 files and input from standard input through "-". If the sources are URIs, the list file should not exceed 24kb. The sources can exist on either the local host or the remote host (for download), but not on both. Each source must be specified on a separate line, for example: src src2 ... srcN

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. If --file-list or --file-pair-list is used, you cannot also include file names on the command line; only files from the file list will be transferred.

--file-pair- Extract a list of sources and corresponding destinations from filename. There is no list=filename command-line equivalent for specifying file pairs. If the sources or destination are URIs, the list file should not exceed 24kb. Each source and each destination must be specified on a separate line: src1 dst1 src2 dst2 ... srcN dstN

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. If --file-list or --file-pair-list is used, you cannot also include file names on the command line; only files from the file list will be transferred.

--dest64 Indicate that the destination is base64 encoded. --source- Indicate that the specified source prefix is base64 encoded. If a non-encoded source prefix64=prefix prefix is also specified on the command line, the later argument takes precedence. --symbolic- Specify the rule to handle symbolic links. This option takes following values: links=method (Default: follow) . • 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. | ascp: Transferring from the Command Line | 25

Option Description • 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. Important: On Windows, the only option is skip.

--remove-after- Remove all source files (excluding the source directory) after they are successfully transfer transferred. Requires write permissions on the source. --move-after- Move source files and copy source directories to archivedir after they are successfully transfer=archivedir transferred. Requires write permissions on the source and the archivedir. 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\Pat\Archive C: \Users\Pat\srcdir\file0012 [email protected]:/ Results:

• file0012 is uploaded to Pat's docroot on 10.0.0.1, the server (destination). • On the current machine (source), file0012 is moved (not copied) to C:\Users \Pat\Archive Example download:

$ ascp --move-after-transfer=Archive [email protected]:/ srcdir C:\Users\Pat Results:

• srcdir is downloaded to C:\Users\Pat on the current machine (destination). • On the server (source), srcdir is moved (not copied) to the archive directory [email protected]:/Archive. When the file or directory is moved to the archive, no portion of the path above the transferred file or directory is included, unless the --src-base option is specified. The --src-base=prefix option preserves paths in the archive directory the same way it preserves them with transfers. That is, when --src-base=prefix is specified, files are moved to the archivedir and they include the portion of the path that remains when prefix is removed. Example:

$ ascp --src-base=C:\Users\Pat --move-after-transfer=C: \Users\Pat\Archive C:\Users\Pat\srcdir\file0012 [email protected]:/ Results:

• file0012 is uploaded to Pat's docroot on 10.0.0.1. The file includes the path minus the prefix C:\Users\Pat — that is, srcdir/file0012. • On the current machine (source), file0012 is moved to C:\Users\Pat \Archive. The file includes the path minus the prefix C:\Users\Pat — that is, C:\Users\Pat\Archive\srcdir\file0012. | ascp: Transferring from the Command Line | 26

Option Description 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, add the flag --remove-empty-directories to the ascp command. 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. • Empty directories are not saved to archivedir.

--remove-empty- Remove empty source directories once the transfer has completed (not including a directories directory specified as the source to transfer). Do not use if multiple processes (ascp or other) might access the source directory at the same time.

--remove-empty- Remove the source directory argument itself (for use with --remove-empty- source-directory directories). --skip-special- Skip special files (for example, devices and pipes). files --file- Generate a list of all transferred files, where output is none or text (Default: none) manifest=output --file-manifest- Specify the path to the file manifest. directory path= 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.

--file-manifest- Specify the suffix of the file manifest's temporary file. (Default: .aspera- inprogress- inprogress) suffix=suffix --precalculate- Calculate total size before transfer. The server side aspera.conf setting overrides job-size the ascp command-line option. --overwrite=method Overwrite destination files with source files of the same name. This option takes the following values (Default: diff): • never – Never overwrite the file. However, if the parent folder is not empty, its access, modify, and change times may still be updated. • always – Always overwrite the file. • diff – Overwrite the file if it is different from the source. If a complete file at the destination is the same as the source then it will not be overwritten. Partial files will be overwritten or resumed depending on the resume policy. • diff+older – Overwrite the file if it is older and different than the source. • older – Overwrite the file if its timestamp is older than the source timestamp. Important: If the overwrite method is diff or diff+older, difference is determined by the resume policy (-k{0|1|2|3}). If -k 0 or no -k is specified, the source and destination files are always considered different and the destination file is always overwritten. If -k 1, the source and destination files are compared based on file attributes (currently file size). If -k 2, the source and destination files are | ascp: Transferring from the Command Line | 27

Option Description compared based on sparse checksum. If -k 3, the source and destination files are compared based on full checksum.

--file-crypt=crypt Encrypt or decrypt files for client-side encryption-at-rest (EAR). Valid values are encrypt and decrypt. Set the passphrase (required) with the environment variable ASPERA_SCP_FILEPASS. Encrypted files have the file extension .aspera-env. If a client-side encrypted file is downloaded with an incorrect password, the download is successful but the file is still encrypted and still has the file extension .aspera- env. --file- Report checksums for transferred files, where hash is sha1, md5, sha-512, checksum=hash sha-384, sha-256 or none. (Default: none) --retry- Specify the timeout duration in seconds for a retry attempt. timeout=secs --partial-file- Filename extension on the destination computer while the file is being transferred. suffix=suffix Once the file has been completely transferred, this filename extension will be removed. (Default: blank) Note: This option only takes effect when it is set on the receiver side.

--proxy=proxy_url 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.

--preserve-file- (OS X and Linux/UNIX systems only.) Preserve transferred files' owner information owner-uid (uid). Note: This option requires the transfer user be authenticated as a superuser.

--preserve-file- (OS X and Linux/UNIX systems only.) Preserve transferred files' group information owner-gid (gid). Note: This option requires the transfer user be authenticated as a superuser.

Preserve creation time [Windows only]: Set the file/directory creation time at the --preserve- destination to that of the source. If the destination is a non-Windows host, this option creation-time is ignored. (Note: Do not confuse this with UNIX ctime, which represents "change --preserve- time", indicating the time when metadata was last updated.) modification-time --preserve-access- Preserve modification time: Set the file/directory modification time at the destination time to that of the source. --preserve-source- Preserve access time: Set the file/directory access time (the last time the file was read access-time or written) at the destination to that of the source. This results in the destination file -p having the access time that the source file had prior to the copy operation. The act of copying the source file to the destination results in an update to the source file's access time. Preserve source access time: Restore the access time of the file at the source once the copy operation is complete (because the file system at the source regards the transfer operation as an access).

-p is equivalent to setting --preserve-modification-time and -- preserve-access-time (and --preserve-creation-time, on Windows). | ascp: Transferring from the Command Line | 28

Option Description On Windows, modification time 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. Cloud storage support for timestamp settings depends on the cloud storage implementation. See the documentation for your cloud storage option to determine which of these settings are supported.

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

--ignore-host-key If you are prompted to accept a host key when connecting to a remote host, ascp ignores the request.

--check- Check whether fingerprint matches the server SSH host key fingerprint specified sshfp=fingerprint in the server's aspera.conf. Aspera fingerprint convention is to use a hex string without the colons; for example, f74e5de9ed0d62feaf0616ed1e851133c42a0082. Note: When the HTTP fallback feature is enabled and the client "falls back" to HTTP, this option enforces server SSL certificate validation (HTTPS). Validation fails if the server has a self-signed certificate; a properly signed certificate is required.

--apply-local- Apply the local docroot. This option is equivalent to setting the environment variable docroot ASPERA_SCP_DOCROOT. --multi-session- This option augments the -C option, which enables multi-session transfers (also threshold=threshold known as parallel transfers). With the threshold option, if the size of the files to be transferred is greater than or equal to threshold, files will be split across multiple sessions. If the total file size is less than the threshold or no threshold is set (default), files are not split. The client node API can specify the multi-session-threshold, and this will be passed to the ascp command line. If the client doesn't specify a value, then the multi_session_threshold_default is taken from the server. A default value for the threshold can be specified in aspera.conf by setting multi_session_threshold_default. Setting it to 0 (zero) means "do not split". The command-line setting overrides the aspera.conf setting. Note: For cloud transfers, file-splitting is currently (3.6.0) supported for S3 only. Multi-session uploads to cloud storage:Currently only supported for S3. Unlike non- cloud file splitting, files for transfer to cloud storage are sent in chunks, with the chunk size is specified by in aspera.conf:

. . . 0 File-splitting needs to respect a minimum split size, which for cloud storage is a part, such that each ascp call must deliver full parts. Thus, the chunk size must be equal to the cloud-storage part size. If the file size is greater than the multi-session threshold but smaller than the chunk size, then the file is not split. Set chunk size and part size as follows: | ascp: Transferring from the Command Line | 29

Option Description 1. In aspera.conf set the chunk size to some value greater than 5 MB (the minimum part size), for example:

67108864 2. In /opt/aspera/etc/trapd/s3.properties set the upload part size (default 64 MB) to the same value as the chunk size and set a ONE_TO_ONE gathering policy:

aspera.transfer.upload.part-size=64MB aspera.transfer.gathering-policy=ONE_TO_ONE

--delete-before- Delete files that exist at the destination but not at the source, before any files are transfer transferred. Requires write permissions on the destination. Do not use with multiple sources, keepalive, URI storage, or HTTP fallback. The utility asdelete provides the same capability. Preserve extended attributes (xattrs) and/or access control lists (ACLs) when --preserve- mode transferring files between different types of file systems. mode can be native, xattrs= , or (default): --remote-preserve- metafile none xattrs=mode native xattrs and ACLs are preserved using native capabilities of the --preserve- file system. However, this storage mode is not supported on all acls=mode file systems. --remote-preserve- mode acls= metafile xattrs and ACLs for a file (say, readme.txt) are preserved in a second file, whose name is composed of the name of the primary file with .aspera-meta appended to it; for example, readme.txt.aspera-meta. The Aspera metafiles are platform independent and can be copied between hosts without loss of information. This storage mode is supported on all file systems.

none xattrs and ACLs are not preserved. This storage mode is supported on all file systems. The modes of preserving xattrs and ACLs on each side of the transfer will end up being the same, even if specified differently. In this case, the metafile mode takes precedence, silently.

The options with the remote- prefix specify the storage mode used on the remote file system. If not specified, the default behavior is to use the same storage mode specified for the local file system. A remote option with mode set to native may be overridden by the remote ascp if that mode is not supported there. Older versions of ascp do not support this feature. Thus, these options may be overridden by the peer, to none, and ascp will abort and indicate the problem is incompatible FASP protocol versions. The amount of xattr/ACL data per file that can be transferred successfully is subject to ascp's internal PDPU size limitation. | ascp: Transferring from the Command Line | 30

Ascp Options for HTTP Fallback

Option Description

-y {0|1} Enable HTTP Fallback transfer server when UDP connection fails. Set to 1 to enable (default: 0).

-j {0|1} Encode all HTTP transfers as JPEG files. Set to 1 to enable (default: 0). -Y key_file The HTTPS transfer's key file name. -I cert_file The HTTPS certificate's file name. -t port Specify the port for HTTP Fallback Server. -x proxy_server Specify the proxy server address used by HTTP Fallback.

Ascp General Examples

The following are examples of initiating FASP file transfers using the ascp command: • Fair-policy transfer Fair-policy transfer with maximum rate 100 Mbps and minimum at 1 Mbps, without encryption, transfer all files in \local-dir\files to 10.0.0.2:

$ ascp -T --policy=fair -l 100m -m 1m /local-dir/files [email protected]:/remote-dir • Fixed-policy transfer

Fixed-policy transfer with target rate 100 Mbps, without encryption, transfer all files in \local-dir\files to 10.0.0.2:

$ ascp -T -l 100m /local-dir/files [email protected]:/remote-dir • Specify UDP port for transfer Perform a transfer with UDP port 42000:

$ ascp -l 100m -O 42000 /local-dir/files [email protected]:/remote-dir • Public key authentication

Transfer with public key authentication using key file /.ssh/aspera_user_1-key local- dir/files:

$ ascp -T -l 10m -i ~/.ssh/aspera_user_1-key local-dir/files [email protected]:/remote-dir • Username or filepath contains a space Enclose the target in double-quotes when spaces are present in the username and remote path:

$ ascp -l 100m local-dir/files "User [email protected]:/remote directory" • Network shared location transfer

Send files to a network shares location \\1.2.3.4\nw-share-dir, through the computer 10.0.0.2:

$ ascp local-dir/files [email protected]:"//1.2.3.4/nw-share-dir/" • Parallel transfer on a multicore system Use parallel transfer on a dual-core system, together transferring at the rate 200Mbps, using UDP ports 33001 and 33002. Two commands are executed in different Terminal windows:

$ ascp -C 1:2 -O 33001 -l 100m /file [email protected]:/remote-dir & | ascp: Transferring from the Command Line | 31

$ ascp -C 2:2 -O 33002 -l 100m /file [email protected]:/remote-dir • Upload with content protection

Upload the file space\file to the server 10.0.0.2 with password protection (password: secRet):

$ export ASPERA_SCP_FILEPASS=secRet; ascp -l 10m --file-crypt=encrypt local-dir/file [email protected]:/remote-dir/ • Download with content protection and decryption Download from the server 10.0.0.2 and decrypt while transferring:

$ export ASPERA_SCP_FILEPASS=secRet; ascp -l 10m --file-crypt=decrypt [email protected]:/remote- dir /local-dir • Decrypt a downloaded, encrypted file

If the password-protected file file1 is downloaded on the local computer without decrypting, decrypt file1.aspera-env (the name of the downloaded/encrypted version of file1) to file1:

$ export ASPERA_SCP_FILEPASS=secRet; /Library/Aspera/bin/asunprotect -o file1 file1.aspera- env • Download through Aspera forward proxy with proxy authentication

User Pat transfers the file /data/file1 to /Pat_data/ on 10.0.0.2, through the proxy server at 10.0.0.7 with the transfer user aspera_proxy and transfer user password pa33w0rd. After running the command, Pat is prompted for the ascp password.

$ ascp --proxy dnat://aspera_proxy:[email protected] /data/file1 [email protected]:/Pat_data/

Test transfers using faux:// For information on the syntax, see Testing and Optimizing Transfer Performance. • Transfer random data (no source storage required)

Transfer 20 GB of random data as user root to file newfile in the directory /remote-dir on 10.0.0.2:

$ascp --mode=send --user=root --host=10.0.0.2 faux:///newfile?20g /remote-dir • Transfer a file but do not save results to disk (no destination storage required)

Transfer the file /tmp/sample as user root to 10.0.0.2, but do not save results to disk:

$ascp --mode=send --user=root --host=10.0.0.2 /temp/sample faux:// • Transfer random data and do not save result to disk (no source or destination storage required)

Transfer 10 MB of random data from 10.0.0.2 as user root and do not save result to disk:

$ascp --mode=send --user=root --host=10.0.0.2 faux:///dummy?10m faux://

Ascp File Manipulation Examples

Below are examples of using the ascp command to manipulate files. • Upload a directory

Upload a directory, /content/, to the remote server 10.0.0.1. The following produces /storage/content/ * on the remote server:

$ ascp /data/content/ [email protected]:/storage/ • Upload only the contents of a directory | ascp: Transferring from the Command Line | 32

Upload only the contents of /content/ to the remote server, stripping the srcbase path and preserving the rest of the file structure. The following produces /storage/* on the remote server:

$ ascp --src-base=/data/content /data/content/ [email protected]:/storage • Upload a directory to a new directory

Upload /content/ to the remote server and create a new folder, /storage2, to contain it. The following produces /storage2/content/* on the remote server:

$ ascp -d /data/content/ [email protected]:/storage2/ • Download only the contents of a directory

Download the contents of /storage/content/ from the remote server, while stripping the srcbase path and preserving the rest of the file structure. The following produces /data/* on the local machine:

$ ascp --src-base =/storage/content [email protected]:/storage/content/ /data • Upload only the contents of a file and a directory to a new directory

Upload a file, /monday/file1and a directory, /tuesday/*, to the /storage directory on the remote server, while stripping the srcbase path and preserving the rest of the file structure. The following produces / storage/monday/file1and /storage/tuesday/* on the remote server:

$ ascp --src-base=/data/content /data/content/monday/file1 /data/content/ tuesday/ [email protected]:/storage • Download only the contents of a file and a directory to a new directory

Download a file, /monday/file1, and a directory, /tuesday/*, from the remote server, while stripping the srcbase path and preserving the rest of the file structure. The following produces /data/monday/file1 and / data/tuesday/* on the local machine:

$ ascp --src-base=/storage/content [email protected]:/storage/content/monday/ file1 [email protected]:/storage/content/tuesday/ /data • Delete a local directory once it has been transferred to the remote server

Remove /content/ from the local machine after its contents (excluding partial files) have been transferred to the remote server. The following produces /storage/content/* on the remote server:

$ ascp -k2 -E "*.partial" --remove-after-transfer --remove-empty- directories /data/content [email protected]:/storage • Delete a local directory once its contents have been transferred to the remote server

Remove /content/ from the local machine after the contents (excluding partial files) have been transferred to the remote server, while stripping the srcbase path and preserving the rest of the file structure. The following produces /storage/* on the remote server:

$ ascp -k2 -E "*.partial" --src-base=/data/content --remove-after-transfer --remove-empty-directories /data/content [email protected]:/storage

Important: For version 2.7.1, the "-d" option is required when specifying the "--src-base" option if the target directory does not exist. As of version 2.7.3+, this constraint has been removed.

Ascp Transfers to Cloud Storage

If you have access to cloud storage that is hosted by Aspera On Demand, you can use ascp to transfer to it. | ascp: Transferring from the Command Line | 33

With Docroot Already Configured

If your transfer server account already has a docroot set up, ascp transfers to S3 storage, IBM Cloud Object Storage, Google storage, Akamai, Softlayer, and Azure are the same as regular ascp transfers:

$ ascp options myfile username@server:/targetpath

For examples, see Ascp General Examples on page 30. In some cases, ascp transfers to cloud storage can be made without a preconfigured docroot. See the examples below. With No Docroot Configured: S3 and IBM Cloud Object Storage To transfer to S3 if the transfer server account does not have a docroot, you need your S3 Access ID and Secret Key and you have an S3 bucket. The syntax is:

$ ascp options --mode=send --user=username --host=s3_server_addr files s3://access_id:[email protected]/s3_bucket For example:

$ ascp --mode=send --user=bob --host=s3.asperasoft.com myfiles s3://1K3C18FBWF9902:[email protected]/demos2014 With No Docroot Configured: Softlayer To transfer to Softlayer if the transfer server account does not have a docroot, use following syntax:

$ ascp options --mode=send --user=root --host=ip_addr files swift://softlayer_user: [email protected]/container Example Upload:

$ ascp --mode=send --user=root --host=192.155.218.130 bigfile.txt swift:// XYZO...46-2:bob:[email protected]/ test Example Download:

$ ascp --mode=recv --user=root --host=192.155.218.130 swift://XYZO... 46-2:bob:[email protected]/ test/bigfile.txt /tmp/ With No Docroot Configured: Azure | ascp: Transferring from the Command Line | 34

To transfer to Azure if the transfer server account does not have a docroot, set an Aspera environment variable with the password. Run the following:

$ export ASPERA_SCP_PASS = password

Then run ascp with the following syntax:

$ ascp options --mode=send --user=uname --host=server files azu://storage:[email protected].net/abc For example:

$ ascp --mode=send --user=AS037d8eda429737d6 --host=dev920350144d2.azure .asperaondemand.com bigfile.txt azu://astransfer:zNfMtU... [email protected]/abc

Applying Filters to Include and Exclude Files

Specifying Rules on the Command Line

Filtering rules may be specified on the command line to make ascp skip or include specific directories and files. The following command-line options can be freely intermixed:

-E pattern Exclude files or directories matching pattern.

-N pattern Include files or directories matching pattern. Rules are applied in the order they are encountered, and the first matching rule takes precedence (regardless of whether -E or -N). For example, if the following options are specified, rule1, rule2, rule3, and rule4 are applied in that order:

-N rule1 -E rule2 -E rule3 -N rule4

Directories and files are visited in strict depth order, so that with the command-line options -E /above/ -N / above/below , the file /above/below is never considered. Because the directory /above/ is not scanned, /above/below has no opportunity to be checked against any rules. Note: If rules are specified in aspera.conf, they are applied first.

Notes on Path Separators, Case, and Quotation Marks

• In filtering rules, \ is exclusively a quoting operator, and / is the only recognized path separator. • Case always matters, even if the scanned file system does not enforce such a distinction. For example, on Windows FAT / NTFS file systems and Mac OSX HPFS+, if the user writes "DEBUG", it matches the files "Debug" and "debug". However, in filtering rules, the comparison is always exact. To pick up both "Debug" and "debug", the pattern must be "[Dd]ebug". • Rules must be interpreted by ascp, not by the command shell. For this reason, rules that contain wildcards must be surrounded by quotation marks to protect them from interpretation by the shell.

Individual Matching Rules Rules applied to directory and file names are limited regular expressions (referred to as "globs" in UNIX terminology). Standard Globbing, as in POSIX sh(1) and find(1) | ascp: Transferring from the Command Line | 35

* ? [abc] [a-z] *.[!cos] *.[^cos] [![:digit:][:blank:]] • * matches any number of characters • ? matches any single character • [] matches exactly one of a set of characters. The [] may also contain the following: regular character literals The ^ or ! as the first character specifies that the sequence will match any character not in the set. Ranges, specified by giving the first and last characters with a "-" between them. [:alnum:] – alphanumeric, same as [:alpha:][:digit:] [:alpha:] – alphabetic [:blank:] – space or tab [:cntrl:] – control character [:digit:] – digit, 0-9 [:graph:] – not [:blank:] and not [:cntrl:] [:lower:] – lowercase alphabetic [:punct:] – [:graph:] but not [:alnum:] [:space:] – space, tab, linefeed, vertical tab, carriage return [:upper:] – uppercase alphabetic [:xdigit:] – 0-9a-fA-F • Directory names, file names and glob literal characters may be multibyte unicode. For example, voilà is matched by rules voilà, voil[àáâ], voil[[:alpha:]] (but not voil[[=a=]] or voil[[.a- grave.]]). • The \ quotes any character literally, including itself. For example, the pattern a\*b\[c[\]]d\?e\\f matches the a*b[c]d?e\f file. • Wildcards * , [] and ? match neither / nor . immediately after / (for example, /. ). abc/def is not matched by abc*def, abc[/]def or abc?def abc/.def is not matched by any of abc/*, abc/[![:alpha:]]def, or abc/?def abc/.def is matched by */.??* Globbing Extensions

• The wildcard /** is like * but also matches / : abc/**/def matches abc/wxy/def abc/**/def matches abc/def abc/**/def does not match abc/wxy/.def abc/**/def matches abc/.wxy/def (only the last /. counts) • File-type specificity:

A rule ending with * or /** matches both directories and files. A rule ending with / matches only directories. A rule ending without / matches only files. • Rules that start with / are anchored; that is, the entire string must be matched: /abc/**/def matches /abc/wxy/def abc/**/def matches xyz/abc/wxy/def /abc/**/def does not match /xyz/abc/wxy/def

Rule Composition

Example Expected Behavior

-N rule1 -N rule2 Includes all file or directory names that match rule1 or rule2. | ascp: Transferring from the Command Line | 36

Example Expected Behavior

-N rule1 -E rule2 Includes all file or directory names that match rule1; of those, it excludes all that match rule2.

-E rule2 -N rule1 Excludes all file or directory names that match rule2; of the rest, it includes those that match rule1.

An anchored rule -N /a/b/c matches directories /a/ and /a/b/ in addition to file /a/b/c . There is no such extension for -E a/b/c . A rule containing /** bounds this extension. That is, -N "/a/b/**/c/d" matches directories /a and /a/ b , but not the /a/b/c directory. A file or directory name that does not match any rule is still tracked, as if by a final -N "*" . To exclude all unmatched files reliably, add -E "*" as the final rule.

Token Generation

Overview A token authorizes the download of one or more files, or an upload of one or more files into a directory (called destination root). It supports the traditional “cp” paradigm of ascp (copy file1, file2, file3 to directory) or source/ destination pairs (ascp --file-pair-list). You can generate tokens using the astokengen command.

General Usage Examples • Authorize uploads to a specific destination:

$ astokengen --mode=send [options] -u user --dest=path [-v token]

• Authorize uploads of one or more files as source/destination pairs to a specific destination:

$ astokengen --mode=send [options] -u user --file-pair-list=filename -- dest=destination [-v token]

• Authorize downloads of one or more files or directories from a specific destination:

$ astokengen --mode=recv [options] -u user -p path [-p path …] [-v token]

• Authorize downloads of files specified in a file list:

$ astokengen --mode=recv [options] -u user --file-list=filename [-v token]

• Authorize downloads of one or more files as source/destination pairs:

$ astokengen --mode=recv [options] -u user --file-pair-list=filename [- v token]

| ascp: Transferring from the Command Line | 37

• Display the contents of the token:

$ astokengen -t token [options]

Usage Examples

Description Example Common upload In a common upload, only the destination is encoded into the token.

$ astokengen --user=user --dest=path --mode=send

Source paths and file lists (--path and --file-list) are not allowed and will cause astokengen to fail. Paired upload The destination is prepended to the destinations in the paired list file and they are encoded into the token. The destinations are in the odd numbered lines of the file (1, 3, 5, 7, and so on).

$ astokengen --user=user --dest=path --file-pair-list=filename --mode=send

Source paths and file lists (--path and --file-list) are not allowed and will cause astokengen to fail. Common The specified paths are encoded into the token. download $ astokengen --user=user --path=filepath1 --path=filepath2 -- mode=recv $ astokengen --user=user --file-list=filename --mode=recv

In this case, --dest and --file-pair-list are illegal. Paired download The source files from the file pair list are encoded in the token. The sources are in the even numbered lines of the file (0, 2, 4, 6, 8, etc.).

$ astokengen --user=user --file-pair-list=filename --mode=recv

In this case, --dest, --path and --file-list are illegal.

Options

Option (short form) Option (long form) Description

-A --version Print version information. --mode=mode Direction of the transfer mode (send | recv) -p --path=path Source path --dest=destination Destination path -u --user=user Generate the token for this user name. This name is embedded in the token and also used to retrieve further information from | ascp: Transferring from the Command Line | 38

Option (short form) Option (long form) Description aspera.conf (user_value and token_life_seconds). --file-list=filename Specifies a file name that contains a list of sources for a download token. Each line of the file contains a single source and blank lines are ignored. For example:

/monday/first_thing.txt /monday/next_thing.txt

/monday/last_thing.txt

--file-pair-list=filename Specifies a file name that contains a multiplexed list of source and destination pairs for an upload or download token. Each pair of lines encodes one source and one destination and blank lines are ignored. For example

/monday/first_thing.txt /archive/monday/texts/ first_thing /monday/next_thing.txt

/archive/monday/texts/ next_thing /monday/last_thing.txt

/archive/monday/texts/ last_thing

-v token Verify token against user and path parameters.

-t token Display the contents of the token. -k passphrase Passphrase to decrypt token. For use with -t. -b Assume user name and paths are encoded in base64.

Creating SSH Keys (Command Line)

Public key authentication (SSH Key) is a more secure alternative to password authentication that allows users to avoid entering or storing a password, or sending it over the network. Public key authentication uses the client computer to generate the key-pair (a public key and a private key). The public key is then provided to the remote computer's administrator to be installed on that machine. Note: You can use the application GUI to create SSH keys or import existing keys for use with a selected user account. For instructions, see Creating SSH Keys. | ascp: Transferring from the Command Line | 39

1. Create a .ssh directory in your home directory if it does not already exist:

$ mkdir /Users/username/.ssh

Go to the .ssh folder:

$ cd /Users/username/.ssh

2. Run ssh-keygen to generate an SSH key-pair. Run the following command in the .ssh folder to create a key pair. For key_type, specify either RSA (rsa) or ED25519 (ed25519). At the prompt for the key-pair's filename, press ENTER to use the default name id_rsa or id_ed25519. For a passphrase, you can either enter a password, or press return twice to leave it blank:

$ ssh-keygen -t key_type

Note: When you run ascp in FIPS mode ( is set to true in aspera.conf), and you use passphrase-protected SSH keys, you must either (1) use keys generated by running ssh-keygen in a FIPS-enabled system, or (2) convert existing keys to a FIPS-compatible format using a command such as the following:

$ openssl pkcs8 -topk8 -v2 aes128 -in id_rsa -out new-id_rsa 3. Retrieve the public key file. The key-pair is generated to your home directory's .ssh folder. For example, assuming you generated the key with the default name id_rsa:

/Users/username/.ssh/id_rsa.pub

Provide the public key file (for example, id_rsa.pub) to your server administrator so that it can be set up for your server connection.

Ascp FAQs

1. How do I control the transfer speed? You can specify a transfer policy that determines how a FASP transfer utilizes the network resource, and you can specify target and minimum transfer rates where applicable. In an ascp command, use the following flags to specify transfer policies that are fixed, fair, high, or low:

Policy Command template

Fixed --policy=fixed -l target_rate

Fair --policy=fair -l target_rate -m min_rate

High --policy=high -l target_rate -m min_rate

Low --policy=low -l target_rate -m min_rate

The policies have the following characteristics:

• 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 | ascp: Transferring from the Command Line | 40

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. 2. What transfer speed should I expect? How do I know if something is "wrong" with the speed? Aspera's FASP transport has no theoretical throughput limit. Other than the network capacity, the transfer speed may be limited by rate settings and resources of the computers. To verify that your system's FASP transfer can fulfill the maximum bandwidth capacity, prepare a client machine to connect to this computer, and test the maximum bandwidth. Note: This test typically occupies most of a network's bandwidth. Aspera recommends this test be performed on a dedicated file transfer line or during a time of low network activity. On the client machine, start a transfer with fixed bandwidth policy. Start with a lower transfer rate and gradually increase the transfer rate toward the network bandwidth (for example, 1 MB, 5 MB, 10 MB, and so on). Monitor the transfer rate; at its maximum, it should be slighly below your available bandwidth:

$ ascp -l 1m source-file destination To improve the transfer speed, also consider upgrading the following hardware components:

Component Description Hard disk The I/O throughput, the disk bus architecture (such as RAID, IDE, SCSI, ATA, and Fiber Channel). Network I/O The interface card, the internal bus of the computer. CPU Overall CPU performance affects the transfer, especially when encryption is enabled. 3. How do I ensure that if the transfer is interrupted or fails to finish, it will resume without retransferring the files? Use the -k flag to enable resume, and specify a resume rule: • -k 0 – Always retransfer the entire file. • -k 1 – Check file attributes and resume if the current and original attributes match. • -k 2 – Check file attributes and do a sparse file checksum; resume if the current and original attributes/ checksums match. • -k 3 – Check file attributes and do a full file checksum; resume if the current and original attributes/ checksums match.

Corruption or deletion of the .asp-meta file associated with an incomplete transfer will often result in a permanently unusable destination file even if the file transfer resumed and successfully transferred. 4. How does Aspera handle symbolic links? The ascp command follows symbolic links by default. This can be changed using --symbolic- links=method with the following options: • 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. | ascp: Transferring from the Command Line | 41

• 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. Important: On Windows, the only option is skip. 5. What are my choices for overwriting files on the destination computer? In ascp, you can specify the --overwrite=method rule with the following method options: • never – Never overwrite the file. However, if the parent folder is not empty, its access, modify, and change times may still be updated. • always – Always overwrite the file. • diff – Overwrite the file if it is different from the source. If a complete file at the destination is the same as the source then it will not be overwritten. Partial files will be overwritten or resumed depending on the resume policy. • diff+older – Overwrite the file if it is older and different than the source. • older – Overwrite the file if its timestamp is older than the source timestamp. Important: If the overwrite method is diff or diff+older, difference is determined by the resume policy (- k{0|1|2|3}). If -k 0 or no -k is specified, the source and destination files are always considered different and the destination file is always overwritten. If -k 1, the source and destination files are compared based on file attributes (currently file size). If -k 2, the source and destination files are compared based on sparse checksum. If -k 3, the source and destination files are compared based on full checksum. | Transferring with ascp4 | 42

Transferring with ascp4

Introduction to A4

Aspera A4 is an optimized transfer engine based on FASP technology. A4 is designed for sending extremely large sets of individual files efficiently, and it supports UDP multicast. The executable, ascp4, is similar to ascp and shares many of the same options and capabilities. For more information on using ascp4 for UDP multicast, see the IBM Aspera Faspstream User Guide.

Both ascp4 and ascp are automatically installed with IBM Aspera Enterprise Server, Connect Server, Point-to- Point, and Desktop Client applications. Patches for A4 may be available between releases of these applications. To upgrade your ascp4 to the latest version, follow the steps in Upgrading A4.

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: • URIs can only be specified on the command line. • If source paths are specified with a URI, all source paths specified on the command line must be from the same cloud storage account, and all must include URIs. | Transferring with ascp4 | 43

• If source paths are specified with a URI, no docroot (download), local docroot (upload), or source prefix can be specified. • If a destination path is specified with a URI, no docroot (upload) or local docroot (download) can be specified. • The special schemes stdio:// and stdio-tar:// are supported on the client only. Usage as a destination (upload) or source (download) is undefined. • If required, URI passphrases can either be embedded in the URI or specified with the applicable environment variable ASPERA_SRC_PASS or ASPERA_DST_PASS.

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 in aspera.conf on the server. If size is set with both -Z (client side) and (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 . 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) | Transferring with ascp4 | 44

Option Description

-E 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 -N pattern 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. symbolic-links=method Specify the rule to handle symbolic links. This option takes following values (default: follow):

• follow – Follow symbolic links and transfer the linked files. | Transferring with ascp4 | 45

Option Description • copy – Copy only the alias file. If a file with the same name exists on the destination, the symbolic link will not be copied. • skip – Skip the symbolic links. Important: On Windows, the only option is skip.

--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/ [email protected]:/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 [email protected]:/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 [email protected]:/clips/outgoing/file1 [email protected]:/ clips/outgoing/folderA/file2 /incoming

Result:

(docroot)/incoming/file1 (docroot)/incoming/file2 | Transferring with ascp4 | 46

Option Description

--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-file- Preserve transferred files' owner information (uid). owner-uid Note: This option requires the transfer user be authenticated as a superuser.

--preserve-file- Preserve transferred files' group information (gid). owner-gid Note: This option requires the transfer user be authenticated as a superuser.

--preserve-access- Currently has the same effect as -p. time --preserve-source- Currently has the same effect as -p. access-time --preserve- Currently has the same effect as -p. modification-time --preserve-creation- Currently has the same effect as -p. This feature is supported on Windows only. time --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- For compression algorithms that offer configuration of compression levels. hint=num 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. | Transferring with ascp4 | 47

Option Description

--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. | Transferring with ascp4 | 48

Option Description

--exclude-newer- Exclude files from the transfer based on when the file was last changed. This than=mtime option does not consider directories. --exclude-older- than=mtime | Technical Support | 49

Technical Support

Support Websites For an overview of IBM Aspera Support services, go to http://asperasoft.com/company/support/. To view product announcements, webinars, and knowledgebase articles, as well as access the Aspera Support Community Forum, sign into the IBM Aspera Support site at support.asperasoft.com using your email address (not your company Aspera credentials), or set up a new account. You can click on a heading then click Follow to receive notifications when new knowledgebase articles are available; if you follow RELEASE NOTES under a specific product, you will be automatically notified of new releases.

Personalized Support You may contact an Aspera support technician 24 hours a day, 7 days a week, through the following methods, with a guaranteed 4-hour response time. If you have an emergency, create a ticket using the Support Request Form with as many details as you have available and then call. If you are asked to leave a voice message, include the ticket number.

Email [email protected] Phone (North America) +1 (510) 849-2386, option 2 Phone (Europe) +44 (0) 207-993-6653 option 2 Phone (Singapore) +81 (0) 3-4578-9357 option 2 Support Request Form https://support.asperasoft.com/anonymous_requests/new/ | Legal Notice | 50

Legal Notice

© 2005-2017 Aspera, Inc., an IBM Company. All rights reserved. Licensed Materials - Property of IBM © Copyright IBM Corp.2005, 2017. Used under license. US Government Users Restricted Rights- Use, duplication or disclosure restricted by GSA ADP Schedule Contract with IBM Corp. Aspera, the Aspera logo, and FASP transfer technology are trademarks of Aspera, Inc., registered in the United States. Aspera Connect Server, Aspera Drive, Aspera Enterprise Server, Aspera Point-to-Point, Aspera Client, Aspera Connect, Aspera Cargo, Aspera Console, Aspera Orchestrator, Aspera Crypt, Aspera Shares, the Aspera Add-in for Microsoft Outlook, and Aspera Faspex are trademarks of Aspera, Inc. All other trademarks mentioned in this document are the property of their respective owners. Mention of third-party products in this document is for informational purposes only. All understandings, agreements, or warranties, if any, take place directly between the vendors and the prospective users.