IBM Aspera Desktop Client 4.

IBM
Contents

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

Introduction................................................................................................................................................. 1
Getting started as a transfer client.............................................................................................................. 3
Installation and upgrades............................................................................................................................4
Requirements......................................................................................................................................... 4
Before upgrading or downgrading..........................................................................................................4
Installing Desktop Client........................................................................................................................ 7
Configuring the firewall.......................................................................................................................... 9
Testing a transfer.................................................................................................................................... 9
Uninstalling...........................................................................................................................................10
Transfer files in the GUI............................................................................................................................. 11
Overview of the Desktop Client GUI.................................................................................................... 11
Global bandwidth settings................................................................................................................... 13
Enabling a transfer proxy or HTTP proxy............................................................................................. 14
Adding and editing connections...........................................................................................................18
Exporting and importing connections..................................................................................................26
Creating SSH keys in the GUI............................................................................................................... 27
Transferring content............................................................................................................................. 31
Managing transfers...............................................................................................................................33
Scheduling and customizing transfers in advanced mode..................................................................35
Configuring transfer notifications........................................................................................................ 38
Using transfer notifications.................................................................................................................. 45
Hot Folders.................................................................................................................................................46
Setting up Hot Folders..........................................................................................................................47
Managing Hot Folders.......................................................................................................................... 52
ascp: Transferring from the command line............................................................................................... 55
Ascp command reference.................................................................................................................... 55
Ascp general examples........................................................................................................................ 71
Ascp file manipulation examples.........................................................................................................74
Ascp transfers with object storage and HDFS..................................................................................... 75
Using standard I/O as the source or destination.................................................................................79
Using filters to include and exclude files............................................................................................. 82
Symbolic link handling......................................................................................................................... 87
Creating SSH keys from the command line......................................................................................... 89
Reporting checksums...........................................................................................................................90
Client-Side Encryption-at-Rest (EAR).................................................................................................. 94
Comparison of ascp and ascp4 options...............................................................................................95
Ascp FAQs.............................................................................................................................................98
ascp4: Transferring from the command line...........................................................................................100
Introduction to ascp4........................................................................................................................ 100
Ascp4 command reference................................................................................................................100
Ascp4 transfers with object storage..................................................................................................109
Ascp4 examples................................................................................................................................. 109
Built-in I/O provider........................................................................................................................... 109
Appendix.................................................................................................................................................. 110
Managing the Aspera service account...............................................................................................110
Restarting Aspera services................................................................................................................ 111
Testing and optimizing transfer performance................................................................................... 111
aclean reference.............................................................................................................................. 114
Log files...............................................................................................................................................115
Connecting to IBM Aspera Shares from the GUI...............................................................................116

ii
Logging client file system activity on HSTS....................................................................................... 117
Product limitations.............................................................................................................................117

iii
iv
High-Speed Transfer Client Admin Guide for Windows
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 started 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 whether 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 IBM Aspera High-Speed Transfer Server (HSTS), IBM Aspera High-Speed
Transfer Endpoint (HSTE), 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 to the Aspera server. Aspera applications that
can act as clients include:
• IBM Aspera Desktop Client.
• Faspex.
• IBM Aspera Connect.
• HSTS and HSTE.
• IBM Aspera Command Line Interface - ascli (open source).
What is FASP?
At the heart of your Aspera ecosystem are the FASP transfer engines Ascp and Ascp4.
Ascp maximizes data transport over any network and is suited to large files. It is a powerful command line
tool and also drives transfers that are started in the GUI.

High-Speed Transfer Client Admin Guide for Windows 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 in real time, 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 that is 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 various 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.4

 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 the Aspera Watch service 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 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.

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

Procedure
1. Review the system requirements and install Desktop Client.
See “Requirements” on page 4 and “Installing Desktop Client” on page 7.
2. Configure the firewall, if it is not already configured.
See “Configuring the firewall” on page 9.
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 13 and “Enabling a transfer proxy or
HTTP proxy” on page 14.
4. Test a locally initiated transfer to the Aspera demonstration server to confirm that your installation and
firewall configuration are operational.
For instructions, see “Testing a transfer” on page 9. 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 38.
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 27 or “Creating
SSH keys from the command line” on page 89.
7. To run transfers in the GUI, create and configure a connection to the server.
For instructions, see “Adding and editing connections” on page 18. If required, configure a proxy
(“Enabling a transfer proxy or HTTP proxy” on page 14). You can also configure transfer notifications
(“Scheduling and customizing transfers in advanced mode” on page 35).

High-Speed Transfer Client Admin Guide for Windows 3

 Once your connection is configured, you can initiate transfers with the server. For instructions, see
“Transferring content” on page 31.
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 95.
• For more information about ascp, see “Ascp command reference” on page 55 and “Ascp general
examples” on page 71.
• For more information about A4, see “Ascp4 command reference” on page 100 and “Ascp4
examples” on page 109.

Results
Once you confirm that you can transfer with your server, your basic setup is complete.
• If you want to automatically send or receive files and folders when they are added to a specific folder on
your computer or the server, see “Hot Folders” on page 46.

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 .
• Windows 64-bit: Windows 8.1, 10, or Windows Server 2012 R2, 2016, 2019.
• For usage in an Active Directory environment you must have access to a domain administrator account
to install the product.
• Access to run WMI.

Before upgrading or downgrading

When upgrading or downgrading, the following preparation ensures a smooth process, minimal transfer
disruption so that your original configuration is backed up in case of any problems.

About this task

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 the installation of the new version.
On a Windows system, the installer displays the following message when an older version of the product
is detected:

4 IBM Aspera Desktop Client 4.4

• Although the installer performs your upgrade automatically, complete the following tasks 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
HSTS). To upgrade, you need to back up the configuration, uninstall the product, and perform a fresh
installation of the new version of the product.
• When upgrading, on Windows the usernames are now case-sensitive.
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.
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 these steps to prepare your machine. Uninstall the application (for instructions,
see “Uninstalling” on page 10). Copy the older Redis DB file into the var directory before installing the
older (downgrade) version.
C:\Program Files\Aspera\Client\var\
• Without a backup: Follow these steps to prepare your machine. Uninstall the application (for
instructions, see “Uninstalling” on page 10) 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
might be compatible with older versions, but not all configurations might be read.
C:\Program Files\Aspera\Client\var\
C:\Program Files\Aspera\Client\etc\
Preparing for an Upgrade or Downgrade

Procedure
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 or run the following command:

> ascp -A

2. Review product release notes.

High-Speed Transfer Client Admin Guide for Windows 5

 Review the release notes for the versions that were released since your current version. In particular,
the Breaking Changes section highlights changes that might require you to adjust your workflow,
configuration, or usage.
3. Confirm your Aspera service account.
The Aspera service account was created when you first installed Desktop Client on your computer
and you need to provide the account information during the upgrade. By default, the username for
the Aspera services account is svcAspera; however, this is not a requirement and you can select a
different user to run the services.
To identify which user is designated as your Aspera service account:
a) Open the services manager:
Windows 8.1 and 10: Go to Search from the taskbar and type Services.
Windows Server 2012 R2, 2016, 2019: Go to Search from the taskbar and type Services.
b) Find the account associated with the Aspera services, such as Aspera Central, and record the
username.
If you forgot the Aspera service account password or would like to change the designated Aspera
service account, follow the instructions in “Managing the Aspera service account” on page 110.
4. 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.
• Stop Hot Folders by clicking .
• 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.
5. Back up configuration and settings files.
These files are found in the etc and var folders. Their location depends on the version of your
previous installation and the operating system.
Aspera 2.5+
• C:\Program Files\Aspera\Client\etc\ (contains Configuration files, Shared Remote Hosts)
• C:\Program Files\Aspera\Client\var\ (contains Pre-post scripts)
• <APPDATA>\Aspera\Client (contains the individual user's remote hosts and Hot Folders
configuration)
To determine the current user's <APPDATA> path, run the following command in a Command Prompt
window :

