IBM Aspera Desktop Client 4.

IBM
Contents

High-Speed Transfer Client Admin Guide for Linux..................................................1

Introduction................................................................................................................................................. 1
Get Started as a Transfer Client...................................................................................................................3
Installation and Upgrades........................................................................................................................... 4
Requirements......................................................................................................................................... 4
Before Upgrading or Downgrading.........................................................................................................4
Installing Desktop Client........................................................................................................................ 5
Configuring the Firewall..........................................................................................................................6
Testing a Transfer................................................................................................................................... 6
Uninstalling............................................................................................................................................. 8
Transfer Files in the GUI.............................................................................................................................. 8
Overview of the Desktop Client GUI...................................................................................................... 8
Global Bandwidth Settings...................................................................................................................10
Enabling a Transfer Proxy or HTTP Proxy............................................................................................ 12
Adding and Editing Connections.......................................................................................................... 15
Exporting and Importing Connections.................................................................................................22
Creating SSH Keys in the GUI...............................................................................................................23
Transferring Content............................................................................................................................ 26
Managing Transfers.............................................................................................................................. 27
Scheduling and Customizing Transfers in Advanced Mode................................................................ 29
Configuring Transfer Notifications....................................................................................................... 31
Using Transfer Notifications.................................................................................................................37
ascp: Transferring from the Command Line..............................................................................................38
Ascp Command Reference...................................................................................................................38
Ascp General Examples....................................................................................................................... 53
Ascp File Manipulation Examples........................................................................................................ 56
Ascp Transfers with Object Storage and HDFS................................................................................... 58
Using Standard I/O as the Source or Destination................................................................................61
Using Filters to Include and Exclude Files.......................................................................................... 64
Symbolic Link Handling........................................................................................................................ 69
Creating SSH Keys (Command Line).................................................................................................... 71
Reporting Checksums.......................................................................................................................... 72
Client-Side Encryption-at-Rest (EAR).................................................................................................. 75
Comparison of Ascp and Ascp4 Options............................................................................................. 76
Ascp FAQs.............................................................................................................................................79
ascp4: Transferring from the Command Line............................................................................................81
Introduction to Ascp4.......................................................................................................................... 81
Ascp4 Command Reference.................................................................................................................82
Ascp4 Transfers with Object Storage.................................................................................................. 90
Ascp4 Examples................................................................................................................................... 90
Built-in I/O Provider............................................................................................................................. 90
Appendix.................................................................................................................................................... 91
Restarting Aspera Services.................................................................................................................. 91
Testing and Optimizing Transfer Performance.................................................................................... 91
aclean Reference..................................................................................................................................94
Log Files................................................................................................................................................95
Preserving IBM Spectrum Scale ACLs of Transferred Files.................................................................98
Connecting to IBM Aspera Shares from the GUI.................................................................................99
Logging Client File System Activity on an HST Server......................................................................... 99
Product Limitations............................................................................................................................ 100

ii
High-Speed Transfer Client Admin Guide for Linux
Welcome to the High-Speed Transfer Client documentation, where you can find information about how to
install, maintain, and use the High-Speed Transfer Client.

Introduction
Thanks for choosing Aspera and welcome to the world of unbelievably fast and secure data transfer.

The Basics
Aspera high-speed transfers begin when an Aspera client authenticates to an Aspera server and requests
a transfer. If the client user has authorization, then transfer tools are launched on the client and server
and the transfer proceeds.
For example, an IBM Aspera Desktop Client user connects to an IBM Aspera High-Speed Transfer Server
and initiates a transfer:

Depending on the user's transfer request, files and folders can be transferred to the server from the client
(uploaded) or transferred to the client from the server (downloaded). The source and destination can be
cloud storage, an NFS or CIFS mount, and IBM Spectrum Scale storage, to name a few.
What is the Server?
The Aspera server receives transfer requests from Aspera clients, determines if the user has permission
to access the server and authorization to the target area of the file system (source or destination with read
or write access), and participates in transfers. The server can be:
• an on-premises installation of HSTS, IBM Aspera High-Speed Transfer Endpoint (which permits one
client connection),
• a HSTS installed as part of IBM Aspera Faspex, or
• an HSTS deployed in object storage as an IBM Aspera On Demand instance, an IBM Aspera on Cloud
transfer service node, or an IBM Aspera Transfer Cluster Manager node.
What is the Client?
The Aspera client is the program that requests a transfer with the Aspera server. Aspera applications that
can act as clients include:
• Desktop Client,
• IBM Aspera Drive,
• IBM Aspera Connect,
• IBM Aspera Command-Line Interface,
• HSTS and HSTE
What is FASP?
At the heart of your Aspera ecosystem are the FASP transfer engines Ascp and Ascp 4. Ascp maximizes
data transport over any network and is particularly suited to large files. It is a powerful command-line tool
and also drives transfers started in the GUI.

High-Speed Transfer Client Admin Guide for Linux 1

 Ascp 4 is another command-line transfer tool that is optimized for both large files and transfers of
thousands to millions of small files, handling large amounts of file metadata as part of the high-speed
transfer.
Both Ascp and Ascp 4 are installed and enabled with your installation of HSTS, HSTE, and Desktop Client.

The Aspera Transfer Server

Your Aspera transfer server is a powerful, customizable hub for your high speed transfer activity.
Configuration settings allow you to control which clients have access for uploading or downloading data,
how much bandwidth their transfers can use, the priority of those transfers, and how data is secured
during and after transfer. The transfer queue can be managed on the fly, enabling you to adjust as
priorities change. You can also monitor transfers and receive email notifications when transfer sessions or
individual file transfers start and stop.
The Aspera Server GUI
The Aspera desktop GUI is primarily a client transfer tool, but it also offers a user-friendly interface for
managing users and configuring your server on supported platforms (Windows, Linux, macOS). Security
settings, bandwidth use policies, and file handling rules can all be set in the GUI. Configurations can be
applied to all users (globally), to groups, or to individual users.
HSTS Web Portal
Your HSTS can be made even more accessible to clients by hosting a web-based storage directory.
Authorized clients can browse files by using any modern web browser, and transfer using the free,
automatically-installed Connect.
Asconfigurator: The Aspera Configuration Tool
If you are unfamiliar with the XML formatting required for your Aspera server's configuration file, or need
to configure settings that are not available in the GUI, you can edit your configuration with confidence by
using asconfigurator. These commands ensure that the XML structure is correctly maintained when
you add or change settings.
Tap into the Aspera Ecosystem
If you have a variety of data storage systems and internal and external customers who need access to
the content in that storage, HSTS can be incorporated into a scalable Aspera data transfer ecosystem that
meets your needs. Your Aspera server can be monitored and managed by IBM Aspera Console, and added
as a node to IBM Aspera Faspex, IBM Aspera Shares, IBM Aspera on Cloud, and IBM Aspera Application
for Microsoft SharePoint.

The Aspera Client Transfer Tools

Your installation includes the following transfer tools, some of which require an additional license for
activation.
The Aspera Client GUI
The Aspera desktop GUI offers a simple, intuitive way to create connections with Aspera servers, and to
start and manage your high-speed transfers. The transfer job queue shows real-time progress and allows
on-the-fly reordering and bandwidth control.
The FASP Transfer Engines: ascp and ascp4
These command line tools enable you to run transfers to any server to which you have access, and
to customize the transfers (within the parameters set by the server). They are scriptable, supporting
unattended data transfer and custom pre- and post-transfer file processing.
Hot Folders: Automatic Data Transfer in the GUI
Sending or receiving files can be even easier and faster by using Hot Folders. Available only on Windows,
you can set up a Hot Folder to watch for and automatically transfer any new files that are added to that

2 IBM Aspera Desktop Client 4.3

 folder. Automatically send files to a server as they are added to a folder on your own desktop, or receive
files as they are added to a folder on the server. Transfers use Ascp and are easily managed from the GUI.
Watch Folders: Automatic Content Delivery at Any Scale
Using asperawatchd and Watch Folders creates a powerful, efficient file system monitoring and automatic
transfer tool that can comfortably handle millions of files and "growing" sources. Automatically transfer
files as they are added to a source folder. With a REST API interface, you have full programmatic control
for custom, automatic transfer processing.
Watch Folders offer the same transfer and bandwidth management options as ascp, and can be
monitored and managed through Console. Watch Folders are enabled in your HSTS or HSTE.
IBM Aspera Sync: Directory Synchronization at the Speed of FASP
When everyone needs to see the same files or you need to be sure that every file is replicated, Aspera
Sync provides a high-speed tool to do it. Unique among Aspera's transfer tools, Aspera Sync supports
bidirectional synchronization for optimum collaboration and consistency between computers.
Aspera Sync uses efficient file system monitoring and change detection to minimize redundant data
transfer and to reduce database storage requirements. Aspera Sync offers the same transfer and
bandwidth management options as ascp, and can be monitored and managed through Console.
Aspera Sync is installed with your HSTS and HSTE, but both the client and server require a Aspera
Sync-enabled license.

Get Started as a Transfer Client

Aspera transfer clients connect to a remote Aspera transfer server and request a transfer with that server.
Your Aspera application can be used as a client to initiate transfers with Aspera servers, as described in
the following steps.
1. Review the system requirements and install Desktop Client.
See “Requirements” on page 4 and “Installing Desktop Client” on page 5.
2. Configure the firewall, if it is not already configured.
See “Configuring the Firewall” on page 6.
3. Configure transfer preferences.
You can configure your bandwidth usage, email notification, and proxy settings to apply to all transfers.
For more information, see “Global Bandwidth Settings” on page 10 and “Enabling a Transfer Proxy or
HTTP Proxy” on page 12.
4. Test a locally-initiated transfer to the Aspera demonstration server to confirm your installation and
firewall configuration are operational.
For instructions, see “Testing a Transfer” on page 6. This provides a simple walk through of how to
set up a connection with a server and transfer.
5. Configure your email notification preferences.
You can receive emails when transfer sessions start and finish to keep up-to-date on your transfer
progress. For more information, see “Configuring Transfer Notifications” on page 31.
6. If you need to authenticate to the remote server with an SSH key, create an SSH key and send the
public key to the server admin.
For instructions on creating an SSH key, see “Creating SSH Keys in the GUI” on page 23 or “Creating
SSH Keys (Command Line)” on page 71.
7. To run transfers in the GUI, create and configure a connection to the server.
For instructions, see “Adding and Editing Connections” on page 15. If required, configure a proxy
(“Enabling a Transfer Proxy or HTTP Proxy” on page 12). You can also configure transfer notifications
(“Scheduling and Customizing Transfers in Advanced Mode” on page 29).
Once your connection is configured, you can initiate transfers with the server. For instructions, see
“Transferring Content” on page 26.

High-Speed Transfer Client Admin Guide for Linux 3

 8. To run transfers from the command line, review the instructions for the Aspera command line clients.
Your Aspera product comes with two command line clients: ascp and A4. They are similar but have
different capabilities. For a comparison, see “Comparison of Ascp and Ascp4 Options” on page 76.
• For more information about ascp, see “Ascp Command Reference” on page 38 and “Ascp General
Examples” on page 53.
• For more information about A4, see “Ascp4 Command Reference” on page 82 and “Ascp4
Examples” on page 90.
Once you confirm that you can transfer with your server, your basic set up is complete.

Installation and Upgrades

Before you install the current release, review the following information about hardware and software
requirements, system preparation for upgrades or downgrades, installation instructions, and product
security configuration.

Requirements
System requirements for Desktop Client.
• Product-specific Aspera license file.
• Ubuntu 14.04 LTS, 16.04 LTS, 17.10; RHEL 6-7; CentOS 6-7; SLES 11-12; Debian 7-9; Fedora 26-27;
Kernel 2.4 or higher and Glibc 2.5+. Linux distributions/kernels released after the product release date
might not be compatible.
• Glibc 2.5 or higher.
• Screen resolution 1024 x 768 or higher for graphical user interface.

Before Upgrading or Downgrading

When upgrading (or downgrading), Aspera recommends the following preparation to ensure a smooth
process, minimal transfer disruption, and peace-of-mind that your original configuration is backed up in
case of any problems.
Upgrading
• The installer automatically checks for an older version of the product on your system. If an older version
is found, the installer automatically removes it before installing the new version.
• Although the installer performs your upgrade automatically, Aspera highly recommends completing the
tasks below before upgrading. If you do not follow these steps, you risk installation errors or losing your
former configuration settings.
• You cannot upgrade directly between different Aspera transfer products (such as from HSTE or /> to
HSTS). To upgrade, you need to back up the configuration, uninstall the product, and perform a fresh
install of the new version of the product.
Downgrading
Older installers do not check for newer versions of the application. You must prepare your machine as
described below then uninstall the newer version before continuing with your downgrade.
Note: Installers of versions 3.7.4 and older do not support systemd. When downgrading to one of these
versions on an OS that uses systemd, you must manually start Aspera services because the installer
cannot start them automatically. Run the following commands to start the services:

# systemctl start asperacentral

# systemctl start asperahttpd
# systemctl start asperarund
# systemctl start asperanoded

4 IBM Aspera Desktop Client 4.3

 Newer versions of the Redis database are not compatible with older versions of the application. Your
downgrade process depends on whether a backup of the older Redis DB is available, either as a separate
backup file or as part of your backup of the var directory from the older version.
• With a backup: Follow the steps below to prepare your machine. Uninstall the application (for
instructions, see ). Copy the older Redis DB file into the var directory before installing the older
(downgrade) version.
/opt/aspera/var/
• Without a backup: Follow the steps below to prepare your machine. Uninstall the application (for
instructions, see ) and delete the var and etc directories from your machine. Then do a fresh
installation of the older version. The configuration files in the etc directory may be compatible with
older versions, but not all configurations may be read.
/opt/aspera/var/
/opt/aspera/etc/
Preparing for an Upgrade or Downgrade
1. Verify the current version.
The steps that are required to prepare for an upgrade depend on your version. To view the current
product and version, click Tools > License in the GUI orrun the following command:

2. Review product release notes.

Review the release notes for the versions that were released since your current version. In particular,
the Breaking Changes section highlights changes that may require you to adjust your workflow,
configuration, or usage.
3. Stop or allow to complete any FASP transfers that were initiated by the computer that you are
upgrading.
FASP transfers cannot proceed during your Aspera product upgrade.
• Close the application GUI.
• Stop (and resume after upgrade) or allow to complete any Ascp, Ascp 4, or Aspera Sync transfers in
the command line.
4. Back up configuration and settings files.
These files are found in the etc and var folders.
• /opt/aspera/etc/ (contains server configuration, web configuration, user settings, license info)
• /opt/aspera/var/ (contains Pre- and Post-Processing scripts)
5. Back up the Redis database.
The Redis database is backed up as part of backing up the var directory, but Aspera recommends
backing it up separately as well, particularly if it is stored on a different machine.

# sudo /opt/aspera/bin/asnodeadmin -b /filepath/database.backup

6. If you modified the daemon startup scripts for Aspera Central and asperanoded (for example, as part
of an Aspera API integration), back up the modified files. These files are overwritten during an upgrade
and you will need to copy your modifications into the new files after upgrading.

Installing Desktop Client

To install Desktop Client, log into your computer with root permissions.
Important: If this is a product upgrade, review all prerequisites described in “Before Upgrading or
Downgrading” on page 4.
1. Download the HSTS installer from https://www.ibm.com/products/aspera/downloads.
2. For product upgrades, ensure you have prepared your system to upgrade to a newer version.

High-Speed Transfer Client Admin Guide for Linux 5

 Although the installer performs your upgrade automatically, Aspera highly recommends completing the
tasks described in “Before Upgrading or Downgrading” on page 4
3. Run the installer
Run the following commands with the admin permissions. Replace the product version with that of
your package.

OS Commands

RedHat, zLinux, $ rpm -Uvh /path_to_installer/aspera-desktopclient-version.rpm

CentOS
Note: If your Linux OS is a minimal clean system, ensure that all the required
dependencies are installed with your Aspera application by installing the
product with a yum install:

$ yum --nogpgcheck install /path_to_installer/aspera-desktopclient-

version.rpm

Debian $ dpkg -i /path_to_installer/aspera-desktopclient-version.deb

4. Installation troubleshooting.
If the installer freezes during installation, another Aspera product might be running on your
computer. To stop all FASP transfer-related applications and connections, see “Before Upgrading or
Downgrading” on page 4.

Configuring the Firewall

Desktop Client requires access through specific ports. If you cannot establish the connection, review your
local corporate firewall settings and remove the port restrictions accordingly.

The following is basic information for configuring your firewall to allow Aspera file transfers. The outbound
TCP port for SSH may differ depending on your organization's unique network settings. Although TCP/
33001 is the default setting, refer to your IT Department for questions related to which SSH port(s) are
open for file transfer. Consult your operating system's documentation for instructions on configuring your
firewall. If your client host is behind a firewall that does not allow outbound connections, you will need to
allow the following ports:
• Outbound TCP/33001: Allow outbound connections from the Aspera client on the TCP port (TCP/33001
by default, when connecting to a Windows server, or on another non-default port for other server
operating systems).
• Outbound UDP/33001: Allow outbound connections from the Aspera client on the FASP UDP port
(33001, by default).
• Local firewall: If you have a local firewall on the client (such as iptables), verify that it is not blocking
your SSH and FASP transfer ports (such as TCP/UDP 33001).

Testing a Transfer
To make sure the software is working properly, set up a connection with a server and test downloads and
uploads.
Linux users may use the GUI or command line, and instructions for both are shown below.
1. Launch the application.
Run the following command in a terminal window:

$ asperascp

2. Add the server in the Connection Manager.

6 IBM Aspera Desktop Client 4.3

 Click Connections.
In the Connection Manager, click to add a new connection, click OK to create a standard
connection, and enter the following information (with the appropriate values for your server), leaving
the other options with their default values or blank:

Field Value
Host my_demo.example.com
User my_user_name
Authentication my_password
(Password)
3. Test your connection to the remote server.
Click Test Connection to determine whether you can reach the remote server with the settings you
configured. An alert box opens and reports whether the connection is successful.
4. Connect to the server and download test files.
From the main window, select the server entry and click the Connect button.
On the server file browser (right panel), browse to a folder with a file that you want to use, select the
file, and click to download it to your local machine.
You should see the session appear in the Transfer pane.
5. Upload to the server.
Select the same file (100MB) on the local file browser (left panel), go to the folder /Upload on the
server, and click to upload it.
6. Download test files from the server.
Use the ascp command to download, press y to accept the server's key, and enter your password
when prompted. For example

# ascp -T xeno@my_demo.example.com:test-dir-large/100MB /tmp/

The transfer command is based on the following settings:

Item Value
server address my_demo.example.com
Login account xeno
Test file /test-dir-large/100MB
Download location /tmp/
Transfer settings Fair transfer policy, target rate 10M, minimum rate 1M, encryption disabled.

You should see a message similar to the following:

This message provides the following information:

Item Description
100 MB The name of the file that is being transferred.
28% The percentage completed.
28 MB The amount transferred.

High-Speed Transfer Client Admin Guide for Linux 7

 Item Description
2.2 Gbps The current transfer rate.
01:02 ETA The estimated time the transfer will complete.
7. Upload test files to the demo server.
Run the command to upload the same file (100MB) back to the demo server, to its /Upload directory.
Enter the your password when prompted. For example:

# ascp -T /tmp/100MB xeno@my_demo.example.com:Upload/

Uninstalling
Desktop Client can be uninstalled without removing existing configuration files.
1. If you are uninstalling in order to upgrade your Aspera product, review the upgrade preparation steps
in “Before Upgrading or Downgrading” on page 4.
2. Close or stop the following applications and services:
• FASP transfers
• SSH connections
• user interface
3. Uninstall by running the following command:

Platform Command

RedHat, CentOS # rpm -e aspera-scp-client

Debian # dpkg -P aspera-scp-client

Note: This process does not remove Aspera configuration files. If you reinstall an Aspera product, these
configuration files are applied to the new installation.

Transfer Files in the GUI

Use the Desktop Client GUI to create connections to Aspera servers, configure transfer settings, set up
transfer notifications, and start, stop, pause, and schedule transfers.

Overview of the Desktop Client GUI

The Desktop Client GUI is an intuitive tool for starting and managing transfers. Learn how to launch the
GUI and how to navigate its features.

Launching the Application

To launch the application, run the following command:

# asperascp

8 IBM Aspera Desktop Client 4.3

The Application GUI

Item Description
A Click Transfer to enter the transfer viewing mode. This is the default view when you
launch the application, which shows the local and remote file browsers. For more
information, see “Transferring Content” on page 26.
B Select a transfer from the bottom pane and click Details to enter the transfer details
viewing mode. This view shows the details of the selected transfer session, as well as the
transfer control options. For more information, see “Managing Transfers” on page 27.
C Click Connections to open the Connection Manager window in which you can manage
the remote endpoints. For more information, see “Adding and Editing Connections” on
page 15.
D Click Preferences to set the local computer's default transfer settings, such as the FASP
global bandwidth and the number of simultaneous transfers in the queue, and the SMTP
server's information for transfer notifications.
E Browse the local file system to view files to transfer.
F When not connected, a list of the saved connections is displayed. When connected (by
clicking on a Connection Name and clicking Connect), browse the remote file system.
G Display previous, ongoing, and queued transfers. Manage the priority.

The File Browser

All options in the File Browser, including the file browser's contextual menu (Mouse right-click):

High-Speed Transfer Client Admin Guide for Linux 9

 Item Description
A Path indicator/selector.
B Go to the parent directory.
C Create a new folder.
D Choose between the list views and the detail view.
E Create a new folder.
F View the advanced upload or download window.
G Decrypt the selected file if it is encrypted with the content protection.
H Choose between the detail or the list views. Refresh the folder.
I Options to manipulation the selected files.
J Show the selected files' properties.

Global Bandwidth Settings

Aspera FASP transport has no theoretical throughput limit. In addition to network capacity, transfer rates
can be limited by user-configured rate settings and the resources of the local and remote machines. You
can configure bandwidth usage limits and the number of concurrent FASP transfers that are allowed by
Desktop Client.

1. Launch the application with administrator privileges and click Tools > Global Preferences.

10 IBM Aspera Desktop Client 4.3

2. Click Transfers.

3. To limit total bandwidth usage by FASP uploads and downloads, edit System-Wide Settings.
System-wide settings set the aggregated bandwidth cap for all FASP transfers on this computer.
To override the default bandwidth limits, under System-Wide Settings select the boxes next to Limit
Download Bandwidth and Limit Upload Bandwidth and enter new values in the fields. The global
settings for download and upload bandwidth limits cannot be reset by non-admin users. However,
users can view the global limit from the Preferences > Transfers dialog.
4. To set default target rates for all users, edit Default Target Rate.
Non-admin users can adjust their personal default target rates above or below the global default value.
5. To limit the number of active transfers, edit Maximum Active Transfers.
Non-admin users can adjust their personal maximum active transfers above or below the global
default value.
6. Click OK to activate your changes.

High-Speed Transfer Client Admin Guide for Linux 11

Enabling a Transfer Proxy or HTTP Proxy
If, for network security reasons, you are behind a transfer proxy server, you can enable the proxy for
Aspera file transfers. If you have admin privileges, you can enable transfer proxies for all users by setting
global preferences. If you are a non-admin user, you can override global transfer-proxy settings for your
own account, including enabling or disabling the feature. By default, proxy is disabled.
Open the proxy configuration dialog by clicking Preferences > Proxy.
Clicking Preferences opens the user-account proxy settings. If you have permission, you can click Global
Preferences to access those settings.

Configuring Global Transfer and HTTP Proxy Settings

You must have admin privileges to set global preferences.
To enable a transfer proxy:
1. Go to Global Preferences > Proxy.
2. Select Enable transfer proxy.
3. Enter the proxy server's hostname or IP address and port number.
4. Select Secure if your proxy server allows secure connections.
5. Enter your username and password to authenticate with your proxy server.

