Aspera Desktop Client Admin Guide 3.7.4
Windows
Revision: 152482 Generated: 01/15/2018 10:19
| Contents | 2
Contents
Introduction............................................................................................................... 4
What's New?..............................................................................................................7
Get Started as a Transfer Client.............................................................................8
Comparison of Aspera File Delivery and Synchronization Tools........................ 9
Installation and Upgrades......................................................................................12
Requirements.......................................................................................................................................................12
Before Upgrading or Downgrading....................................................................................................................12
Product Setup...................................................................................................................................................... 14
Upgrade Follow up................................................................................................................................. 18
Configuring the Firewall.................................................................................................................................... 19
Testing a Transfer............................................................................................................................................... 19
Updating the Product License............................................................................................................................ 21
Uninstalling......................................................................................................................................................... 22
Transfer Files in the GUI...................................................................................... 23
Application Overview......................................................................................................................................... 23
Global Bandwidth Settings.................................................................................................................................25
Enabling a Transfer Proxy or HTTP Proxy....................................................................................................... 26
Managing Connections....................................................................................................................................... 32
Creating SSH Keys in the GUI..........................................................................................................................39
Transferring Content and Managing Transfers.................................................................................................. 43
Managing Transfers................................................................................................................................ 45
Scheduling and Customizing Transfers in Advanced Mode..............................................................................48
Configuring Transfer Notifications.................................................................................................................... 50
Using Transfer Notifications.............................................................................................................................. 59
Hot Folders.............................................................................................................. 61
Setting Up Hot Folders.......................................................................................................................................61
Managing Hot Folders........................................................................................................................................ 65
ascp: Transferring from the Command Line.......................................................69
Ascp Command Reference................................................................................................................................. 69
Ascp General Examples......................................................................................................................................82
Ascp File Manipulation Examples..................................................................................................................... 84
Ascp Transfers with Object Storage and HDFS................................................................................................ 85
Applying Filters to Include and Exclude Files.................................................................................................. 89
Creating SSH Keys (Command Line)................................................................................................................95
Comparison of Ascp and Ascp4 Options...........................................................................................................95
| Contents | 3
Ascp FAQs.......................................................................................................................................................... 99
ascp4: Transferring from the Command Line with A4.................................... 102
Introduction to A4............................................................................................................................................ 102
A4 Command Reference.................................................................................................................................. 102
Built-in I/O Providers....................................................................................................................................... 109
Ascp4 Examples................................................................................................................................................110
Using A4 from the GUI................................................................................................................................... 111
Appendix................................................................................................................ 112
Managing the Aspera Service Account............................................................................................................112
Update the Aspera Service Account Password.................................................................................... 112
Change the Aspera Service Account....................................................................................................112
Restarting Aspera Services...............................................................................................................................113
Testing and Optimizing Transfer Performance................................................................................................ 113
aclean Reference............................................................................................................................................... 115
Log Files........................................................................................................................................................... 116
Accessing Shares from the GUI.......................................................................................................................118
Product Limitations...........................................................................................................................................119
Technical Support................................................................................................. 120
Legal Notice........................................................................................................... 121
| Introduction | 4
Introduction
Thanks for choosing Aspera and welcome to the world of unbelievably fast and secure data transfer.
The Basics
Aspera high-speed transfers begin when an Aspera client authenticates to an Aspera server and requests a transfer. If
the client user has authorization, then transfer tools are launched on the client and server and the transfer proceeds.
For example, an IBM Aspera Desktop Client user connects to an IBM Aspera Enterprise 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).
What is the Server?
The Aspera server receives transfer requests from Aspera clients, determines if the user has permission to access the
server and authorization to the target area of the file system (source or destination with read or write access), and
participates in transfers. The server can be:
•
•
•
an on-premises installation of Enterprise Server, IBM Aspera Connect Server, or IBM Aspera Point-to-Point
Client (which permits one client connection),
an Enterprise Server installed as part of IBM Aspera Faspex, or
an Enterprise Server deployed in object storage as an IBM Aspera On Demand instance, an IBM Aspera Transfer
Service, or an IBM Aspera Transfer Cluster Manager node.
What is the Client?
The Aspera client is the program that requests a transfer with the Aspera server. Aspera applications that can act as
clients include:
•
•
•
•
•
Desktop Client,
IBM Aspera Drive,
IBM Aspera Connect web browser plugin,
IBM Aspera CLI,
Enterprise Server, Connect Server, and Point-to-Point Client.
What is FASP?
At the heart of your Aspera ecosystem are the FASP transfer engines ascp and IBM Aspera A4. ascp maximizes
data transport over any network and is particularly suited to large files. It is a powerful command-line tool and also
drives transfers started in the GUI.
A4 (ascp4) 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 ascp4 are installed and enabled with your installation of Enterprise Server, Connect Server, Pointto-Point, and Desktop Client applications.
| Introduction | 5
The Aspera Transfer Server
Your Aspera transfer server is a powerful, customizable hub for your high speed transfer activity. Configuration
settings allow you to control which clients have access for uploading or downloading data, how much bandwidth their
transfers can use, the priority of those transfers, and how data is secured during and after transfer. The transfer queue
can be managed on the fly, enabling you to adjust as priorities change. You can also monitor transfers and receive
email notifications when transfer sessions or individual file transfers start and stop.
The Aspera Server GUI
The Aspera desktop GUI is primarily a client transfer tool, but it also offers a user-friendly interface for managing
users and configuring your server. Security settings, bandwidth use policies, and file handling rules can all be set in
the GUI. Configurations can be applied to all users (globally), or to individual users.
Connect Server Web Portal
Connect Server takes an Enterprise Server and makes it 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 Aspera Connect browser plug-in.
Asconfigurator: The Aspera Configuration Tool
If you are unfamiliar with the XML formatting required for your Aspera server's configuration file, or need to
configure settings that are not available in the GUI, you can edit your configuration with confidence by using
asconfigurator. These commands ensure that the XML structure is correctly maintained when you add or
change settings.
Tap into the Aspera Ecosystem
If you have a variety of data storage systems and internal and external customers who need access to the content in
that storage, Enterprise Server with a Connect-enabled license 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 Files, and IBM Aspera 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 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.
Watchfolders: Automatic Content Delivery at Any Scale
The Aspera Watch Service and Watchfolders combined create a powerful, efficient 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 RESTful API interface, you have full programmatic control for custom, automatic
transfer processing.
| Introduction | 6
Watchfolders offer the same transfer and bandwidth management options as ascp, and can be monitored and
managed through Aspera Console. Watchfolders are enabled in your Enterprise Server, Connect Server, or Point-toPoint Client.
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, Sync provides a highspeed tool to do it. Unique among Aspera's transfer tools, Sync supports bidirectional synchronization for optimum
collaboration and consistency between computers.
Sync uses efficient file system monitoring and change detection to minimize redundant data transfer and to reduce
database storage requirements. Sync offers the same transfer and bandwidth management options as ascp, and can
be monitored and managed through IBM Aspera Console.
Sync is installed with your Enterprise Server, Connect Server, and Point-to-Point Client, but both the client and server
require a Sync-enabled license.
| What's New? | 7
What's New?
What's New in 3.7.4?
General
•
•
•
•
•
Hot Folder processes are now multi-threaded, allowing other processes to continue in cases when periodic scans
take a long time (>1 hour).
A new Hot Folder maintenance option enables updating passwords from the command line. This command
provides a scriptable way to update passwords in cases when passwords must be updated frequently, such as for
Aspera Shares authentication in which passwords must be refreshed every 30 days. See Managing Hot Folders on
page 65.
Data is now encrypted in transit (using AES-128) by default when a new connection is created in the GUI.
Transfers with Microsoft Azure Files are now supported, including using Azure Files access keys and the ability to
create connections to Azure Files storage in the GUI.
A new command-line tool, aclean, 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, and the tool supports doing a dry
run to determine what content will be deleted. For information, see aclean Reference on page 115.
A4
•
•
•
•
The -u option can now be used with ascp4 to specify user strings, such as pre- and post-processing variables.
Persistent ascp4 sessions are now supported by using the --keepalive option.
Improved ascp4 transfer stability.
Improved error handling including: 1) errors are reported to both the client and server, 2) if the destination does
not have enough disk space to receive the transfer then the session now exits with an error message, and 3) if some
files in a transfer session fail to transfer, the last failure is now reported in the A4 session status.
| Get Started as a Transfer Client | 8
Get Started as a Transfer Client
Aspera transfer clients connect to a remote Aspera transfer server and request a transfer with that server. Your Aspera
application can be used as a client to initiate transfers with Aspera servers, as described in the following steps.
1. Review the system requirements and install Desktop Client.
See Requirements on page 12 and Product Setup on page 14.
2. Configure the firewall.
See Configuring the Firewall on page 19.
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 25 and Enabling a Transfer Proxy or HTTP Proxy on
page 26.
4. Test a locally-initiated transfer to the Aspera demonstration server to confirm your installation and firewall
configuration are operational.
For instructions, see Testing a Transfer on page 19. 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 50.
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 39 or Creating SSH Keys
(Command Line) on page 95.
7. To run transfers in the GUI, create and configure a connection to the server.
For instructions, see Managing Connections on page 32. If required, configure a proxy (Enabling a Transfer
Proxy or HTTP Proxy on page 26). You can also configure transfer notifications (Scheduling and Customizing
Transfers in Advanced Mode on page 48).
Once your connection is configured, you can initiate transfers with the server. For instructions, see Transferring
Content and Managing Transfers on page 43.
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 69 and Ascp General Examples
on page 82.
For more information about A4, see A4 Command Reference on page 102 and Ascp4 Examples on page
110.
Once you confirm that you can transfer with your server, your basic set up 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 61.
For a comparison of automatic transfer tools, see Comparison of Aspera File Delivery and Synchronization Tools on
page 9.
| Comparison of Aspera File Delivery and Synchronization Tools | 9
Comparison of Aspera File Delivery and Synchronization
Tools
Your Aspera server has several tranfer tools, besides ascp and A4, that can be used for automatic file delivery and
synchronization:
Hot folders: a Windows-only, GUI-managed automatic file delivery tool.
Watchfolders: an automatic file delivery tool that is easily managed from IBM Aspera Console.
Sync: a multi-directional synchronization tool for when complete file system synchronization is required.
•
•
•
See the following table for a complete comparison.
Hot Folders
Watchfolders
Sync
Windows only
Windows
macOS
Linux
AIX
Solaris
Linux on z Systems
BSD
Isilon
Windows
macOS
Linux
AIX
Solaris
Linux on z Systems
BSD
Additional license required No
No
Yes, a Sync-enabled
license is required on both
endpoints
Interface
Aspera desktop GUI
Node API in any command
line, command line on the
Aspera client, or Console
web UI
Aspera client command
line, Console web UI for
management only (no
creation)
Client applications
Desktop Client
Point-to-Point Client
Enterprise Server
Connect Server
Point-to-Point Client
Enterprise Server
Connect Server
Point-to-Point Client
Enterprise Server
Connect Server
IBM Aspera Drive
Server configuration
required
No
No
Recommended
Create in Console
No, but you can monitor
transfers
Yes, you can create,
monitor, and manage
No, but you can monitor
Sync jobs and their
associated transfer sessions
Transfer modes
•
•
•
•
•
•
File delivery or
synchronization
File delivery:
File delivery:
Synchronization:
Files and folders added to
or modified within a Hot
folder on the source are
automatically sent to the
Files and folders added
to or modified within a
Watchfolder on the source
are automatically sent to
All file system changes
(additions, deletions,
and modifications) are
synchronized from source
Supported platforms
Client to server (push)
Server to client (pull)
Client to server (push)
only
Client to server (push)
Server to client (pull)
Client and server
(bidirectional)
| Comparison of Aspera File Delivery and Synchronization Tools | 10
File system monitoring
Hot Folders
Watchfolders
Sync
destination folder. Files
deleted from the source
are not deleted on the
destination.
the destination folder. Files
deleted from the source
are not deleted on the
destination.
to destination (push or pull)
or synchronized between
source and destination
(bidirectional).
Windows operating system
notifications
File system snapshots
collected by the
Aspera Watch Service
(asperawatchd)
•
•
•
Transfer schedules
•
•
Immediate (as soon as
a file system change
in the Hot folder is
detected)
On a user-specified
schedule
•
Immediate (as soon as
a difference between
snapshots is detected)
•
•
In continuous mode:
file system notifications
In scan (on-demand)
mode: Sync scans
the file system on
the source side and
compares it to the Sync
database
Aspera Watch Service
Immediate (in
continous mode or
when using Sync with
the Aspera Watch
Service)
On a user-specified
schedule (Sync run as a
cron job)
Growing file support
No
Yes (on Enterprise Server
and Connect Server)
Database space
requirements
None
At least 2 GB free per 1
At least 2 GB free per 1
million files, 3 GB free per million files, 3 GB free per
1 million files on Windows 1 million files on Windows
Best for
•
•
Push and pull delivery
with a simple GUI
interface that does not
require Console
No
Push delivery from
•
non-Windows platforms
that is managed and
monitored through
Console
•
•
Limitations
•
•
•
Windows only
•
GUI must remain open
In pull mode, Hot
folders pull files even if •
they are in use
Challenging set up
•
when not done in
Console
Transfer rate of millions
of small files can
•
become limited by the
speed at which database
metadata can be written
Precise synchronization
between two endpoints
of all file system
changes (including
deletions)
Bidirectional
synchronization
Very large file sets - up
to 100 million items
across thousands of
directories
Continuous mode
available only for
Windows and Linux
sources
Transfer rate of millions
of small files can
become limited by the
speed at which database
metadata can be written
| Comparison of Aspera File Delivery and Synchronization Tools | 11
More information
Hot Folders
Watchfolders
Sync
Hot Folders on page
61Aspera Enterprise
Server Admin Guide for
Windows
Aspera Enterprise Server
Admin Guide
Aspera Enterprise Server
Admin Guide or Aspera
Sync Admin Guide
| Installation and Upgrades | 12
Installation and Upgrades
Requirements
System requirements for IBM Aspera Desktop Client:
•
•
•
•
•
Windows 7, 8, 10, or Windows Server 2008 R2, 2012 R2, 2016
Product-specific Aspera license file.
For usage in an Active Directory environment you must have access to a domain administrator account to install
the product.
Access to run WMI.
Screen resolution 1024 x 768 or higher.
Before Upgrading or Downgrading
Upgrading
•
The Aspera Client installer automatically checks for an older version of the product on your system. If an older
version is found, the installer automatically removes it before installing the new version.
On a Windows system, the installer displays the following message when an older version of the product is
detected:
•
•
•
Although the installer performs your upgrade automatically, Aspera highly recommends completing the tasks
below before upgrading. If you do not follow these steps, you risk installation errors or losing your former
configuration settings.
You cannot upgrade directly between different Aspera transfer products (such as from Point-to-Point to Desktop
Client, or from Point-to-Point to Enterprise Server). To upgrade, you need to back up the configuration, uninstall
the product, and perform a fresh install of the new version of the product.
When upgrading from versions 2.7.6 and earlier to version 3.X on Windows, user names are now case sensitive.
Downgrading
| Installation and Upgrades | 13
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 the steps below to prepare your machine. Uninstall the application (for instructions, see
Uninstalling on page 22). Copy the older Redis DB file into the var directory before installing the older
(downgrade) version.
C:\Program Files[ (x86)]\Aspera\Client\var\
Without a backup: Follow the steps below to prepare your machine. Uninstall the application (for instructions,
see Uninstalling on page 22) and delete the var and etc directories from your machine. Then do a fresh
installation of the older version. The configuration files in the etc directory may be compatible with older
versions, but not all configurations may be read.
C:\Program Files[ (x86)]\Aspera\Client\var\
C:\Program Files[ (x86)]\Aspera\Client\etc\
Preparing for an Upgrade or Downgrade
1. Verify the version of your existing product.
The steps required to prepare for an upgrade may differ depending on your current product version. To view the
current product and version, run the following command:
> ascp -A
2. Review product release notes.
Review the release notes for the versions that were released since your current version. In particular, the Breaking
Changes section highlights changes that may require you to adjust your workflow, configuration, or usage.
3. Confirm your Aspera service account.
The Aspera service account was created when you first installed Aspera Client on your computer and you will
need this account information during the upgrade. By default, the user name for the Aspera services account is
svcAspera; however, this is not a requirement and you may have selected a different user to run the services.
To identify which user is designated as your Aspera service account in Windows 7, 8, and 10, click Control Panel
> Administrative Tools > Services. In Windows Server 2008, 2012, and 2016, go to the Server Manager and
select Configuration > Services. Find the account associated with the Aspera services (such as Aspera Central)
and record the username. If you have forgotten the Aspera service account password or would like to change the
designated Aspera service account, follow the instructions described in Managing the Aspera Service Account on
page 112.
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, A4, or 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[ (x86)]\Aspera\Client\etc\ (contains Configuration files, Shared Remote
Hosts)
C:\Program Files[ (x86)]\Aspera\Client\var\ (contains Prepost scripts, Connect Server)
<APPDATA>\Aspera\Client (contains the individual user's remote hosts and hot folder configuration)
| Installation and Upgrades | 14
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 Prepost scripts, Connect Server)
C:\Program Files[ (x86)]\Aspera\Aspera Scp\etc\(contains Remote Hosts and Hot Folders
settings)
Product Setup
Important: If this is a product upgrade, review all prerequisites described in Before Upgrading or
Downgrading on page 12.
To install Desktop Client, log into your computer with Administrator (or Domain Administrator if you are in an
Active Directory environment) permissions, and follow the steps below.
1. Download the IBM Aspera product installer.
Use the credentials provided to your organization by Aspera (not your personal Aspera ID) to access:
http://downloads.asperasoft.com/en/downloads/2
If you need help determining your firm's access credentials, contact your Aspera account manager.
2. For product upgrades, ensure you have prepared your machine to upgrade to a newer version.
Although the installer performs your upgrade automatically, Aspera highly recommends completing the tasks
described in Before Upgrading or Downgrading on page 12. If you do not follow these steps, you risk
installation errors or losing your configuration settings.
3. Open the installation package and select the setup type.
Follow the on-screen instructions. After the license agreement screen, select the desired setup type. If you are
upgrading from a previous version, the installer will skip this step.
Setup Type
Description
Typical
Install the standard Desktop Client.
Custom
Select the features and the path to install.
Complete
(Same as the Typical setup type).
4. For a Custom setup, select features to install and the installation path.
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.
| Installation and Upgrades | 15
5. Set up the Aspera service account.
The Aspera service account runs services for Aspera products, including:
•
Aspera Sync
By default, the user name is svcAspera. User names 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
users (users who wish to transfer with your server are
authenticated through Active Directory).
Domain account with local admin privileges.
Transfer users store files on a remote file system (not
on your server machine), such as an SMB file share.
Domain account with local admin privileges.
Additional actions may required. Please see the
| Installation and Upgrades | 16
Requirement
Type of Service Account User
aspera knowledgebase or contact your Aspera account
manager for assistance.
Local accounts: If a local account does not already exist, enter new credentials and click Next. If the account
already 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 wish to change the Aspera service user,
see Managing the Aspera Service Account on page 112.
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
username@fully.qualified.domain.name. See the example below.
| Installation and Upgrades | 17
6. Install the license.
Launch the application to add or update the license. Click: Start Menu > All Programs > Aspera > Client >
Client.
If this is a fresh install, an Enter License window appears. Either click Import License File and select the license
file, or Paste License Text to copy-and-paste the license file's content. The license information appears in the
window. Verify that it is correct and click Close.
| Installation and Upgrades | 18
If you are updating your product license after the installation, see Updating the Product License on page 21.
7. Troubleshooting
If the installer freezes during installation, another Aspera product might be running on your computer. To stop all
FASP transfer-related applications and connections, see Before Upgrading or Downgrading on page 12.
Upgrade Follow up
1. If not using, disable the Aspera Watch Service.
On an upgrade, the Aspera Watch Service is automatically enabled and a Watchfolder instance is automatically
started as the default user (svcAspera). If you do not plan to use these services, you can disable them by running
the following commands to retrieve the service ids and disable them. This stops Watch Service logging that
otherwise continues in the backgournd.
> asrun send -g
The output will look similar to the following:
[asrun send] code=0, body={"services":[{"id":"52ca847a-6981-47e1-9f9bb661cf298af1","configuration":{"enabled":true,"run_as":
{"user":"svcaspera"},"type":"WATCHD"},"state":"RUNNING","state_changed_at":"2016-10-20T19:14:34Z"},
{"id":"svcaspera","configuration":{"enabled":true,"run_as":
{"user":"svcaspera"},"type":"WATCHFOLDERD"},"state":"RUNNING","state_changed_at":"2016-10-20T00:11:19Z"}
In the resulting output, find the IDs for the Watch Service and Watchfolder instances. You can identify the
asperawatchd service by searching for the string "type":"WATCHD" and, before this entry in the output,
locate the string following "id". You can identify the asperawatchfolderd service by searching for the
string: "type":"WATCHFOLDERD". The ID for the asperawatchfolderd service is generally the name of
the user running the service.
To disable the services, run the following command for both the asperawatchd service id and the
asperawatchfolderd service id:
> asrun send --disable watch_service_id
For example, using the output shown above:
> asrun send --disable 52ca847a-6981-47e1-9f9b-b661cf298af1
| Installation and Upgrades | 19
> asrun send --disable svcaspera
The first command disables the Watch Service instance and the second disables the Watchfolder instance.
2. Migrate sshd configuration settings.
Upgrading backs up and deletes the existing sshd_config file before installing the new, default
sshd_config. Therefore, you may want to migrate any customizations from the backup file
(sshd_config.old) to the newly installed sshd_config.
Once you have made changes, reload SSH: go to Control Panel > Administrative Tools > Services. Locate the
OpenSSH Service and click Restart.
3. For all upgrades: Validate aspera.conf.
The aspera.conf file is not overwritten during an upgrade and your configurations are preserved. However,
the XML formatting, parameters, and acceptable values may have changed between your old version and new
version. Run the following command to check aspera.conf for XML form and valid configuration settings:
> asuserdata -v
Configuring the Firewall
Your Aspera transfer product requires access through the ports listed below. If you cannot establish the connection,
review your local corporate firewall settings and remove the port restrictions accordingly.
Desktop Client
The following is basic information for configuring your firewall to allow Aspera file transfers. The outbound TCP
port for SSH may differ depending on your organization's unique network settings. Although TCP/33001 is the
default setting, refer to your IT Department for questions related to which SSH port(s) are open for file transfer.
Consult your operating system's documentation for instructions on configuring your firewall. If your client host is
behind a firewall that does not allow outbound connections, you will need to allow the following ports:
•
•
•
Outbound TCP/33001: Allow outbound connections from the Aspera client on the TCP port (TCP/33001 by
default, when connecting to a Windows server, or on another non-default port for other server operating systems).
Outbound UDP/33001: Allow outbound connections from the Aspera client on the FASP UDP port (33001, by
default).
Local firewall: If you have a local firewall on the client (such as 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 the software is working properly, follow these steps to set up a simple connection with the Aspera
Demo Server and test download and upload transfers.
1. Launch the application.
Click Start menu > All Programs > Aspera > Client > Client
2. Add the Aspera Demo Server in the Connection Manager.
| Installation and Upgrades | 20
Click Connections:
In the Connection Manager, click
to add a new connection, click OK to create a standard connection, and
enter the following information, leaving the other options with their default values or blank:
Field
Value
Host
demo.asperasoft.com
User
aspera
Authentication (Password) demoaspera
3. Test your connection to the remote server.
| Installation and Upgrades | 21
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 Demo Server and download test files.
From the main window, select the demo server entry and click the Connect button.
On the server file browser (right panel), browse to the folder /aspera-test-dir-large, select the file
100MB, and click
to download it to your local machine.
You should see the session appear in the Transfer pane.
5. Upload to the Demo Server
Select the same file (100MB) on the local file browser (left panel), go to the folder /Upload on the Demo Server,
and click
to upload it.
Updating the Product License
1. Run Aspera Client as Administrator.
| Installation and Upgrades | 22
Go to Start > All Programs > Aspera > Client > Client. Right-click Client and click Run as administrator.
2. Click Tools > License to open the license window.
3. Import the license file.
You can either click the Import License File and select the license file, or click Paste License Text to paste
the copied content of the license file. Verify that the license information that appears is correct and click
Close.
Uninstalling
To uninstall Desktop Client, first close or stop the following applications and services:
•
•
•
•
ascp connections
SSH connections
user interface
asperasync services
Open the Control Panel. Depending on your version of Windows, click Add/Remove Programs, Uninstall a
program, or Programs and Features. Click Aspera Client and click uninstall.
| Transfer Files in the GUI | 23
Transfer Files in the GUI
Application Overview
Launching the Application
To launch the application, go to Start > All Programs > Aspera > Client > Client . To perform administrator tasks
(such as server configuration, license updates, or configure email notification templates), right-click Enterprise
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 launch the
application, which shows the local and remote file browsers.
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 Transferring Content and Managing Transfers on page 43.
| Transfer Files in the GUI | 24
Item
Description
C
Click Connections to open the Connection Manager window in which you can manage the
remote endpoints. For more informations, see Managing Connections on page 32.
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 61.
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.
| Transfer Files in the GUI | 25
Item
Description
F
View the advanced upload or download window.
G
Decrypt the selected file if it is encrypted with the content protection.
H
Choose between the detail or the list views. Refresh the folder.
I
Options to manipulation the selected files.
J
Show the selected files' properties.
Global Bandwidth Settings
Aspera FASP transport has no theoretical throughput limit. Other than the network capacity, the transfer speed can be
limited by user-configured rate settings and the resources of the local and remote machines.
To set the transfer bandwidth for all FASP transfers, launch the application with administrator privileges and click
Tools > Global Preferences.
In the Global Preferences dialog, click Transfers. This window provides the following options:
Item
Description
System-Wide Settings
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.
| Transfer Files in the GUI | 26
To override the default bandwidth limits, under System-Wide Settings select the boxes next to Limit Download
Bandwidth and Limit Upload Bandwidth and enter new values in the fields. The global settings for download
and upload bandwidth limits cannot be reset by non-admin users. However, users can view the global limit from the
Preferences > Transfers dialog.
To set default target rates for uploads and downloads, enter new values in the fields next to Default Target Rate. To
adjust the maximum active transfers for all users, enter new values in the fields next to Maximum Active Transfers.
Non-admin users can adjust their personal default target rates and maximum active transfers above or below the
default values.
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 file transfer by
configuring settings in the Preferences dialog. Preferences can be accessed either from the Preferences button, or
from the Tools menu in the main toolbar.
| Transfer Files in the GUI | 27
If you have admin privileges, you can enable transfer proxies for all users by setting global preferences. If you are a
non-admin user, you can override global transfer-proxy settings for your own account, including enabling or disabling
the feature.
By default, proxy is disabled.
Global Proxy Settings
To enable or edit proxy settings globally, click Tools > Global Preferences. You must have admin privileges to set
global preferences.
To enable a transfer proxy, set the following:
•
•
•
•
Select Enable transfer proxy.
Enter the proxy server's hostname or IP address and port number.
Select Secure if your proxy server allows secure connections.
Enter your username and password to authenticate with your proxy server.
| Transfer Files in the GUI | 28
To enable HTTP proxy, set the following:
•
•
•
Select Enable HTTP proxy.
Enter the HTTP proxy's hostname or IP address and port number.
If your HTTP proxy requires authentication, select Authenticated and enter the username and password for your
HTTP proxy.
| Transfer Files in the GUI | 29
By default, all proxy settings are turned off. For global preferences, clicking Restore System Defaults clears all
settings.
User Proxy Settings
To override the global settings, you can enter personal settings for your own account. Click Tools > Preferences or
the Preferencesbutton:
| Transfer Files in the GUI | 30
Under Proxy, the values inherited from the global proxy settings are displayed.
To configure the transfer proxy settings:
•
•
•
•
Select or unselect Enable transfer proxy to enable or disable transfer proxy.
Enter the proxy server's hostname or IP address and port number.
Select Secure if your proxy server allows secure connections.
Enter your username and password to authenticate with your proxy server.
Click Restore Defaults to revert all user settings to the global values.
| Transfer Files in the GUI | 31
To configure the HTTP proxy settings:
•
•
•
Select or unselect Enable HTTP proxy.
Enter the HTTP proxy's hostname or IP address and port number.
If your HTTP proxy requires authentication, select Authenticated and enter the username and password for your
HTTP proxy.
| Transfer Files in the GUI | 32
Note: If you are an admin, you can access the global proxy dialog by clicking the Global Preferences
button.
Click Restore Defaults to revert all user settings to the global values.
Managing Connections
To connect to a remote computer or to a server in the cloud, you need to add it in the Connection Manager. The
sections below describe how to:
•
•
•
•
Open the Connection Manger
Use the Connection Manager to create or modify connections, with a full connection configuration reference
Connect to a remote host
Import and export connections
Note: If you are planning to perform transfers with cloud storage, you must meet the following prerequisites:
•
•
You (username) have permissions to access the cloud storage and the necessary authentication information
(depending on the type of cloud storage).
To transfer files with an S3 storage device using an S3 direct connection, you cannot have a local docroot,
which will cause a transfer to fail. Be sure to confirm your docroot settings before attempting a transfer.
| Transfer Files in the GUI | 33
Opening the Connection Manager
Start the application. Click Start menu > All Programs > Aspera > Client > Client .
In the upper-right corner, click Connections to open the Connection Manager.
This opens the Connection Manager dialog.
Using the Connection Manger
Click
to create a new connection. You can also use
into a new profile) and
to duplicate a selected connection (to copy all information
to delete a connection profile.
When you create a new connection, the Create Connection dialog pops up in which you select the type of
connection. Select Create a standard connection if you are not using the Aspera Transfer Service (ATS) to
authenticate a connection to cloud storage.
| Transfer Files in the GUI | 34
Select Create a standard connection for all connections that do not use the Aspera Transfer Service (ATS) to
connect to cloud storage.
Select Create a connection with a new Aspera Transfer Service (ATS) Access Key to create a connection to
cloud storage and generate a new ATS access key to authenticate the connection. Select the storage type from the
drop-down menu, and enter the required authentication information (depending on storage type). Entering a name
is optional; it can be edited in the Connection Manager.
Select Create a connection with an existing ATS Access Key to create a connection to cloud storage with an
existing Aspera access key. Enter the Aspera access key ID and secret. Entering a name is optional; it can be
edited in the Connection Manager.
•
•
•
To name or rename a connection, click the orange connection profile name at the top of the screen to open the
Rename Connection dialog. You can also launch the Rename Connection dialog by clicking once on an already
selected connection name in the left panel of the Connection Manager. When you have entered the new name, save it
by clicking OK (once in the Rename Connection dialog and again in the Connection Manager).
The Connection Manager includes the following configuration tabs:
Tab
Description
Connection
Host information, such as the address, login credentials, and connection ports.
Transfer
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 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 source files.
The following tables describe the configuration options in these tabs.
| Transfer Files in the GUI | 35
Connection
Option
Description
Host
Required The server's address, such as 192.168.1.10 or companyname.com.
User
The login user for the server.
Authentication
Choose password or public key authentication. To use key-based authentication, see
Creating SSH Keys in the GUI on page 39.
Storage Type
The default option is local storage. Use the drop-down menu to configure object storage.
Connecting to object storage requires an ALEE-enabled Aspera server on the remote
storage.
Object storage types include the following:
•
•
Akamai NetStorage
Amazon S3: Requires your Access Id, Secret Access Key, and bucket path. The local
machine must be reasonably time-synchronized in order to communicate with the
Amazon servers. You can also select the Advanced button to modify the following
settings:
•
•
Host: Amazon S3 hostname (default: s3.amazonaws.com).
Port: Default is port 443.
HTTPS connection for file browsing: Enable for secure browsing.
Server-side file encryption: Enable for AES256 encryption.
Reduced redundancy storage class: Assign objects to a to the "reduced
redundancy" storage class (durability of 99.99%).
Google Storage: Requires your Project Number and bucket path.
Limelight: Requires your Account, Username, and Password.
IBM Cloud Object Storage - Swift: Requires your User name, API Key (Password),
and Authentication Endpoint.
Rackspace Swift: Requires your Storage Account and Access Key.
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 dropdown menu next to Api and click OK.
Windows Azure SAS: Requires your Shared URL.
•
•
•
•
•
•
•
•
Note: You can only choose special storage if you have full access to that storage on
the cloud-based machine.
Target Directory
(or Bucket Path or
Path for most cloud
storage)
The default directory when connecting to this computer. When left blank, browsing the
remote host brings up either the user account's document root (docroot), or the last-visited
folder. When a path is set, connecting to the host always brings up the exact directory.
Advanced Settings >
SSH Port (TCP)
The TCP network port. Default: 33001. Note that if connecting on 33001 fails, the
application attempts to establish a connection on port 22. If the connection on 22 succeeds,
the setting is updated to 22.
Advanced Settings >
fasp Port (UDP)
The UDP network port: Default: 33001.
Advanced Settings >
Connection Timeout
Time out the connection attempt after the selected time.
| Transfer Files in the GUI | 36
Option
Description
Test Connection
Click this button to test the connection to the remote server with the settings you configured.
An alert box opens and reports whether the connection is successful.
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.
fixed
high
fair
low
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. It requires setting a maximum (target) rate (-l option).
Adjust the transfer rate to fully utilize the available bandwidth up to
the maximum rate. When congestion occurs, the transfer rate is twice
as fast as a fair-policy transfer. The high policy requires the setting
of maximum (target) and minimum transfer rates (-l and -m).
Adjust the transfer rate to fully utilize the available bandwidth up
to the maximum rate. When congestion occurs, bandwidth is shared
fairly by transferring at an even rate. The fair policy requires the
setting of maximum (target) and minimum transfer rates (-l and -m).
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.
Speed
Select to specify the transfer rate. The target rate is constrained by the global bandwidth in
the Preferences window. Refer to Global Bandwidth Settings on page 25.
Retry
Select to automatically retry the transfer after a recoverable failure for a set amount of
time, in seconds, minutes or hours. You may set the initial and maximum retry intervals by
clicking the More Options button.
•
•
Initial interval: The first retry waits for the initial interval. Input in seconds, minutes or
hours.
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.
| Transfer Files in the GUI | 37
Option
Description
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.
Click the Show Advanced Settings button to reveal the following options:
Show Advanced
Settings
•
•
Specify FASP datagram size (MTU): By default, the detected path MTU is used. Select
this option to specify a value between 296 and 10000 bytes.
Disable calculation of source files size before transferring: Select this option to turn
off job size calculation on the client-side ()if allowed by the server.
Tracking
Option
Description
Generate delivery
confirmation receipt
Select this option to create the delivery receipt file in the specified location.
Send email
notifications
Send out email notifications based on specified events (start, complete, and error).See Using
Transfer Notifications on page 59 for more information.
Filters
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:
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 Applying Filters to Include and Exclude Files on page 89.
Security
Option
Description
Encryption
Select Encrypt data in transit to encrypt files during transfer. Encryption may decrease
performance, especially at higher transfer speeds and with slower computers.
Content Protection
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.
Select Decrypt password-protected files downloaded to prompt for the decryption
password when downloading encrypted files.
| Transfer Files in the GUI | 38
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 dropdown 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.
(Default)
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.
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 Delete empty source subdirectories to also remove the
folder.
Select Automatically move uploaded source files to a directory after transfer and
specify the location on the source machine to which they should be moved. Only a path to an
existing location on the client can be specified.
Important: When managing connections, changes are not saved until you click OK. Selecting Cancel
will discard any unsaved changes made in the Connection Manager, including the addition and removal of
connections.
Connecting to a Remote Host
To connect to this remote host, double-click the connection in the Connection panel, or select it and click Connect.
| Transfer Files in the GUI | 39
Importing and Exporting Connections
You can also export and import your connection list to and from a text file. To export your connection list, right-click
the remote server panel and select Export. To import your connection list, right-click the remote server panel and
select Import. Both options are shown below (with "export" selected).
Note:
•
•
•
•
Exported and imported connections do not include passwords. Because the password encryption uses
a per-user/per-machine cryptographic key, the encrypted passwords cannot be used on other machines.
Since the passwords are not transferred, they must be re-entered once the connection has been imported.
If you are exporting a connection that uses keys, then you will need to back up those keys manually and
import separately.
A shared connection that is exported or imported by a non-administrator will import as a regular
connection (not as a shared connection).
Email templates are not exported with the connection.
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. 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. To use your Aspera product's transfer-client functionality with public
key authentication, follow the steps below.
You can use the application GUI to generate key pairs and to import existing key pairs. You can also generate key
pairs using the command line; for instructions, see Creating SSH Keys (Command Line) on page 95.
1. Launch the application.
Start the application by clicking Start menu > All Programs > Aspera > Client > Client.
2. In the menu bar, click Tools > Manage Keys.
| Transfer Files in the GUI | 40
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.
| Transfer Files in the GUI | 41
4. In the New SSH Key Pair window, enter the requested information.
Field
Description
Identity
Name your key pair, such as with your user name.
Passphrase
(Optional) Set a passphrase on your SSH key, which will be prompted for whenever
it needs to use the key. If you don't want the user to be prompted for passphrase when
logging in, leave this field blank.
Type
Choose between RSA (default) and DSA keys.
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.
Click OK when finished. The public key is displayed in the window and you may 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 identity.pub in the following
location (in the example below, the public key filename is id_rsa.pub):
user_home_dir\.ssh\id_rsa.pub
5. 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.
| Transfer Files in the GUI | 42
6. Set up connections using public key authentication.
When your public key has been installed on the remote host by its server administrator, click Connections to open
the Connection Manager.
Select the connection for which you want to set up the key. In its Connection tab, select the Public Key
Authentication option and select the key from the drop-down menu.
| Transfer Files in the GUI | 43
Importing keys:
To import keys created outside the GUI, go to Tools > Manage Keys to open the SSH Keys dialog. Click the
button in the upper-left corner of the dialog to open a file browser. You can import the key pair by selecting either the
private key or the public key; this will copy both keys into the user's .ssh directory. You cannot import a key pair if
a key pair with the same identity already exists in the .ssh directory.
Imported key pairs can be shared with other users. In the SSH Keys dialog, select a key and click the
button
to open the Edit SSH Key Pair dialog. Select Access to allow shared connections to use this key. Shared keys are
moved to the Enterprise Server etc directory.
Transferring Content and Managing Transfers
Caution: Do not use the following characters in file or folder names:
/ \ " : ' ? > < & * |
The steps below describe how to initiate a transfer. Instructions for managing transfer progress, order, and rate follow.
1. Connect to the remote host.
Double-click the connection in the Connection panel, or select it and click Connect.
| Transfer Files in the GUI | 44
In the connections panel, the Target Directory shows either a specific path when the target directory is set, or
the last-visited folder when left blank. For how to set up the target directory, see Managing Connections on page
32.
2. Initiate the transfer.
To transfer content to or from the remote computer, select the content to transfer and then click the upload or
download arrow.
3. Transfer content using drag-and-drop or copy-and-paste.
You can transfer files or folders between the right and left browser panels and move them within the browser
panels using drag-and-drop or copy-and-paste. You can copy files or folders within the browser panels using copyand-paste.
You can also initiate an upload using drag-and-drop from Windows Explorer to the right (remote) browser panel.
4. Transfer content without browsing the remote host.
If you have entered the target directory for this connection (See Managing Connections on page 32), you can
also transfer content without browsing the remote computer. To do so, select the files and fodlers from the left
panel (local), select the connection name from the right panel (remote) and click
remote computer's target directory (as shown in the screenshot), or
to push the content to the
to pull content from it.
| Transfer Files in the GUI | 45
Note: If you attempt to transfer too many files, regardless of the method, the transfer is disabled and the
following warning message is displayed:
Too many files selected. Select fewer files, or transfer the folder
containing your selection instead.
The file limit is OS dependent. The limit does not apply to copy-and-paste operations within the same file
browser panel.
Managing Transfers
The Transfers Panel: Start, Stop, and Reorder Transfers
Once the transfer has been successfully initiated, a progress bar will appear in the Transfers panel.
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
indicates the transfer's order in the queue.
and
to change the selected transfer's priority. The # field
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.
| Transfer Files in the GUI | 46
The Details display shows the following information:
Item
Name
Description
A
Details (tab)
Transfer details, including status (rate and ETA) and statistics (session size, files
transferred vs. total files to be transferred, average speed, time elapsed, RTT
delay and average loss in percent).
B
Files (tab)
All files being transferred in this session, along with each files' size and transfer
progress.
C
Transfer controls
Set the FASP transfer policy and transfer rate, if allowed.
fixed
high
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. It requires setting a maximum (target) rate (-l
option).
| Transfer Files in the GUI | 47
Item
Name
Description
fair
low
Adjust the transfer rate to fully utilize the available
bandwidth up to the maximum rate. When congestion
occurs, the transfer rate is twice as fast as a fair-policy
transfer. The high policy requires the setting of maximum
(target) and minimum transfer rates (-l and -m).
Adjust the transfer rate to fully utilize the available
bandwidth up to the maximum rate. When congestion
occurs, bandwidth is shared fairly by transferring at
an even rate. The fair policy requires the setting of
maximum (target) and minimum transfer rates (-l and m).
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.
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.
| Transfer Files in the GUI | 48
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 settings under the Email tab, see Configuring Transfer Notifications on page 50.
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, and scheduling,
that override the default transfer settings.
To initiate a transfer in advanced mode, right-click a file or folder to open the context menu and select Upload (in the
client panel) or Download (in the server panel).
| Transfer Files in the GUI | 49
The advanced transfer dialog includes the following configuration tabs:
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 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 this transfer.
Note: All configuration tabs, except Scheduling, are identical to those in the Connection Manager. For
information on these tabs, see Managing Connections on page 32. The Scheduling tab is described
below.
Scheduling
To enable transfer scheduling, select Schedule this transfer. When finished, click Transfer. The following
scheduling options are available in the Transfer repeats dropdown 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.
| Transfer Files in the GUI | 50
Click Transfer to submit the scheduled transfer. The transfer is then listed under the Transfers tab, along with an icon
(
) under the # column.
To modify the transfer, right-click it and select Edit to view the transfer settings.
Note: When scheduling transfers, ensure that the application is running. Unlike Hot Folders on page 61,
scheduled transfers do not run when the application is closed.
Configuring Transfer Notifications
Transfer notification emails are triggered by three transfer session events: start, completion, and error. These emails
are generated from default or customized mail templates.
| Transfer Files in the GUI | 51
Note: The GUI must remain open for transfer notification emails to send. Closing the GUI stops email
notifications.
The following instructions describe how to configure the SMTP server and to create or modify your email templates.
1. Run Aspera Clientwith Administrator permissions..
Go to Start > All Programs > Aspera > Client > Client. Right-click Client and click Run as administrator.
2. Open Global Preferences by clicking Tools > Global Preferences.
3. Click Mail to configure global email notification settings.
To turn on email notifications for all users, select Enable email notifications. When email notifications are
enabled you must enter the email address from which the notifications are sent in the From Address field and
enter the outgoing email server host name in the Host field. The other values are optional. To test your settings,
click Send test email, which sends a test message to the From Address.
To enable notifications on Hot Folder transfers, select Send email notifications for hot folders.
| Transfer Files in the GUI | 52
4. Set your personal mail preferences.
| Transfer Files in the GUI | 53
To override the global mail settings and configure personal mail settings, click Tools > Preferences or click
Preferences:
Click Mail and edit the inherited global default values. To restore your settings to global values, click Restore
Defaults.
| Transfer Files in the GUI | 54
5. Open the Mail Templates window by clicking Tools > Mail Templates.
| Transfer Files in the GUI | 55
6.
To create a new template, click
, or to edit an existing template, select the template and click
7. For new templates, name the template and select its base template.
Select an existing template from the Based On menu. Click OK.
8. 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.
| Transfer Files in the GUI | 56
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
...
| Transfer Files in the GUI | 57
#end
All conditional statements are categorized in four parts: the conditional (what must occur to trigger the action),
session information (what action is triggered), time, and statistics.
Conditional
Use conditional tests in an if statement. For example:
#if ($event.isFailed())
...
#end
Statement
Description
$event.isStarted()
If the transfer session is started.
$event.isCompleted()
If the transfer session is completed.
$event.isEnded()
If the transfer session is ended.
$event.isFailed()
If the transfer session is failed.
Session Information
Statement
Description
$event.getSourceHost()
The source host name (or host address if the host name
is not discoverable).
$event.getSourceHostAddress()
The source host address.
$event.getSourcePaths()
The source file path.
$event.getDestinationHost()
The destination host name (or host address if the host
name is not discoverable).
$event.getDestinationHostAddress()
The destination host address.
$event.getDestinationPath()
The destination file path.
$event.getInitiatingHost()
The session-initiating host name (or host address if the
host name is not discoverable).
$event.getInitiatingHostAddress()
The session-initiating host address.
$event.getId()
The session ID.
$event.getName()
The session name.
$event.getType().getDescription()
The session state. Three outputs: "STARTED",
"FAILED", and "COMPLETED".
$event.getUser()
The transfer login.
$event.getFiles()
The files that are being transferred. Use this statement
in a foreach loop: (Any text after ## is a comment)
#foreach ($file in $event.getFiles())
## $file is a new variable visible in this
foreach loop.
## $file holds the complete file path and
file name.
## $formatter.decodePath() is used to
ensure a correct string decoding.
$formatter.decodePath($file)
| Transfer Files in the GUI | 58
Statement
Description
#end
Use the counter $velocityCount in an if
statement to limit the output file count. For example, to
list only the first ten files:
#foreach ($file in $event.getFiles())
#if ($velocityCount > 10)
#break
#end
$file
#end
$event.getMessage()
The message that is entered in the email Message field.
$event.getError()
The error message.
Time
Statement
Description
$formatter.date(var, "lang",
"format")
Formatting the date and time output. Enter three values
in the parenthesis:
•
•
•
var is either $event.getStartTime() or
$event.getEndTime()
lang is an abbreviated language name; for example,
en for English.
format is the display format. Use these symbols:
•
•
•
•
•
•
•
•
yyyy The year; for example, 2010.
MM Month of the year; for example, 03.
dd Day of the month; for example, 26.
HH Hour of the day; for example, 16.
mm Minute.
ss Second.
z Time zone.
EEE The abbreviated weekday name; for
example, Fri.
For example,
"EEE, yyyy-MM-dd HH:mm:ss z"
shows Fri, 2010-03-26 16:19:01 PST.
$event.getStartTime()
The session start time.
$event.getEndTime()
The session end time.
Statistics
Statement
Description
$event.getSourceFileCount()
The number of source files.
$event.getCompletedFileCount()
The number of files that successfully transferred.
$event.getFailedFileCount()
The number of files that failed to transfer.
| Transfer Files in the GUI | 59
Statement
Description
$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.
9. Click OK to save your changes.
You can 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 59.
Using Transfer Notifications
Transfer notifications can be sent upon transfer start, complete, and error. Follow these instructions to select and apply
them to your transfer sessions:
1. Preview mail templates.
Preview existing templates to decide which one to use. In the application, click Tools > Mail Templates to
open the Mail Template window. Select an existing template and click
. 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 50.
2. Enable email notifications for connections.
To configure which emails will be sent to specified recipients on specified events, click Connections on the main
page of the application, select the connection, and select the Tracking tab. Select Send email notifications, which
enables you to do the following:
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 50.
To
Enter the recipients, comma separated.
Template
Select a mail template.
Message
Optionally enter a message to include in the notifications.
| Transfer Files in the GUI | 60
Click OK to save your changes.
3. Set up notifications for transfers.
Email notifications can also be applied to transfer sessions. In the file browser of the application, right click the
file or directory and click Upload or Download. Go to the Tracking tab and select Send email notifications.
Refer to the previous section for information on the settings.
| Hot Folders | 61
Hot Folders
Setting Up Hot Folders
Hot Folders are used to monitor 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 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 26.
Creating a New Hot Folder
To create a new Hot Folder, launch the Aspera application as an administrator. In the file browser, go to the folder
you wish 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.
| Hot Folders | 62
Tab
Description
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.
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 one 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 in
order 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.
fixed
high
fair
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. It requires setting a maximum (target) rate (-l option).
Adjust the transfer rate to fully utilize the available bandwidth up to
the maximum rate. When congestion occurs, the transfer rate is twice
as fast as a fair-policy transfer. The high policy requires the setting
of maximum (target) and minimum transfer rates (-l and -m).
Adjust the transfer rate to fully utilize the available bandwidth up
to the maximum rate. When congestion occurs, bandwidth is shared
| Hot Folders | 63
Option
Description
fairly by transferring at an even rate. The fair policy requires the
setting of 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.
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).
Tracking
Option
Description
Send Email
Notifications
Select to enable email notifications and to display configuration options; however,
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 50.
Important: For Hot Folder email notifications to work, the GUI must remain
open.
When (not displayed
until checkbox is
enabled)
Select one or more events that trigger the notification (transfer start, completion, and error).
To (not displayed
until checkbox is
enabled)
Enter the email addresses of the recipients.
Template (not
displayed until
checkbox is enabled)
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 50.
Message (not
displayed until
checkbox is enabled)
Include a custom message with the notification.
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 below, the asterisk (*) can be used
to represent zero to many characters in a string, for example *.tmp matches .tmp and abcde.tmp:
Filter Pattern
Excludes these files
*dirName
path/to/dirName, another/dirName
*1
a/b/file1, /anotherfile1
*filename
path/to/filename, /filename
| Hot Folders | 64
Note: The temporary files that are used by Aspera to resume incomplete files are automatically ignored based
on the resume suffix that was set by the sender.
Security
Option
Description
Encryption
Select Encrypt data in transit to encrypt files during transfer. Encryption might decrease
performance, especially at higher transfer speeds and with slower computers.
Content Protection
Select if files are encrypted or decrypted, depending on whether the Hot Folder is in push or
pull mode:
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.
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 dropdown 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.
(Default)
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.
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. Select Delete empty source subdirectories to also remove the
folder.
Push mode: Select Automatically move uploaded source files to a directory after
transfer and specify the location on the source machine to which they should be moved.
Only a path to an existing location on the client can be specified. Only files are moved, not
| Hot Folders | 65
Option
Description
the parent directory structure. To preserve the directory structure, enable the --src-base
option after the Hot folder is created:
1. Quit the Aspera transfer server application (Enterprise Server, Connect Server, or Point
to Point Client).
2. Stop the Aspera Sync service by going to Control Panel > Administrative Tools >
Services, selecting Aspera Sync, and clicking Stop.
3. Open C:\Program Files[ (x86)]\Aspera\Aspera_product\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.
Note: Any empty folders created in a hot folder are not pushed to the server. However, empty folders that are
created on the server are pulled to the local destination.
Managing Hot Folders
You can 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 Folder 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, you can 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.
| Hot Folders | 66
On the Files tab, you can view the state of individual files:
| Hot Folders | 67
File states can be the following:
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....
| Hot Folders | 68
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 a Shares node and the password for the connection must be refreshed every 30 days, you can use
the following command in a script to update the password:
> asperasync -P new_password -N hot_folder_name
The hot_folder_name is the text in the Name column of the Hot Folders tab.
| ascp: Transferring from the Command Line | 69
ascp: Transferring from the Command Line
Ascp Command Reference
The executable ascp is a command-line FASP transfer program that has the following syntax and command options,
and that supports the following environment variables.
For examples of ascp commands, see the following topics:
•
•
•
Ascp General Examples on page 82
Ascp File Manipulation Examples on page 84
Ascp Transfers with Object Storage and HDFS on page 85
Another command-line FASP transfer program, A4 (ascp4), is optimized for transfers of many small files. It has
many of the same capabilities as ascp as well as its own features. For more information, see Introduction to A4 on
page 102 and Comparison of Ascp and Ascp4 Options on page 95.
Ascp Syntax
ascp options [[username@]src_host:]source1[ source2 ...]
[[username@]dest_host:]dest_path
username
The username of the Aspera transfer user can be specified as part of the source or destination,
whichever is the remote server. It can also be specified with the --user option. If you do not
specify a username for the transfer, the local username is authenticated by default.
Note: If you are authenticating on a Windows machine 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 machine where the files or directories to be transferred reside.
source
The source file or directory to be transferred. Multiple arguments are separated by space characters.
dest_host
The name or IP address of the machine where the source files or directories are to be transferred.
dest_path
The destination directory where the source files or directories are to be transferred. If the source
is a single file, the destination can be a filename. However, if there are multiple source arguments,
the destination must be a directory. To transfer to the transfer user's docroot, specify "." as the
destination.
Specifying Files, Directories, and Paths
•
•
•
Avoid the following characters in file and directory names: / \ " : ' ? > < & * |
Specify paths with forward-slashes, regardless of the operating system.
If directory or file arguments contain special characters, specify arguments with single-quotes (' ') to avoid
interpretation by the shell.
URI paths: URI paths are supported, but with the following restrictions:
| ascp: Transferring from the Command Line | 70
•
•
•
•
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 using one of the following conventions:
•
•
As an 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 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, you can 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 Testing and Optimizing Transfer
Performance on page 113. For examples, see Ascp General Examples on page 82.
Environment Variables
The following environment variables can be used with the ascp command:
ASPERA_DST_PASS=password
Set the password to authenticate a URI destination.
ASPERA_PROXY_PASS=proxy_server_password
Set the password for an Aspera Proxy server.
ASPERA_SCP_COOKIE=cookie
Set a cookie that you want associated with transfers.
ASPERA_SCP_DOCROOT=docroot
Set the transfer user docroot. Equivalent to using --apply-local-docroot when a docroot is
set in aspera.conf.
ASPERA_SCP_FILEPASS=password
Set the passphrase to be used to encrypt or decrypt files. For use with --file-crypt.
ASPERA_SCP_KEY="-----BEGIN RSA PRIVATE KEY..."
Set the transfer user private key. Use instead of the -i option.
ASPERA_SCP_PASS=password
Set the password for the transfer user.
ASPERA_SCP_TOKEN=token
Set the transfer user authorization token. Overridden by -W.
ASPERA_SRC_PASS=password
Set the password to authenticate to a URI source.
Ascp Options
-6
Enable IPv6 address support. When specifying an IPv6 numeric
host for src_host or dest_host, write it in brackets. For example,
username@[2001:0:4137:9e50:201b:63d3:ba92:da]:/path or -host=[fe80::21b:21ff:fe1c:5072%eth1].
| ascp: Transferring from the Command Line | 71
-@ 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 set in aspera.conf for this transfer user. Use to avoid specifying object
storage access credentials in the command line. This option is equivalent to setting the environment
variable ASPERA_SCP_DOCROOT.
-C nodeid:nodecount
Enable multi-session transfers (also known as parallel transfers) on a multi-node/multi-core system.
A node ID (nodeid) and count (nodecount) are required for each session. nodeid and nodecount
can be 1-128, but nodeid must be less than or equal to nodecount, such as 1:2, 2:2. Each session
must use a different UDP port specified with the -O option. Large files can be split across sessions,
see --multi-session-threshold. For more information, see the Enterprise Server Admin
Guide: Configuring Multi-Session Transfers.
-c {aes128|aes192|aes256|none}
Encrypt in-transit file data using the specified cipher. This option overrides the
<encryption_cipher> setting in aspera.conf.
--check-sshfp=fingerprint
Compare fingerprint to the server SSH host key fingerprint that is set with
<ssh_host_key_fingerprint> in aspera.conf. Aspera fingerprint convention is to use
a hex string without the colons; for example, f74e5de9ed0d62feaf0616ed1e851133c42a0082. For
more information on SSH host key fingerprints, see the Enterprise Server Admin Guide: Securing
your SSH Server.
Note: If HTTP fallback is enabled and the transfer "falls back" to HTTP, this option enforces server
SSL certificate validation (HTTPS). Validation fails if the server has a self-signed certificate; a
properly signed certificate is required.
-D | -DD | -DDD
Log at the specified debug level. With each D, an additional level of debugging information is
written to the log.
-d
Create the destination directory if it doesn't already exist. This option is applied automatically to
uploads to object storage.
--delete-before-transfer
Before transfer, delete any files that exist at the destination but not also at the source. 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 the specified pattern. Use the -N option
(include) to specify exceptions to -E rules. Up to 16 -E and -N rules can be specified. 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.
| ascp: Transferring from the Command Line | 72
•
? (question mark) represents a single character, for example t?p matches tmp but not temp.
For details and examples, see Applying Filters to Include and Exclude Files on page 89.
Note: When filtering rules are found in aspera.conf, they are applied before rules
given on the command line (-E and -N).
-e prepost_script
Run the specified pre-post script as an alternate to the default aspera-prepost.bat script.
Specify the full path to the pre-post script. The purpose of the pre-script is to run custom commands
such as shellscripts, perl scripts, Windows batch files, and executable binaries. The custom
commands can make use of transfer statistics and other information placed in environment
variables. For details on the setup and usage of prepost scripts, see the Enterprise Server Admin
guide.
--exclude-newer-than=mtime, --exclude-older-than=mtime
Exclude files (but not directories) from the transfer, based on when the file was last modified.
Positive mtime values are used to express time, in seconds, since the original system time (usually
1970-01-01 00:00:00). Negative mtime values (prefixed with "-") are used to express the number of
seconds prior to the current time.
-f config_file
Read Aspera configuration settings from config_file rather than aspera.conf(the default).
--file-checksum=hash
Enable checksum reporting for transferred files, where hash is the type of checksum to calculate:
sha1, md5, sha-512, sha-384, sha-256, or none (the default). For more information about
checksum reporting, see IBM Aspera Enterprise Server Admin Guide: Reporting Checksums.
Note: If the default value is none, the checksum is the type configured on the server,
if any.
--file-crypt={encrypt|decrypt}
Encrypt files (when sending) or decrypt files (when receiving) for client-side encryption-at-rest
(EAR). Encrypted files have the file extension .aspera-env. This option requires the encryption/
decryption passphrase to be set with the environment variable ASPERA_SCP_FILEPASS. If a
client-side encrypted file is downloaded with an incorrect password, the download is successful, but
the file remains encrypted and still has the file extension .aspera-env.
--file-list=file
Transfer all source files and directories listed in file. Each source item is specified on a separate line.
UTF-8 file format is supported. Only the files and directories are transferred. Path information is not
preserved at the destination. To read a file list from standard input, use "-" in place of file.
For example, if list.txt contains the following list of sources:
/tmp/code/compute.php
doc_dir
images/iris.png
images/rose.png
and the following command is run:
> ascp --file-list=list.txt --mode=send --user=username -host=ip_addr .
then the destination, in this case the the transfer user's docroot, will contain the following:
compute.php
doc_dir (and its contents)
| ascp: Transferring from the Command Line | 73
iris.png
rose.png
Restrictions:
•
•
•
•
•
•
The command line cannot use the user@host:source syntax. Instead, specify this
information with the options --mode, --host, and --user.
Paths specified in the file list cannot use the user@host:source syntax.
Because multiple sources are being transferred, the destination must be a directory.
Only one --file-list or --file-pair-list option is allowed per ascp session. If
multiple lists are specified, only the last one is used.
Only files and directories specified in the file list are transferred; any sources specified on the
command line are ignored.
If the source paths are URIs, the size of the file list cannot exceed 24 KB.
To create a file list that also specifies destination paths, use --file-pair-list.
--file-manifest={none|text}
Generate a list of all transferred files when set to text. Requires --file-manifest-path to
specify the location of the list. (Default: none)
--file-manifest-path=directory
Save the file manifest to the specified location when using --file-manifest=text. File
manifests must be stored locally. For cloud or other non-local storage, specify a local manifest path.
--file-manifest-inprogress-suffix=suffix
Apply the specified suffix to the file manifest's temporary file. For use with --filemanifest=text. (Default suffix: .aspera-inprogress)
--file-pair-list=file
Transfer files and directories listed in file to their corresponding destinations. Each source is
specified on a separate line, with its destination on the line following it.
Specify destinations relative to the transfer user's docroot. Even if a destination is specified as an
absolute path, the resulting path at the destination will still be relative to the docroot. Destination
paths specified in the list are created automatically if they do not already 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
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:
| ascp: Transferring from the Command Line | 74
•
•
•
•
•
•
The command line cannot use the user@host:source syntax. Instead, specify this
information with the options --mode, --host, and --user.
The user@host:source syntax cannot be used with paths specified in the file list.
Because multiple sources are being transferred, the destination specified on the command line
must be a directory.
Only one --file-pair-list or --file-list option is allowed per ascp session. If
multiple lists are specified, only the last one is used.
Only files from the file pair list are transferred; any additional source files specified on the
command line are ignored.
If the source paths are URIs, the file list cannot exceed 24 KB.
For additional examples, see Ascp General Examples on page 82.
-G write_size
If the transfer destination is a server, use the specified write-block size, which is the maximum
number of bytes that the receiver can write to disk at a time. Default: 256 KB, Range: up to
500 MB. This option accepts suffixes "M" or "m" for mega and "K" or "k" for kilo, such that a
write_size of 1M is one MB.
This is a performance-tuning option that overrides the write_block_size set in the client's
aspera.conf. However, the -G setting is overriden by the write_block_size set in the
server's aspera.conf. The receiving server never uses the write_block_size set in the
client's aspera.conf.
-g read_size
If the transfer source is a server, use the specified read-block size, which is the maximum number of
bytes that the sender reads from the source disk at a time. Default: 256 KB, Range: up to 500 MB.
This option accepts suffixes "M" or "m" for mega and "K" or "k" for kilo, such that a read_size of
1M is one MB.
This is a performance-tuning option that overrides the read_block_size set in the client's
aspera.conf. However, the -g setting is overriden 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 host name or address. Requires --mode. This option can be used instead
of specifying the host with the hostname:file syntax.
-i private_key_file
Authenticate the transfer 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 have been tried without success, at which point authentication fails.
-K probe_rate
Measure bottleneck bandwidth at the specified probing rate (Kbps). (Default: 100Kbps)
-k {0|1|2|3}
Enable the resuming of partially transferred files at the specified resume level. (Default: 0)
Specify this option for the first transfer or it will not work for subsequent transfers. Resume levels:
-k 0 – Always retransfer the entire file.
-k 1 – Compare file attributes and resume if they match, and retransfer if they do not.
| ascp: Transferring from the Command Line | 75
-k 2 – Compare file attributes and the sparse file checksums; resume if they match, and
retransfer if they do not.
-k 3 – Compare file attributes and the full file checksums; 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 recorded in the .aspx file are compared.
-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). See also -R for setting the log directory on the server.
-l max_rate
Transfer at rates up to the specified target rate. (Default: 10000 Kbps) This option accepts
suffixes "G" or "g" for giga, "M" or "m" for mega, "K" or "k" for kilo, and "P", "p", or "%" for
percentage. Decimals are allowed. If this option is not set by the client, the setting in the server's
aspera.conf is used. If a rate cap is set in the local or server aspera.conf, the rate does not
exceed the cap.
-m min_rate
Attempt to transfer no slower than the specified minimum transfer rate. (Default: 0) If this option is
not set by the client, then the server's aspera.conf setting is used. If a rate cap is set in the local
or server aspera.conf, then the rate does not exceed the cap.
--mode={send|recv}
Transfer in the specified direction: send or recv (receive). Requires --host.
--move-after-transfer=archivedir
Move source files and copy source directories to archivedir after they are successfully transferred.
Because directories are copied, the original source tree remains in place. The transfer user must
have write permissions to the archivedir. The archivedir is created if it does not already exist. If
the archive directory cannot be created, the transfer proceeds and the source files remain in their
original location.
To preserve portions of the file path above the transferred file or directory, use this option with -src-base. For an example, see Ascp File Manipulation Examples on page 84.
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.
If the source is on a remote system (ascp is run in receive mode), archivedir is subject to the
same docroot restrictions as the remote user.
--remove-after-transfer and --move-after-transfer are mutually exclusive.
Using both in the same session generates an error.
Empty directories are not saved to archivedir.
When used with --remove-empty-directories and --src-base, scanning for empty
directories starts at the specified source base and proceeds down any subdirectories. If no source
base is specified and a file path (as opposed to a directory path) is specified, then only the
immediate parent directory is removed (if empty) after the source files have been moved.
--multi-session-threshold=threshold
Split files across multiple ascp sessions if their size is greater than or equal to threshold. Use with
-C, which enables multi-session transfers.
| ascp: Transferring from the Command Line | 76
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 Enterprise Server Admin Guide: Configuring MultiSession Transfers.
-N pattern
Protect ("include") files or directories from exclusion by any -E (exclude) options that follow it.
Files and directories are specified using pattern. Each option-plus-pattern is a rule. Up to 16 rules
can be specified. Rules are applied in the order (left to right) in which they're encountered. Thus, N rules protect files only from -E rules that follow them. Create patterns using standard globbing
wildcards and special characters such as the following:
•
•
* (asterisk) represents zero or more characters in a string, for example *.tmp matches .tmp
and abcde.tmp.
? (question mark) represents any single character, for example t?p matches tmp but not temp.
For details on specifying patterns and rules, including examples, see Applying Filters to Include and
Exclude Files on page 89.
Note: Filtering rules can also be specified in aspera.conf. Rules found in
aspera.conf are applied before any -E and -N rules specified on the command
line.
-O fasp_port
Use the specified UDP port for FASP transfers. (Default: 33001)
--overwrite={never|always|diff|diff+older|older}
Overwrite destination files with source files of the same name. Default: diff. This option takes the
following values:
never
Never overwrite the file. However, if the parent folder is not empty, its access, modify, and change
times may still be updated.
always
Always overwrite the file.
diff
Overwrite the file if different from the source. If a complete file at the destination is the same as a
file on the source, it is not overwritten. Partial files are overwritten or resumed depending on the
resume policy.
diff+older
Overwrite the file if older and also different than the source. For example, if the destination file
is the same as the source, but with a different timestamp, it will not be overwritten. Plus, if the
destination file is different than the source, but newer, it will not be overwritten.
older
Overwrite the file if its timestamp is older than the source timestamp.
Interaction with resume policy (-k): If the overwrite method is diff or diff+older,
difference is determined by the resume policy (-k {0|1|2|3}). If -k 0 or no -k is specified,
the source and destination files are always considered different and the destination file is always
| ascp: Transferring from the Command Line | 77
overwritten. If -k 1, the source and destination files are compared based on file attributes
(currently file size). If -k 2, the source and destination files are compared based on sparse
checksums. If -k 3, the source and destination files are compared based on full checksums.
-P ssh-port
Use the specified TCP port to initiate the FASP session. (Default: 22)
-p
Preserve file timestamps for access and modification time. Equivalent to setting --preservemodification-time, --preserve-access-time, and --preserve-creationtime. Timestamp support in object storage varies by provider; consult your object storage
documentation to determine which settings are supported.
On Windows, modification time may be affected when the system automatically adjusts
for Daylight Savings Time (DST). For details, see the Microsoft KB article, http://
support.microsoft.com/kb/129574.
On Isilon IQ OneFS systems, access time (atime) is disabled by default. In this case, atime is the
same as mtime. To enable the preservation of atime, run the following command:
# sysctl efs.bam.atime_enabled=1
--partial-file-suffix=suffix
Enable the use of partial files for files that are in transit, and set the suffix to add to names of partial
files. (The suffix does not include a " . ", as for a file extension, unless explicitly specified as part
of the suffix.) This option only takes effect when set on the receiver side. When the transfer is
complete, the suffix is removed. (Default: suffix is null; use of partial files is disabled.)
--policy={fixed|high|fair|low}
Set the FASP transfer 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. It requires
setting a maximum (target) rate (-l option).
high
Adjust the transfer rate to fully utilize the available bandwidth up to the maximum rate. When
congestion occurs, the transfer rate is twice as fast as a fair-policy transfer. The high policy
requires the setting of 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. The fair policy
requires the setting of 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, ascp 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
| ascp: Transferring from the Command Line | 78
Preserve the source-file access timestamps at the destination. Because source access times are
updated by the transfer operation, the timestamp preserved is the one just prior to the transfer.
(To prevent access times at the source from being updated by the transfer operation, use the -preserve-source-access-time option.)
On Isilon IQ OneFS systems, access time (atime) is disabled by default. In this case, atime is the
same as mtime. To enable the preservation of atime, run the following command:
# sysctl efs.bam.atime_enabled=1
--preserve-acls=mode, --remote-preserve-acls=mode
--preserve-xattrs=mode, --remote-preserve-xattrs=mode
Preserve a file's access control lists (ACLs) and/or extended attributes (xattrs) when transferring
between different file system types. The storage mode can be one of the following:
native
Preserve attributes using the native capabilities of the file system. However, native mode is not
supported on all file systems; --preserve-acls=native and --remote-preserveacls=nativework only on Windows computers, and --preserve-xattrs=native and -remote-preserve-xattrs=native work only on Linux computers.
metafile
Preserve 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. The
metafiles are platform independent and can be copied between hosts without loss of information.
The metafile mode is supported on all file systems.
none
Do not preserve attributes (default).
If the client and server have different values for mode, metafile is used silently. Metafiles are
overwritten by subsequent transfers if --overwrite is set to any value other than never.
The remote- options specify the storage mode to use on the remote file system. If this option is
not specified, the mode will be whatever is specified for the local file system. A remote- option
with mode set to native may be overridden by the remote ascp if native mode is unsupported
on the remote file system.
The amount of attribute data per file that can be transferred successfully is subject to ascp's
internal PDPU size limitation.
Note that older versions of ascp do not support values other than none, and transfers using
native or metafile fail with an error that reports incompatible FASP protocol versions.
--preserve-creation-time
(Windows only) Preserve source-file creation timestamps at the destination. Only Windows systems
retain information about creation time. If the destination is not a Windows machine, this option is
ignored.
--preserve-file-owner-gid, --preserve-file-owner-uid
(Linux, UNIX, and macOS only) Preserve the group information (gid) or owner information (uid)
of the transferred files. These options require the transfer user to be authenticated as a superuser.
--preserve-modification-time
Set the modification time, the last time a file or directory was modified (written), of a transferred
file to the modification of the source file or directory. Preserve source-file modification timestamps
at the destination.
On Windows, modification time may be affected when the system automatically adjusts
for Daylight Savings Time (DST). For details, see the Microsoft KB article, http://
support.microsoft.com/kb/129574.
| ascp: Transferring from the Command Line | 79
--preserve-source-access-time
Preserve the access times of the original sources to the last access times prior to transfer. This
prevents access times at the source from being updated by the transfer operation. Typically used in
conjunction with the --preserve-access-time option.
--preserve-xattrs={native|metafile|none}
Preserve a file's extended attributes (xattrs) when transferring between different file system types.
mode can be native, metafile, or none (default). See --preserve-acls for a full
description of mode and the behavior of this option.
--proxy=proxy_url
Use the proxy server at the specified address. proxy_url should be specified with the following
syntax:
dnat[s]://proxy_username:proxy_password@server_ip_address:port
The default ports for DNAT and DNATS protocols are 9091 and 9092. For a usage example, see
Ascp General Examples on page 82.
-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}
Preserve a file's access control lists (ACLs) when transferring between different file system types.
mode can be native, metafile, or none (default). See --preserve-acls for a full
description of mode and the behavior of this option.
--remote-preserve-xattrs={native|metafile|none}
Preserve a file's extended attributes (xattrs) when transferring between different file system types.
mode can be native, metafile, or none (default). See --preserve-acls for a full
description of mode and the behavior of this option.
--remove-after-transfer
Remove all source files, but not the source directories, once the transfer has completed sucessfully.
Requires write permissions on the source.
--remove-empty-directories
Remove empty source directories once the transfer has completed sucessfully, but do not remove a
directory specified as the source argument. To also remove the specified source directory, use -remove-empty-source-directory. Directories can be emptied using --move-aftertransfer or --remove-after-transfer. Scanning for empty directories starts at the
srcbase and proceeds down any subdirectories. If no source base is specified and a file path (as
opposed to a directory path) is specified, then only the immediate parent directory is scanned and
removed if it's empty following the move of the source file. Note: Do not use this option if multiple
processes (ascp or other) might access the source directory at the same time.
--remove-empty-source-directory
Remove directories specified as the source arguments. For use with --remove-emptydirectories.
-S remote_ascp
Use the specified remote ascp binary, if different than ascp.
--save-before-overwrite
| ascp: Transferring from the Command Line | 80
Save a copy of a file before it is overwritten by the transfer. A copy of filename.ext is saved
as filename.yyyy.mm.dd.hh.mm.ss.index.ext in the same directory. index is set to 1
at the start of each second and incremented for each additional file saved during that second. The
saved copies retain the attributes of the original.
--skip-special-files
Skip special files, such as devices and pipes, without reporting errors for them.
--source-prefix=prefix
Prepend prefix to each source path. The prefix can be a conventional path or a URI; however, URI
paths can be used only if no docroot is defined.
--source-prefix64=prefix
Prepend the base64-encoded prefix to each source path. If --source-prefix=prefix is also
used, the last option takes precedence.
--src-base=prefix
Strip the specified path prefix from the source path of each transferred file or 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.)
Example: To transfer the folders and files in the /clips/out folder, but not the out folder itself,
run the following command:
> ascp -d --src-base=/clips/out/ /clips/out/ root@10.0.0.1:/in
Result: At the destination, the source folders and files appear in the in directory:
Source
/clips/out/file1
/clips/out/folderA/file2
/clips/out/folderB/file3
Destination (docroot)
/in/file1
/in/folderA/file2
/in/folderB/file3
Destination without --src-base
/in/out/file1
/in/out/folderA/file2
/in/out/folderB/file3
Note: Sources located outside the source base are not transferred. No errors or
warnings are issued, but the skipped files are logged. For example, if /clips/
file4 were included in the above example sources, it would not be transferred
because it is located outside the specified source base, /clips/out/.
Use with URIs: The --src-base option performs a character-to-character match with the source
path. For object storage source paths, the prefix must specify the URI in the same manner as the
source paths. For example, if a source path includes an embedded passphrase, the prefix must also
include the embedded passphrase otherwise it will not match.
For additional examples, see Ascp File Manipulation Examples on page 84.
--symbolic-links={follow|copy|copy+force|skip}
Handle symbolic links using the specified method. 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
| ascp: Transferring from the Command Line | 81
Copy only the alias file. If a file (not a directory) with the same name is found at the destination, the
alias replaces the file. If the destination is a symbolic link to a directory, it's not replaced.
skip
Skip symbolic links. Do not copy the link or the file it points to.
-T
Disable in-transit encryption for maximum throughput.
-u user_string
Define a user string, such as variables, for pre- and post-processing. This string is passed to the preand -post-processing scripts as the environment variable $USERSTR.
--user=username
Authenticate the transfer using the specified username. You can 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. For this reason, you must
specify the domain explicitly.
-v
Run ascp in verbose mode. This option prints connection and authentication debug messages in the
log file. For information on log files, see Log Files on page 116 .
-W {token_string|@token_file}
-wr, -wf
Authenticate using the authorization token string for the transfer, either as the string itself or when
preceded with an @, the full path to the token file. This option takes precedence over the setting for
the ASPERA_SCP_TOKEN environment variable.
Measure and report bandwidth from server to client (-wr) or client to server (-wf) before the
transfer.
-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 v3.3, datagram size can be specified on the server by setting <datagram_size> in
aspera.conf. The server setting overrides the client setting, unless the client is using a version
of ascp that is older than 3.3, in which case the client setting is used. If the pre-3.3 client does not
set -Z, the datagram size is the discovered MTU and the server logs the message "LOG Peer client
doesn't support alternative datagram size".
Ascp Options for HTTP Fallback
-I cert_file
Certify fallback transfers with the specified HTTPS certificate file.
-j {0|1}
Encode all HTTP transfers as JPEG files when set to 1. (Default: 0)
-t port
Transfer via the specified server port for HTTP fallback.
-x proxy_server
Transfer to the specified proxy server address for HTTP fallback.
| ascp: Transferring from the Command Line | 82
-Y key_file
Cerfity HTTPS fallback transfers using the specified HTTPS transfer key.
-y {0|1}
If set to "1", use the HTTP fallback transfer server when a UDP connection fails. (Default: 0)
Ascp General Examples
The following are examples of initiating FASP file transfers using the ascp command.
To describe filepaths, use single-quote (' ') and forward-slashes (/) on all platforms. Avoid the following characters in
filenames: / \ " : ' ? > < & * |
•
Fair-policy transfer
Fair-policy transfer with maximum rate 100 Mbps and minimum at 1 Mbps, without encryption, transfer all files
in \local-dir\files to 10.0.0.2:
> ascp -T --policy=fair -l 100m -m 1m /local-dir/files root@10.0.0.2:/remote-dir
•
Fixed-policy transfer
Fixed-policy transfer with target rate 100 Mbps, without encryption, transfer all files in \local-dir\files to
10.0.0.2:
> ascp -T -l 100m /local-dir/files root@10.0.0.2:/remote-dir
•
Specify UDP port for transfer
Perform a transfer with UDP port 42000:
> ascp -l 100m -O 42000 /local-dir/files user@10.0.0.2:/remote-dir
•
Public key authentication
Transfer with public key authentication using key file /Documents and Settings/
aspera_user_1/.ssh/aspera_user_1:
> ascp -T -l 10m -i "/Documents and Settings/aspera_user_1/.ssh/aspera_user_1" local-dir/
files root@10.0.0.2:/remote-dir
•
Username or filepath contains a space
Enclose the target in double-quotes when spaces are present in the username and remote path:
> ascp -l 100m local-dir/files "User Name@10.0.0.2:/remote directory"
•
Content is specified in a file pair list
Specify source content to transfer to various destinations in a file pair list. Source content is specified using
the full file or directory path. Destination directories are specified relative to the transfer user's docroot, which
is specified as a "." at the end of the ascp command. For example, the following is a simple file pair list,
filepairlist.txt that lists two source folders, folder1 and folder2, with two destinations, tmp1 and
tmp2:
/tmp/folder1
tmp1
/tmp/folder2
tmp2
> ascp --user=user_1 --host=10.0.0.2 --mode=send --file-pair-list=/tmp/
filepairlist.txt .
| ascp: Transferring from the Command Line | 83
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 root@10.0.0.2:"//1.2.3.4/nw-share-dir/"
•
Parallel transfer on a multicore system
Use parallel transfer on a dual-core system, together transferring at the rate 200Mbps, using UDP ports 33001 and
33002. Two commands are executed in different Terminal windows:
> ascp -C 1:2 -O 33001 -l 100m /file root@10.0.0.2:/remote-dir &
> ascp -C 2:2 -O 33002 -l 100m /file root@10.0.0.2:/remote-dir
•
Upload with content protection
Upload the file space\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
root@10.0.0.2:/remote-dir/
•
Download with content protection and decryption
Download from the server 10.0.0.2 and decrypt while transferring:
> set ASPERA_SCP_FILEPASS=secRet&& ascp -l 10m --file-crypt=decrypt root@10.0.0.2:/remote-dir
/local-dir
•
Decrypt a downloaded, encrypted file
If the password-protected file file1 is downloaded on the local computer without decrypting, decrypt
file1.aspera-env (the name of the downloaded/encrypted version of file1) to file1:
> 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 usernameaspera_proxy and password pa33w0rd. After running the command, Pat is
prompted for the ascp password.
> ascp --proxy dnat://aspera_proxy:pa33w0rd@10.0.0.7 /data/file1 Pat@10.0.0.2:/Pat_data/
Test transfers using faux://
For information on the syntax, see Testing and Optimizing Transfer Performance on page 113.
•
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)
| ascp: Transferring from the Command Line | 84
Transfer 10 MB of random data from 10.0.0.2 as user root and do not save result to disk:
>ascp --mode=send --user=root --host=10.0.0.2 faux:///dummy?10m faux://
Ascp File Manipulation Examples
Below are examples of using the ascp command to manipulate files. In each example, the client is the local
computer and the server is the remote computer.
•
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/
•
root@10.0.0.1:/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/ root@10.0.0.1:/storage/
•
Upload a directory and its contents to a new directory by using the -d opton.
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/ root@10.0.0.1:/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/ root@10.0.0.1:/in/
Result: The source folders and their content appear in the in directory at the destination:
Source
/clips/out/file1
/clips/out/folderA/file2
/clips/out/folderB/file3
Destination (docroot)
/in/file1
/in/folderA/file2
/in/folderB/file3
Destination without --src-base
/in/out/file1
/in/out/folderA/file2
/in/out/folderB/file3
Without --src-base, the example command transfers not only the contents of the out/ folder, but the folder
itself.
•
Upload only the contents of a file and a directory to a new directory by using --src-base
Upload a file, /monday/file1, and a directory, /tuesday/*, to the /storage/ directory on the server,
while stripping the srcbase path and preserving the rest of the file structure. The content is saved as /storage/
monday/file1and /storage/tuesday/* on the server.
> ascp --src-base=/data/content /data/content/monday/file1 /data/content/
tuesday/ root@10.0.0.1:/storage
•
Download only the contents of a file and a directory to a new directory by using --src-base
| ascp: Transferring from the Command Line | 85
Download a file, /monday/file1, and a directory, /tuesday/*, from the server, while stripping the srcbase
path and preserving the rest of the file structure. The content is saved as /data/monday/file1 and /data/
tuesday/* on the client.
> ascp --src-base=/storage/content root@10.0.0.1:/storage/content/monday/
file1 root@10.0.0.1:/storage/content/tuesday/ /data
•
Move the source file on the client after it is uploaded to the server by using --move-after-transfer
Uploadfile0012 to Pat's docroot on the server at 10.0.0.1, and move (not copy) the file from C:/Users/
Pat/srcdir/ to C:/Users/Pat/Archive on the client.
> ascp --move-after-transfer=C:/Users/Pat/Archive C:/Users/Pat/srcdir/
file0012 Pat@10.0.0.1:/
•
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 Pat@10.0.0.1:/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 Pat@10.0.0.1:/
•
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-emptydirectories /data/content root@10.0.0.1:/storage
•
Delete a local directory once its contents have been transferred to the remote server by using --src-base,
--remove-after-transfer, and --remove-empty-directories
Upload /content/ to the server, while stripping the srcbase path and preserving the rest of the file structure.
The content is saved as /storage/* on the server. On the client, the contents of /content/, including empty
directories but excluding partial files, are deleted.
> ascp -k2 -E "*.partial" --src-base=/data/content --remove-after-transfer
--remove-empty-directories /data/content root@10.0.0.1:/storage
Ascp Transfers with Object Storage and HDFS
With an Aspera On Demand-entitled Aspera server installed in your cloud or on-premises object storage, you can
use ascp to transfer to and from it. The syntax of an ascp command transferring to cloud or on-premises object
storage depends on how you authenticate the transfer. The following options for authenticating to the object storage
are described below:
•
•
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.
| ascp: Transferring from the Command Line | 86
•
Specify the storage password or secret key in the command line.
Authenticating the Aspera Transfer User
You must enter the transfer user's password each time you run an ascp transfer, unless you either set the transfer
user's password as an environment variable or set up an SSH key (token) and specify it in the command.
Environment Variable:To set the transfer user's password as the value of the ASPERA_SCP_PASS environment
variable, run the following command:
•
> set ASPERA_SCP_PASS = password
SSH Key:To authenticate with an SSH key, configure token authorization as described in Aspera Enterprise
Server Admin Guide: Setting Up Token Authorization. When you run the ascp transfer, specify the SSH key as an
option:
•
> ascp -i path_to_private_key ...
With Docroot Configured: Authenticate in the Docroot
If your transfer user account has a docroot set, ascp transfers to and from AWS S3, IBM COS - S3, Google Cloud
Storage, Akamai, Softlayer, and Azure are the same as regular ascp transfers. For command syntax examples, see
Ascp General Examples on page 82.
For instructions on configuring a docroot for these types of storage, see Aspera Enterprise Server Admin Guide
(Linux): Docroot Path Formatting for Cloud, Object, and HDFS Storage. You are prompted for the transfer user's
password upon running these commands unless you have set the ASPERA_SCP_PASS environment variable or are
using an SSH key, as described previously.
With No Docroot Configured: Authenticate with Environment Variables
You can set an environment variable (ASPERA_DEST_PASS) with the storage password or access key using the
command below:
> set ASPERA_DEST_PASS = secret_key
With this and ASPERA_SCP_PASS set, run ascp with the syntax listed in the table above, but you do not need
to include the storage password or access key, and are not prompted for the Aspera password upon running the
command.
Note: The ASPERA_DEST_PASS variable is not applicable to Google Cloud Storage or AWS S3 using IAM
roles.
With No Docroot Configured: Authenticate in the Command Line
If you do not have a docroot configured and do not set an environment variable (described previously), you must
authenticate in the command line. In the examples below, you include the storage password or secret key as part of the
destination path. You are prompted for the transfer user's password upon running these commands unless you have set
the ASPERA_SCP_PASS environment variable or are using an SSH key, as described above.
Storage Platform
ascp Syntax and Examples
AWS S3
•
If you are using IAM roles, you do not need to specify the access ID or secret key for
your S3 storage.
Upload syntax:
> ascp options --mode=send --user=username -host=s3_server_addr source_files s3://access_id:secret_key@s3.amazonaws.
| ascp: Transferring from the Command Line | 87
Storage Platform
ascp Syntax and Examples
Upload example:
> ascp --mode=send --user=bear -host=s3.asperasoft.com bigfile.txt
s3://1K3C18FBWF9902:GEyU...AqXuxtTVHWtc@s3.amazonaws.com/
demos2014
Dowload syntax:
> ascp options --mode=recv --user=username -host=s3_server_addr s3://access_id:secret_key@s3.amazonaws.com/my_bucket
my_source_path destination_path
Download example:
> ascp --mode=recv --user=bear --host=s3.asperasoft.com
s3://1K3C18FBWF9902:GEyU...AqXuxtTVHWtc@s3.amazonaws.com/
demos2014/bigfile.txt /tmp/
Azure
These examples are for Azure blob storage. For Azure Files, use the syntax: azurefiles://storage_account:storage_access_key@file.core.windows.net/share
Upload syntax:
> ascp options --mode=send --user=username -host=server_address source_files azu://storage_account:storage_access_ke
Upload example:
> ascp --mode=send --user=AS037d8eda429737d6 -host=dev920350144d2.azure.asperaondemand.com bigfile.txt
azu://astransfer:zNfMtU...nBTkhB@blob.core.windows.net/abc
Dowload syntax:
> ascp options --mode=recv --user=username -host=server azu://storage_account:storage_access_key@blob.core.windows.n
Download example:
> ascp --mode=recv --user=AS037d8eda429737d6 -host=dev920350144d2.azure.asperaondemand.com azu://
astransfer:zNfMtU...nBTkhB@blob.core.windows.net/abc /
downloads
Google Cloud
Storage
Note: The examples below require that the VMI running the Aspera server is a Google
Compute instance.
> ascp options --mode=send --user=username -host=server_address source_files gs:///my_bucket/my_path
Upload example:
> ascp --mode=send --user=bear --host=10.0.0.5 bigfile.txt
gs:///2017_transfers/data
| ascp: Transferring from the Command Line | 88
Storage Platform
ascp Syntax and Examples
Dowload syntax:
> ascp options --mode=recv --user=username -host=server gs:///my_bucket/my_path/source_file destination_path
Download example:
> ascp --mode=recv --user=bear --host=10.0.0.5
gs:///2017_transfers/data/bigfile.txt /data
HDFS
Aspera recommends running ascp transfers with HDFS with a docroot configured.
IBM COS - S3
Upload syntax:
> ascp options --mode=send --user=username -host=server_address source_files s3://access_id:secret_key@accessor_endp
Upload example:
> ascp --mode=send --user=bear -host=s3.asperasoft.com bigfile.txt
s3://3ITI3OIUFEH233:KrcEW...AIuwQ@38.123.76.24/demo2017
Dowload syntax:
> ascp options --mode=send --user=username -host=server_address s3://access_id:secret_key@accessor_endpoint/vault_na
source_files destination_path
Download example:
> ascp --mode=send --user=bear --host=s3.asperasoft.com
s3://3ITI3OIUFEH233:KrcEW...AIuwQ@38.123.76.24/demo2017 /
tmp/
IBM Cloud Object
Storage (COS) Swift and IBM
Bluemix
Aspera recommends running ascp transfers with IBM Cloud Object Storage (COS) - Swift
and IBM Bluemix with a docroot configured.
OpenStack Swift
Upload syntax:
> ascp options --mode=send --user=username -host=ip_addr source_files swift://account_id:api_key@auth_url/my_bucket
Example Upload:
> ascp --mode=send --user=bear -host=192.155.218.130 bigfile.txt swift://
XYZO...46-2:bob:437e...bc16@sjc01.objectstorage.service.networklayer.com
test
Dowload syntax:
> ascp options --mode=recv --user=username -host=ip_addr swift://account_id:api_key@auth_url/my_bucket/
my_source_path destination_path
| ascp: Transferring from the Command Line | 89
Storage Platform
ascp Syntax and Examples
Download example:
> ascp --mode=recv --user=bear
--host=192.155.218.130 swift://
XYZO...46-2:bob:437e29...f616@sjc01.objectstorage.service.networklayer.c
test/bigfile.txt /tmp/
Note: Swift requires additional Trapd configuration settings that can be included as
queries attached to the docroot, with the format docroot?setting.
For example, for an upload to IBM COS - Swift, the path is written as follows:
swift://
XYZO...46-2:bob:437e...bc16@sjc01.objectstorage.service.networklayer
test?aspera.swift.endpoint.auth-path=/auth/v1.0
Applying Filters to Include and Exclude Files
Filters allow you to refine the list of files (or directories) designated for transfer. With filters, you indicate which files
in the transfer list to skip or include. At runtime, ascp looks for filters in two locations: on the ascp command line,
and in aspera.conf. Filters can be set in the aspera.conf file either from the GUI, or by modifying it directly
with an editor or asconfigurator. When filtering rules are found in aspera.conf, they are applied before
rules on the command line. If no filtering rules are specified, ascp transfers all source files in the transfer list. This
topic describes filtering using option flags on the ascp command line.
Note: Filter settings apply only when the server is acting as a client. Servers cannot exclude files or
directories uploaded or downloaded by remote clients.
Specifying Rules on the Command Line
To specify filtering rules on the ascp command line, use the -E and -N options:
-E pattern
-N pattern
Exclude files or directories matching pattern.
Include files or directories matching pattern.
Each rule consists of a -E or -N option and its pattern. A pattern can be a file or directory name, or a set of names
expressed with UNIX glob patterns.
To determine which files to transfer, each file in the set of source files to transfer (the transfer list) is evaluated by the
filters as follows:
1. ascp compares the next file (or directory) in the transfer list to the first rule.
2. If the file matches the pattern, ascp includes it (-N) or excludes it (-E) and for this file, filtering stops.
3. If the file does not match, ascp compares it with the next rule and repeats the process for each rule until a match
is found or until all rules have been tried.
4. If the file never matches any rules, it is included in the transfer.
Filtering operates only on the set of files and directories in the transfer list. That is, an include option (-N) cannot add
files or directories that are not already part of the transfer list.
Filtering is a process of exclusion, and -N rules act as overrides to any -E rules that follow them. For example,
consider the following example command:
> ascp -N 'file2' -E 'file[0-9]' C:\tmp\L\file* user1@examplehost:/tmp
The transfer set is file* (all files that start with file). If file1, file2, and fileA are in C:\tmp\L, they are
filtered as follows:
| ascp: Transferring from the Command Line | 90
1. When file1 is compared with the first rule (-N), no match is found, and filtering continues. When file1 is
compared with the second rule (-E), there is a match; file1 is therefore excluded from transfer, and filtering
stops for file1.
2. When file2 is compared with the first rule, there is a match; file2 is therefore included in the transfer, and
filtering stops for file2.
3. When fileA is compared with the first rule, no match is found. When it is compared with the second rule, again
no match is found. Because no further rules exclude it, fileA is therefore included in the transfer.
If directories or files reside in directories that have already been excluded, they will also be excluded and therefore
not checked against any further rules. Thus, with the command-line options -E '/above/' -N '/above/
below', the file /above/below is never considered because its parent directory /above/ has already been
excluded.
Creating Rule Patterns
In order to filter directories and files to be transferred, their names are matched against patterns (globs) that include
wildcards and special characters. The patterns use the standard globbing syntax found in UNIX systems as well as
several Aspera extensions to the standard.
Character case: Case always matters, even if the scanned file system does not enforce such a distinction. For example,
"debug" does not match "Debug". To match both, the pattern should be "[Dd]ebug".
Single quotes: Patterns must be interpreted only by ascp, not by the command shell. For this reason, patterns that
contain wildcards should be surrounded by single quotes to protect them from expansion by the shell. (Even if
patterns contain no wildcards, they can still be surrounded by single quotes.)
Partial matches: With globs, unlike standard regular expressions, the entire filename or directory name must match the
pattern. That is, abcdef matches the pattern abc*f but abcdefg does not.
Pattern position: A pattern given with -N will match a path only if it falls directly under the transfer directory.
However, a pattern given with -E will match a path regardless of where (which level) the path falls under the transfer
directory. For example, given the pattern 'zzz*' and a transfer directory AAA:
•
•
The -N option matches only if the path to file (or directory) zzz falls directly under AAA. That is, AAA/zzz.
The -E option matches regardless of the where the path to file (or directory) zzz falls under AAA. For example,
AAA/abc/def/zzz.
Standard Globbing: Wildcards and Special Characters
/
The only recognized path separator.
\
Quotes any character literally, including itself. The \ character is exclusively a
quoting operator, not a path separator.
*
Matches zero or more characters, except a / , or the . when preceded immediately
by a / character.
?
Matches any single character, except a / , or a . when preceded immediately by a
/ character.
[…]
Matches exactly one of a set of characters, except a / or a . preceded immediately
by a / character.
[^… ]
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
| ascp: Transferring from the Command Line | 91
/**
Like * but also matches the / character, or a . preceded immediately by a /
(that is, the . in /. ).
* or /** at end of pattern
Matches both directories and files.
/ at end of pattern
Matches directories only. With -N, no files under matched directories or their
subdirectories are included in the transfer. All subdirectories are still included,
although their files will not be included. However, with -E, excluding a directory also
excludes all files and subdirectories under it.
no / or * at end of pattern
Matches files only.
/ at start of pattern
Must match the entire string from the root of the transfer set. (Note: The leading /
does not refer to the system root or the docroot.)
Standard Globbing Examples
Wildcard
Example
Matches
Does Not Match
/
abc/def/xyz
abc/def/xyz
abc/def
\
abc\?
abc?
abc\? abc/D abcD
*
abc*f
abcdef abc.f
abc/f abcefg
?
abc??
abcde abc.z
abcdef abc/d abc/.
[…]
[abc]def
adef cdef
abcdef ade
[^… ]
[^abc]def
zdef .def 2def
bdef /def /.def
[!… ]
[!abc]def
zdef .def 2def
cdef /def /.def
[:xxxxx:]
[[:lower:]]def
cdef ydef
Adef 2def .def
Globbing Extension Examples
Wildcard
Example
Matches
Does Not Match
/**
a/**/f
a/f a/.z/f a/d/e/f
a/d/f/ za/d/f
* at end of rule
abc*
abc/ abcfile
/** at end of rule
abc/**
abc/.file abc/d/e/
abc/
/ at end of rule
abc/*/
abc/dir
abc/file
no / at end of rule
abc
abc (file)
abc/
/ at start of rule
/abc/def
/abc/def
xyz/abc/def
Rule Composition
Example
Transfer Result
-N rule
Includes all files and directories whose names match rule. Because there is no -E, all
the originally specified files and directories are included anyway; in other words, by
itself, a -N rule does nothing.
-N rule1 -E rule2
Includes all files and directories whose names match rule1. Excludes all that match
rule2, except those that also matched rule1.
-E rule
Excludes all files and directories whose names match rule.
| ascp: Transferring from the Command Line | 92
Example
Transfer Result
-E rule1 -N rule2
Excludes all files and directories whose names match rule1. Because there is no -E
following the -N, all files and directories not already excluded by the preceding -E
are included anyway; in other words, a trailing -N rule does nothing to change the
result.
Testing Your Filter Rules
If you plan to use filtering rules, it's best to test them first. An easy way to test filtering rules, or to learn how they
work, is to set up source and destination directories and use demo.asperasoft.com as the Aspera server:
1. On your computer, create a small set of directories and files that generally matches a file set you typically transfer.
Since filenames are all that matter, the files can be small.
2. Place the file set in an accessible location, for example /tmp/src.
3. Upload the file set to the Aspera demo server as user "aspera". Specify the demo-server target directory Upload.
You will be prompted for the password, which is "demoaspera":
> ascp C:\tmp\src aspera@demo.asperasoft.com:Upload/
4. Create a destination directory on your computer, for example C:\tmp\dest.
5. You can now download your files from the demo server to C:\tmp\dest, running the ascp commands with N and -E to test your filtering rules. For example:
> ascp -N 'wxy/**' -E 'def' aspera@demo.asperasoft.com:Upload/src/abc/ C:
\tmp\dest
6. Compare the destination directory with the source to determine whether files were filtered as expected.
Example Filter Rules
The example rules below are based on running a command such as the following to download a directory AAA from
demo.asperasoft.com to C:\tmp\dest:
> ascp rules aspera@demo.asperasoft.com:Upload/AAA C:\tmp\dest
The examples below use the following file set:
AAA/abc/def
AAA/abc/.def
AAA/abc/.wxy/def
AAA/abc/wxy/def
AAA/abc/wxy/.def
AAA/abc/wxy/tuv/def
AAA/abc/xyz/def/wxy
AAA/wxyfile
AAA/wxy/xyx/
AAA/wxy/xyxfile
Key for interpreting example results below:
< xxx/yyy = Excluded
xxx/yyy = Included
zzz/ = directory name
zzz = filename
(1) Transfer everything except files and directories starting with ".":
-N '*' -E 'AAA/**'
| ascp: Transferring from the Command Line | 93
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 will be included:
-N '*/wxy*' -E 'AAA/**'
Results:
AAA/abc/wxy/tuv/
AAA/abc/xyz/def/wxy
AAA/wxyfile
AAA/wxy/xyx/
< AAA/abc/def
| ascp: Transferring from the Command Line | 94
<
<
<
<
<
<
AAA/abc/.def
AAA/abc/.wxy/def
AAA/abc/wxy/def
*
AAA/abc/wxy/.def
AAA/abc/wxy/tuv/def
AAA/wxy/xyxfile
* Even though wxy is included, def is excluded because it's a file.
(5) Include wxy directories and files at any level, even those starting with ".":
-N '*/wxy*' -N '*/wxy/**' -E 'AAA/**'
Results:
AAA/abc/wxy/def
AAA/abc/wxy/.def
AAA/abc/wxy/tuv/def
AAA/abc/xyz/def/wxy
AAA/wxyfile
AAA/wxy/xyx/
AAA/wxy/xyxfile
< AAA/abc/def
< AAA/abc/.def
< AAA/abc/.wxy/def
(6) Exclude directories and files starting with wxy, but only those found at a specific location in the tree:
-E '/AAA/abc/wxy*'
Results:
AAA/abc/def
AAA/abc/.def
AAA/abc/.wxy/def
AAA/abc/xyz/def/wxy
AAA/wxyfile
AAA/wxy/xyx/
AAA/wxy/xyxfile
< AAA/abc/wxy/def
< AAA/abc/wxy/.def
< AAA/abc/wxy/tuv/def
(7) Include the wxy directory at a specific location, and include all its subdirectories and files, including those starting
with ".":
-N 'AAA/abc/wxy/**' -E 'AAA/**'
Results:
AAA/abc/wxy/def
AAA/abc/wxy/.def
AAA/abc/wxy/tuv/def
< AAA/abc/def
< AAA/abc/.def
< AAA/abc/.wxy/def
< AAA/abc/xyz/def/wxy
< AAA/wxyfile
< AAA/wxy/xyx/
< AAA/wxy/xyxfile
| ascp: Transferring from the Command Line | 95
Creating SSH Keys (Command Line)
Public key authentication (SSH Key) is a more secure alternative to password authentication that allows users to avoid
entering or storing a password, or sending it over the network. Public key authentication uses the client computer
to generate the key-pair (a public key and a private key). The public key is then provided to the remote computer's
administrator to be installed on that machine.
To log in into other Aspera servers with public key authentication, you can create key-pairs from the command line,
as follows:
1. Create a .ssh directory in your home directory if it does not already exist:
> md user_home_dir\.ssh
Go to the .ssh folder:
> cd user_home_dir\.ssh
2. Run ssh-keygen to generate an SSH key-pair.
Run the following command in the .ssh folder to create a key pair. For key_type, specify either RSA (rsa) or
ED25519 (ed25519). At the prompt for the key-pair's filename, press ENTER to use the default name id_rsa
or id_ed25519, or enter a different name, such as your username. For a passphrase, you can either enter a
password, or press return twice to leave it blank:
> ssh-keygen -t key_type
Note: When you run ascp in FIPS mode (<fips_enabled> is set to true in aspera.conf), and
you use passphrase-protected SSH keys, you must either (1) use keys generated by running ssh-keygen
in a FIPS-enabled system, or (2) convert existing keys to a FIPS-compatible format using a command such
as the following:
> openssl pkcs8 -topk8 -v2 aes128 -in id_rsa -out new-id_rsa
3. Retrieve the public key file.
The key-pair is generated to your home directory's .ssh folder. For example, assuming you generated the key
with the default name id_rsa:
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.
4. Start a transfer using public key authentication with the ascp command.
To transfer files using public key authentication on the command line, use the option -i private_key_file. For
example:
> ascp -T -l 10M -m 1M -i "user_home_dir\.ssh\id_rsa" myfile.txt
jane@10.0.0.2:\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.
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,
| ascp: Transferring from the Command Line | 96
and the options that are available with both. If the option behavior is different, the ascp option has ** added to the
end and the difference is described following the table.
ascp
ascp4
-6
-@[range_low:range_high]
-A, --version
-A, --version
--apply-local-docroot
-C nodeid:nodecount
-c cipher
--check-sshfp=fingerprint
--chunk-size=bytes
--compare=method
--compression=method
--compression-hint=num
-D | -DD | -DDD
-d
--delete-after
--delete-before
--delete-before-transfer**
--delete-before-transfer**
--dest64
-E pattern
-E pattern
-e prepost_filepath
--exclude-newer-than=mtime
--exclude-older-than=mtime
-f config_file
--faspmgr-io
--file-checksum=hash
--file-crypt={encrypt|decrypt}
--file-list=filepath
--file-manifest={none|text}
--file-manifest-path=directory
--file-manifest-inprogress-suffix=suffix
--file-pair-list=filepath
-G write_size
-g read_size
--file-list=filepath
| ascp: Transferring from the Command Line | 97
ascp
ascp4
-h, --help
-h, --help
-i private_key_file_path**
-i private_key_file_path
-K probe_rate
-k {0|1|2|3}
-k {0|1|2|3}
--keepalive
-l max_rate
-l max_rate
-L local_log_dir[:size]
-L local_log_dir[:size]
-m min_rate
-m min_rate
--memory=bytes
--meta-threads=num
--mode={send|recv}
--mode={send|recv}
--move-after-transfer=archivedir
--multi-session-threshold=threshold
-N pattern
-N pattern
--no-open
--no-read
--no-write
-O fasp_port
-O fasp_port
--overwrite=method**
--overwrite=method**
-P ssh-port
-P ssh-port
-p
-p
--partial-file-suffix=suffix
--policy={fixed|high|fair|low}
--policy={fixed|high|fair|low}
--precalculate-job-size
--preserve-access-time
--preserve-acls=mode
--preserve-creation-time
--preserve-file-owner-gid
--preserve-file-owner-gid
--preserve-file-owner-uid
--preserve-file-owner-uid
--preserve-modification-time
--preserve-source-access-time
--preserve-xattrs=mode
--proxy=proxy_url
-q
-q
| ascp: Transferring from the Command Line | 98
ascp
ascp4
-R remote_log_dir
-R remote_log_dir
--read-threads=num
--remote-memory=bytes
--remote-preserve-acls=mode
--remote-preserve-xattrs=mode
--remove-after-transfer
--remove-empty-directories
--remove-empty-source-directory
--resume (similar to -k)
--retry-timeout=secs
-S remote_ascp
--save-before-overwrite
--scan-threads=num
--source-prefix=prefix
--source-prefix64=prefix
--sparse-file
--src-base=prefix
--src-base=prefix
--symbolic-links=method**
--symbolic-links=method**
-T
-T
-u user_string
-u user_string
--user=username
--user=username
-v
-W token_string | @token_filepath
-w{r|f}
-X rexmsg_size
-X rexmsg_size
-Z dgram_size
-Z dgram_size
Differences in Option Behavior
--delete-before-transfer
With ascp4, --delete-before-transfer can be used with URI storage. URI storage is not supported for this
option in ascp.
-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
| ascp: Transferring from the Command Line | 99
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
1. How do I control the transfer speed?
You can specify a transfer policy that determines how a FASP transfer utilizes the network resource, and you can
specify target and minimum transfer rates where applicable. In an ascp command, use the following flags to
specify transfer policies that are fixed, fair, high, or low:
Policy
Command template
Fixed
Fair
High
Low
--policy=fixed -l target_rate
--policy=fair -l target_rate -m min_rate
--policy=high -l target_rate -m min_rate
--policy=low -l target_rate -m min_rate
The policies have the following characteristics:
fixed
high
fair
low
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. It requires
setting a maximum (target) rate (-l option).
Adjust the transfer rate to fully utilize the available bandwidth up to the maximum rate. When
congestion occurs, the transfer rate is twice as fast as a fair-policy transfer. The high policy
requires the setting of maximum (target) and minimum transfer rates (-l and -m).
Adjust the transfer rate to fully utilize the available bandwidth up to the maximum rate. When
congestion occurs, bandwidth is shared fairly by transferring at an even rate. The fair policy
requires the setting of maximum (target) and minimum transfer rates (-l and -m).
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.
2. What transfer speed should I expect? How do I know if something is "wrong" with the speed?
Aspera's FASP transport has no theoretical throughput limit. Other than the network capacity, the transfer speed
may be limited by rate settings and resources of the computers. To verify that your system's FASP transfer can
fulfill the maximum bandwidth capacity, prepare a client machine to connect to this computer, and test the
maximum bandwidth.
Note: This test typically occupies most of a network's bandwidth. Aspera recommends this test be
performed on a dedicated file transfer line or during a time of low network activity.
| ascp: Transferring from the Command Line | 100
On the client machine, start a transfer with fixed bandwidth policy. Start with a lower transfer rate and gradually
increase the transfer rate toward the network bandwidth (for example, 1 MB, 5 MB, 10 MB, and so on). Monitor
the transfer rate; at its maximum, it should be slighly below your available bandwidth:
$ ascp -l 1m source-file destination
To improve the transfer speed, also consider upgrading the following hardware components:
Component
Description
Hard disk
The I/O throughput, the disk bus architecture (such as RAID, IDE, SCSI, ATA, and Fiber
Channel).
Network I/O
The interface card, the internal bus of the computer.
CPU
Overall CPU performance affects the transfer, especially when encryption is enabled.
3. How do I ensure that if the transfer is interrupted or fails to finish, it will resume without retransferring the
files?
Use the -k flag to enable resume, and specify a resume rule:
-k 0 – Always retransfer the entire file.
-k 1 – Compare file attributes and resume if they match, and retransfer if they do not.
-k 2 – Compare file attributes and the sparse file checksums; resume if they match, and retransfer if they do
not.
-k 3 – Compare file attributes and the full file checksums; resume if they match, and retransfer if they do not.
Corruption or deletion of the .asp-meta file associated with an incomplete transfer will often result in a
permanently unusable destination file even if the file transfer resumed and successfully transferred.
4. How does Aspera handle symbolic links?
The ascp command skips symbolic links by default.
Important: On Windows, the only option is skip.
5. What are my choices for overwriting files on the destination computer?
In ascp, you can specify the --overwrite=method rule with the following method options:
never
Never overwrite the file. However, if the parent folder is not empty, its access, modify, and change
times may still be updated.
always
Always overwrite the file.
diff
Overwrite the file if different from the source. If a complete file at the destination is the same as a
file on the source, it is not overwritten. Partial files are overwritten or resumed depending on the
resume policy.
diff+older
Overwrite the file if older and also different than the source. For example, if the destination file
is the same as the source, but with a different timestamp, it will not be overwritten. Plus, if the
destination file is different than the source, but newer, it will not be overwritten.
older
Overwrite the file if its timestamp is older than the source timestamp.
Interaction with resume policy (-k): If the overwrite method is diff or diff+older, difference is
determined by the resume policy (-k {0|1|2|3}). If -k 0 or no -k is specified, the source and destination
| ascp: Transferring from the Command Line | 101
files are always considered different and the destination file is always overwritten. If -k 1, the source and
destination files are compared based on file attributes (currently file size). If -k 2, the source and destination files
are compared based on sparse checksums. If -k 3, the source and destination files are compared based on full
checksums.
| ascp4: Transferring from the Command Line with A4 | 102
ascp4: Transferring from the Command Line with A4
Introduction to A4
Aspera A4 is an optimized transfer engine based on FASP technology. A4 is designed for sending extremely large sets
of individual files efficiently, and it supports UDP multicast. The executable, ascp4, is similar to ascp and shares
many of the same options and capabilities. For more information on using ascp4 for UDP multicast, see the IBM
Aspera Faspstream User Guide.
Both ascp4 and ascp are automatically installed with IBM Aspera Enterprise Server, Connect Server, Point-toPoint, and Desktop Client applications.
As installed, ascp is used for transfers intiated from the GUI and ascp4 transfers can only be initiated from the
command line. For information on how to make GUI-initiated transfers use ascp4, see Using A4 from the GUI on
page 111.
A4 Command Reference
Supported environment variables, the general syntax, and command options for A4 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.
Note: Not all ascp options are available with ascp4. For more information, see Comparison of Ascp and
Ascp4 Options on page 95. Additionally, ascp4 transfers fail if the user's docroot is a symlink, whereas
ascp supports symlink docroots.
ascp4 Syntax
ascp4 options [[user@]srcHost:]source_file1[,source_file2,...]
[[user@]destHost:]target_path
User
The username of the Aspera transfer user can be specified as part of the filepath 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 target paths
•
•
•
If there are multiple source arguments, then the target path must be a directory.
To describe filepaths, use single quotes (' ') and forward slashes (/) on all platforms.
Avoid the following characters in filenames: / \ " : ' ? > < & * |.
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. 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).
| ascp4: Transferring from the Command Line with A4 | 103
UNC paths: If the server is Windows and the path on the server is a UNC path (a path that points to a shared
directory or file on Windows operating systems) then it can be specified in an ascp4 command using one of the
following conventions:
1. UNC path that uses backslashes ( \ )
If the client 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.
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
operating system.
Environment Variables
If needed, you can set the following environment variables for use with an ascp4 session.
ASPERA_SCP_PASS=password
The password that is used for SSH authentication of the transfer user.
ASPERA_SCP_COOKIE=cookie
A cookie string that is passed to monitoring services.
ASPERA_SRC_PASS=password
The password that is used to authenticate to a URI source.
ASPERA_DST_PASS=password
Set the password that is used to authenticate to a URI destination.
Ascp4 Options
-A, --version
Display version and license information.
--chunk-size=bytes
Perform storage read/write operations with the specified buffer size. Also use the buffer size as an
internal transmission and compression block. Valid range: 4 Kb - 128 Mb.
--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.
--delete-after, --delete-after-transfer
After all files are transferred, delete files that exist at the destination but not at the source. Objects
on the destination that have the same name but different type or size as objects on the source are
not deleted. Requires write permissions on the destination. Do not use with multiple sources, -keepalive, or HTTP fallback.
Using --delete-after can be slower than --delete-before because the destination data
set that is used to compare objects can be larger after the transfer.
| ascp4: Transferring from the Command Line with A4 | 104
--delete-before, --delete-before-transfer
Before transfer, delete files that exist at the destination but not at the source. Requires write
permissions on the destination. 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, -keepalive, or HTTP fallback.
Using --delete-before can be faster than --delete-after because the destination data
set that is used to compare objects can be smaller before the transfer occurs.
-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. Up to 16 -E and -N rules can be specified. 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 Applying Filters to Include and Exclude Files on page 89.
Note: When filtering rules are found in aspera.conf, they are applied before rules
given on the command line (-E and -N).
--exclude-newer-than=mtime
--exclude-older-than=mtime
Exclude files (but not directories) from the transfer based on when the file was last changed.
Positive mtime values are used to express time, in seconds, since the original system time (usually
1970-01-01 00:00:00). Negative mtime values (prefixed with "-") are used to express the number of
seconds prior to the current time.
--faspmgr-io
Run ascp4 in API mode using FASP manager I/O. ascp4 reads FASPMGR4 commands from
management and executes them. The FASPMGR4 commands are PUT/WRITE/STOP to open/
write/close on a file on the server.
--file-list=filename
Transfer the content that is listed in filepath. Only the files and directories are transferred; path
information is not preserved at the destination. To read a file list from standard input, use "-" in
place of file. UTF-8 file format is supported. If a directory does not exist at the destination, it is
created (-d is automatically applied). Each source must be specified on a separate line, for example:
src
src2
...
srcN
Restrictions:
•
•
•
-h, --help
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 ascp session. If multiple file lists are specified,
all but the last are ignored.
Only files from the file list are transferred, and any additional source files specified on the
command line are ignored.
Display the usage summary.
--host=host
| ascp4: Transferring from the Command Line with A4 | 105
Transfer to the specified host name or address. Requires --mode. This option can be used instead
of specifying the host as part of the filename (as hostname:filepath).
-i private_key_file
Authenticate the transfer using public key authentication with the specified SSH private key
file (specified with a full or relative path). The private key file is typically in the directory
$HOME/.ssh/. If multiple -i options are specified, only the last one is used.
-k {0|1|2|3}
Enable the resumption of partially transferred files at the specified resume level. Default: 0. This
option must be specified for your first transfer or it does not work for subsequent transfers. Resume
levels:
•
•
•
•
-k 0: Always 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).
-L local_log_dir[:size]
Log to the specified directory on the local host 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.
-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}
-N pattern
Transfer in the specified direction: send or recv (receive). Requires --host.
Protect ("include") files or directories from exclusion by any -E (exclude) options that follow it.
Files and directories are specified using pattern. Each option-plus-pattern is a rule. Up to 16 rules
can be specified. Rules are applied in the order (left to right) in which they're encountered. Thus, N rules protect files only from -E rules that follow them. Create patterns using standard globbing
wildcards and special characters such as the following:
•
•
* (asterisk) represents zero or more characters in a string, for example *.tmp matches .tmp
and abcde.tmp.
? (question mark) represents any single character, for example t?p matches tmp but not temp.
For details on specifying patterns and rules, including examples, see Applying Filters to Include and
Exclude Files on page 89.
| ascp4: Transferring from the Command Line with A4 | 106
Note: Filtering rules can also be specified in aspera.conf. Rules found in
aspera.conf are applied before any -E and -N rules specified on the command
line.
--no-open
In test mode, do not actually open or write the contents of destination files.
--no-read
In test mode, do not read the contents of source files.
--no-write
In test mode, do not write the contents of destination files.
-O fasp_port
Use the specified UDP port for FASP transfers. Default: 33001.
--overwrite={always|never|diff|diff+older|older}
Overwrite files at the destination with source files of the same name based on the method. Default:
always. Use with --compare and --resume. method can be the following:
•
•
•
•
•
-P ssh-port
always – Always overwrite the file.
never – Never overwrite the file. If the destination contains partial files that are older or the
same as the source files and --resume is enabled, the partial files resume transfer. Partial files
with checksums or sizes that differ from the source files are not overwritten.
diff – Overwrite 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.
Use the specified TCP port to initiate the FASP session. (Default: 22)
-p
Preserve file timestamps for access and modification time. Equivalent to setting --preservemodification-time, --preserve-access-time, and --preserve-creationtime. Timestamp support in object storage varies by provider; consult your object storage
documentation to determine which settings are supported.
On Windows, modification time may be affected when the system automatically adjusts
for Daylight Savings Time (DST). For details, see the Microsoft KB article, http://
support.microsoft.com/kb/129574.
On Isilon IQ OneFS systems, access time (atime) is disabled by default. In this case, atime is the
same as mtime. To enable the preservation of atime, run the following command:
# sysctl efs.bam.atime_enabled=1
--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
| ascp4: Transferring from the Command Line with A4 | 107
•
•
•
can consume most of the network's bandwidth and is not recommended for most types of file
transfers. This option requires a maximum (target) rate value (-l).
high – Adjust the transfer rate to fully utilize the available bandwidth up to the maximum rate.
When congestion occurs, the transfer rate is twice as fast as transfer with a fair policy. This
option requires maximum (target) and minimum transfer rates (-l and -m).
fair – Adjust the transfer rate to fully utilize the available bandwidth up to the maximum rate.
When congestion occurs, bandwidth is shared fairly by transferring at an even rate. This option
requires maximum (target) and minimum transfer rates (-l and -m).
low – Adjust the transfer rate to use the available bandwidth up to the maximum rate. Similar
to fair mode, but less aggressive when sharing bandwidth with other network traffic. When
congestion occurs, the transfer rate is reduced to the minimum rate until other traffic decreases.
If --policy is not set, ascp4 uses the server-side policy setting (fair by default).
--preserve-access-time
Preserve the file timestamps (currently the same as -p).
--preserve-creation-time
Preserve the file timestamps (currently the same as -p).
--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
-q
Preserve the file timestamps (currently the same as -p).
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.
--remote-memory=bytes
Allow the remote ascp4 process to use no more than the specified memory. Default: 256 MB.
--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.
--sparse-file
Enable ascp4 to write sparse files to disk. This option prevents ascp4 from writing zero content
to disk for sparse files; ascp4 writes a block to disk if even one bit is set in that block. If no bits are
set in the block, ascp4 does not write the block (ascp4 blocks are 64 KB by default).
--src-base=prefix
| ascp4: Transferring from the Command Line with A4 | 108
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. For usage examples, see Ascp File
Manipulation Examples on page 84.
Use with URIs: The --src-base option performs a character-to-character match with the source
path. For object storage source paths, the prefix must specify the URI in the same manner as the
source paths. For example, if a source path includes an embedded passphrase, the prefix must also
include the embedded passphrase otherwise it will not match.
--symbolic-links={follow|copy|skip}
Handle symbolic links using the specified method. On Windows, the only option is skip. On other
operating systems, this option takes following values:
•
•
follow – Follow symbolic links and transfer the linked files. (Default)
copy – Copy only the alias file. If a file with the same name exists on the destination, the
symbolic link is not copied.
skip – Skip symbolic links. Do not copy the link or the file it points to.
•
-T
Disable in-transit encryption for maximum throughput.
-u user_string
Define a user string for pre- and post-processing. This string is passed to the pre- and -postprocessing scripts as the environment variable $USERSTR.
--user=username
Authenticate the transfer using the specified username. Use this option instead of specifying the
username as part of the destination path (as user@host:file).
Note: If you are authenticating on a Windows machine as a domain user, the transfer
server strips the domain from the username. For example, Administrator is
authenticated rather than DOMAIN\Administrator. For this reason, 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.
| ascp4: Transferring from the Command Line with A4 | 109
As of v3.3, datagram size can be specified on the server by setting <datagram_size> in
aspera.conf. The server setting overrides the client setting, unless the client is using a version
of ascp that is older than 3.3, in which case the client setting is used. If the pre-3.3 client does not
set -Z, the datagram size is the discovered MTU and the server logs the message "LOG Peer client
doesn't support alternative datagram size".
Built-in I/O Providers
Input/Output providers are library modules that abstract I/O scheme in ascp4 architecture. ascp4 has the following
three built-in I/O providers:
•
•
•
file (as a simple path or file://path)
UDP (as udp://233.3.3.3)
TCP (as tcp://192.168.120.11)
The default I/O scheme is file if there is no docroot and no scheme in the path. For examples of ascp4 sessions that
use UDP and TCP providers, see Ascp4 Examples on page 110.
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
UDP provider
A UDP stream can be specified for ascp4 I/O by using a URL that starts with udp. If the UDP stream is a multicast
IP address, then ascp4 connects to the multicast address. ascp4 reads the UDP datagrams on the source and writes
UDP datagrams on the destination. A UDP-provider filepath has the following format:
udp://ip_address:port[?option=value[&option=value]]
The UDP provider URL accepts the following options:
pktbatch={0|1} — Enable packet batching in read/write. Default: 1.
maxsize=N — Set the maximum stream length. Default: unlimited.
maxtime=N — Set the maximum stream duration, in seconds. Default: unlimited.
maxidle=N — Set the maximum idle duration, in seconds. Default: unlimited.
rcvbufsz=N — Set the receive buffer size. Default: 10 MB.
sndbufsz=N — Set the send buffer size. Default: 10 MB.
ifaddr=ip_address — Set the multicast interface. Default: 0.0.0.0.
srcaddr=ip_address — Set the multicast source for IGMPb3 source-specific multicast.
ttl=N — Set the multicast time-to-live. Default: 1.
loopback=N — Set the multicast loopback. Default: 1.
dontfrag=N — Prevent fragmentation of outgoing packets. Default: 0.
| ascp4: Transferring from the Command Line with A4 | 110
TCP provider
A TCP stream can be used for ascp4 I/O by specifying a URL that starts with tcp. ascp4 reads TCP data from the
source and writes TCP data on the destination. Use the following format to specify a TCP provider on the source or
destination:
tcp://ip_address:port[?option=value[&option=value]]
The TCP provider of the sender can also be specified with the following format:
tcp://:port[?option=value[&option=value]]
With this format, ascp4 listens on the specified port up to a specified time (maxidle, see the following description
of options for TCP provider URLs).
The TCP provider URL accepts the following options:
port=N — Set the network port number, default: 0.
iosize=N — Specify the read/write size, default: 32 KB.
maxsize=N — Set the maximum stream length, in bytes, no default.
maxtime=N — Set the maximum stream duration, in seconds, no default.
maxidle=N — Set the maximum idle duration, in seconds, default: 10 sec.
rcvbufsz=N — Set the receive buffer size, default: 4 MB.
sndbufsz=N — Set the send buffer size, default: 4 MB.
ifaddr=ip_address — Specify the TCP connection interface address.
srcaddr=ip_address — Specify the TCP connection source-specific address.
Ascp4 Examples
The commands for ascp4 are generally similar to those for ascp, see Ascp Command Reference on page 69 for
examples and Comparison of Ascp and Ascp4 Options on page 95 for option availability.
The following command examples demonstrate options that are unique to A4. These options enable reading
management commands, enable read/write concurrency,and transfer TCP and UDP data streams.
•
Read FASP4 management commands
Read management commands V4 from management port 5000 and execute the management commands. The
management commands version 4 are PUT, WRITE and CLOSE.
> ascp4 -L /tmp/client-logs -R /tmp/server-logs --faspmgr-io -M 5000
localhost:/tmp
•
Increase concurrency
The following command runs ascp4 with two scan threads and eight read threads on the client, and eight meta
threads and 16 write threads on the server.
> ascp4 -L /tmp/logs -R /tmp/logs -l1g --scan-threads=2 --read-threads=8
--write-threads=16 --meta-threads=8 /data/100K aspera@10.0.113.53:/data
•
Send a TCP stream
Read a TCP stream from 192.168.10.10 port 2000 and send it to 10.10.0.51. On 10.10.0.51, write the stream to
localhost port 3000.
> ascp4 -l 6000 -m 5000 --host=10.10.0.51 --mode=send --read-threads=1 -write-threads=1 tcp://192.168.10.10:2000 tcp://localhost:3000
•
Send a UDP data stream
| ascp4: Transferring from the Command Line with A4 | 111
Send a UDP stream multicasted on 233.3.3.3 port 3000 to host 192.168.0.11, then multicast the stream on
233.3.3.3 port 3001.
> ascp4 -l 6000 -m 5000 --host=192.168.0.11 --mode=send --read-threads=1
--write-threads=1
udp://233.3.3.3:3000/?pktbatch=0 udp://233.3.3.3:3001/?loopback=1
Using A4 from the GUI
Transfers intiated from the GUI use ascp and ascp4 transfers can be run only from the command line. You can
make transfers initiated from the GUI use ascp4 by following these steps.
1. Back up the ascp executable.
Locate the ascp executable.
C:\Program Files [(x86)]\Aspera\Client\bin\ascp
Rename the file ascp-version.bak.
2. In the same directory, make a copy of ascp4 and rename it ascp.
The transfer server now uses ascp4 for transfers initiated from the GUI.
Important: Not all standard ascp options are available with ascp4.
| Appendix | 112
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 Aspera Central, Aspera HTTPD, Aspera Sync, and OpenSSH Service (if installed). Use the
instructions below to change the password for the Aspera service account and to change the user account from the
default "svcAspera."
Update the Aspera Service Account Password
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 entering 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.
1. Open the Windows User Accounts management tool (Start > Control Panel > User Accounts).
2. Click the user name of the Aspera service account.
3. Click Change your password and follow the onscreen instructions.
Change the Aspera Service Account
Note: In Windows 2008 or Windows 7, you must run the script with administrator credentials or disable
UAC.
1. Open a Command Prompt window and run as administrator.
Click Start > All Programs > Accessories, right-click Command Prompt then click 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
Note: If you are running a non-English version of Windows, your admin group may 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
| Appendix | 113
Restarting Aspera Services
Aspera Central
If Aspera Central is stopped, or if you have modified the <central_server> or <database> sections in
aspera.conf, then you need to restart the service.
You can restart the Aspera Central from the Computer Management window. Go to Control Panel > Administrative
Tools > Computer Management > Services and Applications > Services, click Aspera Central, and click Restart.
Aspera NodeD
Restart Aspera NodeD if you have modified any setting in aspera.conf.
Go to Control Panel > Administrative Tools > Computer Management > Services and Applications > Services,
click 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 machine to connect to this 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 have destroyed at the destination, eliminating
the need to read from or write to disk and saving disk space.
To send random data in place of a source file, run the following command:
> ascp --mode=send --user=username --host=host_ip_address faux:///fname?fsize target_path
where 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) up to 9 EB.
To send a file but not save the results to disk at the destination, run the following command:
> ascp --mode=send --user=username --host=host_ip_address source_file1 faux://
To send random data and not save the results to disk, run the following command:
> ascp --mode=send --user=username --host=host_ip_address faux:///fname?fsize faux://
For usage examples, see Ascp General Examples on page 82. Once you start a transfer from the command line, you
can monitor it from the GUI.
1. Start a transfer with Fair transfer policy and compare the transfer rate to the target rate.
On the client machine, open the user interface and start a transfer (either from the GUI or command line). Click
Details to open the Transfer Monitor.
| Appendix | 114
To leave more network resources for other high-priority traffic, use the Fair policy and adjust the target rate and
minimum rate by sliding the arrows or entering values.
2. Test the maximum bandwidth.
Note: This test will typically occupy a majority of the network's bandwidth. Aspera recommends
performing it on a dedicated file transfer line or during a time of very low network activity.
Use Fixed policy for the maximum transfer speed. Start with a lower transfer rate and increase gradually toward
the network bandwidth.
| Appendix | 115
To improve the transfer speed, you may also upgrade the related hardware components:
Component
Description
Hard disk
The I/O throughput, the disk bus architecture (e.g. RAID, IDE, SCSI, ATA, and Fiber
Channel).
Network I/O
The interface card, the internal bus of the computer.
CPU
Overall CPU performance affects the transfer, especially when encryption is enabled.
aclean Reference
The Aspera aclean command-line tool is a fast method of deleting directories and files from local and object
storage. Directories and files can be filtered based on their last modified times. For Windows operating systems,
the created time (CTIME) and modified time (MTIME) are used as the matching criteria. You can do a dry run of an
aclean command to test what content will be deleted. aclean can be run on any machine on which Aspera A4 is
supported.
Note: The directory specified in an aclean command is not deleted. Only the content in the directory that
matches the options is deleted.
Syntax
aclean [options] directory
Directory path format
•
•
Local paths: Paths to local storage can be full or relative paths, and use "/" separators for all operating systems,
including Windows. Full Windows paths must use the format /c:/path/to/delete.
Object storage: Specify a path to object storage with its URI. For example, Azure storage has the syntax
azu://storage_account:storage_access_key@blob.core.windows.net/path_to_blob
and a URL to AWS S3 ahs the syntax
s3://access_id:secret_key@s3.amazonaws.com/my_bucket/path. For more information on
URL syntax for other object storage types, see Ascp Transfers with Object Storage and HDFS on page 85. The
| Appendix | 116
variable components of the URI must be URL encoded. For instructions on URL encoding, see Aspera Enterprise
Server Admin Guide (Linux): URL Encoding.
Options
Option (short version, long
version)
Description
-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/
Delete files that have a last-modified time older than March 27, 2017 13:34 from Azure object storage:
$ aclean --remove-older-than=2017-03-27 13:34
azu://user:key@blob.microsoft.com
Log Files
The log file includes detailed transfer information and can be useful for review and support requests.
To view the application log, go to Tools > View Log.
| Appendix | 117
To review logs of other components, click Open Logs Folder to open the folder that contains transfer logs:
C:\Program Files [(x86)]\Aspera\Client\var\log
The following files are available in the log folder. Older logs are stored with the same filename, appended with
incremental numbers (e.g. 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 Folder events
async.log
Sync events
To set the logging level for transfers, open the My Preferences dialog by clicking Tools > Preferences or by clicking
Preferences in the upper-right corner of the application window.
The five logging levels to select from are: Off, Error, Warn, Info, and Debug. The system default is Info.
| Appendix | 118
Accessing Shares from the GUI
As of Shares version 1.9.3, the client must have version 3.6.0 or later of Enterprise Server, Point-to-Point Client, or
Desktop Client installed in order to access Shares on a server with version 3.6.0 or later of Enterprise Server, Point-toPoint Client, or Desktop Client installed.
Note: As of version 3.6.0, you can connect to Shares through the GUI, but command-line connection to
Shares is not supported. To connect to Shares through the command line, you must download the Aspera CLI
from the following location:
http://downloads.asperasoft.com/en/downloads/62
1.
To access Shares from the GUI, go to Connections and click the
Enter the following information:
button.
Field
Value
Example
Host
https://host_FQDN
https://shares.asperasoft.com/
User
Shares username (of user with API
Login enabled)
shares_user
Authentication
Shares user password
X45ape34_1
2. Click Test Connection to confirm your client application has successfully connected to Shares.
| Appendix | 119
3. Click Browse to specify the target directory.
4. Click OK to save the connection.
Product Limitations
Describes any limitations that currently exist for Aspera transfer server and client products.
•
•
Path Limit: The maximum number of characters that can be included in any pathname is 512 characters.
Usernames with "@" symbol: You cannot add a username with an "@" symbol through the Aspera GUI. You
can, however, perform the following actions: (1) Set up a Hot Folder to sync with a Linux server using a Linux
account containing the "@" symbol; and (2) Connect to and start a transfer with a Linux server through the Aspera
GUI with user credentials containing the "@" symbol.
| Technical Support | 120
Technical Support
Support Websites
For an overview of IBM Aspera Support services, go to http://asperasoft.com/company/support/.
To view product announcements, webinars, and knowledgebase articles, as well as access the Aspera Support
Community Forum, sign into the IBM Aspera Support site at support.asperasoft.com using your email address (not
your company Aspera credentials), or set up a new account. You can click on a heading then click Follow to receive
notifications when new knowledgebase articles are available; if you follow RELEASE NOTES under a specific
product, you will be automatically notified of new releases.
Personalized Support
You may contact an Aspera support technician 24 hours a day, 7 days a week, through the following methods, with a
guaranteed 4-hour response time.
If you have an emergency, create a ticket using the Support Request Form with as many details as you have
available and then call. If you are asked to leave a voice message, include the ticket number.
Email
support@asperasoft.com
Phone (North America)
+1 (510) 849-2386, option 2
Phone (Europe)
+44 (0) 207-993-6653 option 2
Phone (Singapore)
+81 (0) 3-4578-9357 option 2
Support Request Form
https://support.asperasoft.com/anonymous_requests/new/
| Legal Notice | 121
Legal Notice
© 2005-2017
Aspera, Inc., an IBM Company. All rights reserved.
Licensed Materials - Property of IBM
5725-S57
© Copyright IBM Corp. 2017. Used under license.
US Government Users Restricted Rights - Use, duplication or disclosure restricted by GSA ADP Schedule Contract
with IBM Corp.
Aspera, the Aspera logo, and FASP transfer technology are trademarks of Aspera, Inc., registered in the United
States. Aspera Connect Server, Aspera Drive, Aspera Enterprise Server, Aspera Point-to-Point, Aspera Client, Aspera
Connect, Aspera Cargo, Aspera Console, Aspera Orchestrator, Aspera Crypt, Aspera Shares, the Aspera Add-in for
Microsoft Outlook, Aspera FASPStream and Aspera Faspex are trademarks of Aspera, Inc. All other trademarks
mentioned in this document are the property of their respective owners. Mention of third-party products in this
document is for informational purposes only. All understandings, agreements, or warranties, if any, take place directly
between the vendors and the prospective users.