> echo %APPDATA%

Aspera 2.2.x and earlier

• C:\Program Files[ (x86)]\Aspera\FASP\etc\ (contains Configuration files)
• C:\Program Files[ (x86)]\Aspera\FASP\var\ (contains Pre-post scripts)
• C:\Program Files[ (x86)]\Aspera\Aspera Scp\etc\(contains Remote Hosts and Hot
Folders settings)
6. Back up the Redis database.
The Redis database is backed up as part of backing up the var directory, but back it up separately to
keep an extra copy as well, particularly if it is stored on a different machine.

> asnodeadmin -b C:\filepath\database.backup

7. If you modified the daemon startup scripts for Aspera Central and the Aspera Node Service (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.

6 IBM Aspera Desktop Client 4.4

Installing Desktop Client
To install Desktop Client, log in to your computer with Administrator (or Domain Administrator if you are in
an Active Directory environment) permissions.

About this task

Important: If this is a product upgrade, review all prerequisites that are in “Before upgrading or
downgrading” on page 4.

Procedure
1. Download the HSTS installer from Fix Central.
2. For product upgrades, ensure that you prepared your system to upgrade to a newer version.
Although the installer performs your upgrade automatically, you must complete the tasks that are
described in “Before upgrading or downgrading” on page 4
3. Open the installation package and select the setup type.
Follow the on-screen instructions. After the license agreement screen, select the wanted setup type. If
you are upgrading from a previous version, the installer skips this step.

Setup Type Description

Typical Install the standard Desktop Client.
Custom Select the path to install.
Complete Same as the Typical setup.
4. For a Custom setup, configure the installation path and users.
Select the destination folder for the installation or use the default filepath. Under Install this
application for, select Anyone who uses this computer (all users) to allow access for all system
users, or Only for me to allow only your user account to use the application.

5. Set up the Aspera service account.

The Aspera service account runs services for Aspera products, including:
• Aspera Sync

High-Speed Transfer Client Admin Guide for Windows 7

 By default, the username is svcAspera. Usernames for Desktop Client version 3.1.0 and later are
case-sensitive.
A local account (such as the default svcAspera) is all that is required to run Aspera services if your
machine is not joined to a Windows domain. If your machine is joined to a domain, if you need to
provision Active Directory accounts, or if transfer users store files remotely, refer to the following table
for the type of service account to use:

Requirement Type of service account user

Provision-local transfer users only. Local account. Domain account with local admin
privileges can be used, but is not required.
Provision Active Directory accounts for transfer Domain account with local administrator
users. Users who want to transfer with privileges.
your server are authenticated through Active
Directory.
Transfer users store files on a remote file system Domain account with local admin privileges.
(not on your server machine), such as an SMB file Additional actions might be required. See the
share. Aspera knowledge base or contact your Aspera
account manager for assistance.

Local accounts: If a local account does not exist, enter new credentials and click Next. If the account
exists (for example, if it was created for the previous installation), enter the account password and
click Next. If the existing user's password you have entered is incorrect, or you want to change the
Aspera service user, see “Managing the Aspera service account” on page 110.

Domain accounts: If the server is configured to accept a domain user login, use a domain account that
has been added to the local administrator's group to run the services. You must create this domain
account in your Domain Controller first. The username for a domain account must be in the form
[email protected], as in the following example:

8 IBM Aspera Desktop Client 4.4

 6. Installation troubleshooting.
If the installer stops responding 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.

The following is basic information for configuring your firewall to allow Aspera file transfers. The outbound
TCP port for SSH might differ depending on your organization's unique network settings. Although TCP/
33001 is the default setting, refer to your IT Department for questions that are related to which SSH ports
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 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 nondefault 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 Windows Firewall), verify that it is not
blocking your SSH and FASP transfer ports (such as TCP/UDP 33001).

Testing a transfer
To make sure that the software is working properly, set up a connection with a server and test downloads
and uploads.

About this task

Procedure
1. Start the application.
Go to Search and type Desktop Client

High-Speed Transfer Client Admin Guide for Windows 9

 2. Add the server in the Connection Manager.
Click Connections.
In the Connection Manager, click to add a 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 Connect.
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 must see that the session appears 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.

Uninstalling
Desktop Client can be uninstalled without removing existing configuration files.

Procedure
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.
• Hot Folders.
3. Go to Search from the taskbar and type Add or remove programs.
4. Select IBM Aspera Desktop Client, click the kebab menu and select Uninstall.

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

10 IBM Aspera Desktop Client 4.4

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 start the GUI
and how to navigate its features.

Starting the application

To start the application, go to Search from the taskbar and type Desktop Client . To perform
administrator tasks (such as server configuration, license updates, or configure email notification
templates), right-click High-Speed Transfer Server and click Run as administrator.

The application GUI

Item Description
A Click Transfer to enter the transfer viewing mode. This is the default view when you start
the application, which shows the local and remote file browsers. For more information,
see “Transferring content” on page 31.
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 33.
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 18.

High-Speed Transfer Client Admin Guide for Windows 11

 Item Description
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.
H Display all configured Hot Folders. Start or manage Hot Folders. For more information,
see “Hot Folders” on page 46.

The file browser

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

Item Description
A Path indicator/selector.
B Go to the parent directory.
C Create a new folder, or set up a Hot Folder.
D Choose between the list views and the detail view.
E Create a new folder, or set up a Hot 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.

12 IBM Aspera Desktop Client 4.4

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.

About this task

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

2. Click Transfers.

3. To limit total bandwidth usage by FASP uploads and downloads, edit System-Wide Settings.

High-Speed Transfer Client Admin Guide for Windows 13

 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 nonadmin 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.
Nonadmin 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.
Nonadmin users can adjust their personal maximum active transfers above or below the global default
value.
6. Click OK to activate your changes.

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

14 IBM Aspera Desktop Client 4.4

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.
4. If your HTTP proxy requires authentication, select Authenticated and enter the username and
password for your HTTP proxy.

High-Speed Transfer Client Admin Guide for Windows 15

 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.

16 IBM Aspera Desktop Client 4.4

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.

High-Speed Transfer Client Admin Guide for Windows 17

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

Adding and editing connections

To transfer with HSTS, HSTE, IBM Aspera Shares, or IBM Aspera on Cloud transfer service (AoC), 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.

About this task

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 that uses 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 26.
To create a new connection:

Procedure
1. Start the application.
Go to Search from the taskbar and type Desktop Client.

18 IBM Aspera Desktop Client 4.4

2. To open the Connection Manager, click Connections.

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 wanted.
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
window. Click OK to save your changes.

High-Speed Transfer Client Admin Guide for Windows 19

 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 the Aspera Node
Service, 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).
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 27.

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 that
are 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:

20 IBM Aspera Desktop Client 4.4

 Connection Description
Option

– 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 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 nondefault 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.
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 nondefault 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-Speed Transfer Client Admin Guide for Windows 21

 Transfer Option Description

• high - Adjust the transfer rate to fully use 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 use 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 the bandwidth
is shared 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. Use the fixed policy only for specific contexts,
such as bandwidth testing, otherwise, avoid the use of this policy. 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 you 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 13.
Retry Select to automatically retry the transfer after a recoverable failure for a set
amount of time, in seconds, minutes, or hours. You might 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.
• 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 in the range 296 - 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.

22 IBM Aspera Desktop Client 4.4

 8. Configure tracking and email notifications, if needed.
On the Tracking Tab, configure nondefault 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 For more information, see “Using transfer notifications” on page 45.
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
82.
10. Configure security settings, if needed.
On the Security tab, configure nondefault transfer settings by editing any of the following settings:

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

High-Speed Transfer Client Admin Guide for Windows 23

 Security Option Description

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

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