To enable HTTP proxy:

1. Go to Global Preferences > Proxy.
2. Select Enable HTTP proxy.
3. Enter the HTTP proxy's hostname or IP address and port number.

12 IBM Aspera Desktop Client 4.3

4. If your HTTP proxy requires authentication, select Authenticated and enter the username and
password for your HTTP proxy.

To clear all settings, click Restore System Defaults.

User Proxy Settings

To override the global settings, edit the proxy settings for your account. Click Preferences > Proxy. The
values are those that you inherited from the global proxy settings.
To configure user transfer proxy settings:
1. Select or clear Enable transfer proxy to enable or disable transfer proxy.
2. Enter the proxy server's hostname or IP address and port number.
3. Select Secure if your proxy server allows secure connections.
4. Enter your username and password to authenticate with your proxy server.

High-Speed Transfer Client Admin Guide for Linux 13

 To configure user HTTP proxy settings:
1. Select or clear Enable HTTP proxy.
2. Enter the HTTP proxy's hostname or IP address and port number.
3. If your HTTP proxy requires authentication, select Authenticated and enter the username and
password for your HTTP proxy.

14 IBM Aspera Desktop Client 4.3

 To revert all user settings to the global values, click Restore Defaults.

Adding and Editing Connections

To transfer with HSTS, HSTE, IBM Aspera Shares, IBM Aspera on Cloud transfer service (AoCts), or an IBM
Aspera Transfer Cluster Manager node, add it as a connection in the Connection Manager. The following
instructions describe how to create and configure a connection and edit or delete connections.
To connect with cloud storage, you must meet the following prerequisites:
• You have permissions to access the cloud storage and the necessary authentication information.
• To transfer files with an S3 storage device using an S3 direct connection, the user must have a
restriction rather than a docroot set on the server.
Once you create connections, you can export and import connection lists. For instructions, see “Exporting
and Importing Connections” on page 22.
To create a new connection:
1. Start the application.

# asperascp

2. To open the Connection Manager, click Connections.

High-Speed Transfer Client Admin Guide for Linux 15

 3. Click to create a new connection.

Click to duplicate a selected connection (to copy all information into a new profile) and to delete
a connection profile.
4. Configure the connection name, if desired.
By default, connections are named username@host.
To name or rename a connection, click the connection name and enter the new name in the pop-up.
Click OK to save your changes.

5. Configure the required settings for the connection.

On the Connection tab, enter the following information. In most cases, only Host, User, and
Authentication are required.

Connection Description
Option
Host The server's address, such as 192.168.1.10 or companyname.com. For Shares,
Node API, or AoCts connections, enter the URL and port for asperanoded, such
as https://ats-aws-us-west-2.aspera.io:443.
User The transfer user's username, the Shares user, Node API credentials, or an
access key ID.
Authentication The authentication method. Select Password to authenticate with the transfer
user's password, the Shares user's password, the Node API user password, or
an access key secret (such as for AoCts or ATC Manager).

16 IBM Aspera Desktop Client 4.3

 Connection Description
Option

Select Public Key to authenticate with the transfer user's public SSH key. For
more information, see “Creating SSH Keys in the GUI” on page 23 and .

Storage Type The default option is local storage. Use this option to connect to:
• on-premises servers
• AoCts
• cloud-based servers when the transfer user has the storage credentials
configured in their docroot on the server
When the server is in the cloud but the storage credentials are not configured
in the transfer user's docroot, use the drop-down menu to select the object
storage type and enter credentials.
Supported object storages include the following:
• Akamai NetStorage
• Amazon S3: Requires your Access Id, Secret Access Key, and bucket
path. The local machine must be reasonably time-synchronized in order to
communicate with the Amazon servers. You can also select the Advanced
button to modify the following settings:
– Host: Amazon S3 hostname (default: s3.amazonaws.com).
– Port: Default is port 443.
– HTTPS connection for file browsing: Enable for secure browsing.
– Server-side file encryption: Enable for AES256 encryption.
– Reduced redundancy storage class: Assign objects to a to the "reduced
redundancy" storage class (durability of 99.99%).
• Google Storage: Requires your Project Number and bucket path.
• Limelight: Requires your Account, Username, and Password.
• Windows Azure: Requires your Storage Account and Access Key.
Azure storage is set to use the Azure block blob REST API by default. To
specify the REST API for page blobs, enter your account credentials then click
Advanced. Select PAGE from the drop-down menu next to Api and click OK.
• Windows Azure SAS: Requires your Shared URL.
• Azure Files: Requires your File service endpoint and password.

6. Configure other connection settings, if needed.

On the Connection tab, configure non-default connection settings by editing any of the following
settings:

Connection Description
Option
Target Directory The default directory when connecting to this computer. When left blank,
(or Bucket Path browsing the remote host brings up either the user's docroot or the last-visited
for most object folder. When a path is set, the connection opens to the exact directory.
storage)
Advanced Settings The TCP port for SSH connections. Default: 33001. If the application cannot
> SSH Port (TCP) connect on 33001, it automatically attempts a connection on port 22. If the
connection on 22 succeeds, the setting is updated to 22.

High-Speed Transfer Client Admin Guide for Linux 17

 Connection Description
Option
Advanced Settings The UDP port for FASP transfers. Default: 33001.
> FASP Port (UDP)
Advanced Settings Time out the connection attempt after the specified time.
> Connection
Timeout
Test Connection Click to test the connection to the remote server with the settings you
configured.
7. Configure the connection's transfer settings, if needed.
On the Transfer tab, configure non-default transfer settings by editing any of the following settings:

Transfer Option Description

Transfer Name Select from the following options: Automatically generate allows the user
interface to generate the transfer name; Automatically generate and add
prefix uses auto-generated name with a customizable prefix; Specify uses the
user-specified name.
Policy Select the FASP transfer policy.
• high - Adjust the transfer rate to fully utilize the available bandwidth up
to the maximum rate. When congestion occurs, the transfer rate is twice as
fast as a fair-policy transfer. The high policy requires maximum (target) and
minimum transfer rates.
• fair - Adjust the transfer rate to fully utilize the available bandwidth up to
the maximum rate. When congestion occurs, bandwidth is shared fairly by
transferring at an even rate. The fair policy requires maximum (target) and
minimum transfer rates.
• low - Adjust the transfer rate to use the available bandwidth up to the
maximum rate. Similar to fair mode, but less aggressive when sharing
bandwidth with other network traffic. When congestion occurs, the transfer
rate is reduced to the minimum rate until other traffic decreases.
• fixed - Attempt to transfer at the specified target rate, regardless of network
or storage capacity. This can decrease transfer performance and cause
problems on the target storage. Aspera discourages using the fixed policy
except in specific contexts, such as bandwidth testing. The fixed policy
requires a maximum (target) rate.
• aggressiveness - The aggressiveness of transfers that are authorized by
this access key in claiming available bandwidth. Value can be 0.00-1.00. For
example: These values correspond to the policy option where a policy of
high approximates to aggressiveness of 0.75, fair to 0.50 and low to 0.25.
Aggressiveness can be used if there is a need to fine tune the transfer policy.

Speed Select Override default transfer rate settings to specify the transfer rate.
The target rate is constrained by the global bandwidth settings; for more
information, see “Global Bandwidth Settings” on page 10.
Retry Select to automatically retry the transfer after a recoverable failure for a set
amount of time, in seconds, minutes or hours. You may set the initial and
maximum retry intervals by clicking the More Options button.
• Initial interval: The first retry waits for the initial interval. Input in seconds,
minutes or hours.

18 IBM Aspera Desktop Client 4.3

 Transfer Option Description

• Maximum interval: After the initial interval, the next interval doubles until
the maximum interval is met, and then stops retrying after the retry time is
reached. Input in seconds, minutes or hours.
For example, if the retry is set for 180 seconds, the initial interval is 10
seconds, and the maximum interval is 60 seconds, then the transfer will retry
at 10, 30, 70, 130, and 180 seconds after the first try, such that the interval
progression is 10, 20, 40, 60, 60, and 50 seconds. The last interval is not the
maximum because the retry period ends with a final retry.
As another example, if the retry is set for 600 seconds, the initial interval is 30
seconds, and the maximum interval is 120 seconds, then the transfer will retry
at 30, 90, 210, 330, 450, 570, and 600 seconds after the first try, such that
the interval progression is 30, 60, 120, 120, 120, 120, and 30 seconds. Again,
the last interval is not the maximum because the retry period ends with a final
retry.

Show Advanced Click Show Advanced Settings to edit the following options:
Settings
• Specify FASP datagram size (MTU): By default, the detected path MTU is
used. Select to specify a value between 296 and 10000 bytes.
• Disable calculation of source files size before transferring: Select to turn
off job size calculation on the client side, if allowed by the server.

8. Configure tracking and email notifications, if needed.

On the Tracking Tab, configure non-default transfer settings by editing any of the following settings:

Tracking Option Description

Generate delivery Select to create a delivery receipt file in the specified location.
confirmation
receipt
Send email Send email notifications based on specified events (start, complete, and error).
notifications See “Using Transfer Notifications” on page 37 for more information.
9. Configure filters to automatically exclude certain files from transfers with this connection, if needed.
On the Filters tab, click Add and enter the pattern to exclude files or directories with the specified
pattern in the transfer. The exclude pattern is compared with the whole path, not just the file name or
directory name. Two special symbols can be used in the setting of patterns:

Filter Symbol Name Description

* Asterisk Represents zero to many characters in a string, for example
*.tmp matches .tmp and abcde.tmp.
? Question mark Represents one character, for example t?p matches tmp but not
temp.

For more information on filter rule syntax, see “Using Filters to Include and Exclude Files” on page
64.
10. Configure security settings, if needed.
On the Security tab, configure non-default transfer settings by editing any of the following settings:

High-Speed Transfer Client Admin Guide for Linux 19

 Security Option Description

Encryption Select the encryption cipher. Aspera supports three sizes of AES cipher keys
(128, 192, and 256 bits) and supports two encryption modes, cipher feedback
mode (CFB) and Galois/counter mode (GCM). The GCM mode encrypts data
faster and increases transfer speeds compared to the CFB mode, but the server
must support and permit it.
Cipher rules
The encryption cipher that you are allowed to use depends on the server
configuration and the version of the client and server:
• When you request a cipher key that is shorter than the cipher key that is
configured on the server, the transfer is automatically upgraded to the server
configuration. For example, when the server setting is AES-192 and you
request AES-128, the server enforces AES-192.
• When the server requires GCM, you must use GCM (requires version 3.9.0 or
newer) or the transfer fails.
• When you request GCM and the server is older than 3.8.1 or explicitly
requires CFB, the transfer fails.
• When the server setting is "any", you can use any encryption cipher. The only
exception is when the server is 3.8.1 or older and does not support GCM
mode; in this case, you cannot request GCM mode encryption.
• When the server setting is "none", you must use "none". Transfer requests
that specify an encryption cipher are refused by the server.
Cipher Values

Value Description Support

AES-128 Use the GCM or CFB All client and server versions.
AES-192 encryption mode, depending
AES-256 on the server configuration
and version (see cipher
negotiation matrix).

AES-128- Use the CFB encryption Clients version 3.9.0 and

CFB mode. newer, all server versions.
AES-192-
CFB
AES-256-
CFB

AES-128- Use the GCM encryption Clients and servers version

GCM mode. 3.9.0 and newer.
AES-192-
GCM
AES-256-
GCM

NONE Do not encrypt data in transit. All client and server versions.
Aspera strongly recommends
against using this setting.

Client-Server Cipher Negotiation

20 IBM Aspera Desktop Client 4.3

 Security Option Description

The following table shows which encryption mode is used depending on the
server and client versions and settings:

Server, Server, Server, Server,

v3.9.0+ v3.9.0+ v3.9.0+ v3.8.1 or
older
AES-XXX- AES-XXX- AES-XXX
GCM CFB AES-XXX

Client, v3.9.0+ GCM server GCM server

refuses refuses
AES-XXX-GCM
transfer transfer
Client, v3.9.0+ server refuses CFB CFB CFB
transfer
AES-XXX-CFB

Client, v3.9.0+ GCM CFB CFB CFB

AES-XXX

Client, v3.8.1 or server refuses CFB CFB CFB

older transfer
AES-XXX

Content Select Encrypt uploaded files with a password to encrypt the uploaded files
Protection with the specified password (client-side encryption at rest). The protected
file has the extension .aspera-env appended to the file name. Anyone
downloading the file must have the password to decrypt it.
Select Decrypt password-protected files downloaded to prompt for the
decryption password when downloading encrypted files.
For more information about client-side encryption at rest, see “Client-Side
Encryption-at-Rest (EAR)” on page 75.

11. Configure file handling, if needed.

On the File Handling tab, configure non-default transfer settings by editing any of the following
settings:

File Handling Description

Option
Resume Select Resume incomplete files to enable the resume feature. Select the file
comparison method from the When checking files for differences drop-down
menu:
• Compare file attributes - Compares the sizes of the existing and original file.
If they are the same, then the transfer resumes, otherwise the original file is
transferred again.
• Compare sparse file checksums - Performs a sparse checksum on the
existing file and resumes the transfer if the file matches the original,
otherwise the original file is transferred again. (Default)
• Compare full file checksums - Performs a full checksum on the existing
file and resumes the transfer if the file matches the original, otherwise the
original file is transferred again.

High-Speed Transfer Client Admin Guide for Linux 21

 File Handling Description
Option

Under When a complete file already exists at the destination, select an

overwrite rule when the same file exists at the destination. By default, files on
the destination are overwritten if different from the source.

File Attributes • Select Preserve Access Time to set the access time of the destination file to
the same value as that of the source file.
• Select Preserve Modification Timeto set the modification time of the
destination file to the same value as that of the source file.
• Select Preserve Source Access Time to keep the access time of the source
file the same as its value before the transfer.
Note: Access, modification, and source access times cannot be preserved for
node and Shares connections that are using cloud storage.

Source Handling Select Automatically delete source files after transfer to delete the files that
transferred successfully from the source.
Select Automatically move uploaded source files to a directory after
transfer and specify the location on the source machine to which they should
be moved. Only a path to an existing location on the client can be specified.
Select Delete empty source subdirectories to remove empty subdirectories
from the source once the files that they contain transfer successfully. This
option is usually used to clean up the Hot Folder when source files are moved
or deleted after transfer.

12. Click OK to save your changes.

Changes are not saved until you click OK. Selecting Cancel will discard any unsaved changes made in
the Connection Manager, including the addition and removal of connections.
13. Connect to the remote host.
Double-click the connection name, or select it and click Connect.

Editing and Deleting Connections

Click Connections and select the connection you want to edit or delete. Edit the settings or click to
delete the connection. Deleting connections cannot be undone. When in doubt, export the connections as
a backup before deleting a connection.

Exporting and Importing Connections

Connections, and optionally their passwords, can be exported and imported as a text file, and the text file
can be password protected.
Usage notes:
• If you are exporting a connection that uses SSH key authentication, back up the keys manually and
import separately. For instructions, see “Creating SSH Keys in the GUI” on page 23.
• A shared connection that is exported or imported by a non-administrator is imported as a regular
connection (not as a shared connection).
• Email templates are not exported with the connection.

22 IBM Aspera Desktop Client 4.3

 Export Connections
1. Right-click the remote server panel and click Export.

2. Enter the following information:

• Destination: Enter or browse to the location on your computer where to save the file.
• Options: The passwords associated with your connections can be exported. Select if you do not
want to export passwords, export passwords without obscuring the passwords (Export passwords
in clear), or export encrypted passwords (Encrypt passwords).
• Password: Required if Encrypt passwords is selected. When the connections are imported, use the
password to decrypt the connection passwords.
3. Click OK to export your connection information to the file.

Import Connections
1. Right-click the remote server panel and select Import.
2. Enter the following information:
• Source file: The file with the exported connections.
• Options: Select the appropriate option, depending on how the connections were exported.
• Password: If you select the Passwords are encrypted option, enter the password that was set when
the connections were exported.
3. Click OK to import the connection information.
4. Before deleting the source file, confirm that the import process was successful by testing your
connections.

Creating SSH Keys in the GUI

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. The client creates an SSH
key pair (a public key and a private key) and then sends the public key to the server's administrator. Once
the admin configures the server with the client's public key, the client can authenticate connections to the
server with their private key.
You can use the application GUI to generate key pairs and to import existing key pairs. You can also
generate key pairs using the command line; for instructions, see “Creating SSH Keys (Command Line)” on
page 71.
1. Launch the application.

# asperascp

2. In the menu bar, click Tools > Manage Keys.

High-Speed Transfer Client Admin Guide for Linux 23

 3. In the SSH Keys dialog, click to create a new key pair.

The SSH Keys dialog is also available from the Connection tab in the Connection Manager. When you
select Public Key for authentication, the Manage Keys button appears; clicking it opens the SSH Keys
dialog.
4. In the New SSH Key Pair window, enter the requested information.

Field Description
Identity Name your key pair, such as with your user name.
Passphrase (Optional) Set a passphrase on your SSH key, which will be prompted for
whenever it needs to use the key. If you don't want the user to be prompted
for passphrase when logging in, leave this field blank.
Type Select RSA (default) or ECDSA key.
Access When sharing a connection with public key authentication, or a connection that
is has a Hot Folder (on Windows machines), this option must be checked.

24 IBM Aspera Desktop Client 4.3

5. Click OK to create the key.
The public key is displayed in the window and you can copy it to a clipboard or export it to a file that
is easy to locate. The key is automatically saved as a file named id_key_type.pub in the following
location (in the example below, the public key filename is id_rsa.pub):
/home/username/.ssh/id_rsa.pub
6. Distribute the public key.
Provide the public key file to your server administrator so that it can be set up for your server
connection.
To copy or export the public key, select the key in the SSH Keys window, click Copy Public Key to
Clipboard, and paste the string into an email to send to the server administrator, or click Export to File
and save the public key as a file.

7. Set up connections using public key authentication.

Note: Your public key must be configured on the server before you can connect with it.
a) Click Connections to open the Connection Manager.

High-Speed Transfer Client Admin Guide for Linux 25

 b) Select the connection for which you want to set up the key.
c) In the Connection tab, select the Public Key Authentication option and select the key from the
drop-down menu.

Importing keys:
To import keys created outside the GUI, go to Tools > Manage Keys to open the SSH Keys dialog. Click
the button in the upper-left corner of the dialog to open a file browser. You can import the key pair by
selecting either the private key or the public key; this will copy both keys into the user's .ssh directory.
You cannot import a key pair if a key pair with the same identity already exists in the .ssh directory.

Imported key pairs can be shared with other users. In the SSH Keys dialog, select a key and click the
button to open the Edit SSH Key Pair dialog. Select Access to allow shared connections to use this key.
Shared keys are moved to the Aspera etc directory.

Transferring Content
The GUI provides an easy, intuitive way to transfer content between the local computer and a remote
host.
Note: Do not use the following characters in file or folder names:

/ \ " : ' ? > < & * |

They can produce unpredictable transfer behavior.

1. If you have not already created a connection, create one.
For instructions, see “Adding and Editing Connections” on page 15.
2. Select the remote server under Connection Name.

26 IBM Aspera Desktop Client 4.3

 3. For uploads, if the target directory is correct, then you can select the content to upload from the local
file tree and either drag-and-drop the content into the connection pane, or click the upload arrow. If
you want to browse the remote file system or download content from it, go on to the next step.

4. Connect to the remote server by either double-clicking the connection name, or select it and click
Connect.
5. Select the content to transfer (from the local or remote file system) and do any of the following:
• click the upload or download arrow
• drag and drop the files between the windows
• copy and paste the files between the windows

6. Once a transfer is started, you can manage the transfer rate, transfer policy, and priority. For
information, see “Managing Transfers” on page 27.

Managing Transfers
The Desktop Client GUI enables you to start, stop, and reorder transfers, as well as adjust transfer rates
and policies and configure transfer preferences.

The Transfers Panel: Start, Stop, and Reorder Transfers

Once the transfer starts, a progress bar appears in the Transfers panel. You can manage transfer behavior
with the following actions:
Click to start the selected transfer.
Click to stop the selected transfer.
Click to delete the selected transfer.
If you have multiple ongoing transfers, use the and to change the selected transfer's priority. The
# field indicates the transfer's order in the queue.

High-Speed Transfer Client Admin Guide for Linux 27

 The Details View: Adjust Transfer Rates and Policies of Active Transfers
The Details button provides additional oversight and control (if you have permission) over transfers.
Select a transfer session from the Transfers panel and click Details to view details and adjust settings.

The Details display shows the following information:

Item Name Description

A Details (tab) Transfer details, including status (rate and ETA) and statistics (session
size, files transferred vs. total files to be transferred, average speed, time
elapsed, RTT delay and average loss in percent).
B Files (tab) All files being transferred in this session, along with each files' size and
transfer progress.
C Transfer controls Set the FASP transfer policy and transfer rate, if allowed.
• high - Adjust the transfer rate to fully utilize the available bandwidth
up to the maximum rate. When congestion occurs, the transfer rate
is twice as fast as a fair-policy transfer. The high policy requires
maximum (target) and minimum transfer rates.
• fair - Adjust the transfer rate to fully utilize the available bandwidth
up to the maximum rate. When congestion occurs, bandwidth is
shared fairly by transferring at an even rate. The fair policy requires
maximum (target) and minimum transfer rates.
• low - Adjust the transfer rate to use the available bandwidth up to
the maximum rate. Similar to fair mode, but less aggressive when
sharing bandwidth with other network traffic. When congestion occurs,
the transfer rate is reduced to the minimum rate until other traffic
decreases.
• fixed - Attempt to transfer at the specified target rate, regardless of
network or storage capacity. This can decrease transfer performance
and cause problems on the target storage. Aspera discourages using
the fixed policy except in specific contexts, such as bandwidth
testing. The fixed policy requires a maximum (target) rate.
• aggressiveness - The aggressiveness of transfers that are
authorized by this access key in claiming available bandwidth. Value
can be 0.00-1.00. For example: These values correspond to the policy
option where a policy of high approximates to aggressiveness of 0.75,
fair to 0.50 and low to 0.25. Aggressiveness can be used if there is a
need to fine tune the transfer policy.

28 IBM Aspera Desktop Client 4.3

 Item Name Description

Important: If --policy is not set, ascp uses the server-side policy

setting (fair by default).

D Transfer Monitor The transfer graph. Use the sliders on the vertical axis to adjust the
transfer rate up or down (if allowed).

Configuring Transfer Preferences

If you have administrator privileges, you can set the target transfer rate for all users from the Global
Preferences dialog. As an individual user, you can override the global settings from My Preferences.
To update these settings, go to Tools > Global Preferences or Tools > Preferences. You can also open
My Preferences from the Preferences button in the upper-right corner of the application's main window;
from there you can also reach the Global Preferences dialog by clicking Global Preferences.

The following options are available under the Transfers tab:

Item Description
Global Bandwidth Limits The aggregated bandwidth cap for all FASP transfers on this computer.
Default Target Rate The initial download and upload rates for all transfers.
Maximum Active Transfers The maximum number of concurrent upload transfers and download
transfers.

For information about Email settings, see “Configuring Transfer Notifications” on page 31.

Scheduling and Customizing Transfers in Advanced Mode

You can start a transfer in advanced mode to set per-session transfer options such as filters, security,
which override the default transfer settings. You can also schedule the transfer as a one-time transfer or
recurring.
1. In the GUI, right-click a file or folder to open the context menu and select Upload (in the client panel)
or Download (in the server panel).

High-Speed Transfer Client Admin Guide for Linux 29

 2. Configure the transfer settings, as needed.
The advanced transfer configuration options except Scheduling are identical to those in the
Connection Manager. For information on these tabs, see “Adding and Editing Connections” on page
15. The Scheduling tab is described in the next step.