Server Server Server Server

AES-XXX-GCM AES-XXX-CFB AES-XXX AES-XXX

Client GCM Server refuses GCM Server refuses

transfer transfer
AES-XXX-GCM

Client Server refuses CFB CFB CFB

transfer
AES-XXX-CFB

Client GCM CFB CFB CFB

AES-XXX

Client Server refuses CFB CFB CFB

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.

24 IBM Aspera Desktop Client 4.4

 Security Option Description

For more information about client-side encryption at rest, see “Client-Side

Encryption-at-Rest (EAR)” on page 94.

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.
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 must
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 discards any unsaved changes that are
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.

High-Speed Transfer Client Admin Guide for Windows 25

 Results
Editing and Deleting Connections
Click Connections and select the connection that 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 27.
• A shared connection that is exported or imported by a nonadministrator is imported as a regular
connection (not as a shared connection).
• Email templates are not exported with the connection.

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

26 IBM Aspera Desktop Client 4.4

 2. Enter the following information:
• Destination: Enter or browse to the location on your computer where to save the file.
• Options: The passwords that are 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.

About this task

You can use the application GUI to generate key pairs and to import existing key pairs. You can also
generate key pairs by using the command line; for instructions, see “Creating SSH keys from the
command line” on page 89.

High-Speed Transfer Client Admin Guide for Windows 27

 Procedure
1. Start the application.
Go to Search from the taskbar and type Desktop Client.
2. In the menu bar, click Tools > Manage Keys.

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

28 IBM Aspera Desktop Client 4.4

 Field Description
Passphrase Set a passphrase on your SSH key, which is 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.

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, the public key file name is id_rsa.pub:
user_home_dir\.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.

High-Speed Transfer Client Admin Guide for Windows 29

 7. Set up connections by 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.

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.

30 IBM Aspera Desktop Client 4.4

 Results
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 copies both keys into the user's .ssh directory. You
cannot import a key pair if a key pair with the same identity 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.

About this task

Note: Do not use the following characters in file or folder names:

/ \ " : ' ? > < & * |

They can produce unpredictable transfer behavior.

Procedure
1. Create a connection.
For instructions, see “Adding and editing connections” on page 18.

High-Speed Transfer Client Admin Guide for Windows 31

 2. Select the remote server under Connection Name.

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.
You can also initiate an upload by using drag-and-drop from Windows Explorer to the right (remote)
browser panel.

32 IBM Aspera Desktop Client 4.4

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

Managing transfers
The Desktop Client GUI enables the option to start, stop, and reorder transfers, and adjust the 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.

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 versus total files to be transferred, average speed,
time elapsed, RTT delay and average loss in percent).

High-Speed Transfer Client Admin Guide for Windows 33

 Item Name Description
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 use 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 use 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
the bandwidth is shared 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. Use the fixed policy only for
specific contexts, such as bandwidth testing, otherwise, avoid the use
of this policy. 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 you need to
fine-tune the transfer policy.
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.

34 IBM Aspera Desktop Client 4.4

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

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 overrides the default transfer settings. You can also schedule the transfer as a one-time transfer or
recurring.

Procedure
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 Windows 35

 2. Configure the transfer settings, as needed.
The advanced transfer configuration options except Scheduling are identical to those in the
Connection Manager. For more information about these tabs, see “Adding and editing connections”
on page 18. 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. Unlike
“Hot Folders” on page 46, scheduled transfers do not run when the application is closed.
To enable transfer scheduling, select Schedule this transfer.

36 IBM Aspera Desktop Client 4.4

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

High-Speed Transfer Client Admin Guide for Windows 37

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.

About this task

Note: The GUI must remain open for transfer notification emails to send. Closing the GUI stops email
notifications.

Enable email notifications

Procedure
1. Start Desktop Client.
Go to Search from the taskbar and type Desktop Client, right-click and select Run as administrator..
2. To configure global email notification settings:
a) Click Tools > Global Preferences.

b) Click Mail.

38 IBM Aspera Desktop Client 4.4

 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 hostname in the Host field. The other values are optional.
To enable notifications on Hot Folder transfers, select Send email notifications for hot folders.
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.

High-Speed Transfer Client Admin Guide for Windows 39

 To restore your settings to global values, click Restore Defaults.

Configure email templates

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

40 IBM Aspera Desktop Client 4.4

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 Windows 41

 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

42 IBM Aspera Desktop Client 4.4

Use conditional tests in an if statement. For example,

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

Statement Description
$event.isStarted() If the transfer session is started.
$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 hostname (or host
address if the hostname is not
discoverable).
$event.getSourceHostAddress() The source host address.
$event.getSourcePaths() The source file path.
$event.getDestinationHost() The destination hostname (or host
address if the hostname is not
discoverable).
$event.getDestinationHostAddress() The destination host address.
$event.getDestinationPath() The destination file path.

$event.getInitiatingHost() The mail template supports MIME The session-

initiating
hostname (or
host address if
the hostname
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.

High-Speed Transfer Client Admin Guide for Windows 43

 Statement Description
## $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 10 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.
$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, 2022.
– 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

44 IBM Aspera Desktop Client 4.4

 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.

Results
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 45.

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.

Procedure
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 38.
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.

High-Speed Transfer Client Admin Guide for Windows 45

 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 38.
To Enter the recipients, comma-separated.
Template Select a mail template.
Message Enter a message to include in the notifications (optional).
c) Click OK to save your changes.

Hot Folders
Hot Folders is an automatic file delivery tool that can download from a server (pull) or upload to a server
(push). Files and folders added to or modified within a Hot Folder on the source are automatically sent
to the destination folder. Files that are deleted from the source are not deleted on the destination. The
following section describes how to set up and manage Hot Folders.

46 IBM Aspera Desktop Client 4.4

Setting up Hot Folders
Hot Folders are used to monitor local or remote folders for changes and automatically transfer new or
modified files. Hot Folders can be used for one-way replication between two locations, or as a way of
forwarding files in your workflow.
Important: In order to use a transfer proxy or an HTTP proxy with Hot Folders, you must configure global
proxy settings (Tools > Global Preferences) because Hot Folders does not use the proxy settings that are
configured for a user in My Preferences. For more information about enabling a proxy server globally, see
“Enabling a transfer proxy or HTTP proxy” on page 14.

Creating a Hot Folder

To create a new Hot Folder, start the Aspera application as an administrator. In the file browser, go to the
folder you want to set up as the Hot Folder. Right-click the panel and select New > Hot Folder to open the
New Hot Folder dialog. You can also open the New Hot Folder dialog by clicking File > New > Hot Folder.

The New Hot Folder window includes the following configuration tabs:

Tab Description
Hot Folder Set the source, the destination, and the synchronization interval.
Transfer Set the transfer speed and transfer policy.
Tracking Turn on and configure email notifications for transfer start, completion, and error.
Filters Create filters to skip files that match certain patterns.
Security Enable transfer encryption and content protection.
File Handling Set up a resume rule, preserve transferred file attributes, and remove or move
source files.

The following tables describe the options available on each configuration tab.

Hot Folder

Option Description
Name The name of the Hot Folder. Use the default name or enter your own. The default
name is the name of the Windows folder. Click Generate to restore the default
name.
Source Specify the source for the Hot Folder. If the source is This Computer, then the Hot
Folder is in push mode.

High-Speed Transfer Client Admin Guide for Windows 47

 Option Description
Destination Specify the destination for the Hot Folder. If the destination is This Computer, then
the Hot Folder is in pull mode.
Send Changes Select when to synchronize. The options depend on whether the Hot Folder is in
push or pull mode:
• Push and pull mode: Select Daily at to specify a time to synchronize daily.
Note: When the specified time is reached, file transfers from the Hot Folder
are allowed for 1 hour, including any new files added during that window. The
one-hour window supports retries.
• Pull mode: Select Every to specify the interval at which to scan the source Hot
Folder and receive updates.
• Push mode: Select Periodic scan to specify the interval at which to scan the
source Hot Folder and send updates if changes are detected.
Note: When file notification is not available, this feature must be activated to
detect file changes in your Hot Folders.
• Push mode: Select Send immediately to synchronize whenever a file in the
folder is changed.