Tab Description
Transfer The transfer session-related options, such as the transfer speed and retry rules.
Tracking Options for tracking the transfer session, including the confirmation receipt and the
email notifications.
Filters Create filters to skip or include files that match certain patterns.
Security Enable the transfer encryption and the content protection.
File Handling Set up resume rule, preserve transferred file attributes, and remove or move source
files.
Scheduling Schedule the transfer.
3. Schedule the transfer.
Note: When scheduling transfers, ensure that the Desktop Client GUI stays open and running.
Scheduled transfers do not run when the application is closed.
To enable transfer scheduling, select Schedule this transfer.

The following scheduling options are available in the Transfer repeats drop-down menu:
Does not repeat
Set the time and date for a single transfer.

30 IBM Aspera Desktop Client 4.3

 Daily
Set the time for a daily transfer. For End repeat, select Never to continue daily transfers
indefinitely, or On and set an end date and time.
Monday-Friday
Set the time for a daily transfer only on weekdays. For End repeat, select Never to continue daily
transfers indefinitely, or On and set an end date and time.
Weekly
Select the time and days of the week for a repeating transfer. For End repeat, select Never to
continue weekly transfers indefinitely, or On and set an end date and time.
Periodically
Set the frequency to repeat the transfer, in minutes.
4. Click Transfer to submit the scheduled transfer.
The transfer is then listed under the Transfers tab, along with an icon ( ) under the # column.
5. To modify the transfer, right-click the row and click Edit

Configuring Transfer Notifications

Transfer notification emails are triggered by three transfer session events: start, completion, and error.
Transfer notification emails can be enabled and configured globally and by each user. The emails are
generated from mail templates that can be customized.
Note: The GUI must remain open for transfer notification emails to send. Closing the GUI stops email
notifications.

Enable Email Notifications

1. Run Desktop Client with root permissions.

# asperascp

2. To configure global email notification settings:

a) Click Tools > Global Preferences.

High-Speed Transfer Client Admin Guide for Linux 31

 b) Click Mail.

c) To turn on email notifications for all users, select Enable email notifications.
Enter the email address from which the notifications are sent in the From Address field and enter
the outgoing email server host name in the Host field. The other values are optional.
d) To test your settings, click Send test email, which sends a test message to the From Address.
3. Set your personal mail preferences.
Personal mail preferences override global settings.
a) Click Preferences.
b) Click Mail and edit the inherited global default values.
To restore your settings to global values, click Restore Defaults.

Configure Email Templates

1. Open the Mail Templates window by clicking Tools > Mail Templates.

32 IBM Aspera Desktop Client 4.3

2. To create a new template, click , or to edit an existing template, select the template and click

3. For new templates, name the template and select its base template.
Select an existing template from the Based On menu. Click OK.
4. Edit the template text.
The Edit Template window has four fields:

Field Description
Name The template name.
HTML The HTML mail body. Click Insert Image to insert an image into the template.
The image is copied to the template directory. Preview the template by clicking
Preview.
Text The plain text mail body. Preview the template by clicking Preview.
Access Select Share this template with all users on this computer to allow other
system users to access this template.

High-Speed Transfer Client Admin Guide for Linux 33

 The mail template supports MIME (Multipurpose Internet Mail Extensions) multipart messages.
You can edit both the HTML and plain text versions of the mail body. The templates are
rendered by Apache Velocity (for more information, see the Apache Velocity User Guide at http://
velocity.apache.org/). Templates use two predefined variables:
• $formatter - Contains some utility methods
• $notifications - Holds the transfer notifications
To iterate over notifications, use a foreach loop. A foreach loop generates content for each iteration
of the loop. In the following example, a local $event variable is declared for use within the foreach
loop:

#foreach ($event in $notifications.getEvents())

...
#end

To generate content only under specific conditions, use a conditional statement. To construct a
conditional statement, use #if, #else, and #end, with the following syntax:

#if
...
#else
...
#end

All conditional statements are categorized in four parts: the conditional (what must occur to trigger the
action), session information (what action is triggered), time, and statistics.
Conditional
Use conditional tests in an if statement. For example:

#if ($event.isFailed())
...
#end

Statement Description
$event.isStarted() If the transfer session is started.

34 IBM Aspera Desktop Client 4.3

Statement Description
$event.isCompleted() If the transfer session is completed.
$event.isEnded() If the transfer session is ended.
$event.isFailed() If the transfer session is failed.

Session Information

Statement Description
$event.getSourceHost() The source host name (or host address if the host
name is not discoverable).
$event.getSourceHostAddress() The source host address.
$event.getSourcePaths() The source file path.
$event.getDestinationHost() The destination host name (or host address if the host
name is not discoverable).
$event.getDestinationHostAddress() The destination host address.
$event.getDestinationPath() The destination file path.
$event.getInitiatingHost() The session-initiating host name (or host address if
the host name is not discoverable).
$event.getInitiatingHostAddress() The session-initiating host address.
$event.getId() The session ID.
$event.getName() The session name.
$event.getType().getDescription() The session state. Three outputs: "STARTED",
"FAILED", and "COMPLETED".
$event.getUser() The transfer login.
$event.getFiles() The files that are being transferred. Use this
statement in a foreach loop: (Any text after ## is
a comment)

#foreach ($file in $event.getFiles())

## $file is a new variable visible in this
foreach loop.
## $file holds the complete file path and
file name.
## $formatter.decodePath() is used to ensure
a correct string decoding.
$formatter.decodePath($file)
#end

Use the counter $velocityCount in an if

statement to limit the output file count. For example,
to list only the first ten files:

#foreach ($file in $event.getFiles())

#if ($velocityCount > 10)
#break
#end
$file
#end

$event.getMessage() The message that is entered in the email Message

field.

High-Speed Transfer Client Admin Guide for Linux 35

 Statement Description
$event.getError() The error message.

Time

Statement Description
$formatter.date(var, Formatting the date and time output. Enter three values in the
"lang", "format") parenthesis:
• var is either $event.getStartTime() or
$event.getEndTime()
• lang is an abbreviated language name; for example, en for English.
• format is the display format. Use these symbols:
– yyyy The year; for example, 2010.
– MM Month of the year; for example, 03.
– dd Day of the month; for example, 26.
– HH Hour of the day; for example, 16.
– mm Minute.
– ss Second.
– z Time zone.
– EEE The abbreviated weekday name; for example, Fri.
For example,

"EEE, yyyy-MM-dd HH:mm:ss z"

shows Fri, 2010-03-26 16:19:01 PST.

$event.getStartTime() The session start time.

$event.getEndTime() The session end time.

Statistics

Statement Description
$event.getSourceFileCount() The number of source files.
$event.getCompletedFileCount() The number of files that successfully transferred.
$event.getFailedFileCount() The number of files that failed to transfer.
$event.getAverageRatePercentage() The average transfer rate in bps. Enclose this
statement with $formatter.formatRate() to
simplify the output.
$event.getAverageLossPercentage() The average packet loss percentage.
$event.getSourceSizeB() The source file size. Enclose this statement with
$formatter.toBestUnit() to simplify the output.
$event.getTransferredB() The transferred file size. Enclose this statement with
$formatter.toBestUnit() to simplify the output.
$event.getWrittenB() The destination file size. Enclose this statement with
$formatter.toBestUnit() to simplify the output.
5. Click OK to save your changes.

36 IBM Aspera Desktop Client 4.3

 Apply the notifications to a specific connection host or a transfer session. You can also customize the
subject line of the notification emails. For details, see “Using Transfer Notifications” on page 37.

Using Transfer Notifications

Transfer notifications can be emailed to a set list of recipients upon transfer start, complete, and
error. The email templates can be fully customized. These instructions describe how to configure email
notifications for all transfers to and from a specific connection.
1. Preview existing mail templates and create new ones, if needed.
a) Click Tools > Mail Templates to open the Mail Template window.
b) Select an existing template and click .
c) In the Edit Template window, click Preview to view the template's output example.
For instructions on how to create a new template or edit an existing one, see “Configuring Transfer
Notifications” on page 31.
2. Enable email notifications for connections.
a) Click Connections on the main page of the application, select the connection that you want to
configure with email notifications, and go to the Tracking tab.

b) Select Send email notifications, and configure the following settings:

Item Description
When Check the events for which to send notifications.
Subject Customize the subject line, which can use the same template fields as
described in “Configuring Transfer Notifications” on page 31.
To Enter the recipients, comma separated.
Template Select a mail template.
Message Optionally enter a message to include in the notifications.
c) Click OK to save your changes.

High-Speed Transfer Client Admin Guide for Linux 37

ascp: Transferring from the Command Line
Ascp is a scriptable FASP transfer binary that enables you to transfer to and from Aspera transfer servers
to which you have authentication credentials. Transfer settings are customizable and can include file
manipulation on the source or destination, filtering of the source content, and client-side encryption-at-
rest.

Ascp Command Reference

The ascp executable is a command-line FASP transfer program. This reference describes ascp syntax,
command options, and supported environment variables.
For examples of ascp commands, see the following topics:
• “Ascp General Examples” on page 53
• “Ascp File Manipulation Examples” on page 56
• “Ascp Transfers with Object Storage and HDFS” on page 58
Another command-line FASP transfer program, Ascp4, is optimized for transfers of many small files.
It has many of the same capabilities as ascp, as well as its own features. For more information, see
“Introduction to Ascp4” on page 81 and “Comparison of Ascp and Ascp4 Options” on page 76.

Ascp Syntax
ascp options [[username@]src_host:]source1[ source2 ...] [[username@]dest_host:]dest_path

username
The username of the Aspera transfer user can be specified as part of the source or destination,
whichever is the remote server. It can also be specified with the --user option. If you do not specify
a username for the transfer, the local username is authenticated by default.
Note: If you are authenticating on a Windows computer as a domain user, the transfer server
strips the domain from the username. For example, Administrator is authenticated rather than
DOMAIN\Administrator. For this reason, you must specify the domain explicitly.
src_host
The name or IP address of the computer where the files or directories to be transferred reside.
source
The file or directory to be transferred. Separate multiple arguments with spaces.
The growing files feature can be used with the source option to start transferring files to the target
directory while they are still being written to the source directory.
Note: To use the growing files feature, the source file must be on a native file system. Growing files
cannot be larger than 8 exabyte - 1 (9,223,372,036,854,775,807 bytes). However, the maximum file
size of the file system will override a setting that is larger.
Growing files use can also be configured statically with aspera.conf, see aspera.conf - File System
Configuration. See also “Ascp General Examples” on page 53.
To use the growing files feature with ascp, the source parameter can be used with the following
syntax:

source?grow=wait_time[&wait_start=[mtime | null_read]][[&confirm_stop=[ true | false ]]

A file transfer is deemed to be complete when the time since last update to the source file reaches the
wait_time value (in seconds). However, the time is only sampled when all currently available source
data has been transferred. In other words, if more data arrives after the wait time has elapsed, but the
transfer is still in progress, the additional data will still be transferred.

38 IBM Aspera Desktop Client 4.3

 grow
Enables the growing file feature and is used to set the wait time in seconds. The wait time is the
amount of time that is allowed to pass before a file that is not changing is treated as complete.
The grow element must be set to a non-negative integer to define wait time. If it is set to a
non-numeric string, the default wait time of 10 seconds is used.
wait_start
Can be used to specify how time is calculated to determine if a file is complete. If mtime is used,
then the file modification time is used when calculating the wait time. If null_read is used, then
the time of a file read that returns zero bytes is used. The default is mtime.
confirm_stop
Can be used to indicate when all the data has been added to the source file and to prevent any
additional wait time following a read of EOF.
Note that confirm_stop is ignored if wait_start is set to null_read.
To use confirm_stop, set it to true (the default is false). Then use an external program to
adjust the source file mtime upon completion of writing data to the source file, using the following
criteria:

mtime < current_system_time - wait_time, mtime != 0

Any value for mtime that meets this criteria is acceptable to flag this condition except mtime =
0,which is used to flag a file error. You can, for example, use touch 1. If mtime is not adjusted
before the timeout is reached, an error will be generated.
An alternative method for defining the wait_time value is to use modifiers for powers of 1,024.
However, the value must be less than 8 * 2^60. The modifier must consist of an integer, and a unit
specifier. The unit specifiers are:
• k or K for 1 * 1024
• m or M for 1 * 1024 * 1024
• g or G for 1 * 1024 * 1024 * 1024
dest_host
The name or IP address of the computer where the source files or directories are to be transferred.
dest_path
The destination directory where the source files or directories are to be transferred.
• If the source is a single file, the destination can be a filename. However, if there are multiple source
arguments, the destination must be a directory.
• To transfer to the transfer user's docroot, specify "." as the destination.
• If the destination is a symbolic link, then the file or directory is written to the target of the symbolic
link.

Specifying Files, Directories, and Paths

• Specify paths on the remote computer relative to the transfer user's docroot. If the user has a
restriction instead of a docroot, specify the full path, which must be allowed by the restriction.
• Avoid the following characters in file and directory names: / \ " : ' ? > < & * |
• Specify paths with forward-slashes, regardless of the operating system.
• If directory or file arguments contain special characters, specify arguments with single-quotes (' ') to
avoid interpretation by the shell.
URI Paths
URI paths are supported, but with the following restrictions:
• If the source paths are URIs, they must all be in the same cloud storage account. No docroot
(download), local docroot (upload), or source prefix can be specified.

High-Speed Transfer Client Admin Guide for Linux 39

 • If a destination path is a URI, no docroot (upload) or local docroot (download) can be specified.
• The special schemes stdio:// and stdio-tar:// are supported on the client side only. They cannot
be used for specifying an upload destination or download source.
• If required, specify the URI passphrase as part of the URI or set it as an environment variable
(ASPERA_SRC_PASS or ASPERA_DST_PASS, depending on the transfer direction).
UNC Paths
If the server is Windows and the path on the server is a UNC path (a path that points to a shared directory
or file on Windows), it can be specified in an ascp command using one of the following conventions:
• As an UNC path that uses backslashes ( \ ): If the client side is a Windows computer, the UNC path
can be used with no alteration. For example, \\192.168.0.10\temp. If the client is not a Windows
computer, every backslash in the UNC path must be replaced with two backslashes. For example, \\\
\192.168.0.10\\temp.
• As an UNC path that uses forward slashes ( / ): Replace each backslash in the UNC path with a forward
slash. For example, if the UNC path is \\192.168.0.10\temp, change it to //192.168.0.10/temp.
This format can be used with any client-side operating system.
Testing Paths
To test ascp transfers, use a faux:// argument in place of the source or target path to send random
data without writing it to disk at the destination. For more information, see . For examples, see “Ascp
General Examples” on page 53.
Websocket Protocol
The Websocket protocol can be used instead of SSH or HTTPS for client connections with the transfer
server. In order to use it, you must configure aspera.conf specifically for Websocket use. Then for
transfers, you must use the ascp --ws-connect option to specify using Websocket, and the -P option to
specify the Websocket port (9093).

Required File Access and Permissions

• Sources (for downloads) or destinations (for uploads) on the server must be in the transfer user's
docroot or match one of the transfer user's file restrictions, otherwise the transfer stops and returns an
error.
• The transfer user must have sufficient permissions to the sources or destinations, for example write
access for the destination directory, otherwise the transfer stops and returns a permissions error.
• The transfer user must have authorization to do the transfer (upload or download), otherwise the
transfer stops and returns a "management authorization refused" error.
• Files that are open for write by another process on a Windows source or destination cannot be
transferred and return a "sharing violation" error. On Unix-like operating systems, files that are open
for write by another process are transferred without reporting an error, but may produce unexpected
results depending on what data in the file is changed and when relative to the transfer.

Environment Variables
The following environment variables can be used with the ascp command. The total size for environment
variables depends on your operating system and transfer session. Aspera recommends that each
environment variable value should not exceed 4096 characters.
ASPERA_DST_PASS=password
The password to authenticate a URI destination.
ASPERA_LOCAL_TOKEN=token
A token that authenticates the user to the client (in place of SSH authentication).
Note: If the local token is a basic or bearer token, the access key settings for cipher and
preserve_time are not respected and the server settings are used. To set the cipher and timestamp
preservation options as a client, set them in the command line.

40 IBM Aspera Desktop Client 4.3

ASPERA_PROXY_PASS=proxy_server_password
The password for an Aspera Proxy server.
ASPERA_SCP_COOKIE=cookie
A cookie string that you want associated with transfers.
ASPERA_SCP_DOCROOT=docroot
The transfer user docroot. Equivalent to using --apply-local-docroot when a docroot is set in
aspera.conf.
ASPERA_SCP_FILEPASS=password
The passphrase to be used to encrypt or decrypt files. For use with --file-crypt.
ASPERA_SCP_KEY="-----BEGIN RSA PRIVATE KEY..."
The transfer user private key. Use instead of the -i option.
ASPERA_SCP_PASS=password
The password for the transfer user.
ASPERA_SCP_TOKEN=token
The transfer user authorization token. Overridden by -W.
ASPERA_SRC_PASS=password
The password to authenticate to a URI source.

Ascp Options
-6
Enable IPv6 address support. When specifying an IPv6 numeric host for src_host or dest_host, write
it in brackets. For example, username@[2001:0:4137:9e50:201b:63d3:ba92:da]:/path or
--host=[fe80::21b:21ff:fe1c:5072%eth1].
-@ range_start:range_end
Transfer only part of a file: range_start is the first byte to send, and range_end is the last. If either
position is unspecified, the file's first and last bytes (respectively) are assumed. This option only works
for downloads of a single file and does not support transfer resume.
-A, --version
Display version and license information.
--apply-local-docroot
Apply the local docroot that is set in aspera.conf for the transfer user. Use to avoid entering object
storage access credentials in the command line. This option is equivalent to setting the environment
variable ASPERA_SCP_DOCROOT.
-C nodeid:nodecount
Enable multi-session transfers (also known as parallel transfers) on a multi-node/multi-core system.
A node ID (nodeid) and count (nodecount) are required for each session. nodeid and nodecount can
be 1-128, but nodeid must be less than or equal to nodecount, such as 1:2, 2:2. Each session must
use a different UDP port specified with the -O option. Large files can be split across sessions, see
--multi-session-threshold. For more information, see the IBM Aspera High-Speed Transfer
Server.
-c cipher
Encrypt in-transit file data using the specified cipher. Aspera supports three sizes of AES cipher
keys (128, 192, and 256 bits) and supports two encryption modes, cipher feedback mode (CFB)
and Galois/counter mode (GCM). The GCM mode encrypts data faster and increases transfer speeds
compared to the CFB mode, but the server must support and permit it.
Cipher rules
The encryption cipher that you are allowed to use depends on the server configuration and the version
of the client and server:
• When you request a cipher key that is shorter than the cipher key that is configured on the server,
the transfer is automatically upgraded to the server configuration. For example, when the server
setting is AES-192 and you request AES-128, the server enforces AES-192.

High-Speed Transfer Client Admin Guide for Linux 41

 • When the server requires GCM, you must use GCM (requires version 3.9.0 or newer) or the transfer
fails.
• When you request GCM and the server is older than 3.8.1 or explicitly requires CFB, the transfer
fails.
• When the server setting is "any", you can use any encryption cipher. The only exception is when the
server is 3.8.1 or older and does not support GCM mode; in this case, you cannot request GCM mode
encryption.
• When the server setting is "none", you must use "none". Transfer requests that specify an encryption
cipher are refused by the server.
Cipher Values

Value Description Support

Use the GCM or CFB encryption mode, All client and server versions.
aes128
depending on the server configuration
aes192
and version (see cipher negotiation
aes256
matrix).
Use the CFB encryption mode. Clients version 3.9.0 and newer, all
aes128cfb
server versions.
aes192cfb
aes256cfb

Use the GCM encryption mode. Clients and servers.

aes128gcm
aes192gcm
aes256gcm

none Do not encrypt data in transit. Aspera All client and server versions.
strongly recommends against using
this setting.

Client-Server Cipher Negotiation

The following table shows which encryption mode is used depending on the server and client versions
and settings:

Server, v3.9.0+ Server, v3.9.0+ Server, Server, v3.8.1 or

v3.9.0+ older
AES-XXX-GCM AES-XXX-CFB
AES-XXX AES-XXX

Client, v3.9.0+ GCM server refuses GCM server refuses

transfer transfer
AES-XXX-GCM

Client, v3.9.0+ server refuses CFB CFB CFB

transfer
AES-XXX-CFB

Client, v3.9.0+ GCM CFB CFB CFB

AES-XXX

Client, v3.8.1 or older server refuses CFB CFB CFB

transfer
AES-XXX

--check-sshfp=fingerprint
Compare fingerprint to the server SSH host key fingerprint that is set with
<ssh_host_key_fingerprint> in aspera.conf. Aspera fingerprint convention is to use a hex

42 IBM Aspera Desktop Client 4.3

 string without the colons; for example, f74e5de9ed0d62feaf0616ed1e851133c42a0082. For more
information on SSH host key fingerprints, see the IBM Aspera High-Speed Transfer Server.
Note: If HTTP fallback is enabled and the transfer "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.
-D | -DD | -DDD
Log at the specified debug level. With each D, an additional level of debugging information is written to
the log.
-d
Create the destination directory if it does not already exist. This option is automatically applied to
uploads to object storage.
--delete-before-transfer
Before transfer, delete any files that exist at the destination but not also at the source. The source
and destination arguments must be directories that have matching names. Do not use with multiple
sources, keepalive, URI storage, or HTTP fallback. The asdelete tool provides the same capability.
--dest64
Indicate that the destination path or URI is base64 encoded.
-E 'pattern'
Exclude files or directories from the transfer based on matching the specified pattern to file names
and paths (to exclude files by modification time, use --exclude-newer-than or --exclude-
older-than). Use the -N option (include) to specify exceptions to -E rules. Rules are applied in
the order in which they are encountered, from left to right. The following symbols can be used in the
pattern:
• * (asterisk) represents zero or more characters in a string, for example *.tmp matches .tmp and
abcde.tmp.
• ? (question mark) represents a single character, for example t?p matches tmp but not temp.
For details and examples, see “Using Filters to Include and Exclude Files” on page 64.
Note: When filtering rules are found in aspera.conf, they are applied before rules given on the
command line (-E and -N).
-e prepost_script
Run the specified pre-post script as an alternate to the default aspera-prepost script. Specify the
full path to the pre-post script. Use pre-post scripts to run custom commands such as shell scripts,
Perl scripts, Windows batch files, and executable binaries that can invoke a variety of environment
variables. For instructions, see the IBM Aspera High-Speed Transfer Server Admin guide.
--exclude-newer-than=mtime, --exclude-older-than=mtime
Exclude files (but not directories) from the transfer, based on when the file was last modified.
Positive mtime values are used to express time, in seconds, since the original system time (usually
1970-01-01 00:00:00). Negative mtime values (prefixed with "-") are used to express the number of
seconds prior to the current time.
-f config_file
Read Aspera configuration settings from config_file rather than aspera.conf(the default).
--file-checksum=hash
Enable checksum reporting for transferred files, where hash is the type of checksum to calculate:
sha1, md5, sha-512, sha-384, sha-256, or none (the default). When the value is none, the
checksum that is configured on the server, if any, is used. For more information about checksum
reporting, see IBM Aspera High-Speed Transfer Server Admin Guide: Reporting Checksums.
Important: When checksum reporting is enabled, transfers of very large files (>TB) take a long time to
resume because the entire file must be reread.
--file-crypt={encrypt|decrypt}
Encrypt files (when sending) or decrypt files (when receiving) for client-side encryption-at-rest
(EAR). Encrypted files have the file extension .aspera-env. This option requires the encryption/

High-Speed Transfer Client Admin Guide for Linux 43

 decryption passphrase to be set with the environment variable ASPERA_SCP_FILEPASS. If a client-
side encrypted file is downloaded with an incorrect password, the download is successful, but the
file remains encrypted and still has the file extension .aspera-env. For more information, see
“Client-Side Encryption-at-Rest (EAR)” on page 75.
--file-list=file
Transfer all source files and directories listed in file. Each source item is specified on a separate line.
UTF-8 file format is supported. Only the files and directories are transferred. Path information is not
preserved at the destination. To read a file list from standard input, use "-" in place of file.
For example, if list.txt contains the following list of sources:

/tmp/code/compute.php
doc_dir
images/iris.png
images/rose.png

and the following command is run:

# ascp --file-list=list.txt --mode=send --user=username --host=ip_addr .

then the destination, in this case the transfer user's docroot, will contain the following:

compute.php
doc_dir (and its contents)
iris.png
rose.png

Restrictions:
• The command line cannot use the user@host:source syntax. Instead, specify this information
with the options --mode, --host, and --user.
• Paths specified in the file list cannot use the user@host:source syntax.
• Because multiple sources are being transferred, the destination must be a directory.
• Only one --file-list or --file-pair-list option is allowed per ascp session. If multiple lists
are specified, only the last one is used.
• Only files and directories specified in the file list are transferred; any sources specified on the
command line are ignored.
• If the source paths are URIs, the size of the file list cannot exceed 24 KB.
To create a file list that also specifies destination paths, use --file-pair-list.
--file-manifest={none|text}
Generate a list of all transferred files when set to text. Requires --file-manifest-path to specify
the location of the list. (Default: none)
--file-manifest-path=directory
Save the file manifest to the specified location when using --file-manifest=text. File manifests
must be stored locally. For cloud or other non-local storage, specify a local manifest path.
--file-manifest-inprogress-suffix=suffix
Apply the specified suffix to the file manifest's temporary file. For use with --file-manifest=text.
(Default suffix: .aspera-inprogress)
--file-pair-list=file
Transfer files and directories listed in file to their corresponding destinations. Each source is specified
on a separate line, with its destination on the line following it.
Specify destinations relative to the transfer user's docroot. Even if a destination is specified as an
absolute path, the path at the destination is still relative to the docroot. Destination paths specified in
the list are created automatically if they do not already exist.

44 IBM Aspera Desktop Client 4.3

 For example, if the file pairlist.txt contains the following list of sources and destinations:

Dir1
Dir2
my_images/iris.png
project_images/iris.png
/tmp/code/compute.php
/tmp/code/compute.php
/tmp/tests/testfile
testfile2

and the following command is run:

# ascp --file-pair-list=pairlist.txt --mode=send --user=username --host=ip_addr .

then the destination, in this case the transfer user's docroot, now contains the following:

Dir2 (and its contents)

project_images/iris.png
tmp/code/compute.php
testfile2

Restrictions:
• The command line cannot use the user@host:source syntax. Instead, specify this information
with the options --mode, --host, and --user.
• The user@host:source syntax cannot be used with paths specified in the file list.
• Because multiple sources are being transferred, the destination specified on the command line
must be a directory.
• Only one --file-pair-list or --file-list option is allowed per ascp session. If multiple lists
are specified, only the last one is used.
• Only files from the file pair list are transferred; any additional source files specified on the command
line are ignored.
• If the source paths are URIs, the file list cannot exceed 24 KB.
For additional examples, see “Ascp General Examples” on page 53.
-G write_size
If the transfer destination is a server, use the specified write-block size, which is the maximum
number of bytes that the receiver can write to disk at a time. Default: 256 KB, Range: up to 500 MB.
This option accepts suffixes "M" or "m" for mega and "K" or "k" for kilo, such that a write_size of 1M is
one MB.
This is a performance-tuning option that overrides the write_block_size set in the client's
aspera.conf. However, the -G setting is overridden by the write_block_size set in the
server's aspera.conf. The receiving server never uses the write_block_size set in the client's
aspera.conf.
-g read_size
If the transfer source is a server, use the specified read-block size, which is the maximum number of
bytes that the sender reads from the source disk at a time. Default: 256 KB, Range: up to 500 MB. This
option accepts suffixes "M" or "m" for mega and "K" or "k" for kilo, such that a read_size of 1M is one
MB.
This is a performance-tuning option that overrides the read_block_size set in the client's
aspera.conf. However, the -g setting is overridden by the read_block_size set in the server's
aspera.conf. When set to the default value, the read size is the default internal buffer size of the
server, which might vary by operating system. The sending server never uses the read_block_size
set in the client's aspera.conf.
-h, --help
Display the help text.

High-Speed Transfer Client Admin Guide for Linux 45

 --host=hostname
Transfer to the specified host name or address. Requires --mode. This option can be used instead of
specifying the host with the hostname:file syntax.
-i private_key_file | cert_file
The -i option can be used to specify either:
• an SSH private key file, for authenticating a transfer using public key authentication with the
specified SSH private key file. The argument can be just the filename if the private key is located in
user_home_dir/.ssh/, because ascp automatically searches for key files there. Multiple private
key files can be specified by repeating the -i option. The keys are tried in order and the process
ends when a key passes authentication or when all keys have been tried without success, at which
point authentication fails.
• a Certificate Authority certificate, for use with fallback transfers or with Websocket use, when you
do not want to use the system default certificate.
-K probe_rate
Measure bottleneck bandwidth at the specified probing rate (Kbps). (Default: 100Kbps)
-k {0|1|2|3}
Enable the resuming of partially transferred files at the specified resume level. (Default: 0)
Specify this option for the first transfer or it will not work for subsequent transfers. Resume levels:
-k 0 – Always re-transfer the entire file.
-k 1 – Compare file attributes and resume if they match, and re-transfer if they do not.
-k 2 – Compare file attributes and the sparse file checksums; resume if they match, and re-
transfer if they do not.
-k 3 – Compare file attributes and the full file checksums; resume if they match, and re-transfer if
they do not.
If a complete file exists at the destination (no .aspx), the source and destination file sizes are
compared. If a partial file and a valid .aspx file exist at the destination, the source file size and the
file size recorded in the .aspx file are compared.
Note: If the destination is a URI path, then the only valid options are -k 0 and -k 1 and no .aspx
file is created.
-L local_log_dir[:size]
Log to the specified directory on the client computer rather than the default directory. Optionally, set
the size of the log file (Default: 10 MB). See also -R for setting the log directory on the server.
-l max_rate
Transfer at rates up to the specified target rate. (Default: 10000 Kbps) This option accepts suffixes "G"
or "g" for giga, "M" or "m" for mega, "K" or "k" for kilo, and "P", "p", or "%" for percentage. Decimals
are allowed. If this option is not set by the client, the setting in the server's aspera.conf is used. If a
rate cap is set in the local or server aspera.conf, the rate does not exceed the cap.
-m min_rate
Attempt to transfer no slower than the specified minimum transfer rate. (Default: 0) If this option is
not set by the client, then the server's aspera.conf setting is used. If a rate cap is set in the local or
server aspera.conf, then the rate does not exceed the cap.
--mode={send|recv}
Transfer in the specified direction: send or recv (receive). Requires --host.
--move-after-transfer=archivedir
Move source files and copy source directories to archivedir after they are successfully transferred.
Because directories are copied, the original source tree remains in place. The transfer user must
have write permissions to the archivedir. The archivedir is created if it does not already exist. If the
archive directory cannot be created, the transfer proceeds and the source files remain in their original
location.
To preserve portions of the file path above the transferred file or directory, use this option with
--src-base. For an example, see “Ascp File Manipulation Examples” on page 56.

46 IBM Aspera Desktop Client 4.3

 To remove empty source directories (except those specified as the source to transfer), use this option
with --remove-empty-directories .
Restrictions:
• archivedir must be on the same file system as the source. If the specified archive is on a separate
file system, it is created (if it does not exist), but an error is generated and files are not moved to it.
• For cloud storage, archivedir must be in the same cloud storage account as the source and must not
already contain files with the same name (the existing files cannot be overwritten and the archiving
fails).
• If the source is on a remote system (ascp is run in receive mode), archivedir is subject to the same
docroot restrictions as the remote user.
• --remove-after-transfer and --move-after-transfer are mutually exclusive. Using both
in the same session generates an error.
• Empty directories are not saved to archivedir.
• When used with --remove-empty-directories and --src-base, scanning for empty
directories starts at the specified source base and proceeds down any subdirectories. If no source
base is specified and a file path (as opposed to a directory path) is specified, then only the
immediate parent directory is removed (if empty) after the source files have been moved.
--multi-session-threshold=threshold
Split files across multiple ascp sessions if their size is greater than or equal to threshold. Use with -C,
which enables multi-session transfers.
Files whose sizes are less than threshold are not split. If threshold is set to 0 (the default), no files are
split.
If --multi-session-threshold is not used, the threshold value is taken from the setting for
<multi_session_threshold_default> in the aspera.conf file on the client. If not found in
aspera.conf on the client, the setting is taken from aspera.conf on the server. The command-line
setting overrides any aspera.conf settings, including when the command-line setting is 0 (zero).
Multi-session uploads to cloud storage are supported for S3 only and require additional configuration.
For more information, see the IBM Aspera High-Speed Transfer Server.
-N 'pattern'
Include files or directories in the transfer based on matching the specified pattern to file names and
paths. Rules are applied in the order in which they are encountered, from left to right, such that -N
rules protect files from -E rules that follow them.
Note: An include rule must be followed by at least one exclude rule, otherwise all files are transferred
because none are excluded. To exclude all files that do not match the include rule, use -N '/**/'
-E '/**' at the end of your filter arguments.
The following symbols can be used in the pattern:
• * (asterisk) represents zero or more characters in a string, for example *.tmp matches .tmp and
abcde.tmp.
• ? (question mark) represents any single character, for example t?p matches tmp but not temp.
For details on specifying patterns and rules, including examples, see “Using Filters to Include and
Exclude Files” on page 64.
Note: Filtering rules can also be specified in aspera.conf. Rules found in aspera.conf are applied
before any -E and -N rules specified on the command line.
-O fasp_port
Use the specified UDP port for FASP transfers. (Default: 33001)
--output-file-progress
Can be used to write the individual file transfer progress to the stdout file descriptor.

High-Speed Transfer Client Admin Guide for Linux 47

 --overwrite={never|always|diff|diff+older|older}
Overwrite destination files with source files of the same name. Default: diff. This option takes the
following values:
• 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 different from the source. If a complete file at the destination is the same
as a file on the source, it is not overwritten. Partial files are overwritten or resumed depending on
the resume policy.
• diff+older - Overwrite the file if older and also different than the source. For example, if the
destination file is the same as the source, but with a different timestamp, it will not be overwritten.
Plus, if the destination file is different than the source, but newer, it will not be overwritten.
• older - Overwrite the file if its timestamp is older than the source timestamp.
Interaction with resume policy (-k): 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 checksums. If -k 3, the source and
destination files are compared based on full checksums.
-P ssh-port | websockets-port
Use the specified TCP port to initiate the FASP transfer session, using the port number that is
appropriate for your use of either SSH or Websocket.
-p
Preserve file timestamps for access and modification time. Equivalent to setting --preserve-
modification-time and --preserve-access-time (and --preserve-creation-time on
Windows). Timestamp support in object storage varies by provider; consult your object storage
documentation to determine which settings are supported.
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.
--partial-file-suffix=suffix
Enable the use of partial files for files that are in transit, and set the suffix to add to names of partial
files. (The suffix does not include a " . ", as for a file extension, unless explicitly specified as part of
the suffix.) This option only takes effect when set on the receiver side. When the transfer is complete,
the suffix is removed. (Default: suffix is null; use of partial files is disabled.)
--policy={high|fair|low|fixed}
Set the FASP transfer policy.
• high - Adjust the transfer rate to fully utilize the available bandwidth up to the maximum rate.
When congestion occurs, the transfer rate is twice as fast as a fair-policy transfer. The high policy
requires maximum (target) and minimum transfer rates.
• fair - Adjust the transfer rate to fully utilize the available bandwidth up to the maximum rate.
When congestion occurs, bandwidth is shared fairly by transferring at an even rate. The fair policy
requires maximum (target) and minimum transfer rates.
• low - Adjust the transfer rate to use the available bandwidth up to the maximum rate. Similar to
fair mode, but less aggressive when sharing bandwidth with other network traffic. When congestion
occurs, the transfer rate is reduced to the minimum rate until other traffic decreases.
• fixed - Attempt to transfer at the specified target rate, regardless of network or storage capacity.
This can decrease transfer performance and cause problems on the target storage. Aspera
discourages using the fixed policy except in specific contexts, such as bandwidth testing. The
fixed policy requires a maximum (target) rate.

48 IBM Aspera Desktop Client 4.3

 • aggressiveness - The aggressiveness of transfers that are authorized by this access key in
claiming available bandwidth. Value can be 0.00-1.00. For example: These values correspond to the
policy option where a policy of high approximates to aggressiveness of 0.75, fair to 0.50 and low to
0.25. Aggressiveness can be used if there is a need to fine tune the transfer policy.
If --policy is not set, ascp uses the server-side policy setting (fair by default). If the server does
not allow the selected policy, the transfer fails.
--precalculate-job-size
Calculate the total size before starting the transfer. The server-side pre_calculate_job_size
setting in aspera.conf overrides this option.
--preserve-access-time
Preserve the source-file access timestamps at the destination. Because source access times are
updated by the transfer operation, the timestamp preserved is the one just prior to the transfer.
(To prevent access times at the source from being updated by the transfer operation, use the
--preserve-source-access-time option.)
For IBM Spectrum Scale clusters, use to preserve the expiration time of immutable files.
--preserve-acls={native|metafile|none}
Preserve Access Control Lists (ACL) data for macOS, Windows, and AIX files. To preserve ACL data for
other operating systems, use --preserve-xattrs. See also --remote-preserve-acls. Default:
none.
• native - Preserve attributes using the native capabilities of the file system. This mode is only
supported for Windows, macOS, and AIX. If the destination and source do not support the same
native ACL format, async reports and error and exits.
• metafile- Preserve file attributes in a separate file, named filename.aspera-meta. For
example, attributes for readme.txt are preserved in a second file named readme.txt.aspera-
meta. These metafiles are platform independent and can be copied between hosts without loss of
information. This mode is supported on all file systems.
• none - Do not preserve attributes. This mode is supported on all file systems.
Important Usage Information:
• ACLs are not preserved for directories.
• Both --preserve-acls and --remote-preserve-acls must be specified in order for the target
side of a pull (Ascp with --mode=recv) to apply the ACLs.
• Very old versions of ascp do not support values other than none, and transfers using native or
metafile fail with an error that reports incompatible FASP protocol versions.
--preserve-creation-time
(Windows only) Preserve source-file creation timestamps at the destination. Only Windows systems
retain information about creation time. If the destination is not a Windows computer, this option is
ignored.
--preserve-file-owner-gid, --preserve-file-owner-uid
(Linux, UNIX, and macOS only) Preserve the group information (gid) or owner information (uid) of
the transferred files. These options require the transfer user to be authenticated as a superuser.
--preserve-modification-time
Set the modification time, the last time a file or directory was modified (written), of a transferred file
to the modification of the source file or directory. Preserve source-file modification timestamps at the
destination.
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.

High-Speed Transfer Client Admin Guide for Linux 49

 --preserve-source-access-time
Preserve the access times of the original sources to the last access times prior to transfer. This
prevents access times at the source from being updated by the transfer operation. Typically used in
conjunction with the --preserve-access-time option.
--preserve-xattrs={native|metafile|none}
Preserve extended file attributes data (xattr). Default: none. See also --remote-preserve-
xattrs.
• native - Preserve attributes using the native capabilities of the file system. This mode is supported
only on macOS and Linux. If the destination and source do not support the same native xattr format,
async reports and error and exits. If the Linux user is not root, some attributes such as system
group might not be preserved.
• metafile- Preserve file attributes in a separate file, named filename.aspera-meta. For
example, attributes for readme.txt are preserved in a second file named readme.txt.aspera-
meta. These metafiles are platform independent and can be copied between hosts without loss of
information. This mode is supported on all file systems.
• none - Do not preserve attributes. This mode is supported on all file systems.
Important Usage Information:
• Extended attributes are not preserved for directories.
• If Ascp is run by a regular user, only user-level attributes are preserved. If run as superuser, all
attributes are preserved.
• The amount of attribute data per file that can be transferred successfully is subject to ascp's
internal PDPU size limitation.
• Very old versions of Ascp do not support values other than none, and transfers using native or
metafile fail with an error that reports incompatible FASP protocol versions.
• Use --preserve-xattrs=native to preserve IBM Spectrum Scale ACLs between clusters. For
more information, see “Preserving IBM Spectrum Scale ACLs of Transferred Files” on page 98.
--proxy=proxy_url
Use the proxy server at the specified address. proxy_url should be specified with the following syntax:
dnat[s]://proxy_username:proxy_password@server_ip_address:port
The default ports for DNAT and DNATS protocols are 9091 and 9092. For a usage example, see “Ascp
General Examples” on page 53.
-q
Run ascp in quiet mode (disables the progress display).
-R remote_log_dir
Log to the specified directory on the server rather than the default directory. Note: Client users
restricted to aspshell are not allowed to use this option. To specify the location of the local log, use
-L.
--remote-preserve-acls={native|metafile|none}
Like --preserve-acls but used when ACLs are stored in a different format on the remote computer.
Defaults to the value of --preserve-acls.
Note: Both --preserve-acls and --remote-preserve-acls must be specified in order for the
target side of a pull (Ascp with --mode=recv) to apply the ACLs.
--remote-preserve-xattrs={native|metafile|none}
Like --preserve-xattrs but used when attributes are stored in a different format on the remote
computer. Defaults to the value of --preserve-xattrs.
--remove-after-transfer
Remove all source files, but not the source directories, once the transfer has completed successfully.
Requires write permissions on the source.

50 IBM Aspera Desktop Client 4.3

--remove-empty-directories
Remove empty source directories once the transfer has completed successfully, but do not remove
a directory specified as the source argument. To also remove the specified source directory, use --
remove-empty-source-directory. Directories can be emptied using --move-after-transfer
or --remove-after-transfer. Scanning for empty directories starts at the srcbase and proceeds
down any subdirectories. If no source base is specified and a file path (as opposed to a directory path)
is specified, then only the immediate parent directory is scanned and removed if it's empty following
the move of the source file. Note: Do not use this option if multiple processes (ascp or other) might
access the source directory at the same time.
--remove-empty-source-directory
Remove directories specified as the source arguments. For use with --remove-empty-
directories.
-S remote_ascp
Use the specified remote ascp binary, if different than ascp.
--save-before-overwrite
Save a copy of a file before it is overwritten by the transfer. A copy of filename.ext is saved as
filename.yyyy.mm.dd.hh.mm.ss.index.ext in the same directory. index is set to 1 at the start
of each second and incremented for each additional file saved during that second. The saved copies
retain the attributes of the original. Not supported for URI path destinations.
-SSH
Use an external SSH program instead of the built-in libssh2 implementation to establish the
connection with the remote host. The desired SSH program must be defined in the environment's
PATH variable. To enable debugging of the SSH process, use the -DD and --ssh-arg=-vv options
with ascp.
--ssh-arg=ARG
Add ARG to the command-line arguments passed to the external SSH program (this implies using-
SSH). This option may be repeated as needed to supply multiple separate SSH arguments. The order
is preserved. The ARG elements are inserted before any key file(s) supplied to ascp, and before the
user/host argument.
--skip-special-files
Skip special files, such as devices and pipes, without reporting errors for them.
--source-prefix=prefix
Prepend prefix to each source path. The prefix can be a conventional path or a URI; however, URI
paths can be used only if no docroot is defined.
--source-prefix64=prefix
Prepend the base64-encoded prefix to each source path. If --source-prefix=prefix is also used,
the last option takes precedence.
--src-base=prefix
Strip the specified path prefix from the source path of each transferred file or directory. The remaining
portion of the path remains intact at the destination.
Without --src-base, source files and directories are transferred without their source path.
(However, directories do include their contents.)
Note: Sources located outside the source base are not transferred. No errors or warnings are issued,
but the skipped files are logged.
Use with URIs: The --src-base option performs a character-to-character match with the source
path. For object storage source paths, the prefix must specify the URI in the same manner as the
source paths. For example, if a source path includes an embedded passphrase, the prefix must also
include the embedded passphrase otherwise it will not match.
For examples, see “Ascp File Manipulation Examples” on page 56.

High-Speed Transfer Client Admin Guide for Linux 51

 --src-base64=<base64-encoded src-base>
An alternative to --src-base, with the same value except base64-encoded to help avoid
character translation issues for non-ascii character sets. If both --src-base and --src-base64
are specified, then the last argument on the command line is used.
--symbolic-links={follow|copy|copy+force|skip}
Handle symbolic links using the specified method, as allowed by the server. For more information on
symbolic link handling, see “Symbolic Link Handling” on page 69. On Windows, the only method is
skip. On other operating systems, any of the following methods can be used:
• follow - Follow symbolic links and transfer the linked files. (Default)
• copy - Copy only the alias file. If a file with the same name is found at the destination, the symbolic
link is not copied.
• copy+force - Copy only the alias file. If a file (not a directory) with the same name is found at the
destination, the alias replaces the file. If the destination is a symbolic link to a directory, it's not
replaced.
• skip - Skip symbolic links. Do not copy the link or the file it points to.
-T
Disable in-transit encryption for maximum throughput.
--tags string
Metatags in JSON format. The value is limited to 4 Kb.
--tags64 string
Metatags in JSON format and base64 encoded. The value is limited to 4 Kb.
-u user_string
Define a user string for Lua scripts that can be run with transfer events. See Transfer Session Data
Accessible to Scripts.
--user=username
Authenticate the transfer using the specified username. Use this option instead of specifying the
username as part of the destination path (as user@host:file).
Note: If you are authenticating on a Windows computer as a domain user, the transfer server
strips the domain from the username. For example, Administrator is authenticated rather than
DOMAIN\Administrator. For this reason, you must specify the domain explicitly.
-v
Run ascp in verbose mode. This option prints connection and authentication debug messages in the
log file. For information on log files, see “Log Files” on page 95 .
-W {token_string|@token_file}
Authenticate using the authorization token string for the transfer, either as the string itself or when
preceded with an @, the full path to the token file. This option takes precedence over the setting for
the ASPERA_SCP_TOKEN environment variable.
-wr, -wf
Measure and report bandwidth from server to client (-wr) or client to server (-wf) before the transfer.
--ws-connect
Use Websocket instead of SSH for client connections with the transfer server.
-X rexmsg_size
Limit the size of retransmission requests to no larger than the specified size, in bytes. (Max: 1440)
-Z dgram_size
Use the specified datagram size (MTU) for FASP transfers. Range: 296-65535 bytes. (Default: the
detected path MTU)
As of version 3.3, datagram size can be specified on the server by setting <datagram_size> in
aspera.conf. The server setting overrides the client setting, unless the client is using a version of
ascp that is older than 3.3, in which case the client setting is used. If the pre-3.3 client does not set
-Z, the datagram size is the discovered MTU and the server logs the message "LOG Peer client does
not support alternative datagram size".

52 IBM Aspera Desktop Client 4.3

 Ascp Options for HTTP Fallback
HTTP fallback serves as a secondary transfer method when the Internet connectivity required for Aspera
FASP transfers (UDP port 33001, by default) is unavailable. When HTTP fallback is enabled and UDP
connectivity is lost or cannot be established, the transfer will continue over the HTTP/S protocol.
Limitations:
• HTTP fallback must be enabled on the server.
• Folders that are symbolic links cannot be downloaded directly by using HTTP fallback. Folders that are
symbolic links are processed correctly when their parent folder is the source.
• HTTP fallback can only follow symbolic links. Settings in aspera.conf or in the command line are
ignored.
• HTTP fallback attempts to transfer at the target rate but is limited by TCP.
• HTTP fallback does not support automated execution of Lua scripts (Automated Execution of Lua
Scripts with Transfer Events).
Options:
-i cert_file
By default ascp uses the system certificates. However, the -i option can be used to use the specified
Certificate Authority certificate for fallback transfers, and for Websocket.
-t port
Transfer via the specified server port for HTTP fallback.
-x proxy_server
Transfer to the specified proxy server address for HTTP fallback.
-Y key_file
Certify HTTPS fallback transfers using the specified HTTPS transfer key.
-y {0|1}
If set to "1", use the HTTP fallback transfer server when a UDP connection fails. (Default: 0)

Ascp General Examples

Use the following Ascp examples to craft your own transfers.
To describe filepaths, use single-quotes (' ') around the filepath string, and forward-slashes (/) on all
platforms. Avoid the following characters in filenames: / \ " : ' ? > < & * |
• Growing Files
The growing files feature allows you to start transferring files to the target directory while they are still
being written to the source directory.
Download the growing file myfile with a wait period of 120 seconds, and using a zero-byte read when
calculating the wait time.

ascp --mode=recv --user=root --host=10.0.0.2 "file:////tmp/myfile?

grow=120&wait_start=null_read" file:////tmp2/mylocalfile

To support this command, the ascp.conf file would have to include the following configuration:

<default>
<file_system>
<access>
<paths><path><absolute>
file:////tmp?grow=120;wait_start=null_read
</absolute></path></paths>
</access>
</file_system>
</default>

For more information, see the discussion of ascp.conf configuration for growing files in aspera.conf -
File System Configuration.

High-Speed Transfer Client Admin Guide for Linux 53

 • Using the Websocket Protocol
This example shows how to use the Websocket protocol for a transfer. The Aspera Node Service
provides a Websocket server, which must be enabled. Because the Ascp client only supports a secure
Websocket transfer (HTTPS), the Aspera Node Service must be configured for HTTPS, or must use a
reverse proxy to terminate the secure connection.
A basic token, bearer token or transfer token must be used with a Websocket connection.
The following ascp options are required for using Websocket:
--ws-connect
Specifies using Websocket.
-P
Specifies the Websocket port (9093).

# ascp -L- --ws-connect -P 9093 --host=www.example.com --mode=send --user=xeno c:/Users/xeno/

Desktop/myfile /Desktop/ dest

• 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 --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 -l 100m /local-dir/files [email protected]:/remote-dir

• Specify UDP port for transfer

Transfer using UDP port 42000:

# ascp -l 100m -O 42000 /local-dir/files [email protected]:/remote-dir

• Public key authentication

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

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

• Content is specified in a file pair list

Specify source content to transfer to various destinations in a file pair list. Source content is specified
using the full file or directory path. Destination directories are specified relative to the transfer user's
docroot, which is specified as a "." at the end of the ascp command. For example, the following is a
simple file pair list, filepairlist.txt that lists two source folders, folder1 and folder2, with two
destinations, tmp1 and tmp2:

/tmp/folder1
tmp1
/tmp/folder2
tmp2

# ascp --user=user_1 --host=10.0.0.2 --mode=send --file-pair-list=/tmp/filepairlist.txt .

54 IBM Aspera Desktop Client 4.3

 This command and file pair list create the following directories within the transfer user's docroot on the
destination:

/tmp1/folder1
/tmp2/folder2

• 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 multi-core 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 -C 2:2 -O 33002 -l 100m /file [email protected]:/remote-dir

• Upload with content protection

Upload the file local-dir/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/

The file is saved on the server as file.aspera-env, with the extension indicating that the file is
encrypted. See the next example for how to download and decrypt an encrypted file from the server.
• Download with content protection and decryption
Download an encrypted file, file.aspera-env, 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/file.aspera-env /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; /opt/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 proxy username aspera_proxy and password pa33w0rd. After running the
command, Pat is prompted for the transfer user's (Pat's) password.