Transfer

Option Description
Policy Set the FASP transfer policy.
• high - Adjust the transfer rate to fully use 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 use 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 the bandwidth is shared 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. Use the fixed policy only for specific contexts, such as
bandwidth testing, otherwise, avoid the use of this policy. 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 you need to fine-tune the transfer policy.
Note: If --policy is not set, ascp uses the server-side policy setting (fair by
default).

Speed Use this option to specify the target transfer rate and minimum transfer rate. (Files
will still be transferred if the available transfer rate is below the minimum).

48 IBM Aspera Desktop Client 4.4

Tracking

Option Description
Send Email Select to enable email notifications and to display configuration options, however,
Notifications notifications are not sent until they are enabled (click Preferences on the
main screen of the application). For more information, see “Configuring transfer
notifications” on page 38.
Important: For Hot Folder email notifications to work, the GUI must remain open.

When 1 Select one or more events that trigger the notification. Transfer Start, Complete,
and Error.
Subject1 Enter the subject of the notification.
To 1 Enter the email addresses of the recipients.
Template 1 Select a notification template from the drop-down list. Add, delete, edit, and
preview templates by clicking Manage Templates. For more information on
configuring templates, see “Configuring transfer notifications” on page 38.
Message 1 Include a custom message with the notification.

1 Not displayed until notifications are enabled.

Filters
Click Add and enter the filter pattern to use to exclude files or directories from the transfer. The exclude
pattern is compared with the whole path, not just the file name or directory name. As shown, the asterisk
(*) can be used to represent zero to many characters in a string, for example *.tmp matches .tmpand
abcde.tmp:

Filter Pattern Excludes these files

*dirName path/to/dirName, another/dirName
*1 a/b/file1, /anotherfile1
*filename path/to/filename, /filename

Note: The temporary files that are used by to resume incomplete files are automatically ignored based on
the resume suffix that was set by the sender.

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

High-Speed Transfer Client Admin Guide for Windows 49

 Option Description

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

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

AES-128-CFB Use the CFB encryption mode. Clients version 3.9.0 and
newer, all server versions.
AES-192-CFB
AES-256-CFB

AES-128-GCM Use the GCM encryption mode. Clients and servers version
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

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

Server Server Server Server

AES-XXX-GCM AES-XXX-CFB AES-XXX AES-XXX

Client GCM Server refuses GCM Server refuses

transfer transfer
AES-XXX-GCM

Client Server refuses CFB CFB CFB

transfer
AES-XXX-CFB

Client GCM CFB CFB CFB

AES-XXX

Client Server refuses CFB CFB CFB

transfer
AES-XXX

50 IBM Aspera Desktop Client 4.4

Option Description
Content Enable client-side encryption at rest:
Protection
Push mode: Select Encrypt uploaded files with a password to encrypt
the uploaded files with the specified password. The protected file has the
extension .aspera-env appended to the file name.
Pull mode: Select Decrypt password-protected files downloaded to require entry
of 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 94.

File handling

Option Description
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.
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 files that
transferred successfully from the source.
Push mode: Select Automatically move uploaded source files to a directory after
transfer and specify the location on the source machine to which they must be
moved. Only a path to an existing location on the client can be specified. Only files
are moved, not the parent directory structure. To preserve the directory structure,
enable the --src-base option after the Hot folder is created:
1. Quit Aspera.
2. Stop the Aspera Sync service by going to Search > Services, selecting Aspera
Sync, and click Stop.

High-Speed Transfer Client Admin Guide for Windows 51

 Option Description

3. Open C:\Program Files\Aspera\\etc\sync-conf.xml, locate the

<EXTRAOPTS> entry, and edit it as follows:

<EXTRAOPTS>--src-base=ldir_path</EXTRAOPTS>

Where ldir_path is the source path for the Hot Folder and matches the setting
for <LDIR>.
4. Save your changes and restart the Aspera Sync service.
Pull mode: Select Transfer source directory contents only to transfer only the
contents of the directory and not the directory itself. If this option is enabled,
for a source folder /folder1 containing file1 and file2 being pulled to the
destination folder /destination, only file1 and file2 are transferred, not /
folder1. If this option is not selected, the transfer produces /destination/
folder1 (containing the two files) on the destination machine.
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.

Note: Empty folders within a Hot Folder are not pushed to the server. However, empty folders on the
server are pulled to the local destination.

Managing Hot Folders

Hot Folders are managed in the Desktop Client GUI. You can control transfers, monitor individual file
transfers, modify the configuration of a Hot Folder, and update connection passwords.
Manage existing Hot Folders by clicking the Hot Folders tab:

Control transfers
Click the , , and buttons to start a transfer, stop a transfer, and delete the Hot Folder, respectively.

View Hot Folders transfer details

Double click the Hot Folder to open the Details view, or click the Details button with the Hot Folder
selected.
On the Details tab, view statistics for the Hot Folder, including the total size of the transfer, the number of
files in each state, and the source and destination.

52 IBM Aspera Desktop Client 4.4

On the Files tab, you can view the state of individual files:

High-Speed Transfer Client Admin Guide for Windows 53

 File states can be the following:

State Description
Pending The file is new or modified and Hot Folders is waiting for the file to stabilize.
Ready A pending file is now stable.
Queued The file is scheduled for transfer.
Transferring The file is transferring.
Complete The file successfully transferred.
Failed The file transfer was unsuccessful. Possible reasons include permissions
conflicts, an invalid destination path, or the file is still in use.

Edit Hot Folders

To edit the configuration of existing Hot Folders, right-click the entry in the Hot Folders panel and select
Edit....

54 IBM Aspera Desktop Client 4.4

 Update Hot Folder passwords
Hot Folder password maintenance can be done from the command line rather than by using the GUI. If a
Hot Folder is authenticating to an IBM Aspera Shares node and the password for the connection must be
refreshed every 30 days, use the following command in a script to update the password:

> asperasync -P new_password -N hot_folder_name

Note: This command must be run in a Command Prompt that is opened with "Run as Administrator", or
the script that uses it must be run with Administrator permissions.
The hot_folder_name is the text in the Name column of the Hot Folders tab.

ascp: Transferring from the command line

Ascp is a scriptable FASP transfer binary that enables the 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 71
• “Ascp file manipulation examples” on page 74
• “Ascp transfers with object storage and HDFS” on page 75
Another command line FASP transfer program is Ascp4, which is optimized for transfers of many small
files. It has many of the same capabilities as ascp, and also its own features. For more information, see
“Introduction to ascp4” on page 100 and “Comparison of ascp and ascp4 options” on page 95.

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

High-Speed Transfer Client Admin Guide for Windows 55

 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 exabytes - 1 (9,223,372,036,854,775,807 bytes). However, the maximum file
size of the file system overrides 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 71.
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 was transferred. In other words, if more data arrives after the wait time has elapsed, but the
transfer is still in progress, the additional data is still transferred.
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 nonnegative integer to define wait time. If it is set to a nonnumeric
string, the default wait time of 10 seconds is used.
wait_start
Can be used to specify how time is calculated to determine whether a file is complete. If mtime is
used, then the file modification time is used to calculate 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 was added to the source file and to prevent any
additional wait time followed by 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 value is false). Then, use an external program
to adjust the source file mtime upon completion of writing data to the source file, by 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 is 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:

56 IBM Aspera Desktop Client 4.4

 • 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 file name. 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 quotation marks