# ascp --proxy dnats://aspera_proxy:[email protected] /data/file1 [email protected]:/Pat_data/

Test transfers using faux://

For information on the syntax, see .
• 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:

High-Speed Transfer Client Admin Guide for Linux 55

 #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

Ascp can manipulate files and directories as part of the transfer, such as upload only the files in the
specified source directory but not the directory itself, create a destination directory, and move or delete
source files after they are transferred.
• Upload a directory
Upload the directory /data/ to the server at 10.0.0.1, and place it in the /storage/ directory on the
server:

# ascp /src/data/ [email protected]:/storage/

• Upload only the contents of a directory (not the directory itself) by using the --src-base option:
Upload only the contents of /data/ to the /storage/ directory at the destination. Strip the /src/
data/ portion of the source path and preserve the remainder of the file structure at the destination:

# ascp --src-base=/src/data/ /src/data/ [email protected]:/storage/

• Upload a directory and its contents to a new directory by using the -d option.
Upload the /data/ directory to the server and if it doesn't already exist, create the new folder /
storage2/ to contain it, resulting in /storage2/data/ at the destination.

# ascp -d /src/data/ [email protected]:/storage2/

• Upload the contents of a directory, but not the directory itself, by using the --src-base option:
Upload all folders and files in the /clips/out/ folder, but not the out/ folder itself, to the /in/ folder
at the destination.

# ascp -d --src-base=/clips/out/ /clips/out/ [email protected]:/in/

Result: The source folders and their content appear in the in directory at the destination:

Source Destination Destination without --src-base

/clips/out/ /in/file1 /in/out/file1
file1 /in/folderA/file2 /in/out/folderA/file2
/clips/out/folderA/file2 /in/folderB/file3 /in/out/folderB/file3
/clips/out/folderB/file3

Without --src-base, the example command transfers not only the contents of the out/ folder, but the
folder itself.
Note: Sources located outside the source base are not transferred. No errors or warnings are
issued, but the skipped files are logged. For example, if /clips/file4 were included in the above
example sources, it would not be transferred because it is located outside the specified source base, /
clips/out/.
• Upload only the contents of a file and a directory to a new directory by using --src-base
Upload a file, /monday/file1, and a directory, /tuesday/*, to the /storage/ directory on the
server, while stripping the srcbase path and preserving the rest of the file structure. The content is
saved as /storage/monday/file1and /storage/tuesday/* on the server.

56 IBM Aspera Desktop Client 4.3

 # 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 by using --src-base
Download a file, /monday/file1, and a directory, /tuesday/*, from the server, while stripping the
srcbase path and preserving the rest of the file structure. The content is saved as /data/monday/
file1 and /data/tuesday/* on the client.

# ascp --src-base=/storage/content [email protected]:/storage/content/monday/file1 [email protected]:/

storage/content/tuesday/ /data

• Move the source file on the client after it is uploaded to the server by using --move-after-
transfer
Uploadfile0012 to Pat's docroot on the server at 10.0.0.1, and move (not copy) the file from C:/
Users/Pat/srcdir/ to C:/Users/Pat/Archive on the client.

# ascp --move-after-transfer=C:/Users/Pat/Archive C:/Users/Pat/srcdir/file0012 [email protected]:/

• Move the source file on the server after it is downloaded to the client by using --move-after-
transfer
Download srcdir from the server to C:/Users/Pat on the client, and move (not copy) srcdir to the
archive directory /Archive on the server.

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

• Move the source file on the client after it is uploaded to the server and preserve the file structure
one level above it by using --src-base and --move-after-transfer
Upload file0012 to Pat's docroot on the server at 10.0.0.1, and save it as /srcdir/
file0012 (stripped of C:/Users/Pat). Also move file0012 from C:/Users/Pat/srcdir/ to
C:/Users/Pat/Archive on the client, where it is saved as C:/Users/Pat/Archive/srcdir/
file0012.

# ascp --src-base=C:/Users/Pat --move-after-transfer=C:/Users/Pat/Archive C:/Users/Pat/srcdir/

file0012 [email protected]:/

• Delete a local directory once it is uploaded to the remote server by using --remove-after-
transfer and --remove-empty-directories
Upload /content/ to the server, then delete its contents (excluding partial files) and any empty
directories on the client.

# 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 by using
--src-base, --remove-after-transfer, and --remove-empty-directories
Upload /content/ to the server, while stripping the srcbase path and preserving the rest of the
file structure. The content is saved as /storage/* on the server. On the client, the contents of /
content/, including empty directories but excluding partial files, are deleted.

# ascp -k2 -E "*.partial" --src-base=/data/content --remove-after-transfer --remove-empty-

directories /data/content [email protected]:/storage

High-Speed Transfer Client Admin Guide for Linux 57

Ascp Transfers with Object Storage and HDFS
Ascp transfers to and from servers in the cloud are similar to other Ascp transfers, though they might
require explicit authorization to the storage as an authorization token or storage credentials.

Transfers with IBM Aspera On Demand and Cloud-Based HSTSs

Transfers to Aspera on Demand and cloud-based HSTSs require authorization credentials to the storage,
but are otherwise the same as transfers to on-premises HSTS.
Provide object storage credentials in one of the following ways:
• Specify the storage password or secret key in the transfer user's docroot. (Preferred method)
• Set the storage password or secret key as an environment variable.
• Specify the storage password or secret key in the command line.

With Docroot Configured: Authenticate in the Docroot

If your transfer user account has a docroot set that includes credentials or credentials are configured
in the .properties file, ascp transfers to and from Alibaba Cloud, Amazon S3, IBM COS - S3, Google
Cloud Storage, Akamai, SoftLayer, Azure, and are the same as regular ascp transfers.
For command syntax examples, see “Ascp General Examples” on page 53. You are prompted for the
transfer user's password when you run an ascp command unless you set the ASPERA_SCP_PASS
environment variable or use SSH key authorization.

With No Docroot Configured: Authenticate with Environment Variables

Note: The ASPERA_DEST_PASS variable is not applicable to Google Cloud Storage or Amazon S3 using
IAM roles.
Set an environment variable (ASPERA_DEST_PASS) with the storage password or access key:

# export ASPERA_DEST_PASS = secret_key

With ASPERA_DEST_PASS and ASPERA_SCP_PASS set, run ascp with the syntax listed in the table for
transfers with no docroot configured, except that you do not need to include the storage password or
access key, and are not prompted for the Aspera password upon running ascp.

With No Docroot Configured: Authenticate in the Command Line

If you do not have a docroot configured and do not set an environment variable (described previously),
authenticate in the command line. In the following examples, the storage password or secret key are
included as part of the destination path. You are prompted for the transfer user's password upon running
ascp unless you set the ASPERA_SCP_PASS environment variable or use SSH key authorization.

Storage Platform ascp Syntax and Examples

Alibaba Cloud Aspera recommends running ascp transfers with Alibaba Cloud with a docroot
configured.
Amazon S3 • If you are using IAM roles, you do not need to specify the access ID or secret key
for your S3 storage.
Upload syntax:

# ascp options --mode=send --user=username --host=s3_server_addr

source_files s3://access_id:[email protected]/my_bucket

58 IBM Aspera Desktop Client 4.3

Storage Platform ascp Syntax and Examples

Upload example:

# ascp --mode=send --user=bear --host=s3.example.com bigfile.txt

s3://1K3C18FBWF9902:[email protected]/demos2014

Download syntax:

# ascp options --mode=recv --user=username --

host=s3_server_addr s3://access_id:[email protected]/my_bucket/
my_source_path destination_path

Download example:

# ascp --mode=recv --user=bear --host=s3.example.com

s3://1K3C18FBWF9902:[email protected]/demos2014/
bigfile.txt /tmp/

Azure These examples are for Azure blob storage.

For Azure Files, use the syntax: azure-files://
storage_account:[email protected]/
share. Aspera recommends running ascp transfers with Azure
Data Lake Storage with a docroot configured.
Upload syntax:

# ascp options --mode=send --

user=username --host=server_address source_files azu://
storage_account:[email protected]/path_to_blob

Upload example:

# ascp --mode=send --user=AS037d8eda429737d6 --

host=dev920350144d2.azure.asperaondemand.com bigfile.txt azu://
astransfer:[email protected]/abc

Download syntax:

# ascp options --mode=recv --user=username --

host=server azu://storage_account:[email protected]/
path_to_blob/source_file destination_path

Download example:

# ascp --mode=recv --
user=AS037d8eda429737d6 --host=dev920350144d2.azure.asperaondemand.com
azu://astransfer:[email protected]/abc /downloads

Google Cloud Note: The examples below require that the VMI running the Aspera server is a
Storage Google Compute instance.

# ascp options --mode=send --user=username --host=server_address

source_files gs:///my_bucket/my_path

Upload example:

# ascp --mode=send --user=bear --host=10.0.0.5 bigfile.txt gs:///

2017_transfers/data

Download syntax:

# ascp options --mode=recv --user=username --host=server gs:///my_bucket/

my_path/source_file destination_path

High-Speed Transfer Client Admin Guide for Linux 59

 Storage Platform ascp Syntax and Examples

Download example:

# ascp --mode=recv --user=bear --host=10.0.0.5 gs:///2017_transfers/data/

bigfile.txt /data

HDFS Aspera recommends running ascp transfers with HDFS with a docroot configured.
IBM COS - S3 Upload syntax:

# ascp options --mode=send --user=username --host=server_address

source_files s3://access_id:secret_key@accessor_endpoint/vault_name

Upload example:

# ascp --mode=send --user=bear --host=s3.example.com bigfile.txt

s3://3ITI3OIUFEH233:[email protected]/demo2017

Download syntax:

# ascp options --mode=send --user=username --

host=server_address s3://access_id:secret_key@accessor_endpoint/vault_name/
source_files destination_path

Download example:

# ascp --mode=send --user=bear --host=s3.example.com

s3://3ITI3OIUFEH233:[email protected]/demo2017 /tmp/

Writing Custom Metadata for Objects in Object Storage

Files that are uploaded to metadata-compatible storage (S3, Google Cloud, and Azure) can have custom
metadata written with them by using the --tags or --tags64 option. The argument is a JSON payload
that specifies the metadata and that is base64 encoded if it is used as an argument for --tags64.
Metadata Behavior
• All objects that are uploaded in a session have the same metadata.
• If an upload resumes, the metadata of the original transfer is used.
• Multi-session transfers must specify the same metadata.
• Metadata are not retrieved when downloading objects; use the REST API associated with the storage.
• Transfers to object storages that do not support metadata (such as HDFS and Azure Files) fail if
metadata is specified.
Specifying Metadata in JSON
The JSON payload has the general syntax of key-value pairs in a "cloud-metadata" section:

{
"aspera": {
"cloud-metadata": [
{"key1":"value1"},
{"key2":"value2"},
...
] } }

Restrictions on key-value pairs:

• key cannot be ctime, mtime, or atime. These keys are reserved and the transfer fails if they are used.
• key might be case-sensitive, depending on the destination storage type.
• The key-value pair must be less than 1024 characters.

60 IBM Aspera Desktop Client 4.3

 Sample Ascp Session with Metadata

# ascp --tags='{"aspera":{"cloud-metadata":[{"location":"skellig"}]}}' --mode=send --user=rey --

host=s3.example.com sourcefile.mov s3://s3.amazonaws.com/project

Using Standard I/O as the Source or Destination

Ascp can use standard input (stdin) as the source or standard output (stdout) as the destination for a
transfer, usually managed by using the Aspera FASP Manager SDK. The syntax depends on the number of
files in your transfer; for single files use stdio:// and for multiple files use stdio-tar://. The transfer
is authenticated using SSH or a transfer token.
Named Pipes
A named pipe can be specified as a stdio destination, with the syntax stdio:///path for single files,
or stdio-tar:///path for multiple files, where path is the path of the named pipe. If a docroot is
configured on the destination, then the transfer goes to the named pipe docroot/path.
Note: Do not use stdio:///path to transfer multiple files. The file data is asynchronously concatenated
in the output stream and might be unusable. Use stdio-tar:///path instead, which demarcates
multiple files with headers.
Note: Do not use zero-byte files with standard I/O transfers.

Single File Transfers

To upload data that is piped into stdin, set the source as stdio:///?fsize, wherefsize is the number
of bytes (as a decimal) that are received from stdin. The destination is set as the path and filename. The
file modification time is set to the time at which the upload starts. Standard input must transfer the exact
amount of data that is set by fsize. If more or less data is received by the server, an error is generated.
To download data and pipe it into stdout, set the destination as stdio://.
Restrictions:
• stdio:// cannot be used for persistent sessions. Use stdio-tar:// instead.
• Only --overwrite=always or --overwrite=never are supported with stdio://. The behavior of
--overwrite=diff and --overwrite=diff+older is undefined.
Single-file Transfer Examples:
• Upload 1025 bytes of data from the client stdin to /remote-dir on the server at 10.0.0.2. Save the
data as the file newfile. Transfer at 100 Mbps.

cat myfile | ascp -l 100m --mode=send --user=username --host=10.0.0.2 stdio:///newfile?1025 /

remote-dir

• Download the file remote_file from the server at 10.0.0.2 to stdout on the client. Transfer at 100
Mbps.

ascp -l 100m --mode=recv --user=username --host=10.0.0.2 remote_file stdio://

• Upload the file local_file to the server at 10.0.0.2 to the named pipe /tmp/outpipe. Transfer at
100 Mbps.

ascp -l 100m --mode=send --user=username --host=10.0.0.2 local_file stdio:////tmp/outpipe

Multi-File Transfers
Ascp can transfer one or more files in an encoded, streamed interface, similar to single file transfers. The
primary difference is that the stream includes headers that demarcate data from individual files.
To upload files that are piped into stdin, set the source as stdio-tar://. The file modification time is
set to the time at which the upload starts.

High-Speed Transfer Client Admin Guide for Linux 61

 The file(s) in the input stream must be encoded in the following format. File can be the file name or file
path, Size is the size of the file in bytes, and Offset is an optional parameter that sets where in the
destination file to begin overwriting with the raw inline data:

[0 - n blank lines]
File: /path/to/file_1
Size: file_size
Offset: bytes

file_1 data
[0 - n blank lines]
File: /path/to/file_2
Size: file_size

file 2 data
...

To download one or more files to stdout, set the destination as stdio-tar://. Normal status output to
stdout is suppressed during downloads because the transfer output is streamed to stdout. The data sent
to stdout has the same encoding as described for uploads.
To download to a named pipe, set the destination to stdio-tar:////path, where path is the path of
the named pipe.
When an offset is specified, the bytes that are sent replace the existing bytes in the destination file (if it
exists). The bytes added to the destination file can extend beyond the current file size. If no offset is set,
the bytes overwrite the file if overwrite conditions are met.
Restrictions:
• When downloading to stdio-tar://, the source list must consist of individual files only. Directories
are not allowed.
• Only --overwrite=always or --overwrite=never are supported with stdio-tar://. The
behavior of --overwrite=diff and --overwrite=diff+older is undefined.
• Offsets are only supported if the destination files are located in the native file system. Offsets are not
supported for cloud destinations.
Multi-file Transfer Examples:
• Upload two files, myfile1 (1025 bytes) and myfile2 (20 bytes), to /remote-dir on the server at
10.0.0.2. Transfer at 100 Mbps.

cat sourcefile | ascp -l 100m --mode=send --user=username --host=10.0.0.2 stdio-tar:// /

remote-dir

Where sourcefile contains the following:

File: myfile1
Size: 1025

<< 1025 bytes of data>>

File: myfile2
Size: 20

<<20 bytes of data>>

• Uploading multiple files from stdin by using a persistent session is the same as a non-persistent
session.
• Update bytes 10-19 in file /remote-dir/myfile1 on the server at 10.0.0.2 at 100 Mbps.

cat sourcefile | ascp -l 100m --mode=send --user=username --host=10.0.0.2 stdio-tar:// /

remote-dir

Where sourcefile contains the following:

File: myfile1
Size: 10
Offset: 10

62 IBM Aspera Desktop Client 4.3

 << 10 bytes of data>>

• Upload two files, myfile1 and myfile2, to the named pipe /tmp/mypipe (streaming output) on the
server at 10.0.0.2. Transfer at 100 Mbps.

ascp -l 100m --mode=send --user=username --host=10.0.0.2 myfile1 myfile2 stdio-tar:////tmp/

mypipe

This sends an encoded stream of myfile1 and myfile2 (with the format of sourcefile in the upload
example) to the pipe /tmp/mypipe. If /tmp/mypipe does not exist, it is created.
• Download the files from the previous example from 10.0.0.2 to stdout. Transfer at 100 Mbps.

ascp -l 100m --mode=recv --user=username --host=10.0.0.2 myfile1 myfile2 stdio-tar://

Standard output receives data identical to sourcefile in the upload example.

• Download /tmp/myfile1 and /tmp/myfile2 to stdout by using a persistent session. Start the
persistent session, which listens on management port 12345:

ascp -l 100m --mode=recv --keepalive -M 12345 --user=username --host=10.0.0.2 stdio-tar://

Send the following in through management port 12345:

FASPMGR 2
Type: START
Source: /tmp/myfile1
Destination: mynewfile1

FASPMGR 2
Type: START
Source: /tmp/myfile2
Destination: mynewfile2

FASPMGR 2
Type: DONE

The destination must be a filename; file paths are not supported.

Standard out receives the transferred data with the following syntax:

File: mynewfile1
Size: file_size

mynewfile1_data
File: mynewfile2
Size: file_size

mynewfile2_data

• Upload two files, myfile1 and myfile2, to named pipe /tmp/mypipe on the server at 10.0.0.2.
Transfer at 100 Mbps.

ascp -l 100m --mode=send --user=username --host=10.0.0.2 myfile1 myfile2 stdio-tar:////tmp/

mypipe

If file/tmp/mypipe does not exist, it is created.

• Upload two files, myfile1 (1025 bytes) and myfile2 (20 bytes) from stdio and regenerate the stream
on the destination to send out through the named pipe /tmp/mypipe on the server at 10.0.0.2.
Transfer at 100 Mbps.

cat sourcefile | ascp -l 100m --mode=send --user=username --host=10.0.0.2 stdio-tar:// stdio-

tar:////tmp/pipe

Where sourcefile contains the following:

File: myfile1
Size: 1025

High-Speed Transfer Client Admin Guide for Linux 63

 << 1025 bytes of data>>
File: myfile2
Size: 20

<<20 bytes of data>>

Using Filters to Include and Exclude Files

Filters refine the list of source files (or directories) to transfer by indicating which to skip or include based
on name matching. When no filtering rules are specified by the client, Ascp transfers all source files in the
transfer list; servers cannot filter client uploads or downloads.

Command Line Syntax

-E 'pattern' Exclude files or directories with names or paths that match pattern.
-N 'pattern' Include files or directories with names or paths that match pattern.
Where:
• pattern is a file or directory name, or a set of names expressed with UNIX glob patterns.
• Surround patterns that contain wildcards with single quotes to prevent filter patterns from being
interpreted by the command shell. Patterns that do not contain wildcards can also be in single quotes.
Basic usage
• Filtering rules are applied to the transfer list in the order they appear on the command line. If filtering
rules are configured in aspera.conf, they are applied before the rules on the command line.
• Filtering is a process of exclusion, and -N rules override -E rules that follow them. -N cannot add back
files that are excluded by a preceding exclude rule.
• An include rule must be followed by at least one exclude rule, otherwise all files are transferred
because none are excluded. To exclude all files that do not match the include rule, use -N '/**/' -E
'/**' at the end of your filter arguments.
• Filtering operates only on the set of files and directories in the transfer list. An include rule (-N) cannot
add files or directories that are not already part of the transfer list.

Example Transfer Result

-E 'rule' Transfer all files and directories except those with names that match rule.
-N 'rule' Transfer all files and directories because none are excluded.
To transfer only the files and directories with names that match rule use:

ascp -N 'rule' -N '/**/' -E '/**'

-N 'rule1' -E 'rule2' Transfer all files and directories with names that match rule1, as well as all
other files and directories except those with names that match rule2.
-E 'rule1' -N 'rule2' Transfer all files and directories except those with names that match rule1. All
files and directories not already excluded by rule1 are included because no
additional exclude rule follows -N 'rule2'.
To transfer only the files and directories with names that do not match rule1
but do match rule2 use:

ascp -E 'rule1' -N 'rule2' -N '/**/' -E '/**'

Filtering Rule Application