(' ') 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.
• 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 by 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 71.
WebSocket protocol
The WebSocket protocol can be used instead of SSH or HTTPS for client connections with the transfer
server. To use it, you must configure aspera.conf specifically for WebSocket use. Then, for transfers,

High-Speed Transfer Client Admin Guide for Windows 57

 you must use the ascp --ws-connect option to specify by using WebSocket, and the -P option to specify
the WebSocket port (9093).
For Windows, you must also use a Windows Credential. To do so:
1. Go to Search and type Credentials Manager.
2. Select Windows Credentials.
3. Click Add a generic credential.
4. Enter the credentials to be used. A domain user can be used.
Note: All of the following credentials must match:
• The Internet or network address field.
• The User name field. The user specified in the ascp client command. (For example, the --
user=username option).
• The Password field.

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 might produce
unexpected results that depend 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. Each environment variable value must
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.
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 use --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.

58 IBM Aspera Desktop Client 4.4

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
Note: To see the ascp usage options, run ascp -h.
-6
Enable IPv6 address support. When you specify 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 and 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 that is specified with the -O option. Large files can be
split across sessions, see --multi-session-threshold. For more information, see IBM Aspera
High-Speed Transfer Server.
-c cipher
Encrypt in-transit file data by 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.
• 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.

High-Speed Transfer Client Admin Guide for Windows 59

 Cipher values

Value Description Support

Use 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 CFB encryption mode. Clients version 3.9.0 and newer, all
aes128cfb
server versions.
aes192cfb
aes256cfb

Use GCM encryption mode. Clients and servers.

aes128gcm
aes192gcm
aes256gcm

none Do not encrypt data in transit. For All client and server versions.
security and to keep the file integrity,
avoid the use of 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 Server Server Server

AES-XXX-GCM AES-XXX-CFB AES-XXX AES-XXX

Client GCM Server refuses transfer GCM Server refuses transfer

AES-XXX-GCM

Client Server refuses transfer CFB CFB CFB

AES-XXX-CFB

Client GCM CFB CFB CFB

AES-XXX

Client Server refuses transfer CFB CFB CFB

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. The Aspera fingerprint convention is to use a
hex string without the colons; for example, f74e5de9ed0d62feaf0616ed1e851133c42a0082. For
more information on SSH host key fingerprints, see 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.

60 IBM Aspera Desktop Client 4.4

-d
Create the destination directory, if it does not exists. 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 82.
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
(V4.0 or higher) The -e option is not valid anymore. The support for pre-post scripts was removed
with version 4.0 or higher.
Run the specified pre-post script as an alternative to the default aspera-prepost.bat 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 various environment
variables. IBM Aspera High-Speed Transfer Server product [] .
--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 before 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 “Reporting checksums” on page 90.
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
and 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 94.
--file-list=file
Transfer all source files and directories that are 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

High-Speed Transfer Client Admin Guide for Windows 61

 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, contains:

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 that are 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 that are specified in the file list are transferred. Any sources that are
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 manifest file to the specified location when you use --file-manifest=text. Manifests
file must be stored locally. For cloud or other nonlocal storage, specify a local manifest file 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 that are listed in file to their corresponding destinations. Each source is
specified on a separate line, with its destination on the line that follows 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 that are
specified in the list are created automatically if they do not exist.
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

62 IBM Aspera Desktop Client 4.4

 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 that are specified in the file list.
• Because multiple sources are being transferred, the destination that is 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 that are 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 71.
-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 1 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 1 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.
--host=hostname
Transfer to the specified hostname 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 by using public key authentication with the
specified SSH private key file. The argument can be just the file name 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 were tried without success, at which point
authentication fails.

High-Speed Transfer Client Admin Guide for Windows 63

 • 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: 100 Kbps).
-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 doesn’t work for subsequent transfers. Resume levels:
-k 0 – Always retransfer the entire file.
-k 1 – Compare file attributes and resume if they match, and retransfer if they do not.
-k 2 – Compare file attributes and the sparse file checksum; resume if they match, and retransfer
if they do not.
-k 3 – Compare file attributes and the full file checksum; resume if they match, and retransfer 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 that is 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 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 74.
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.

64 IBM Aspera Desktop Client 4.4

 • --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 were 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 more information see “Using filters to include and exclude files” on page 82.
Note: Filtering rules can also be specified in aspera.conf. Rules that are found in aspera.conf are
applied before any -E and -N rules that are 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.
--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 might 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 is not overwritten. Plus,
if the destination file is different than the source, but newer, it is overwritten.
• older - Overwrite the file if its timestamp is older than the source timestamp.

High-Speed Transfer Client Admin Guide for Windows 65

 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 checksum. If -k 3, the source and
destination files are compared based on full checksum.
-P ssh-port | websockets-port
Use the specified TCP port to initiate the FASP transfer session, by 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 might be affected when the system automatically adjusts for Daylight
Savings Time (DST). For more information, see Daylight saving time help and support.
--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 use 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 use 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 the bandwidth is shared 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. Use the fixed
policy only for specific contexts, such as bandwidth testing, otherwise, avoid the use of this policy.
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 you 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 a transfer starts. 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 that is preserved is the one just before to the
transfer. (To prevent access times at the source from being updated by the transfer operation, use the
--preserve-source-access-time option).

66 IBM Aspera Desktop Client 4.4

--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 by 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:
• 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.
• Old versions of ascp do not support values other than none, and transfers that use 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 might be affected when the system automatically adjusts for Daylight
Savings Time (DST). For details, see Daylight saving time help and support.
Note: The options --preserve-object-lock-legal-hold and --preserve-object-lock-
retention are available only for connections from S3 to S3 storage. Only available with
libpvcl_cloud configuration. For instructions, see General pvcl_cloud configuration reference. (V4.4.2)
--preserve-object-lock-legal-hold
(V4.4.2) Preserve legal hold status of source files and directories when created at the destination.
--preserve-object-lock-retention
(V4.4.2) Preserve retention information of source files and directories when created at the
destination.
--preserve-source-access-time
Preserve the access times of the original sources to the last access times before to transfer. This
prevents access times at the source from being updated by the transfer operation. Typically used 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 by 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-

High-Speed Transfer Client Admin Guide for Windows 67

 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-preserve-acls={native|metafile|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.
• Old versions of Ascp do not support values other than none, and transfers that use native or
metafile fail with an error that reports incompatible FASP protocol versions.
--proxy=proxy_url
Use the proxy server at the specified address. proxy_url must 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 71.
-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 is completed successfully.
Requires write permissions on the source.
--remove-empty-directories
Remove empty source directories once the transfer is completed successfully, but do not remove a
directory that is specified as the source argument. To also remove the specified source directory,
use --remove-empty-source-directory. Directories can be emptied by using --move-after-
transfer or --remove-after-transfer. Scanning for empty directories starts at the src-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 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 that are specified as the source arguments. For use with --remove-empty-
directories.
-S remote_ascp
Use the specified remote ascp binary, if different than ascp.

68 IBM Aspera Desktop Client 4.4

--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 that is 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 wanted 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 (implies that you use
-SSH). This option might be repeated as needed to supply multiple separate SSH arguments. The
order is preserved. The ARG elements are inserted before any key files supplied to ascp, and before
the user and host argument.
--skip-special-files
Skip special files, such as devices and pipes, without reporting errors for them.
--source-prefix=prefix
Add a 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
Add a 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 folder. The remaining
portion of the path remains intact at the destination.
Without --src-base, source files and folders are transferred without their source path. (However,
folders do include their contents).
Note: Sources that are 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 does not match.
For examples, see “Ascp file manipulation examples” on page 74.
--src-base64=<base64-encoded src-base>
An alternative to --src-base, with the same value except base64-encoded to help avoid character
conversion issues for nonascii 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 that use the specified method, as allowed by the server. For more information,
see “Symbolic link handling” on page 87. 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 is not
replaced.
• skip - Skip symbolic links. Do not copy the link or the file it points to.

High-Speed Transfer Client Admin Guide for Windows 69

 -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. For more information, see
Transfer session data accessible to scripts.
--user=username
Authenticate the transfer by 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 more information, see “Log files” on page 115.
-W {token_string|@token_file}
Authenticate by 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.

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 continues 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).

70 IBM Aspera Desktop Client 4.4

 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 through 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 by 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.

About this task

To describe file paths, use single quotation marks (' ') around the file path string, and forward-slashes
(/) on all platforms. Avoid the following characters in file names: / \ " : ' ? > < & * |
• Growing Files
The growing files feature that allows 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 that uses a 0 bytes read that
calculates 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 must 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 aspera.conf - File system configuration.

• 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 supports only 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 the use of a WebSocket:
--ws-connect
Specifies the use of a WebSocket.
-P
Specifies the WebSocket port (9093).

High-Speed Transfer Client Admin Guide for Windows 71

 > 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 by using UDP port 42000:

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

• Public key authentication

Transfer with public key authentication by using the key file /Documents and Settings/
aspera_user_1/.ssh/aspera_user_1:

> ascp -l 10m -i "/Documents and Settings/aspera_user_1/.ssh/aspera_user_1" local-dir/files

[email protected]:/remote-dir

• Username or file path contains a space

Enclose the target in double quotation marks (" ") 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
by 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 .

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

72 IBM Aspera Desktop Client 4.4

 Use parallel transfer on a dual-core system, together transferring at the rate 200 Mbps, by using UDP
ports 33001 and 33002. Two commands are run 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):

> set 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 that indicates 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 the
transfer:

> set 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 and encrypted version of file1) to file1:

> set ASPERA_SCP_FILEPASS=secRet&& 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 the command is run,
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 that use faux://

For more information, 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:

>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://

High-Speed Transfer Client Admin Guide for Windows 73

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/file1 /in/file1 /in/out/file1
/clips/out/folderA/file2 /in/folderA/file2 /in/out/folderA/file2
/clips/out/folderB/file3 /in/folderB/file3 /in/out/folderB/file3