Filters can be specified on the ascp command line and in aspera.conf. Ascp applies filtering rules that
are set in aspera.conf before it applies rules on the command line.

64 IBM Aspera Desktop Client 4.3

Filtering order
Filtering rules are applied to the transfer list in the order they appear on the command line.
1. Ascp compares the first file (or directory) in the transfer list to the pattern of the first rule.
2. If the file matches the pattern, Ascp includes it (-N) or excludes it (-E) and the file is immune to any
following rules.
Note: When a directory is excluded, directories and files in it are also excluded and are not compared
to any following rules. For example, with the command-line options -E '/images/' -N '/images/
icons/', the directory /images/icons/ is not included or considered because /images/ was
already excluded.
3. If the file does not match, Ascp compares it with the next rule and repeats the process for each rule
until a match is found or until all rules have been tried.
4. If the file never matches any exclude rules, it is included in the transfer.
5. The next file or directory in the transfer list is then compared to the filtering rules until all eligible files
are evaluated.
Example
Consider the following command:

# ascp -N 'file2' -E 'file[0-9]' /images/icons/ user1@examplehost:/tmp

Where /images/icons/ is the source.

If /images/icons/ contains file1, file2, and fileA, the filtering rules are applied as follows:
1. file1 is compared with the first rule (-N 'file2') and does not match so filtering continues.
2. file1 is compared with the second rule (-E 'file[0-9]) and matches, so it is excluded from the
transfer.
3. file2 is compared with the first rule and matches, so it is included in the transfer and filtering stops
for file2.
4. fileA is compared with the first rule and does not match so filtering continues.
5. fileA is compared with the second rule and does not match. Because no rules exclude it, fileA is
included in the transfer.
Note: If the filtering rules ended with -N '/**/' -E '/**', then fileA would be excluded
because it was not "protected" by an include rule.

Rule Patterns
Rule patterns (globs) use standard globbing syntax that includes wildcards and special characters, as well
as several Aspera extensions to the standard.
• Character case: Case always matters, even if the file system does not enforce such a distinction. For
example, on Windows FAT or NTFS file systems and macOS HPFS+, a file system search for "DEBUG"
returns files "Debug" and "debug". In contrast, Ascp filter rules use exact comparison, such that "debug"
does not match "Debug". To match both, use "[Dd]ebug".
• Partial matches: With globs, unlike standard regular expressions, the entire filename or directory name
must match the pattern. For example, the pattern abc*f matches abcdef but not abcdefg.
Standard Globbing: Wildcards and Special Characters

/ The only recognized path separator.

\ Quotes any character literally, including itself. \ is exclusively a quoting
operator, not a path separator.
* Matches zero or more characters, except "/" or the . in "/.".

High-Speed Transfer Client Admin Guide for Linux 65

 ? Matches any single character, except "/" or the . in "/.".
[…] Matches exactly one of a set of characters, except "/" or the . in "/.".
[^… ] When ^ is the first character, matches exactly one character not in the set.
[!… ] When ! is the first character, matches exactly one character not in the set.
[x-x] Matches exactly one of a range of characters.
[:xxxxx:] For details about this type of wildcard, see any POSIX-standard guide to
globbing.

Globbing Extensions: Wildcards and Special Characters

no / or * at end of Matches files only.

pattern
/ at end of pattern Matches directories only. With -N, no files under matched directories or
their subdirectories are included in the transfer. All subdirectories are still
included, although their files will not be included. However, with -E, excluding
a directory also excludes all files and subdirectories under it.
* or /** at end of Matches both directories and files.
pattern
/** Like * but also matches "/" and the . in "/.".
/ at start of pattern Must match the entire string from the root of the transfer set. (Note: The
leading / does not refer to the system root or the docroot.)

Standard Globbing Examples

Wildcard Example Matches Does Not Match

/ abc/def/xyz abc/def/xyz abc/def
\ abc\? abc? abc\? abc/D abcD
* abc*f abcdef abc.f abc/f abcefg
? abc?? abcde abc.z abcdef abc/d abc/.
[…] [abc]def adef cdef abcdef ade
[^… ] [^abc]def zdef .def 2def bdef /def /.def
[!… ] [!abc]def zdef .def 2def cdef /def /.def
[:xxxxx:] [[:lower:]]def cdef ydef Adef 2def .def

Globbing Extension Examples

Wildcard Example Matches Does Not Match

/** a/**/f a/f a/.z/f a/d/e/f a/d/f/ za/d/f
* at end of rule abc* abc/ abcfile
/** at end of rule abc/** abc/.file abc/d/e/ abc/
/ at end of rule abc/*/ abc/dir abc/file
no / at end of rule abc abc (file) abc/
/ at start of rule /abc/def /abc/def xyz/abc/def

66 IBM Aspera Desktop Client 4.3

Testing Your Filter Rules
You can use this procedure to test your filtering rules.
1. On your computer, create a set of directories and files (size can be small) that approximate a typical
transfer file set. In the following example, the file set is in /tmp/src.
2. Upload the file set to a server. For example:

# ascp /tmp/src my_user_name@my_demo.example.com:Upload/

Where the user is "my_user_name", and the target is the Upload directory.
At the prompt, enter my_user_name's password.
3. Create a destination directory on your computer, for example /tmp/dest.
4. Download your files from the demo server to /tmp/dest to test your filtering rules. For example:

# ascp -N 'wxy/**' -E 'def' my_user_name@my_demo.example.com:Upload/src/ /tmp/dest

5. Compare the destination directory with the source to determine if the filter behaved as expected.

$ diff -r dest/ src/

The diff output shows the missing files and directories (those that were not transferred).

Example Filter Rules

The example rules below are based on running a command such as the following to download a directory
AAA from my_demo.example.com to /tmp/dest:

# ascp rules aspera@my_demo.example.com:Upload/AAA /tmp/dest

The examples below use the following file set:

AAA/abc/def
AAA/abc/.def
AAA/abc/.wxy/def
AAA/abc/wxy/def
AAA/abc/wxy/.def
AAA/abc/wxy/tuv/def
AAA/abc/xyz/def/wxy
AAA/wxyfile
AAA/wxy/xyx/
AAA/wxy/xyxfile

Key for interpreting example results below:

< xxx/yyy = Excluded
xxx/yyy = Included
zzz/ = directory name
zzz = filename

1. Transfer everything except files and directories starting with ".":

-N '*' -E 'AAA/**'

Results:

AAA/abc/def
AAA/abc/wxy/def
AAA/abc/wxy/tuv/def
AAA/abc/xyz/def/wxy
AAA/wxyfile
AAA/wxy/xyx/

High-Speed Transfer Client Admin Guide for Linux 67

 AAA/wxy/xyxfile
< AAA/abc/.def
< AAA/abc/.wxy/def
< AAA/abc/wxy/.def

2. Exclude directories and files whose names start with wxy:

-E 'wxy*'

Results:

AAA/abc/def
AAA/abc/.def
AAA/abc/.wxy/def
AAA/abc/xyz/def/
< AAA/abc/wxy/def
< AAA/abc/wxy/.def
< AAA/abc/wxy/tuv/def
< AAA/abc/xyz/def/wxy
< AAA/wxyfile
< AAA/wxy/xyx/
< AAA/wxy/xyxfile

3. Include directories and files that start with "wxy" if they fall directly under AAA:

-N 'wxy*' -E 'AAA/**'

Results:

AAA/wxy/
AAA/wxyfile
< AAA/abc/def
< AAA/abc/.def
< AAA/abc/.wxy/def
< AAA/abc/wxy/def
< AAA/abc/wxy/.def
< AAA/abc/wxy/tuv/def
< AAA/abc/xyz/def/wxy
< AAA/wxy/xyx/
< AAA/wxy/xyxfile

4. Include directories and files at any level that start with wxy, but do not include dot-files, dot-
directories, or any files under the wxy directories (unless they start with wxy). However, subdirectories
under wxy will be included:

-N '*/wxy*' -E 'AAA/**'

Results:

AAA/abc/wxy/tuv/
AAA/abc/xyz/def/wxy
AAA/wxyfile
AAA/wxy/xyx/
< AAA/abc/def
< AAA/abc/.def
< AAA/abc/.wxy/def
< AAA/abc/wxy/def *
< AAA/abc/wxy/.def
< AAA/abc/wxy/tuv/def
< AAA/wxy/xyxfile

* Even though wxy is included, def is excluded because it's a file.

5. Include wxy directories and files at any level, even those starting with ".":

-N '*/wxy*' -N '*/wxy/**' -E 'AAA/**'

Results:

AAA/abc/wxy/def
AAA/abc/wxy/.def
AAA/abc/wxy/tuv/def

68 IBM Aspera Desktop Client 4.3

 AAA/abc/xyz/def/wxy
AAA/wxyfile
AAA/wxy/xyx/
AAA/wxy/xyxfile
< AAA/abc/def
< AAA/abc/.def
< AAA/abc/.wxy/def

6. Exclude directories and files starting with wxy, but only those found at a specific location in the tree:

-E '/AAA/abc/wxy*'

Results:

AAA/abc/def
AAA/abc/.def
AAA/abc/.wxy/def
AAA/abc/xyz/def/wxy
AAA/wxyfile
AAA/wxy/xyx/
AAA/wxy/xyxfile
< AAA/abc/wxy/def
< AAA/abc/wxy/.def
< AAA/abc/wxy/tuv/def

7. Include the wxy directory at a specific location, and include all its subdirectories and files, including
those starting with ".":

-N 'AAA/abc/wxy/**' -E 'AAA/**'

Results:

AAA/abc/wxy/def
AAA/abc/wxy/.def
AAA/abc/wxy/tuv/def
< AAA/abc/def
< AAA/abc/.def
< AAA/abc/.wxy/def
< AAA/abc/xyz/def/wxy
< AAA/wxyfile
< AAA/wxy/xyx/
< AAA/wxy/xyxfile

Symbolic Link Handling

When transferring files using FASP (the Aspera GUI, ascp, ascp4, or async), you can configure how the
server and client handle symbolic links.
Note: Symbolic links are not supported on Windows. Server settings are ignored on Windows servers. If
the transfer destination is a Windows computer, the only supported option that the client can use is skip.

Symbolic Link Handling Options and their Behavior

• Follow: Follow a symbolic link and transfer the contents of the linked file or directory as long as the link
target is in the user's docroot.
• Follow_wide (Server only): For downloads, follow a symbolic link and transfer the contents of the linked
file or directory even if the link target is outside of the user's docroot. Use caution with this setting
because it might allow transfer users to access sensitive files on the server.
• Create (Server only): If the client requests to copy symbolic links in an upload, create the symbolic links
on the server.
• None (Server only): Prohibit clients from creating symbolic links on the server; with this setting clients
can only request to follow or skip symbolic links.
• Copy (Client only): Copy only the symbolic link. If a file with the same name exists at the destination,
the symbolic link does not replace the file.

High-Speed Transfer Client Admin Guide for Linux 69

 • Copy+force (Client only): Copy only the symbolic link. If a file with the same name exists at the
destination, the symbolic link replaces the file. If the file of the same name at the destination is a
symbolic link to a directory, it is not replaced.
Note: Ascp4 and Sync do not support the copy+force option.
• Skip (Client only): Skip symbolic links. Neither the link nor the file to which it points are transferred.
Symbolic link handling depends on the server configuration, the client handling request, and the direction
of transfer, as described in the following tables. Multiple values can be set on the server as a comma-
delimited list, such as the default "follow,create". In this case, the options are logically ORed based on the
client's handling request.
Send from Client to Server (Upload)

Server setting = Server Server Server setting = Server

create, follow setting = setting = follow_wide setting =
(default) create follow none
Client setting = follow Follow Follow Follow Follow Follow
(default for ascp and
ascp4)

Client setting = copy Copy Copy Skip Skip Skip

(default for async)

Client setting = Copy and Copy and Skip Skip Skip

copy+force replace any replace any
existing files. existing files.
Client setting = skip Skip Skip Skip Skip Skip

Receive to Client from Server (Download)

Server setting Server Server Server setting = Server

= create, setting = setting = follow_wide setting =
follow create follow none
(default)
Client setting = Follow Skip Follow Follow even if the Skip
follow target is outside the
user's docroot.
(default for ascp and
ascp4)

Client setting = Copy Copy Copy Copy Copy

copy
(default for async)

Client setting = Copy and Copy and Copy and Copy and replace Copy and
copy+force replace any replace any replace any any existing files. replace any
existing files. existing existing existing
files. files. files.
Client setting = skip Skip Skip Skip Skip Skip

Server and Client Configuration

Server Configuration

70 IBM Aspera Desktop Client 4.3

 In the GUI, go to Configuration > File Handling and set a value for Symbolic Link Actions.
Combinations of actions must be set from the command line using asconfigurator or manually editing
aspera.conf.
To set symbolic link handling globally or per user, run the appropriate command:

# asconfigurator -x "set_node_data;symbolic_links,value"
# asconfigurator -x "set_user_data;user_name,username;symbolic_links,value"

For more information, see .

Client Configuration
Transfers initiated in the GUI request that symbolic links be followed. This cannot be adjusted. To
specify symbolic link handling on the command line (with ascp, ascp4, or async), use --symbolic-
links=option.

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.
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 in the GUI” on page 23.
1. Create a .ssh directory in your home directory if it does not already exist:

$ mkdir /home/username/.ssh

Go to the .ssh folder:

$ cd /home/username/.ssh

2. Generate an SSH key-pair.

In the .ssh folder, use the ssh-keygen command to create a key pair.

# ssh-keygen -m key_format -t key_type

• For key_format, specify a format that is supported by the SSH server.

• For key_type, specify either RSA (rsa) or ECDSA (ecdsa).
At the prompt that appears for the key-pair's filename, press ENTER to use the default name id_rsa
or id_ecdsa, or enter a different name, such as your username. For a passphrase, either enter a
password, or press return twice to leave it blank.
Note: When you run ascp in FIPS mode (<fips_enabled> 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 pkhsts8 -topk8 -v2 aes128 -in id_rsa -out new-id_rsa

3. As the root user, make sure that the SSH key is owned by the transfer user and that proper restrictive
permissions are set. SSH keys must only be readable by the key owner.
Use the following command syntax, where username is the transfer user name and id_rsa is the
key-pair's filename.

chown username /home/username/.ssh/id_rsa

chmod 600 /home/username/.ssh/id_rsa

4. Retrieve the public key file.

High-Speed Transfer Client Admin Guide for Linux 71

 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:
/home/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.
5. Start a transfer using public key authentication with the ascp command.
To transfer files using public key authentication on the command line, use the option -i
private_key_file. For example:

$ ascp -T -l 10M -m 1M -i ~/.ssh/id_rsa myfile.txt [email protected]:/space

In this example, you are connecting to the server (10.0.0.2, directory /space) with the user account
jane and the private key ~/.ssh/id_rsa.

Reporting Checksums
File checksums are useful for trouble-shooting file corruption, allowing you to determine at what point in
the transfer file corruption occurred. Aspera servers can report source file checksums that are calculated
on-the-fly during transfer and then sent from the source to the destination.
To support checksum reporting, the transfer must meet both of the following requirements:
• Both the server and client computers must be running HSTS or HSTE.
• The transfer must be encrypted. Encryption is enabled by default.
The user on the destination can calculate a checksum for the received file and compare it (manually or
programmatically) to the checksum reported by the sender. The checksum reported by the source can be
retrieved in the destination logs, a manifest file, in IBM Aspera Console, or as an environment variable.
Instructions for comparing checksums follow the instructions for enabling checksum reporting.
Checksum reporting is disabled by default. Enable and configure checksum reporting on the server by
using the following methods:
• Edit aspera.conf with asconfigurator.
• Set options in the client GUI.
• Set ascp command-line options (per-transfer configuration).
Command-line options override the settings in aspera.conf and the GUI.
Important: When checksum reporting is enabled, transfers of very large files (>TB) take a long time to
resume because the entire file must be reread.

Overview of Checksum Configuration Options

asconfigurator Option Description

GUI Setting
ascp Option

Enable checksum reporting and specify the type of checksum to

file_checksum
calculate for transferred files.
File checksum method
--file-checksum=type any - Allow the checksum format to be whichever format the
client requests. (Default in aspera.conf and the GUI)
md5 - Calculate and report an MD5 checksum.
sha1 - Calculate and report a SHA-1 checksum.
sha256 - Calculate and report a SHA-256 checksum.
sha384 - Calculate and report a SHA-384 checksum.

72 IBM Aspera Desktop Client 4.3

 Description
asconfigurator Option
GUI Setting
ascp Option

sha512 - Calculate and report a SHA-512 checksum.

Note: The default value for the ascp option is none, in which
case the reported checksum is the one configured on the server,
if any.

The file manifest is a file that contains a list of content that

file_manifest
was transferred in a transfer session. The file name of the file
File Manifest
manifest is automatically generated from the transfer session ID.
--file_manifest=output
When set to none, no file manifest is created. (Default)
When set to text, a text file is generated that lists all files in
each transfer session.

The location where manifest files are written. The location can be
file_manifest_path
an absolute path or a path relative to the transfer user's home
File Manifest Path
directory. If no path is specified (default), the file is generated
--file_manifest_path=path
under the destination path at the receiver, and under the first
source path at the sender.
Note: File manifests can be stored only locally. Thus, if you are
using S3 or other non-local storage, you must specify a local
manifest path.

Enabling checksum reporting by editing aspera.conf

To enable checksum reporting, run the following command:

# asconfigurator -x "set_node_data;file_checksum,checksum"

To enable and configure the file manifest where checksum report data is stored, run the following
commands:

# asconfigurator -x "set_node_data;file_manifest,text"
# asconfigurator -x "set_node_data;file_manifest_path,filepath"

These commands create lines in aspera.conf as shown in the following example, where checksum type
is md5, file manifest is enabled, and the path is /tmp.

<file_system>
...
<file_checksum>md5</file_checksum>
<file_manifest>text</file_manifest>
<file_manifest_path>/tmp</file_manifest_path>
...
</file_system>

Enabling checksum reporting from the GUI

Click Configuration to open the Server Configuration window. Select the Global, Groups, or Users tab,
depending on whether you want to enable checksum reporting for all users, or for a particular group or
user.
Under the File Handling tab, locate the setting for File checksum method. Check the override box and for
the effective value, select any, md5, sha1, sha256, sha384, or sha512.

High-Speed Transfer Client Admin Guide for Linux 73

 To enable the file manifest, select the override check box for File Manifest and set the effective value to
text. To set the path, select the override check box for File Manifest Path and set the effective value to
the folder in which you want the manifest files saved.

In the examples above, the manifest is generated when files are transferred and saved as a text file called
aspera-transfer-transfer_id-manifest.txt in the directory /tmp.

Enabling checksum reporting in an ascp session

To enable checksum reporting on a per-transfer-session basis, run ascp with the --file-
checksum=hash option, where hash is sha1, md5, sha-512, sha-384, sha-256, or none (the default).
Enable the manifest with --file-manifest=output where output is either text or none. Set the path to
the manifest file with --file-manifest-path=path.
For example:

# ascp --file-checksum=md5 --file-manifest=text --file-manifest-path=/tmp file

[email protected]:/destination_path

Setting up a Processing Script

An alternative to enabling and configuring the file manifest to collect checksum reporting is to set up a
script to report the values. See Automated Execution of Lua Scripts with Transfer Events.

Comparing Checksums
If you open a file that you downloaded with Aspera and find that it is corrupted, you can determine when
the corruption occurred by comparing the checksum that is reported by Aspera to the checksums of the
files on the destination and on the source.
1. Retrieve the checksum that was calculated by Aspera as the file was transferred.
• If you specified a file manifest and file manifest path as part of an ascp transfer or Lua transfer event
script, the checksums are in that file in the specified location.
• If you specified a file manifest and file manifest path in the GUI or aspera.conf, the checksums are
in a file that is named aspera-transfer-transfer_id-manifest.txt in the specified location.

74 IBM Aspera Desktop Client 4.3

 2. Calculate the checksum of the corrupted file. This example uses the MD5 checksum method; replace
MD5 with the appropriate checksum method if you use a different one.

# md5sum filepath

3. Compare the checksum reported by Aspera with the checksum that you calculated for the corrupted
file.
• If they do not match, then corruption occurred as the file was written to the destination. Download
the file again and confirm that it is not corrupted. If it is corrupted, compare the checksums again.
If they do not match, investigate the write process or attempt another download. If they match,
continue to the next step.
• If they match, then corruption might have occurred as the file was read from the source. Continue to
the next step.
4. Calculate the checksums for the file on the source. These examples use the MD5 checksum method;
replace MD5 with the appropriate checksum method if you use a different one.
Windows:

> CertUtil -hashfile filepath MD5

Mac OS X:

$ md5 filepath

Linux and Linux on z Systems:

# md5sum filepath

AIX:

# csum -h MD5 filepath

Solaris:

# digest -a md5 -v filepath

5. Compare the checksum of the file on the source with the one reported by Aspera.
• If they do not match, then corruption occurred when the file was read from the source. Download
the file again and confirm that it is not corrupted on the destination. If it is corrupted, continue to the
next step.
• If they match, confirm that the source file is not corrupted. If the source file is corrupted, replace it
with an uncorrupted one, if possible, and then download the file again.

Client-Side Encryption-at-Rest (EAR)

Aspera clients can set their transfers to encrypt content that they upload to a server while it is in transit
and stored on the server, a process known as client-side encryption-at-rest (EAR). The client specifies
an encryption password and the files are uploaded to the server with a .aspera-env extension. Anyone
downloading these .aspera-env files must have the password to decrypt them, and decryption can
occur as the files are downloaded or later once they are physically moved to a computer with no network
connection.
Implementation Notes:
• Client-side and server-side EAR can be used simultaneously, in which case files are doubly encrypted on
the server.
• Servers can require client-side encryption. In this case, transfers that do not use client-side EAR fail
with the error message, "Error: Server aborted session: Server requires content protection."

High-Speed Transfer Client Admin Guide for Linux 75

 • Client-side encryption-at-rest is supported only for ascp transfers, and is not supported for ascp4 or
async transfers.

Using Client-Side EAR

Client-side EAR can be set in the GUI or in the ascp command line.
GUI: Go to Connections > connection_name > Security. Select Encrypt uploaded files with a password
and set the password. Select Decrypt password-protected files downloaded and enter the password.
Ascp command line: First, set the encryption and decryption password as the environment variable
ASPERA_SCP_FILEPASS:

# export ASPERA_SCP_FILEPASS=password

For uploads (--mode=send), use --file-crypt=encrypt. For downloads (--mode=recv), use --

file-crypt=decrypt.

# ascp --mode=send --file-crypt=encrypt source_file user@host:/remote_destination

# ascp --mode=recv --file-crypt=decrypt user@host:/source_path/file.aspera-env local_destination

For more command line examples, see “Ascp General Examples” on page 53.
Note: When a transfer to HSTS falls back to HTTP or HTTPS, client-side EAR is no longer supported. If
HTTP fallback occurs while uploading, then the files are NOT encrypted. If HTTP fallback occurs while
downloading, then the files remain encrypted.

Encrypting and Decrypting Files Outside of a Transfer

For particularly sensitive content, do not store unecrypted content on any computer with network access.
Use an external drive to physically move encrypted files between computers. Desktop Client include the
asprotect and asunprotect command-line tools that can be used to encrypt and decrypt files.
• To encrypt a file before moving it to a computer with network access, run the following command:

# export ASPERA_SCP_FILEPASS=password;/opt/aspera/bin/asprotect -o file1.aspera-env file1

• To download client-side-encrypted files without decrypting them immediately, run the transfer without
decryption enabled (clear Decrypt password-protected files downloaded in the GUI or do not specify
--file-crypt=decrypt on the ascp command line).
• To decrypt encrypted files once they are on a computer with no network access, run the following
command:

# export ASPERA_SCP_FILEPASS=password;/opt/aspera/bin/asunprotect -o file1 file1.aspera-env

Comparison of Ascp and Ascp4 Options

Many command-line options are the same for Ascp and Ascp4; however, some options are available for
only one or the behavior of an option is different. The following table lists the options that are available
only for Ascp or Ascp4, and the options that are available with both. If the option behavior is different, the
Ascp option has ** added to the end and the difference is described following the table.

Ascp Ascp4
-6
-@[range_low:range_high]
-A, --version -A, --version
--apply-local-docroot
-C nodeid:nodecount

76 IBM Aspera Desktop Client 4.3

Ascp Ascp4
-c cipher -c cipher
--check-sshfp=fingerprint
--chunk-size=bytes
--compare=method
--compression=method
--compression-hint=num

-D | -DD | -DDD

-d
--delete-before
--delete-before-transfer** --delete-before-transfer**
--dest64 --dest64
-E pattern -E pattern
-e prepost_filepath
--exclude-newer-than=mtime
--exclude-older-than=mtime
-f config_file -f config_file
--faspmgr-io
--file-checksum=hash
--file-list=filepath** --file-list=filepath**
--file-pair-list=filepath
-G write_size
-g read_size
-h, --help -h, --help
-i private_key_file_path** -i private_key_file_path
-K probe_rate
-k {0|1|2|3} -k {0|1|2|3}
--keepalive --keepalive
-l max_rate -l max_rate
-L local_log_dir[:size] -L local_log_dir[:size]
-m min_rate -m min_rate
--memory=bytes
--meta-threads=num
--mode={send|recv} --mode={send|recv}

--move-after-transfer=archivedir

--multi-session-threshold=threshold

High-Speed Transfer Client Admin Guide for Linux 77

 Ascp Ascp4
-N pattern -N pattern
--no-open
--no-read
--no-write

-O fasp_port -O fasp_port

--overwrite=method** --overwrite=method**
-P ssh-port -P ssh-port
-p -p
--partial-file-suffix=suffix --partial-file-suffix=suffix
--policy={fixed|high|fair|low} --policy={fixed|high|fair|low}
--precalculate-job-size
--preserve-access-time
--preserve-acls=mode
--preserve-creation-time
--preserve-file-owner-gid --preserve-file-owner-gid
--preserve-file-owner-uid --preserve-file-owner-uid
--preserve-modification-time
--preserve-source-access-time
--preserve-xattrs=mode
--proxy=proxy_url
-q -q
-R remote_log_dir -R remote_log_dir
--read-threads=num
--remote-memory=bytes
--remote-preserve-acls=mode
--remote-preserve-xattrs=mode
--remove-after-transfer
--remove-empty-source-directory
--resume (similar to -k)
--retry-timeout=secs
-S remote_ascp
--save-before-overwrite
--scan-threads=num
--source-prefix=prefix
--source-prefix64=prefix

78 IBM Aspera Desktop Client 4.3

 Ascp Ascp4
--sparse-file
--src-base=prefix --src-base=prefix

--symbolic-links=method** --symbolic-links=method**

-T -T
-u user_string -u user_string
--user=username --user=username
-v
-W token_string | @token_filepath
-w{r|f}
-X rexmsg_size -X rexmsg_size
-Z dgram_size -Z dgram_size

Differences in Option Behavior

--delete-before-transfer
With ascp4, --delete-before-transfer can be used with URI storage. URI storage is not
supported for this option in ascp.
--file-list
ascp automatically applies -d if the destination folder does not exist. With ascp4, you must specify
-d, otherwise all the files in the file list are written to a single file.
-i (SSH key authentication)
With ascp, the argument for -i can be just the file name of the private key file and ascp
automatically looks in the .ssh directory of the user's home directory. With ascp4, the full or relative
path to the private key file must be specified.
--overwrite=method
The default overwrite method is "diff" for ascp and "always" for ascp4.
--symbolic-links
Both ascp and ascp4 support follow, copy, and skip, but only ascp supports copy+force.

Ascp FAQs
Answers to some common questions about controlling transfer behavior, such as bandwidth usage,
resuming files, and overwriting files.
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

High-Speed Transfer Client Admin Guide for Linux 79

 Policy Command template

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

The policies have the following characteristics:

• high - Adjust the transfer rate to fully utilize the available bandwidth up to the maximum rate. When
congestion occurs, the transfer rate is twice as fast as a fair-policy transfer. The high policy requires
maximum (target) and minimum transfer rates.
• fair - Adjust the transfer rate to fully utilize the available bandwidth up to the maximum rate.
When congestion occurs, bandwidth is shared fairly by transferring at an even rate. The fair policy
requires maximum (target) and minimum transfer rates.
• low - Adjust the transfer rate to use the available bandwidth up to the maximum rate. Similar to
fair mode, but less aggressive when sharing bandwidth with other network traffic. When congestion
occurs, the transfer rate is reduced to the minimum rate until other traffic decreases.
• fixed - Attempt to transfer at the specified target rate, regardless of network or storage capacity.
This can decrease transfer performance and cause problems on the target storage. Aspera
discourages using the fixed policy except in specific contexts, such as bandwidth testing. The
fixed policy requires a maximum (target) rate.
• aggressiveness - The aggressiveness of transfers that are authorized by this access key in
claiming available bandwidth. Value can be 0.00-1.00. For example: These values correspond to
the policy option where a policy of high approximates to aggressiveness of 0.75, fair to 0.50 and low
to 0.25. Aggressiveness can be used if there is a need to fine tune the transfer policy.
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 computer to
connect to a server, 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 computer, 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 slightly 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 re-
transferring the files?
Use the -k flag to enable resume, and specify a resume rule:
-k 0 – Always re-transfer the entire file.
-k 1 – Compare file attributes and resume if they match, and re-transfer if they do not.

80 IBM Aspera Desktop Client 4.3

 -k 2 – Compare file attributes and the sparse file checksums; resume if they match, and re-
transfer if they do not.
-k 3 – Compare file attributes and the full file checksums; resume if they match, and re-transfer if
they do not.
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. (Default)
• copy - Copy only the alias file. If a file with the same name is found at the destination, the symbolic
link is not copied.
• copy+force - Copy only the alias file. If a file (not a directory) with the same name is found at
the destination, the alias replaces the file. If the destination is a symbolic link to a directory, it's not
replaced.
• skip - Skip symbolic links. Do not copy the link or the file it points to.
Important: On Windows, the only option is skip.
Symbolic link handling also depends on the server configuration and the transfer direction. For more
information, see “Symbolic Link Handling” on page 69.
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 different from the source. If a complete file at the destination is the same
as a file on the source, it is not overwritten. Partial files are overwritten or resumed depending on the
resume policy.
• diff+older - Overwrite the file if older and also different than the source. For example, if the
destination file is the same as the source, but with a different timestamp, it will not be overwritten.
Plus, if the destination file is different than the source, but newer, it will not be overwritten.
• older - Overwrite the file if its timestamp is older than the source timestamp.
Interaction with resume policy (-k): 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 checksums. If -k 3, the source and
destination files are compared based on full checksums.

ascp4: Transferring from the Command Line

Ascp4 is a FASP transfer binary similar to Ascp but it has different strengths as well as capabilities that
are unavailable with Ascp.

Introduction to Ascp4
Ascp4 is a FASP transfer binary that is optimized for sending extremely large sets of individual files. The
executable, ascp4, is similar to ascp and shares many of the same options and capabilities, in addition to
data streaming capabilities.
Both Ascp4 and Ascp are automatically installed with IBM Aspera High-Speed Transfer Server, IBM
Aspera High-Speed Transfer Endpoint, and IBM Aspera Desktop Client.

High-Speed Transfer Client Admin Guide for Linux 81

 As installed, Ascp is used for transfers started from the GUI and Ascp4 transfers can only be initiated
from the command line.

Ascp4 Command Reference

Supported environment variables, the general syntax, and command options for ascp4 are described in
the following sections. ascp4 exits with a 0 on success or a 1 on error. The error code is logged in the
ascp4 log file.

ascp4 Syntax
ascp4 options [[user@]srcHost:]source_file1[,source_file2,...] [[user@]destHost:]dest_path

User
The username of the Aspera transfer user can be specified as part of the as part of the source or
destination, whichever is the remote server or with the --user option. If you do not specify a username
for the transfer, the local username is authenticated by default.
Note: If you are authenticating on a Windows machine as a domain user, the transfer server
strips the domain from the username. For example, Administrator is authenticated rather than
DOMAIN\Administrator. Thus, you must specify the domain explicitly.
Source and destination paths
• If there are multiple source arguments, then the target path must be a directory.
• To describe filepaths, use single quotes (' ') and forward slashes (/) on all platforms.
• To transfer to the transfer user's docroot, specify "." as the destination.
• Avoid the following characters in filenames: / \ " : ' ? > < & * |.
• If the destination is a symbolic link, then the file is written to the target of the symbolic link. However,
if the symbolic link path is a relative path to a file (not a directory) and a partial file name suffix is
configured on the receiver, then the destination path is relative to the user's home directory. Files within
directories that are sent to symbolic links that use relative paths are not affected.
URI paths: URI paths are supported, but only with the following restrictions:
• If the source paths are URIs, they must all be in the same cloud storage account. No docroot
(download), local docroot (upload), or source prefix can be specified.
• If a destination path is a URI, no docroot (upload) or local docroot (download) can be specified.
• The special schemes stdio:// and stdio-tar:// are supported only on the client side. They cannot
be used as an upload destination or download source.
• If required, specify the URI passphrase as part of the URI or set it as an environment variable
(ASPERA_SRC_PASS or ASPERA_DST_PASS, depending on the direction of transfer).
UNC paths: If the server is Windows and the path on the server is a UNC path (a path that points to a
shared directory or file on Windows operating systems) then it can be specified in an ascp4 command
using one of the following conventions:
1. UNC path that uses backslashes ( \ )
If the client side is a Windows machine, the UNC path can be used with no alteration. For example,
\\192.168.0.10\temp. If the client is not a Windows machine, every backslash in the UNC path
must be replaced with two backslashes. For example, \\\\192.168.0.10\\temp.
2. UNC path that uses forward slashes ( / )
Replace each backslash in the UNC path with a forward slash. For example, if the UNC path is
\\192.168.0.10\temp, change it to //192.168.0.10/temp. This format can be used with any
client-side operating system.

82 IBM Aspera Desktop Client 4.3

Required File Access and Permissions
• Sources (for downloads) or destinations (for uploads) on the server must be in the transfer user's
docroot or match one of the transfer user's file restrictions, otherwise the transfer stops and returns an
error.
• The transfer user must have sufficient permissions to the sources or destinations, for example write
access for the destination directory, otherwise the transfer stops and returns a permissions error.
• The transfer user must have authorization to do the transfer (upload or download), otherwise the
transfer stops and returns a "management authorization refused" error.
• Files that are open for write by another process on a Windows source or destination cannot be
transferred and return a "sharing violation" error. On Unix-like operating systems, files that are open
for write by another process are transferred without reporting an error, but may produce unexpected
results depending on what data in the file is changed and when relative to the transfer.

Environment Variables
If needed, you can set the following environment variables for use with an ascp4 session. The total size
for environment variables depends on your operating system and transfer session. Aspera recommends
that each environment variable value should not exceed 4096 characters.
ASPERA_SCP_PASS=password
The password that is used for SSH authentication of the transfer user.
ASPERA_SCP_TOKEN=token
Set the transfer user authorization token. Ascp4 currently supports transfer tokens, which must be
created by using astokengen with the --full-paths option. For more information, see "Transfer
Token Generation (astokengen)" in the IBM Aspera High-Speed
ASPERA_SCP_COOKIE=cookie
A cookie string that is passed to monitoring services.
ASPERA_SRC_PASS=password
The password that is used to authenticate to a URI source.
ASPERA_DST_PASS=password
Set the password that is used to authenticate to a URI destination.
ASPERA_LOCAL_TOKEN=token
A token that authenticates the user to the client (in place of SSH authentication).
Note: If the local token is a basic or bearer token, the access key settings for cipher and
preserve_time are not respected and the server settings are used. To set the cipher and timestamp
preservation options as a client, set them in the command line.

Ascp4 Options
-A, --version
Display version and license information.
-c {aes128|aes192|aes256|none}
Encrypt in-transit file data using the specified cipher. This option overrides the
<encryption_cipher> setting in aspera.conf.
--check-sshfp=fingerprint
Compare fingerprint to the server SSH host key fingerprint that is set with
<ssh_host_key_fingerprint> in aspera.conf. Aspera fingerprint convention is to use a hex
string without the colons; for example, f74e5de9ed0d62feaf0616ed1e851133c42a0082. For more
information on SSH host key fingerprints, see the Admin Guide: Securing your SSH Server.
--chunk-size=bytes
Perform storage read/write operations with the specified buffer size. Also use the buffer size as an
internal transmission and compression block. Valid range: 4 KB - 128 MB. For transfers with object

High-Speed Transfer Client Admin Guide for Linux 83

 storage, use --chunk-size=1048576 if chunk size is not configured on the server to ensure that the
chunk size of ascp4 and Trapd match.
--compare={size|size+mtime|md5|md5-sparse|sha1|sha1-sparse}method
When using --overwrite and --resume, compare files with the specified method. If the --
overwrite method is diff or diff+older, the default --compare method is size.
--compression={none|zlib|lz4}
Compress file data inline. Default: lz4. If set to zlib, --compression-hint can be used to set the
compression level.
--compression-hint=num
Compress file data to the specified level when --compression is set to an option that accepts
compression level settings (currently only zlib). A lower value results in less, but faster, data
compression (0 = no compression). A higher value results in greater, slower compression. Valid values
are -1 to 9, where -1 is "balanced". Default: -1.
-D | -DD | -DDD
Log at the specified debug level. With each D, an additional level of debugging information is written to
the log. This option is not supported if the transfer user is restricted to aspshell.
--delete-before, --delete-before-transfer
Before transfer, delete files that exist at the destination but not at the source. The source and
destination arguments must be directories that have matching names. Objects on the destination that
have the same name but different type or size as objects on the source are not deleted. Do not use
with multiple sources or --keepalive.
--dest64
Indicate that the destination path or URI is base64 encoded.
-E pattern
Exclude files or directories from the transfer based on the specified pattern. Use the -N option
(include) to specify exceptions to -E rules. Rules are applied in the order in which they are
encountered, from left to right. The following symbols can be used in the pattern:
• * (asterisk) represents zero or more characters in a string, for example *.tmp matches .tmp and
abcde.tmp.
• ? (question mark) represents a single character, for example t?p matches tmp but not temp.
Note: When filtering rules are found in aspera.conf, they are applied before rules given on the
command line (-E and -N).
--exclude-newer-than=mtime
--exclude-older-than=mtime
Exclude files (but not directories) from the transfer based on when the file was last changed.
Positive mtime values are used to express time, in seconds, since the original system time (usually
1970-01-01 00:00:00). Negative mtime values (prefixed with "-") are used to express the number of
seconds prior to the current time.
-f config_file
Read Aspera configuration settings from config_file rather than aspera.conf(the default).
--faspmgr-io
Run ascp4 in API mode using FASP manager I/O. ascp4 reads FASPMGR4 commands from
management and executes them. The FASPMGR4 commands are PUT/WRITE/STOP to open/write/
close on a file on the server.
--file-crypt={encrypt|decrypt}
Encrypt files (when sending) or decrypt files (when receiving) for client-side encryption-at-rest
(EAR). Encrypted files have the file extension .aspera-env. This option requires the encryption/
decryption passphrase to be set with the environment variable ASPERA_SCP_FILEPASS. If a client-
side encrypted file is downloaded with an incorrect password, the download is successful, but the
file remains encrypted and still has the file extension .aspera-env. For more information, see
“Client-Side Encryption-at-Rest (EAR)” on page 75.

84 IBM Aspera Desktop Client 4.3

--file-list=filepath
Transfer the files and directories that are listed in filepath. Only the files and directories are
transferred; path information is not preserved at the destination. Each source must be specified on a
separate line, for example:

src
src2
...
srcN

To read a file list from standard input, use "-" in place of filepath (as ascp4 --file-list=- …).
UTF-8 file format is supported. Use with -d if the destination folder does not exist.
Restrictions:
• Paths in file lists cannot use user@host:filepath syntax. You must use --user with --file-
list.
• Only one --file-list option is allowed per ascp4 session. If multiple file lists are specified, all
but the last are ignored.
• Only files and directories from the file list are transferred, and any additional source files or
directories specified on the command line are ignored.
• If more than one read thread is specified (default is 2) for a transfer that uses --file-list, the
files in the file list must be unique. Duplicates can produce unexpected results on the destination.
• Because multiple sources are being transferred, the destination must be a directory.
• If the source paths are URIs, the size of the file list cannot exceed 24 KB.
For very large file lists (~100 MB+), use with --memory to increase available buffer space.
--file-manifest={none|text}
Generate a list of all transferred files when set to text. Requires --file-manifest-path to specify
the location of the list. (Default: none)
--file-manifest-path=directory
Save the file manifest to the specified location when using --file-manifest=text. File manifests
must be stored locally. For cloud or other non-local storage, specify a local manifest path.
--file-manifest-inprogress-suffix=suffix
Apply the specified suffix to the file manifest's temporary file. For use with --file-manifest=text.
(Default suffix: .aspera-inprogress)
-h, --help
Display the usage summary.
--host=host
Transfer to the specified host name or address. Requires --mode. This option can be used instead of
specifying the host as part of the filename (as hostname:filepath).
-i private_key_file
Authenticate the transfer using public key authentication with the specified SSH private key file
(specified with a full or relative path). The private key file is typically in the directory $HOME/.ssh/. If
multiple -i options are specified, only the last one is used.
-k {0|1|2|3}
Enable the resumption of partially transferred files at the specified resume level. Default: 0. This
option must be specified for your first transfer or it does not work for subsequent transfers. Resume
levels:
• -k 0: Always re-transfer the entire file (same as --overwrite=always).
• -k 1: Compare file modification time and size and resume if they match (same as --
overwrite=diff --compare=size --resume).
• -k 2: Compare sparse checksum and resume if they match (same as --overwrite=diff --
compare=md5-sparse --resume).

High-Speed Transfer Client Admin Guide for Linux 85

 • -k 3: Compare full checksum and resume if they match (same as --overwrite=diff --
compare=md5 --resume).
--keepalive
Enable ascp4 to run in persistent mode. This option enables a persistent session that does not
require that source content and its destination are specified at execution. Instead, the persistent
session reads source and destination paths through mgmt commands. Requires --mode and --host.
-L local_log_dir[:size]
Log to the specified directory on the client machine rather than the default directory. Optionally, set
the size of the log file (default 10 MB).
-l max_rate
Transfer at rates up to the specified target rate. Default: 10 Mbps. This option accepts suffixes "G/g"
for Giga, "M/m" for Mega, "K/k" for Kilo, and "P/p/%" for percentage. Decimals are allowed. If this
option is not set by the client, the server target rate is used. If a rate cap is set in the local or server
aspera.conf, then the rate does not exceed the cap.
For streaming, the value should be equal to or greater than the bitrate of the video.
-m min_rate
Attempt to transfer no slower than the specified minimum transfer rate. Default: 0. If this option is not
set by the client, then the server's aspera.conf setting is used. If a rate cap is set in the local or
server aspera.conf, then the rate does not exceed the cap.
--memory=bytes
Allow the local ascp4 process to use no more than the specified memory. Default: 256 MB. See also
--remote-memory.
--meta-threads=num
Use the specified number of directory "creation" threads (receiver only). Default: 2.
--mode={send|recv}
Transfer in the specified direction: send or recv (receive). Requires --host.
-N pattern
Protect ("include") files or directories from exclusion by any -E (exclude) options that follow it. Files
and directories are specified using pattern. Each option-plus-pattern is a rule. Rules are applied in the
order (left to right) in which they're encountered. Thus, -N rules protect files only from -E rules that
follow them. Create patterns using standard globbing wildcards and special characters such as the
following:
• * (asterisk) represents zero or more characters in a string, for example *.tmp matches .tmp and
abcde.tmp.
• ? (question mark) represents any single character, for example t?p matches tmp but not temp.
Note: Filtering rules can also be specified in aspera.conf. Rules found in aspera.conf are applied
before any -E and -N rules specified on the command line.
--no-open
In test mode, do not actually open or write the contents of destination files.
--no-read
In test mode, do not read the contents of source files.
--no-write
In test mode, do not write the contents of destination files.
-O fasp_port
Use the specified UDP port for FASP transfers. Default: 33001.
--overwrite={always|never|diff|diff+older|older}
Overwrite files at the destination with source files of the same name based on the method. Default:
always. Use with --compare and --resume. method can be the following:
• always – Always overwrite the file.

86 IBM Aspera Desktop Client 4.3

 • never – Never overwrite the file. If the destination contains partial files that are older or the same
as the source files and --resume is enabled, the partial files resume transfer. Partial files with
checksums or sizes that differ from the source files are not overwritten.
• diff – Overwrite the file if it is different from the source, depending on the compare method
(default is size). If the destination is object storage, diff has the same effect as always.
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, files resume.
• diff+older – Overwrite the file if it 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 the file if its timestamp is older than the source timestamp.
-P ssh-port
Use the specified TCP port to initiate the FASP session. (Default: 22)
-p
Preserve file timestamps for access and modification time. Equivalent to setting --
preserve-modification-time, --preserve-access-time, and --preserve-creation-
time. Timestamp support in object storage varies by provider; consult your object storage
documentation to determine which settings are supported.
On Windows, modification time 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.
--partial-file-suffix=suffix
Enable the use of partial files for files that are in transit, and set the suffix to add to names of partial
files. (The suffix does not include a " . ", as for a file extension, unless explicitly specified as part of
the suffix.) This option only takes effect when set on the receiver side. When the transfer is complete,
the suffix is removed. (Default: suffix is null; use of partial files is disabled.)
--policy={fixed|high|fair|low}
Transfer according to the specified policy:
• fixed – Attempt to transfer at the specified target rate, regardless of network capacity. Content is
transferred at a constant rate and the transfer finishes in a guaranteed time. The fixed policy can
consume most of the network's bandwidth and is not recommended for most types of file transfers.
This option requires a maximum (target) rate value (-l).
• high – Adjust the transfer rate to fully utilize the available bandwidth up to the maximum rate.
When congestion occurs, the transfer rate is twice as fast as transfer with a fair policy. This option
requires maximum (target) and minimum transfer rates (-l and -m).
• fair – Adjust the transfer rate to fully utilize the available bandwidth up to the maximum rate.
When congestion occurs, bandwidth is shared fairly by transferring at an even rate. This option
requires maximum (target) and minimum transfer rates (-l and -m).
• low – Adjust the transfer rate to use the available bandwidth up to the maximum rate. Similar to
fair mode, but less aggressive when sharing bandwidth with other network traffic. When congestion
occurs, the transfer rate is reduced to the minimum rate until other traffic decreases.
If --policy is not set, ascp4 uses the server-side policy setting (fair by default).
--preserve-access-time
Preserve the file timestamps (currently the same as -p).
--preserve-creation-time
Preserve the file timestamps (currently the same as -p).

High-Speed Transfer Client Admin Guide for Linux 87

 --preserve-file-owner-gid
--preserve-file-owner-uid
(Linux, UNIX, and macOS only) Preserve the group information (gid) or owner information (uid) of
the transferred files. These options require that the transfer user is authenticated as a superuser.
--preserve-modification-time
Preserve the file timestamps (currently the same as -p).
--preserve-source-access-time
Preserve the file timestamps (currently the same as -p).
-q
Run ascp4 in quiet mode. This option disables the progress display.
-R remote_log_dir
Log to the specified directory on the remote host rather than the default directory. Note: Client users
that are restricted to aspshell are not allowed to use this option.
--read-threads=num
Use the specified number of storage "read" threads (sender only). Default: 2. To set "write" threads on
the receiver, use --write-threads.
Note: If more than one read thread is specified for a transfer that uses --file-list, the files in the
file list must be unique. Duplicates can produce unexpected results on the destination.
--remote-memory=bytes
Allow the remote ascp4 process to use no more than the specified memory. Default: 256 MB.
--remove-empty-directories
Remove empty source directories once the transfer has completed successfully, but do not remove
a directory specified as the source argument. To also remove the specified source directory, use --
remove-empty-source-directory. Directories can be emptied using --move-after-transfer
or --remove-after-transfer. Scanning for empty directories starts at the srcbase and proceeds
down any subdirectories. If no source base is specified and a file path (as opposed to a directory path)
is specified, then only the immediate parent directory is scanned and removed if it's empty following
the move of the source file. Note: Do not use this option if multiple processes (ascp4 or other) might
access the source directory at the same time.
--resume
Resume a transfer rather than re-transferring the content if partial files are present at the destination
and they do not differ from the source file based on the --compare method. If the source and
destination files do not match, then the source file is re-transferred. See -k for another way to enable
resume.
--scan-threads=num
Use the specified number of directory "scan" threads (sender only). Default: 2.
-SSH
Use an external SSH program instead of the built-in libssh2 implementation to establish the
connection with the remote host. The desired SSH program must be defined in the environment's
PATH variable. To enable debugging of the SSH process, use the -DD and --ssh-arg=-vv options
with ascp4.
--ssh-arg=ARG
Add ARG to the command-line arguments passed to the external SSH program (this implies using-
SSH). This option may be repeated as needed to supply multiple separate SSH arguments. The order
is preserved. The ARG elements are inserted before any key file(s) supplied to ascp4, and before the
user/host argument.
--sparse-file
Enable ascp4 to write sparse files to disk. This option prevents ascp4 from writing zero content to
disk for sparse files; ascp4 writes a block to disk if even one bit is set in that block. If no bits are set in
the block, ascp4 does not write the block (ascp4 blocks are 64 KB by default).

88 IBM Aspera Desktop Client 4.3

--src-base=prefix
Strip the specified prefix from each source path. The remaining portion of the source path is kept
intact at the destination. Available only in send mode.
Use with URIs: The --src-base option performs a character-to-character match with the source
path. For object storage source paths, the prefix must specify the URI in the same manner as the
source paths. For example, if a source path includes an embedded passphrase, the prefix must also
include the embedded passphrase otherwise it will not match.
--symbolic-links={follow|copy|skip}
Handle symbolic links using the specified method. On Windows, the only option is skip. On other
operating systems, this option takes following values:
• follow – Follow symbolic links and transfer the linked files. (Default)
• copy – Copy only the alias file. If a file with the same name exists on the destination, the symbolic
link is not copied.
• skip – Skip symbolic links. Do not copy the link or the file it points to.
-T
Disable in-transit encryption for maximum throughput.
-u user_string
Define a user string for Lua scripts that can be run with transfer events. See Transfer Session Data
Accessible to Scripts.
--user=username
Authenticate the transfer using the specified username. Use this option instead of specifying the
username as part of the destination path (as user@host:file).
Note: If you are authenticating on a Windows machine as a domain user, the transfer server
strips the domain from the username. For example, Administrator is authenticated rather than
DOMAIN\Administrator. Thus, you must specify the domain explicitly.
--worker-threads=num
Use the specified number of worker threads for deleting files. On the receiver, each thread deletes one
file or directory at a time. On the sender, each thread checks for the presences of one file or directory
at a time. Default: 1.
--write-threads=num
Use the specified number of storage "write" threads (receiver only). Default: 2. To set "read" threads
on the sender, use --read-threads.
For transfers to object or HDFS storage, write threads cannot exceed the maximum number of jobs
that are configured for Trapd. Default: 15. To use more threads, open /opt/aspera/etc/trapd/
trap.properties on the server and set aspera.session.upload.max-jobs to a number larger
than the number of write threads. For example,

# Number of jobs allowed to run in parallel for uploads.

# Default is 15
aspera.session.upload.max-jobs=50

-X rexmsg_size
Limit the size of retransmission requests to no larger than the specified size, in bytes. Max: 1440.
-Z dgram_size
Use the specified datagram size (MTU) for FASP transfers. Range: 296-65535 bytes. Default: the
detected path MTU.
As of version 3.3, datagram size can be specified on the server by setting <datagram_size> in
aspera.conf. The server setting overrides the client setting, unless the client is using a version of
ascp that is older than 3.3, in which case the client setting is used. If the pre-3.3 client does not set
-Z, the datagram size is the discovered MTU and the server logs the message "LOG Peer client doesn't
support alternative datagram size".

High-Speed Transfer Client Admin Guide for Linux 89

Ascp4 Transfers with Object Storage
Files that are transferred with object storage are sent in chunks through the Aspera Trapd service. By
default, ascp4 uses 64 KB chunks and Trapd uses 1 MB chunks; this mismatch in chunk size can cause
ascp4 transfers to fail.
To avoid this problem, take one of the following actions:
1. Set the chunk size (in bytes) in the server's aspera.conf. This value is used by both ascp4 and
Trapd, so the chunk sizes match.
To set a global chunk size, run the following command:

# asconfigurator -x "set_node_data;transfer_protocol_options_chunk_size,value"

Where value is between 256 KB (262144 bytes) and 1 MB (1048576 bytes).

To set a chunk size for the user, run the following command:

# asconfigurator -x "set_user_data;user_name,
username;transfer_protocol_options_chunk_size,value"

2. Set the chunk size in the client's aspera.conf to the Trapd chunk size.
If Trapd is using the default chunk size, run the following command to set the chunk size to 1 MB:

# asconfigurator -x "set_node_data;transfer_protocol_options_chunk_size,1048576"

3. Set the chunk size in the client command line.

Run the ascp4 session with the chunk size setting: --chunk-size=1048576.

Ascp4 Examples
The command options for ascp4 are generally similar to those for ascp. The following examples
demonstrate options that are unique to Ascp4. These options enable reading management commands
and enable read/write concurrency.
For Ascp examples, see “Ascp Command Reference” on page 38. See “Comparison of Ascp and Ascp4
Options” on page 76 for differences in option availability and behavior.
• Read FASP4 management commands
Read management commands V4 from management port 5000 and execute the management
commands. The management commands version 4 are PUT, WRITE and CLOSE.

# ascp4 -L /tmp/client-logs -R /tmp/server-logs --faspmgr-io -M 5000 localhost:/tmp

• Increase concurrency
The following command runs ascp4 with two scan threads and eight read threads on the client, and
eight meta threads and 16 write threads on the server.

# ascp4 -L /tmp/logs -R /tmp/logs -l1g --scan-threads=2 --read-threads=8 --write-threads=16

--meta-threads=8 /data/100K [email protected]:/data

Built-in I/O Provider

Input/Output provider are library modules that abstract I/O scheme in Ascp4 architecture. Ascp4 has the
following built-in I/O provider:
• file (as a simple path or file://path)

90 IBM Aspera Desktop Client 4.3

 File provider
The local disk can be specified for ascp4 I/O by using a simple path or URL that starts with file. The
following paths identify the same file (/test/ascp4.log) on the disk:
file:////test/ascp4.log
/test/ascp4.log
file://localhost:/test/ascp4.log
Similarly, the following URLs identify the same file (test/ascp4.log) on the disk:
file:///test/ascp4.log
test/ascp4.log

Appendix
Restarting Aspera Services
When you change product settings, you might need to restart certain Aspera services in order for the new
values to take effect.

IBM Aspera Central

If asperacentral is stopped, or if you have modified the <central_server> or <database> sections in
aspera.conf, then you need to restart the service.
Run the following command in a Terminal window to restart asperacentral:

# systemctl restart asperacentral

or for Linux systems that use init.d:

# service asperacentral restart

IBM Aspera NodeD

Restart asperanoded if you have modified any setting in aspera.conf.
Run the following commands to restart asperanoded:

# systemctl restart asperanoded

or for Linux systems that use init.d:

# service asperanoded restart

Testing and Optimizing Transfer Performance

To verify that your system's FASP transfer is reaching the target rate and can use the maximum bandwidth
capacity, prepare a client to connect to an Aspera server. For these tests, you can transfer an existing file
or file set, or you can transfer uninitialized data in place of a source file, which you can destroy at the
destination, eliminating the need to read from or write to disk and saving disk space.

Using faux:/// as a Test Source or Destination

You can use faux:/// as the argument for the source or destination of an Ascp session to test data
transfer without reading from disk on the source and writing to disk on the target. The argument takes
different syntax depending on if you are using it as a mock source file or mock source directory.

High-Speed Transfer Client Admin Guide for Linux 91

 Note: If you set very large file sizes (> PB) in a faux:/// source, Aspera recommends that you use
faux:// as a target on the destination because most computers do not have enough system memory
available to handle files of this size and your transfer might fail.
Faux Source File
To send random data in place of a source file (do not read from the source), you can specify the file
as faux:///fname?fsize.fname is the name assigned to the file on the destination and fsize is the
number of bytes to send. fsize can be set with modifiers (k/K, m/M, g/G, t/T, p/P, or e/E) to a maximum of
7x260 bytes (7 EiB).
For example:

# ascp --mode=send --user=username --host=host_ip_address faux:///fname?fsize target_path

Faux Source Directory

In some cases, you might want to test the transfer of an entire directory, rather than a single file. Specify
the faux source directory with the following syntax:

faux:///dirname?file=file&count=count&size=size&inc=increment&seq=sequence&buf_init=buf_option

Where:
• dirname is a name for the directory (required)
• file is the root for file names, default is "file" (optional)
• count is the number of files in the directory (required)
• size is the size of the first file in the directory, default 0 (optional). size can be set with modifiers (k/K,
m/M, g/G, t/T, p/P, or e/E) to a maximum of 7x260 bytes (7 EiB).
• increment is the increment of bytes to use to determine the file size of the next file, default 0 (optional)
• sequence is how to determine the size of the next file: "sequential" or "random". Default is "sequential"
(optional). When set to "sequential", file size is calculated as:

size + ((N - 1) * increment)

Where N is the file index; for the first file, N is one.

When set to "random", file size is calculated as:

size +/- (rand * increment)

Where rand is a random number between zero and one. If necessary, increment is automatically
adjusted to prevent the file size from being negative.
For both options, increment is adjusted to prevent the file size from from exceeding 7x260 bytes.
• buf_option is how faux source data are initialized: "none", "zero", or "random". Default is "zero". "none" is
not allowed for downloads (Ascp run with --mode=recv).
When the defaults are used, Ascp sends a directory that is named dirname and that contains count
number of zero-byte files that are named file_count.
For example, to transfer a faux directory ("mydir") that contains 1 million files to /tmp on 10.0.0.2, and
the files in mydir are named "testfile" and file size increases sequentially from 0 to 2 MB by an increment
of 2 bytes:

# ascp --mode=send --user=username --host=10.0.0.2 faux:///mydir?

file=testfile&count=1m&size=0&inc=2&seq=sequential /tmp

Faux Target
To send data but not save the results to disk at the destination (do not write to the target), specify the
target as faux://.

92 IBM Aspera Desktop Client 4.3

For example, to send a real file to a faux target, run the following command:

# ascp --mode=send --user=username --host=host_ip_address source_file1 faux://

To send random data to a faux target, run the following command:

# ascp --mode=send --user=username --host=host_ip_address faux:///fname?fsize faux://

Testing Transfer Performance

1. Start a transfer with fair transfer policy and compare the transfer rate to the target rate.
On the client computer, open the user interface and start a transfer (either from the GUI or command
line). Click Details to open the Transfer Monitor.

To leave more network resources for other high-priority traffic, use the Fair policy and adjust the target
rate and minimum rate by sliding the arrows or entering values.
2. Test the maximum bandwidth.
Note: This test will typically occupy a majority of the network's bandwidth. Aspera recommends
performing it on a dedicated file transfer line or during a time of very low network activity.
Use Fixed policy for the maximum transfer speed. Start with a lower transfer rate and increase
gradually toward the network bandwidth.

Hardware Upgrades for Better Performance

To improve the transfer speed, you can also upgrade the related hardware components:

Component Description
Hard disk The I/O throughput, the disk bus architecture (such as RAID, IDE, SCSI, ATA, and
Fiber Channel).

High-Speed Transfer Client Admin Guide for Linux 93

 Component Description
Network I/O The interface card, the internal bus of the computer.
CPU Overall CPU performance affects the transfer, especially when encryption is
enabled.

aclean Reference
The Aspera aclean command-line tool is a fast method of deleting directories and files from local and
object storage. Directories and files can be filtered based on their last modified times. For Windows
operating systems, the created time (CTIME) and modified time (MTIME) are used as the matching criteria.
You can do a dry run of an aclean command to test what content will be deleted. aclean can be run on
any platform on which Ascp4 is supported.
Note: The directory specified in an aclean command is not deleted. Only the content in the directory that
matches the options is deleted.
Syntax

aclean [options] directory

Directory path format

• Local paths: Paths to local storage can be full or relative paths, and use "/" separators for all operating
systems, including Windows. Full Windows paths must use the format /c:/path/to/delete.
• Object storage: Specify a path to object storage with its URI. For example, Azure storage has the syntax
azu://storage_account:[email protected]/path_to_blob
and a URL to AWS S3 has the syntax s3://access_id:[email protected]/
my_bucket/path. For more information on URL syntax for other object storage types, see “Ascp
Transfers with Object Storage and HDFS” on page 58. The variable components of the URI must be URL
encoded.
Options

Option (short version, long Description

version)
-h, --help Display help.
-A, --version Display version.
-L, --logdir Set the filepath for the log directory.
-n, --dry-run Run the command as a trial to show what content would be deleted.
-t, --threads Set the number of threads to use to scan the directory. (Default: 8)
--remove-empty-dirs Delete empty subdirectories from the specified directory.
--remove-newer-than=MTIME Delete files that are newer than MTIME. MTIME is a date and time
string with the format YYYY-mm-dd HH:MM. The timestamp is based
on the local time of the machine.
--remove-older-than=MTIME Delete files that are older than MTIME. MTIME is a date and time
string with the format YYYY-mm-dd HH:MM. The timestamp is based
on the local time of the machine.

Examples
Delete the contents of the local directory /temp/logs-test/:

$ aclean /temp/logs-test/

94 IBM Aspera Desktop Client 4.3

 View what files would be deleted if /temp/logs-test/ is deleted:

$ aclean --dry-run /temp/logs-test/

Delete subdirectories in /temp/logs-test/ if they are empty:

$ aclean --remove-empty-dirs /temp/logs-test/

Delete files that have a last-modified time older than March 27, 2017 13:34 from Azure object storage:

$ aclean --remove-older-than=2017-03-27 13:34 azu://user:[email protected]

Log Files
The application log file includes detailed transfer information and can be useful for review and support
requests. You can configure log rotation and redirect Aspera logging so that it is not recorded in the
system log file.

Viewing Logs and Setting Log Preferences

To view the log, from the GUI, click Tools > View Log.

Note: To view logs from the command line in Linux, you must have a functional web-browser or other
default application for opening HTML files.
To set the logging level for transfers, open the My Preferences dialog by clicking Tools > Preferences or
by clicking Preferences in the upper-right corner of the application window.

The five logging levels to select from are: Off, Error, Warn, Info, and Debug. The system default is Info.

High-Speed Transfer Client Admin Guide for Linux 95

 Redirecting Aspera Logging to a Different Location
On Linux systems, the application transfer logs are recorded in the system log file. Instead of mixing
Aspera logging with system logging, you may want to redirect Aspera logging to a separate log file of your
choice.
RedHat, CentOS, and Debian
On RedHat, CentOS, and Debian, the transfer logs are recorded in the following log file: /var/log/
messages
To redirect Aspera logging, modify /etc/syslog.conf (/etc/rsyslog.conf in the case of Red Hat
or CentOS 6.XA) and add local2.none to the /var/log/messages line. For example, if you have the
following line:

*.info;mail.none;authpriv.none;cron.none /var/log/messages

Change it to:

*.info;mail.none;authpriv.none;cron.none;local2.none /var/log/messages

Next, forward local2.info log messages to your new file. For example, to write to /var/log/
aspera.log, add the following line just below the line you modified above:

local2.info -/var/log/aspera.log

The log file name should be separated from the log facility (local2.info) by tab characters, not spaces
and be preceded by a hyphen. The hyphen before the log file name allows for asynchronous logging.
Next, restart the syslog daemon to have it load the new configuration:

# service syslog restart

In the case of Red Hat or CentOS 6.X:

# service rsyslog restart

Your Aspera log messages now appear in /var/log/aspera.log instead of /var/log/messages.

SLES (Suse) systems

96 IBM Aspera Desktop Client 4.3

On SLES (Suse) systems, the transfer logs are recorded in the following system log file: /var/log/
localmessages
To redirect Aspera logging, locate the following section in /etc/syslog-ng/syslog-ng.conf:

filter f_local { facility(local0, local1, local2, local3, local4, local5, local6, local7); };

destination localmessages { file("/var/log/localmessages"); };

log { source(src); filter(f_local); destination(localmessages); };

Modify the section as follows:

filter f_local { facility(local0, local1, local3, local4, local5, local6, local7); };

filter f_aspera { facility(local2); };

destination localmessages { file("/var/log/localmessages"); };

log { source(src); filter(f_local); destination(localmessages); };

destination asperalog { file("/var/log/aspera.log"); };

log { source(src); filter(f_aspera); destination(asperalog); };

Then run the following command:

# rcsyslog restart

Your Aspera log messages now appear in /var/log/aspera.log instead of /var/log/

localmessages.
To test this, run the following commands:

# logger -p local2.info aspera test

# cat /var/log/aspera.log

The cat command should display something similar to the following:

Jun 13 10:30:33 linux-kua5 root: aspera test

Rotating Your Aspera Log File

There are several ways to rotate Aspera logs in Linux:
1. Add /var/log/aspera.log to /etc/logrotate.d/syslog.
2. Create an entry for aspera.log in /etc/logrotate.conf.
3. Create a separate configuration file for aspera.log in /etc/logrotate.d/.
The first option rotates your logs with the system logs (usually once a week, compressed, and saving the
last 10 logs). On some servers, there is so much traffic that the logs need to be rotated more often than
once a week, in which case option 2 or 3 should be used.
1. Add /var/log/aspera.log to the entries in /etc/logrotate.d/syslog, as follows:

/var/log/messages /var/log/secure /var/log/maillog /var/log/spooler /var/log/boot.log /var/log/

cron /var/log/aspera.log
{
sharedscripts
postrotate
/bin/kill -HUP `cat /var/run/syslogd.pid 2> /dev/null` 2> /dev/null || true
/bin/kill -HUP `cat /var/run/rsyslogd.pid 2> /dev/null` 2> /dev/null || true
endscript
}

2. Edit /etc/logrotate.conf by adding the configuration after the line "# system-specific
logs may also be configured here." The following example compresses and rotates 10 logs

High-Speed Transfer Client Admin Guide for Linux 97

 whenever /var/log/aspera.log reaches 100MB. After log rotation is complete, it runs whatever
scripts are specified by postrotate ... endscript.

/var/log/aspera.log {
rotate 10
size 100M
create 664 root
postrotate
/usr/bin/killall -HUP syslogd
endscript
compress
}

The following example compresses and rotates 10 logs once daily. Instead of moving the original log file
and creating a new one, the copytruncate option tells logrotate to first copy the original log file, then
truncate it to zero bytes.

/var/log/aspera.log {
daily
rotate 10
copytruncate
compress
}

3. Create a separate /etc/logrotate.d/aspera configuration file containing the same information as

option 2.

Preserving IBM Spectrum Scale ACLs of Transferred Files

Ascp and Aspera Sync can preserve NFSv4 and POSIX ACLs and immutability attributes when transferring
files from an IBM Spectrum Scale (formerly GPFS) cluster to another cluster.
Preserving Spectrum Scale ACLs
To preserve file attributes and permissions when transferring from one Spectrum Scale cluster to another,
run ascp or async with the --preserve-xattrs=native option.
Preserving Expiration Attributes of Immutable Filesets
To preserve expiration attributes, use timestamp preservation options:
• Ascp: Use --preserve-access-time to preserve only the expiration attributes or -p to preserve all
timestamps.
• Aspera Sync: Use--preserve-access-time.
Important Behavior Notes
Attribute preservation:
• Pools, replication, and cloning attributes are not preserved from source to destination.
• In Aspera Sync transfers, security attributes are preserved only when the user on both endpoints is root.
Immutable files and directories:
• Immutable directories on the source are not set as immutable on the destination. This ensures that the
contents of the directory can be transferred.
• When the destination file already exists and the source file is changed to immutable (immutable:
yes), Ascp and Aspera Sync update the destination file from mutable to immutable. However, if the
source file is changed back to mutable (immutable: no), the change cannot be applied to the
destination file because it is still immutable. Manually change the destination file, after which Ascp
and Aspera Sync can write content and permissions changes.
• When the destination file already exists and is immutable, Ascp and Aspera Sync return an error for the
immutable file (Destination: Read-only file system) and then transfers any other files in the
transfer.
Append-only files:

98 IBM Aspera Desktop Client 4.3

 • When the source file is an append-only file (appendOnly: yes), it can be transferred once to the
destination. After the initial transfer, it cannot be updated by Ascp or Aspera Sync because FASP must
overwrite the file.
• When the destination file already exists and is an append-only file, Ascp and Aspera Sync either stop
the rest of the transfer (for Spectrum Scale 5.0.1) or return an error for the file (Destination:
Read-only file system) and then transfers any other files (for Spectrum Scale 5.0.0). To avoid
transfer failures, Aspera recommends excluding append-only files that exist on the destination from
consideration on the source.

Connecting to IBM Aspera Shares from the GUI

As of IBM Aspera Shares version 1.9.3, the client must have version 3.6.0 or later of HSTS, HSTE, or
Desktop Client installed in order to access Shares on a server with version 3.6.0 or later of HSTS, HSTE, or
Desktop Client installed.
1. To connect to Shares in the Desktop Client GUI, go to Connections and click the button.
Enter the following information:

Field Value Example

Host https://host_FQDN https://shares.example.com/
User Shares username (of user with shares_user
API Login enabled)
Authentication Shares user password X45ape34_1
2. Click Test Connection to confirm your client application has successfully connected to Shares.
3. Click Browse to specify the target directory.
4. Click OK to save the connection.

Logging Client File System Activity on an HST Server

The HST server can be configured to log operations on the server's file system that are performed from
client applications (such as the HST server in client mode, or Console).
The logging of specific file system operations is controlled with an <ascmd> element in aspera.conf,
within which logging can be set to yes or no for each operation.

<ascmd>
<log_cmd>
<as_info>no</as_info>
<as_ls>no</as_ls>
<as_rm>no</as_rm>
<as_du>no</as_du>
<as_df>no</as_df>
<as_mkdir>no</as_mkdir>
<as_cp>no</as_cp>
<as_mv>no</as_mv>
<as_md5sum>no</as_md5sum>
</log_cmd>
</ascmd>

As an example of asconfigurator usage, the following command specifies that any deletions from the
server file system by user xeno are logged:

asconfigurator -x "set_user_data;user_name,xeno;ascmd_log_cmd_as_rm,yes"

The command generates this <ascmd> element in aspera.conf:

<ascmd>
<log_cmd>
<as_rm>yes</as_rm>
</log_cmd>
</ascmd>

High-Speed Transfer Client Admin Guide for Linux 99

Product Limitations
Describes any limitations that currently exist for Aspera transfer server and client products.
• Path Limit: The maximum number of characters that can be included in any pathname is 512 on
Windows and 4096 on Unix-based platforms.
• Illegal Characters: Avoid the following characters in filenames: / \ " : ' ? > < & * |.
• Environment Variables: The total size for environment variables depends on your operating system and
transfer session. Aspera recommends that each environment variable value should not exceed 4096
characters.

100 IBM Aspera Desktop Client 4.3

IBM®