Without --src-base, the example command transfers not only the contents of the out/ folder, but the
folder itself.
Note: Sources that are 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
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 arc-base path and preserving the rest of the file structure. The content is
saved as /storage/monday/file1 and /storage/tuesday/* on the server.

> ascp --src-base=/data/content /data/content/monday/file1 /data/content/tuesday/

[email protected]:/storage

• Download only the contents of a file and a directory to a new directory by using --src-base

74 IBM Aspera Desktop Client 4.4

 Download a file, /monday/file1, and a directory, /tuesday/*, from the server, while stripping the
src-base 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
Upload file0012 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 were transferred to the remote server by using --src-
base, --remove-after-transfer, and --remove-empty-directories
Upload /content/ to the server, while stripping the src-base 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

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 cloud-based HSTS

Transfers to cloud-based HSTS 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:

High-Speed Transfer Client Admin Guide for Windows 75

 • 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 Cloud Object Storage
(COS) and S3, Google Cloud Storage, Akamai, IBM Cloud, Azure, and are the same as regular ascp
transfers.
For command syntax examples, see “Ascp general examples” on page 71. 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 that use
IAM roles.
Set an environment variable (ASPERA_DEST_PASS) with the storage password or access key:

> setexport ASPERA_DEST_PASS = secret_key

With ASPERA_DEST_PASS and ASPERA_SCP_PASS set, run ascp with the syntax that is 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 that is configured and do not set an environment variable (described
previously), authenticate in the command line. In the following examples, the storage password or
the secret keys 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 Run 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_addrgoogle-

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

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_pathdestination_path

76 IBM Aspera Desktop Client 4.4

Storage Platform ascp Syntax and Examples

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.
Run 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 //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: These examples require that the VMI running the Aspera server is a Google
Storage Compute instance.

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

source_files google-gcs:///my_bucket/my_path

Upload example:

> ascp --mode=send --user=bear --host=10.0.0.5 bigfile.txt google-gcs:///

2017_transfers/data

Download syntax:
google-gcs://

> ascp options --mode=recv --user=username --host=server google-gcs:///

my_bucket/my_path/source_filedestination_path

Download example:

> ascp --mode=recv --user=bear --host=10.0.0.5 google-gcs:///

2017_transfers/data/bigfile.txt /data

HDFS Run ascp transfers with HDFS with a docroot configured.

IBM COS and S3 Upload syntax:

High-Speed Transfer Client Admin Guide for Windows 77

 Storage Platform ascp Syntax and Examples

> 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:
secret_key

> 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 that is 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 is not retrieved when objects are downloaded, use the REST API associated with the storage.
• Transfers to object storage that does 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.
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

78 IBM Aspera Desktop Client 4.4

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. 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 by 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 0-byte files with standard I/O transfers.

Single file transfers

To upload data that is piped into stdin, set the source as stdio:///?fsize, where fsize is the number
of bytes (as a decimal) that are received from stdin. The destination is set as the path and file name. 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 by stdio://. The behavior of
--overwrite=diff and --overwrite=diff+older is undefined.
• When the size (?fsize) is not specified, the file is managed by the growing files feature where an
End-of-File (EOF) on reading stdin will signify that the growing file is complete.
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 Windows 79

 The files 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 by 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.

type 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 nonpersistent
session.
• Update bytes 10-19 in file /remote-dir/myfile1 on the server at 10.0.0.2 at 100 Mbps.

type 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

80 IBM Aspera Desktop Client 4.4

 << 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 file name; 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.

type 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 Windows 81

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

<<20 bytes of data>>

Using filters to include and exclude files

For example, on Windows FAT or NTFS (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.

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 quotation marks (' ') to prevent filter patterns
from being interpreted by the command shell. Patterns that do not contain wildcards can also be in
single quotation marks (' ').
Basic usage
• Filtering rules are applied to the transfer list in the order that 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, and 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 that are 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 '/**'

82 IBM Aspera Desktop Client 4.4

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.
Filtering order
Filtering rules are applied to the transfer list in the order that 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 are 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]' C:\images\icons\ user1@examplehost:/tmp

Where C:\images\icons\ is the source.

If C:\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, and
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 file name 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.

High-Speed Transfer Client Admin Guide for Windows 83

 \ Quotes any character literally, including itself. \ is exclusively a quoting
operator, not a path separator.
* Matches zero or more characters, except / or the . in /..
? 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 are not 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/

84 IBM Aspera Desktop Client 4.4

Wildcard Example Matches Does Not Match
/ 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

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 C:\tmp\src.
2. Upload the file set to a server. For example,

> ascp C:\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 user password.
3. Create a destination directory on your computer, for example, C:\tmp\dest.
4. Download your files from the demo server to C:\tmp\dest to test your filtering rules. For example,

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

C:\tmp\dest

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

Example filter rules

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

> ascp rules aspera@my_demo.example.com:Upload/AAA C:\tmp\dest

The examples 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:

< xxx/yyy = Excluded

xxx/yyy = Included
zzz/ = directory name
zzz = file name

1. Transfer everything except files and directories that starts with ".":

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

High-Speed Transfer Client Admin Guide for Windows 85

 Results:

AAA/abc/def
AAA/abc/wxy/def
AAA/abc/wxy/tuv/def
AAA/abc/xyz/def/wxy
AAA/wxyfile
AAA/wxy/xyx/
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 are 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 is a file.

86 IBM Aspera Desktop Client 4.4

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

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

Results:

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
< AAA/abc/def
< AAA/abc/.def
< AAA/abc/.wxy/def

6. Exclude directories and files that start 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

Surround patterns that contain wildcards with single quotation marks (' ') to prevent filter.

Symbolic link handling

When transferring files by 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 when the link
target is in the user's docroot.

High-Speed Transfer Client Admin Guide for Windows 87

 • 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 request only 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.
• 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. The link or the file to which it points are not 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 ordered 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)

88 IBM Aspera Desktop Client 4.4

 Server setting Server Server Server setting = Server
= create, setting = setting = follow_wide setting =
follow create follow none
(default)
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
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 by 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"

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

Creating SSH keys from the command line

About this task

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 the existing keys for use with a selected
user account. For instructions, see “Creating SSH keys in the GUI” on page 27.

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

> md user_home_dir\.ssh

Go to the .ssh folder:

> cd user_home_dir\.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).

High-Speed Transfer Client Admin Guide for Windows 89

 At the prompt that appears for the key pair's file name, 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:
a. Use keys that are generated by running ssh-keygen in a FIPS enabled system. Or,
b. Convert existing keys to a FIPS compatible format by using a command such as:

> openssl pkcs8 -topk8 -v2 aes128 -in id_rsa -out new-id_rsa

3. As the Admin user, make sure that the SSH key is owned by the transfer user and that proper
restrictive permissions are set. SSH keys must be readable only by the key owner.
4. Retrieve the public key file.
The key pair is generated to your home directory's .ssh folder.
For example, assuming you generated the key with the default name id_rsa:
user_home_dir\.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 by using public key authentication with the ascp command.
To transfer files by using public key authentication on the command line, use the option -i
private_key_file.
For example,

> ascp -T -l 10M -m 1M -i "user_home_dir\.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 user_home_dir\.ssh\id_rsa.

Reporting checksums
File checksums are useful for troubleshooting file corruption, allowing to determine at what point in the
transfer file corruption occurred. Aspera servers can report source file checksums that are calculated in
real time 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.

90 IBM Aspera Desktop Client 4.4

Overview of checksum configuration options

Description
asconfigurator Option
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 the MD5 checksum.
sha1 - Calculate and report the SHA-1 checksum.
sha256 - Calculate and report the SHA-256 checksum.
sha384 - Calculate and report the SHA-384 checksum.
sha512 - Calculate and report the 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 nonlocal 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 C:\Users\Public\reports.

<file_system>
...
<file_checksum>md5</file_checksum>
<file_manifest>text</file_manifest>
<file_manifest_path>C:\Users\Public\reports</file_manifest_path>

High-Speed Transfer Client Admin Guide for Windows 91

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

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

In the examples, the manifest is generated when files are transferred and saved as a text file called
aspera-transfer-transfer_id-manifest.txt in the directory C:\Users\Public\reports.

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=C:\Users\Public\reports

file [email protected]:/destination_path

92 IBM Aspera Desktop Client 4.4

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

> CertUtil -hashfile filepath MD5

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.

High-Speed Transfer Client Admin Guide for Windows 93

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

> set 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 71.
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 sensitive content, do not store unencrypted 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 you move it to a computer with network access, run the following command:

> set ASPERA_SCP_FILEPASS=password;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:

> set ASPERA_SCP_FILEPASS=password;asunprotect -o file1 file1.aspera-env

94 IBM Aspera Desktop Client 4.4

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
-@ range_low:range_high
-6
-A, --version -A, --version
--allow-password-prompt
--apply-local-docroot --apply-local-docroot
-C nodeid:nodecount
-c cipher -c cipher
--check-sshfp=fingerprint --check-sshfp=fingerprint
--chunk-size=bytes
--compare=method
--compression=method
--compression-hint=num
--crypt-threads=NUM
-D | -DD | -DDD -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-newer-than=mtime
--exclude-older-than=mtime --exclude-older-than=mtime
-f config_file -f config_file
--fail-bad-filepass
--faspmgr-io
--file-checksum=hash
--file-crypt=CRYPT
--file-list=filename** --file-list=filename**
--file-manifest-inprogress-suffix=SUFFIX
--file-manifest-path=DIRECTORY
--file-manifest=OUTPUT

High-Speed Transfer Client Admin Guide for Windows 95

 Ascp Ascp4
--file-pair-list=filename --file-pair-list=filename
-G write_size
-g read_size
-h, --help -h, --help
--host=HOSTNAME --host=HOSTNAME
-i private_key_file_path** -i private_key_file_path
--ignore-host-key
-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=MAX_MEMORY
--meta-threads=num
--mode={send|recv} --mode={send|recv}
--move-after-transfer=archivedir --move-after-transfer=archivedir
--multi-session-threshold=threshold
-N pattern -N pattern
--no-open
--no-read
--no-write
-O fasp_port -O fasp_port

--output-file-progress
--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 --precalculate-job-size
--precalculate-disable --precalculate-disable
--preserve-access-time --preserve-access-time
--preserve-acls=mode --preserve-acls=mode
--preserve-creation-time --preserve-creation-time
--preserve-file-owner-gid --preserve-file-owner-gid

96 IBM Aspera Desktop Client 4.4

Ascp Ascp4
--preserve-file-owner-uid --preserve-file-owner-uid
--preserve-modification-time --preserve-modification-time
--preserve-source-access-time --preserve-source-access-time
--preserve-xattrs=mode --preserve-xattrs=mode
--proxy=proxy_url --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-acls=mode
--remote-preserve-xattrs=mode --remote-preserve-xattrs=mode
--remove-after-transfer --remove-after-transfer
--remove-empty-source-directory --remove-empty-source-directory
--remove-skipped --remove-skipped
--resume (similar to -k)
--retry-timeout=secs
-S remote_ascp
--save-before-overwrite
--scan-threads=num
--source-prefix=prefix --source-prefix=prefix
--source-prefix64=prefix
--sparse-file
--src-base=prefix --src-base=prefix
--src-base64=base64-encoded 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}
--write-threads=NUM
-X rexmsg_size -X rexmsg_size
-Z dgram_size -Z dgram_size

High-Speed Transfer Client Admin Guide for Windows 97

 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.

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

Policy Command template

Fixed --policy=fixed -l target_rate

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

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

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

The policies have the following characteristics:

• high - Adjust the transfer rate to fully use 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 use 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 the bandwidth is shared 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. Use the fixed
policy only for specific contexts, such as bandwidth testing, otherwise, avoid the use of this policy.
The fixed policy requires a maximum target rate.

98 IBM Aspera Desktop Client 4.4

 • 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 you need to fine-tune the transfer policy.
2. What transfer speed must I expect? How do I know if something is wrong with the speed?
Aspera FASP transport has no theoretical throughput limit. Other than the network capacity, the
transfer speed might 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. Perform this test 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 must 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
Fibre 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 resumes without
retransferring the files?
Use the -k flag to enable resume, and specify a resume rule:
-k 0 – Always retransfer the entire file.
-k 1 – Compare file attributes and resume if they match, and retransfer if they do not.
-k 2 – Compare file attributes and the sparse file checksum; resume if they match, and retransfer
if they do not.
-k 3 – Compare file attributes and the full file checksum; resume if they match, and retransfer if
they do not.
Corruption or deletion of the .asp-meta file that is associated with an incomplete transfer 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 skips symbolic links by default.
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 87.
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 might still be updated.
• always - Always overwrite the file.

High-Speed Transfer Client Admin Guide for Windows 99

 • 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 is not overwritten. Plus, if
the destination file is different than the source, but newer, it is 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 checksum. If -k 3, the source and
destination files are compared based on full checksum.

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 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.
As installed, Ascp is used for transfers that started from the GUI, and Ascp4 transfers can be only 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 file paths, use single quotation marks (' ') and forward slashes (/) on all platforms.
• To transfer to the transfer user's docroot, specify "." as the destination.
• Avoid the following characters in file names: / \ " : ' ? > < & * |.

100 IBM Aspera Desktop Client 4.4

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

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 might produce
unexpected results that depend 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. Each environment
variable value must 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 Admin Guide
ASPERA_SCP_COOKIE=cookie
A cookie string that is passed to monitoring services.

High-Speed Transfer Client Admin Guide for Windows 101

 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
Note: To see the ascp4 usage options, run ascp4 -h.
-A, --version
Display version and license information.
-c {aes128|aes192|aes256|none}
Encrypt in-transit file data by 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 .IBM Aspera High-Speed Admin Guide.
--chunk-size=bytes
Perform storage read and 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
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:

102 IBM Aspera Desktop Client 4.4

 • * (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 that are 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 before 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 by using FASP manager I/O. Ascp4 reads FASPMGR4 commands from
management and runs 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
and 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 94.
--file-list=filepath
Transfer the files and directories that are listed in filepath. Only the files and directories are
transferred. The 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 that are 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 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)

High-Speed Transfer Client Admin Guide for Windows 103

 --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 nonlocal 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 hostname or address. Requires --mode. This option can be used instead of
specifying the host as part of the file name (as hostname:filepath).
-i private_key_file
Authenticate the transfer by 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 retransfer 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).
-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 must be equal to or greater than the bit rate 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.

104 IBM Aspera Desktop Client 4.4

--move-after-transfer=archivedir
Move source files and copy source directories to archiver 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.
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 were moved.
-N pattern
Protect (include) files or directories from exclusion by any -E (exclude) options that follow it. Files
and directories are specified by 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 by using standard globbing wildcards and special characters such
as:
• * (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 that are found in aspera.conf are
applied before any -E and -N rules that are specified on the command line.
--no-open
In test mode, do not 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.

High-Speed Transfer Client Admin Guide for Windows 105

 • 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 might be affected when the system automatically adjusts for Daylight
Savings Time (DST). For more information, see Daylight saving time help and support.
--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 takes effect only 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).
--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 file timestamps (currently the same as -p).
--preserve-creation-time
Preserve the file timestamps (currently the same as -p).

106 IBM Aspera Desktop Client 4.4

--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 is completed successfully, but do not remove a
directory that is specified as the source argument. To also remove the specified source directory,
use --remove-empty-source-directory. Directories can be emptied by using --move-after-
transfer or --remove-after-transfer. Scanning for empty directories starts at the src-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 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 retransferring 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 retransferred. 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 wanted 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 (implies that you
use-SSH). This option might be repeated as needed to supply multiple separate SSH arguments. The
order is preserved. The ARG elements are inserted before any key files supplied to ascp4, and before
the user and 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 1 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).

High-Speed Transfer Client Admin Guide for Windows 107

 --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 does not match.
--symbolic-links={follow|copy|skip}
Handle symbolic links by 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 by 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 uses 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".

108 IBM Aspera Desktop Client 4.4

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.

About this task

To avoid this problem, take one of the following actions:

Procedure
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 55. See “Comparison of ascp and ascp4
options” on page 95 for differences in option availability and behavior.
• Read FASP4 management commands
Read management commands V4 from management port 5000 and run the management commands.
The management commands versions 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)

High-Speed Transfer Client Admin Guide for Windows 109

 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
Managing the Aspera service account
On Windows, the Aspera service account is special user account that is used to run services for Aspera
products. These services include IBM Aspera Central, IBM Aspera HTTPD and IBM Aspera Sync. These
instructions describe how to change the password for the Aspera service account and the user account
from the default svcAspera.

Update the Aspera service account password

About this task

During installation, you were prompted to create a new Aspera service account or add an existing user
account for this purpose. If you have problems when you enter the credentials for the existing Aspera
service account, change the user password.
Note: You must have administrative credentials to change the password of the Aspera service account.

Procedure
1. Open the Windows User Accounts management tool. Go to Search from the taskbar and run this
command netplwiz.
2. Click the username of the Aspera service account.
3. Click Reset Password and follow the onscreen instructions.

Change the Aspera service account

Note: On Windows, you must run the script with administrator credentials or disable UAC.

Procedure
1. Open a Command Prompt window and run it as administrator.
Go to Search from the taskbar and type Command Prompt then right-click and select Run as
administrator.
2. Run asuser-services.bat to change the account.
To change the Aspera service account to an existing domain user account (email_address), run the
following command:

> asuser-services.bat email_address password

To change the Aspera service account to a new user without a preexisting account, run the following
command with the username and password of the new user:

> asuser-services.bat username password

110 IBM Aspera Desktop Client 4.4

 Note: If you are running a non-English version of Windows, your admin group might not be
Administrators. When updating Aspera service account, add a third parameter that specifies the
local admin_group by running the following script:

> asuser-services.bat username password admin_group

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 IBM Aspera Central is stopped, or if you modified the <central_server> or <database> sections in
aspera.conf, then you need to restart the service.
Restart the IBM Aspera Central from the Computer Management window. Go to Search from the taskbar
and type Services, click IBM Aspera Central, and click Restart.

IBM Aspera NodeD

Restart the Aspera Node Service if you modified any setting in aspera.conf.
Go to Search from the taskbar and type Services, click IBM Aspera NodeD, and click 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 delete 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 that depends on if you are using it as a mock source file or mock source directory.
Note: If you set large file sizes (> PB) in a faux:/// source, 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:

High-Speed Transfer Client Admin Guide for Windows 111

 • dirname is a name for the directory (required).
• file is the root for file names. The 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 exceeding 7x260 bytes.
• buf_option is how faux source data is 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 - 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://.
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.

112 IBM Aspera Desktop Client 4.4

 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 typically occupies most of the network's bandwidth. Perform it on a dedicated file
transfer line or during a time of 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
Fibre 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.

High-Speed Transfer Client Admin Guide for Windows 113

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 is deleted. aclean can be run on any
platform on which Ascp4 is supported.
Note: The directory that 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 about URL syntax for other object storage types, see “Ascp
transfers with object storage and HDFS” on page 75. 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/

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/

114 IBM Aspera Desktop Client 4.4

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

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

Log files
The Aspera log file includes detailed transfer information and can be useful for review and support
requests.
To view the Aspera log, go to Tools > View Log.

To review logs of other components, click Open Logs Folder:

C:\Program Files\Aspera\Client\var\log

The following files are available in the log folder. Older logs are stored with the same file name, which is
appended with incremental numbers (for example, ascmd.0.log).

File name Contents

ascmd.log File browsing and manipulation in the GUI
aspera-scp-transfer.log FASP transfer events
asperasync.log Hot Folders events
async.log Aspera Sync events

To set the logging level for transfers, open the My Preferences dialog by clicking Tools > Preferences or
by clicking Preferences in the menu bar of the application window.

High-Speed Transfer Client Admin Guide for Windows 115

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

If you find that logs are being overwritten before long transfers of many files are complete, you can
increase the log size. For more information, see .

Connecting to IBM Aspera Shares from the GUI

As of IBM Aspera Shares version 1.9.3, the client must have HSTS, HSTE, or Desktop Client installed in
order to access Shares on a server with HSTS, HSTE, or Desktop Client installed.

Procedure
1. To connect to Shares in the Desktop Client GUI, go to Connections and click .
Enter the following information:

116 IBM Aspera Desktop Client 4.4

 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 that 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 HSTS

HSTS can be configured to log operations on the server's file system that are performed from client
applications (such as the HSTS 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>

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 path name is 512 on
Windows and 4096 on Unix-based platforms.
• Illegal Characters: Avoid the following characters in file names - / \ " : ' ? > < & * |.
• Environment Variables: The total size for environment variables depends on your operating system and
transfer session. Each environment variable value must not exceed 4096 characters.
• Usernames with @ symbol: You cannot add a username with an "@" symbol through the Aspera GUI.
However, you can perform the following actions:
1. Set up a Hot Folder to sync with a Linux server that is using a Linux account that contains the "@"
symbol.
2. Connect to and start a transfer with a Linux server through the Aspera GUI with user credentials that
contains the "@" symbol.

High-Speed Transfer Client Admin Guide for Windows 117

IBM®