IBM Aspera Enterprise Server 3.5.

Windows 7, 8, 2008r2, 2012

Revision: 3.5.6.109849 Generated: 08/01/2015 13:02
 | Contents | 2

Contents

Introduction............................................................................................................... 5

Standard Installation................................................................................................6
Requirements.........................................................................................................................................................6
Before Upgrading..................................................................................................................................................6
Product Setup........................................................................................................................................................ 9
Configuring the Firewall.................................................................................................................................... 13
Securing your SSH Server................................................................................................................................. 14
Testing a Locally Initiated Transfer................................................................................................................... 18
Updating the Product License............................................................................................................................ 20
Uninstall.............................................................................................................................................................. 21

Transferring Files with the Application............................................................... 23

Application Overview......................................................................................................................................... 23
Managing Connections....................................................................................................................................... 24
Creating SSH Keys.............................................................................................................................................30
Enabling a Transfer or HTTP Proxy..................................................................................................................33
Transferring Files................................................................................................................................................ 37
Advanced Transfer Mode................................................................................................................................... 40
Configuring Transfer Notifications.................................................................................................................... 42
Using Transfer Notifications.............................................................................................................................. 49
Reporting Checksums......................................................................................................................................... 51

Managing Users.......................................................................................................55
Setting Up Users.................................................................................................................................................55
Test User-Initiated Remote Transfer.................................................................................................................. 56
Setting Up Groups.............................................................................................................................................. 57
Configuration Precedence................................................................................................................................... 58
Setting Up a User's Public Key......................................................................................................................... 59

General Configuration Reference......................................................................... 61

Document Root................................................................................................................................................... 61
Configuring Symbolic Links.............................................................................................................................. 62
Advanced Symbolic Link Options (ascp).............................................................................................. 62
Server-Side Symbolic Link Handling.................................................................................................... 63
Authorization.......................................................................................................................................................64
Bandwidth........................................................................................................................................................... 66
Network............................................................................................................................................................... 70
File Handling...................................................................................................................................................... 72

Global Transfer Settings........................................................................................ 76

Global Bandwidth Settings.................................................................................................................................76
Setting Up Virtual Links.................................................................................................................................... 77
Transfer Server Configuration............................................................................................................................ 79
 | Contents | 3

Configuring for Other Aspera Products.............................................................. 81

Configuring for Faspex.......................................................................................................................................81
Configuring for Shares....................................................................................................................................... 85
Configuring for Aspera for SharePoint..............................................................................................................88

Managing the Node API........................................................................................ 95

Overview: Aspera Node API..............................................................................................................................95
Node API Setup..................................................................................................................................................95
Setting up Node Users........................................................................................................................................96
Node Admin Tool............................................................................................................................................... 97
aspera.conf for Nodes......................................................................................................................................... 97
Redis DB Backup/Restore................................................................................................................................ 101
Setting up SSL for your Nodes........................................................................................................................101

Hot Folders............................................................................................................ 105

Setting Up Hot Folders.....................................................................................................................................105
Managing Hot Folders...................................................................................................................................... 108

Pre- and Post-Processing (Prepost).....................................................................110

Setting Up Pre/Post...........................................................................................................................................110
Pre/Post Variables............................................................................................................................................. 111
Pre/Post Examples............................................................................................................................................ 113
Setting Up Email Notification..........................................................................................................................114
Email Notification Examples............................................................................................................................117

Transferring from the Command Line.............................................................. 119

Ascp Command Reference............................................................................................................................... 119
Ascp General Examples....................................................................................................................................128
Ascp File Manipulation Examples................................................................................................................... 129
Ascp Transfers to Cloud Storage..................................................................................................................... 130
Token Generation..............................................................................................................................................132
Creating SSH Keys (Command Line)............................................................................................................133
Ascp FAQs........................................................................................................................................................ 134

Configuring for the Cloud................................................................................... 137

Configuring aspera.conf for S3........................................................................................................................ 137

Appendix................................................................................................................ 139
Updating the Aspera Service Account............................................................................................................. 139
Restarting Aspera Services...............................................................................................................................139
Optimizing Transfer Performance.................................................................................................................... 140
Setting Policies for OpenSSH User................................................................................................................. 141
Log Files........................................................................................................................................................... 142
Setting Up Token Authorization.......................................................................................................................143
Configuring Token Authorization from the GUI............................................................................................. 144
Configuring Token Authorization With aspera.conf........................................................................................ 145
Product Limitations...........................................................................................................................................146
 | Contents | 4

Troubleshooting..................................................................................................... 147
Using the Troubleshooter................................................................................................................................. 147
Error Adding Domain User.............................................................................................................................. 147
Clients Can't Establish Connection.................................................................................................................. 148
Uninstall Version 2.2.1 for Upgrade................................................................................................................ 150

Technical Support................................................................................................. 152

Feedback................................................................................................................ 153

Legal Notice........................................................................................................... 154

 | Introduction | 5

Introduction
IBM Aspera Enterprise Server is an universal file transfer server built upon Aspera's FASP transport. Enterprise
Server offers the following features:

Feature Description
FASP transport technology File transfer protocol that dramatically speeds transfers over IP networks by
eliminating the fundamental bottlenecks in conventional technologies. FASP features
bandwidth control, resume, transfer encryption, content protection, and data integrity
validation.
Transfer server Allows an unlimited number of concurrent client transfers. Uses virtual links to
manage aggregate bandwidth usage.
Enterprise Server A graphical file transfer application for initiating and managing transfers, and for
application configuring transfer users and server settings.
Hot Folders (Aspera Sync) A service, managed by the desktop application, that automates the transferring of files
from a specified directory.
Database Logger A MySQL adapter that logs the server's transfer activity to a database.
Pre- and Post-Processing Executes customizable actions when transfer events - start and end of sessions and
(Prepost) files - occur. An email notification script is included.
ascp command The command-line file transfer program.
 | Standard Installation | 6

Standard Installation
Install the IBM Aspera transfer product and set up your computer for FASP file transfers.

Requirements
Software and hardware requirements for optimal product functionality
System requirements for IBM Aspera Enterprise Server:
• Product-specific Aspera license file.
• For usage in an Active Directory environment - Access to a domain administrator account for product installation.
• Access to run WMI.
• For Database Logging - A MySQL Database.
• For Pre- and Post-Processing (Prepost) - Install Active Perl to enable Perl scripts.
• Screen resolution 1024 x 768 or higher.
If you plan to set up and use the Node API, you must also meet the following requirements on each node machine:
• In order to use this application on a cloud platform and access the object-based cloud storage, you must obtain an
on-demand license. Please contact Technical Support.
• Identify a directory that you plan to use for sharing data. Later on (in the topic Node API Setup), we will use this
directory as the absolute path for the transfer user.
• Verify that the machine's hosts file has an entry for "127.0.0.1 localhost." For UNIX-based nodes, check
/etc/hosts. For Windows nodes, check C:\WINDOWS\system32\drivers\etc\hosts.
• For UNIX-based nodes, verify that SELINUX is disabled via cat /etc/sysconfig/selinux. SELINUX
can be "permissive" or "disabled," but not "enforced."

Before Upgrading
Steps to take before upgrading your IBM Aspera product.
The installer for IBM Aspera Enterprise Server automatically checks for a previous version of the product on your
system. If a previous version is found, the installer automatically removes it and upgrades your computer to the newer
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, we highly recommend completing the tasks below before
starting the installation/upgrade process. If you do not follow these steps, you risk installation errors or losing your
former configuration settings. Skip any steps that do not apply to your specific product version.
Note: 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
 | Standard Installation | 7

configuration, uninstall the product, and perform a fresh install of the new version of the product. If you are
upgrading your Enterprise Server to Connect Server, see the appendix in the Connect Server documentation
located at http://asperasoft.com/en/documentation/4..

1. All Versions - Verify the version of your existing product

Depending on your current product version, the upgrade preparation procedure may differ. In the Windows
Command Prompt ( Start menu > All Programs > Accessories > Command Prompt ), execute this command:

> ascp -A

This displays the product name and version number.

Warning:
When upgrading from 2.7.X to 3.X on Windows, please be aware that user names are now case sensitive.
2. All Versions - Confirm your Aspera service account.
If you have already installed IBM Aspera Enterprise Server, Connect Server, Point-to-Point Client or Desktop
Client on your computer, there is already a user account that has been designated to run the services for Aspera
products. By default, the user name for the Aspera services account is svcAspera; however, this is not a
requirement and you can select a different user to run the services. When you install additional Aspera products
or perform an upgrade to an existing Aspera product, you must identify the same account name and password that
you set for your first Aspera product installation.

To confirm which user is designated as your Aspera service account in Windows 2003, Vista, and 7, right-click on
My Computer and select Manage > Services and Applications > Services. In Windows 2008, go to the Server
Manager and select Configuration > Services. The account designated for each Aspera service is listed. Please
make note of this account for the installation of additional Aspera products or product upgrades. If you have
forgotten your Aspera service account password or would like to change the designated Aspera service account,
please follow the instructions described in Updating the Aspera Service Account on page 139.
3. All versions - Stop all FASP transfer-related applications and connections.
Before upgrading the application, close the following applications and services:
• ascp connections
• SSH connections
• The SSHD service and any SSHD processes. To stop the SSHD service, go to the Computer Management
window, which is accessible via Manage > Services and Applications > Services. Then, kill any SSHD
processes (using the Windows Task Manager).
• The Enterprise Server application
• asperasync service
4. All versions - Back up the files
Depending on the version of your previous installation and the operating system, back up the files in the specified
locations:

Aspera Version Folder

2.5+ Note: If you have installed the product in a different location, change the path
accordingly.

32-bit Windows Default Path:

• C:\Program Files\Aspera\Enterprise Server\etc\ (Configuration
files, Shared Remote Hosts)
• C:\Program Files\Aspera\Enterprise Server\var\(Prepost scripts,
Connect Server)
 | Standard Installation | 8

Aspera Version Folder

64-bit Windows Default Path:
• C:\Program Files (x86)\Aspera\Enterprise Server\etc
\(Configuration files, Shared Remote Hosts)
• C:\Program Files (x86)\Aspera\Enterprise Server\var\(Prepost
scripts, Connect Server)
Individual User Files' Default Path:
• <APPDATA>\Aspera\Enterprise Server\ (Individual user's remote hosts
and hot folder info.)

Note: Use this command in a Command Prompt window to find out the current
user's <APPDATA> path:

> echo %APPDATA%

2.2.x and earlier 32-bit Windows:

• C:\Program Files\Aspera\FASP\etc\ (Configuration files)
• C:\Program Files\Aspera\FASP\var\(Prepost scripts, Connect Server)
• C:\Program Files\Aspera\Aspera Scp\etc\(Remote Hosts an Hot
Folders info)
64-bit Windows:
• C:\Program Files (x86)\Aspera\FASP\etc\ (Configuration files)
• C:\Program Files (x86)\Aspera\FASP\var\(Prepost scripts, Connect
Server)
• C:\Program Files (x86)\Aspera\Aspera Scp\etc\ (Remote Hosts
and Hot Folders info)

5. Version 2.2.x and earlier - Restore the saved "Remote Endpoints"

This is a post-install step.
Since 2.5, a connection (a.k.a. "endpoint") can either be shared with all users, as in previous versions, or kept
exclusive to the user who created it.
When you upgrade a product 2.2.x or earlier, on the first launch of the application, existing connections will be
imported only for that user. Aspera recommends you launch it as an administrator account after the upgrade, so
that you can import the connections and share them with other users.
Note:
When you have finished the upgrade procedure, to share the imported connections with other users, launch
the application and go to Connections. Select a created connection and navigate into the Connection tab.
Check Share this connection with all users on this computer for each connection to share. Refer to
Managing Connections on page 24 for more information.
 | Standard Installation | 9

Product Setup
A walkthrough of the setup process.
Important: If this is a product upgrade, ensure that you have reviewed all prerequisites detailed under the
topic "Before Upgrading."
1. Download the IBM Aspera product installer
Download the installer from the link below. Use the credentials provided to your organization by Aspera to access:
http://asperasoft.com/en/downloads/4
If you need help determining your firm's access credentials, contact Technical Support on page 152.
2. For product upgrades, ensure you have prepared your machine to upgrade to a newer version.
Although the installer for Aspera Enterprise Server performs your upgrade automatically, Aspera highly
recommends completing the tasks identified in the topic Before Upgrading. If you do not follow these steps, you
risk installation errors or losing your former configuration settings.
Warning: When upgrading from 2.7.X to 3.X on Windows, please be aware that user names for 3.X are
case sensitive.
3. Open the installation package and select the setup type
After downloading, open the installation package and follow the on-screen instructions.
Important: On Windows Vista, Windows 7, or Windows 2008 with UAC (User Account Control)
enabled, you must run the installer as an Administrator. To do so, right-click the installation package and
select the option Run as administrator. You may be asked to enter the administrator's password to allow
the installer to make changes to your computer.
After the license agreement screen, click the desired setup type. If you are upgrading from a previous version, the
installer will skip this step.
The following setup options are available:

Setup Type Description

Typical Install the standard Enterprise Server, including an SSH Server (OpenSSH).
 | Standard Installation | 10

Setup Type Description

Custom Select the features and the path to install.
Complete Install all features, including an SSH Server (OpenSSH) and the Connect Server
Web UI (for Connect Server, a web-based transfer server). Note that the Connect
Server Web UI cannot be used unless you have a Connect Server license. To
upgrade Enterprise Server to Connect Server, contact Technical Support on page
152 to obtain the license.

Note: If your system has an existing SSH service installed (such as Cygwin), select the Custom setup
type and deselect SSH Server to avoid conflicts. For assistance, contact Technical Support on page
152.
4. Select features and install path (Custom setup type)
If you selected the custom setup type, you will see the two additional steps during installation, as follows:
Check the features to install. If you wish to configure your own SSH Server for FASP transfers, deselect the SSH
Server (so that the OpenSSH Service is not installed). Check the Connect Server Web UI only if you have a
Connect Server license .

Select the destination folder for the installation. Under Install this application for:, choose between 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.
 | Standard Installation | 11

5. Set up Aspera service account

On Windows Vista, 2003, 2008, and 7, the installer prompts you to create or update an Aspera service account that
runs the services for Aspera products. These services include the following:
• Aspera Central
• OpenSSH Service (optional)
• Aspera NodeD
• Aspera Sync
By default, the user name is svcAspera. If your machine is not joined to a Windows domain, then a local user
(such as the default svcAspera) is all that is required to run Aspera services. If your machine is already joined
to a domain, or you need to support requirements #2 and/or #3 below, then the type of account specified will vary.
Please refer to the following table:

No. Requirement Type of Service Account User

1 Provision local transfer users Local account. Domain account with local admin privileges can be
only. used, but is not required.
2 Provision Active Directory Domain account with local admin privileges.
accounts for transfer users (users
who wish to transfer with your
server are authenticated through
Active Directory).
3 Transfer users store files on a Domain account with local admin privileges. In some cases,
remote file system (not on your additional actions are required to support this requirement. Please
server machine), such as an SMB see the aspera knowledgebase or contact Aspera Technical Support
file share. for assistance.

If the server is configured to accept the 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 on your Domain Controller first.
If the local account does not already exist, enter new credentials and click Next. If the account already exists
(for example, if 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, refer to Updating the
Aspera Service Account on page 139.
 | Standard Installation | 12

If you are entering details for a domain account, then the user name must be in the form
"[email protected]." Please refer to the example below.

6. Install the license

When installation is finished, launch the application to add or update the license. Go to:
Start Menu > All Programs > Aspera > Enterprise Server > Enterprise Server
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. When finished, the license information
appears in the window. Verify that it is correct and click Close.
If you are updating your product license after the installation, see Updating the Product License on page 20.
7. (For upgrades) Check aspera.conf for errors
When upgrading your Aspera product to a newer version, it is recommended that you check the aspera.conf
configuration file for errors. Run the following command in a Command window to validate aspera.conf:
 | Standard Installation | 13

Platform Command
32-bit Windows "C:\Program Files\Aspera\Enterprise Server\bin
\asuserdata" -v
64-bit Windows "C:\Program Files (x86)\Aspera\Enterprise Server\bin
\asuserdata" -v
8. Troubleshooting

Problem Description
Installer freezes You may have another Aspera product running on your computer. To stop all FASP
transfer-related applications and connections, see Before Upgrading on page 6.
"Error 1721" If you are upgrading to the latest version and see "Error 1721" regarding the
installer package, the installer may be having difficulty removing the previous
installation (2.2.1). For details, see Uninstall Version 2.2.1 for Upgrade on page
150.

Configuring the Firewall

Firewall settings required by the product.
Your Aspera transfer product requires access through the ports listed in the table below. If you cannot establish the
connection, review your local corporate firewall settings and remove the port restrictions accordingly.

Product Firewall Configuration

Enterprise Server An Aspera server runs one SSH server on a configurable TCP port (33001 by default).
Important: Aspera strongly recommends running the SSH server on a non-default
port to ensure that your server remains secure from SSH port scan attacks. Please
refer to the topic Securing your SSH Server on page 14 for detailed instructions
on changing your SSH port.
Your firewall should be configured as follows:
• Allow inbound connections for SSH, which is on TCP/33001 by default, or on another
non-default, configurable TCP port. If you have a legacy customer base utilizing
TCP/22, then you can allow inbound connections on both ports. Please refer to the topic
Securing your SSH Server on page 14 for details.
• Allow inbound connections for FASP transfers, which use UDP/33001 by default,
although the server may also choose to run FASP transfers on another port.
• If you have a local firewall on your server (like Windows Firewall), verify that it is
not blocking your SSH and FASP transfer ports (e.g. TCP/UDP 33001).
The firewall on the server side must allow the open TCP port to reach the Aspera server.
Note that no servers are listening on UDP ports. When a transfer is initiated by an Aspera
client, the client opens an SSH session to the SSH server on the designated TCP port and
negotiates the UDP port over which the data transfer will occur.
For Aspera servers that have multiple concurrent clients, the Windows operating system does
not allow the Aspera FASP protocol to reuse the same UDP port for multiple connections.
Thus, if you have multiple concurrent clients and your Aspera server runs on Windows,
then you must allow inbound connections on a range of UDP ports, where the range of
ports is equal to the maximum number of concurrent FASP transfers expected. These UDP
ports should be opened incrementally from the base port, which is UDP/33001, by default.
 | Standard Installation | 14

Product Firewall Configuration

For example, to allow 10 concurrent FASP transfers, allow inbound traffic from
UDP/33001 to UDP/33010.

Client Typically, consumer and business firewalls allow direct outbound connections from client
computers on TCP and UDP. There is no configuration required for Aspera transfers in this
case. In the special case of firewalls disallowing direct outbound connections, typically
using proxy servers for Web browsing, the following configuration applies:
• 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).
• Allow outbound connections from the Aspera client on the FASP UDP port (33001, by
default).
• If you have a local firewall on your server (like Windows Firewall), verify that it is
not blocking your SSH and FASP transfer ports (e.g. TCP/UDP 33001).
Important: Multiple concurrent clients cannot connect to a Windows Aspera
server on the same UDP port. Similarly, multiple concurrent clients that are
utilizing two or more user accounts cannot connect to a Mac OS X or FreeBSD
Aspera server on the same UDP port. If connecting to these servers, you will need
to allow a range of outbound connections from the Aspera client (that have been
opened incrementally on the server side, starting at UDP/33001). For example, you
may need to allow outbound connections on UDP/33001 through UDP/33010 if 10
concurrent connections are allowed by the server.

Important: If you have a local firewall on your server (Windows firewall, Linux iptables or Mac ipfw), then
you will need to allow the Vlink UDP port (55001, by default) for multicast traffic. For additional information
on setting up Vlinks, please refer to the topic Setting Up Virtual Links on page 77.

Securing your SSH Server

Secure your SSH server to prevent potential security risks.
Introduction
Keeping your data secure is critically important. Aspera strongly recommends you take additional steps in setting up
and configuring your SSH server so that it is protected against common attacks. Most automated robots will try to
log into your SSH server on Port 22 as Administrator, with various brute force and dictionary combinations in order
to gain access to your data. Furthermore, automated robots can put enormous loads on your server as they perform
thousands of retries to break into your system. This topic addresses steps to take in securing your SSH server against
potential threats, including changing the default port for SSH connections from TCP/22 to TCP/33001.
Why Change to TCP/33001?
It is well known that SSH servers listen for incoming connections on TCP Port 22. As such, Port 22 is subject to
countless, unauthorized login attempts by hackers who are attempting to access unsecured servers. A highly effective
deterrent is to simply turn off Port 22 and run the service on a seemingly random port above 1024 (and up to 65535).
To standardize the port for use in Aspera transfers, we recommend using TCP/33001.
Note that your Aspera transfer product ships with OpenSSH listening on both TCP/22 and TCP/33001. As such,
Aspera recommends only exposing TCP/33001 through your organization's firewall and disabling TCP/22.
Note: Remote Aspera application connections attempt to establish an SSH connection using the default port
33001. However, if the connection fails, the application attempts the connection using port 22.
The following explains how to change the SSH port to 33001 and take additional steps for securing your SSH server.
The steps all require Administrator access privileges.
 | Standard Installation | 15

1. Locate and open your system's SSH configuration file

Open your SSH configuration file with a text editor. You will find this file in the following system location:

C:\Program Files[ (x86)]\Aspera\Enterprise Server\etc\sshd_config

2. Add new SSH port

Note: Before changing the default port for SSH connections, verify with your network administrators that
TCP/33001 is open.
The OpenSSH suite included in the installer uses TCP/22 and TCP/33001 as the default ports for SSH
connections. Aspera recommends disabling TCP/22 to prevent security breaches of your SSH server.
Once your client users have been notified of the port change (from TCP/22 to TCP/33001), you can disable
Port 22 in your sshd_config file. To disable TCP/22 and use only TCP/33001, comment out Port 22 in your
sshd_config file.

...
#Port 22
Port 33001
...

Note: Aspera recognizes that disabling the default SSH connection port (TCP/22) may affect your client
users. When you change the port, ensure that you advise your users on configuring the new port number.
Basic instructions for specifying the SSH port for FASP file transfers can be found below. To change
the SSH port for Aspera Client, click Connections on the main window, and select the entry for your
computer. Under the Connection tab, click Show Advanced Settings and enter the SSH port number in
the SSH Port (TCP) field.

To make an impromptu connection to TCP/33001 during an ascp session, specify the SSH port (33001) with the -
P (capital P) flag. Note that this command does not alter ascp or your SSH server's configuration.

> ascp -P 33001 ...

3. Disable non-admin SSH tunneling

 | Standard Installation | 16

Note: The instructions below assume that OpenSSH 4.4 or newer is installed on your system. For
OpenSSH 4.4 and newer versions, the "Match" directive allows some configuration options to be
selectively overridden if specific criteria (based on user, group, hostname and/or address) are met. If you
are running an OpenSSH version older than 4.4, the Match directive is not available; Aspera recommends
updating to the latest version.
In OpenSSH versions 4.4 and newer, disable SSH tunneling to avoid potential attacks; thereby only allowing
tunneling from Administrator group users. To disable non-admin SSH tunneling, open your SSH Server
configuration file, sshd_config, with a text editor.
Add the following lines to the end of the file (or modify them if they already exist):

...
AllowTcpForwarding no
MatchGroupAdministrators
AllowTcpForwarding yes

Depending on your sshd_config file, you may have additional instances of AllowTCPForwarding that are set
to the default Yes. Review your sshd_config file for other instances and disable as appropriate.
4. Update authentication methods
Public key authentication can prevent brute-force SSH attacks if all password-based authentication methods are
disabled. For this reason, Aspera recommends disabling password authentication in the sshd_config file and
enabling private/public key authentication. To do so, add or uncomment PubkeyAuthentication yes and
comment out PasswordAuthentication yes.

...
PubkeyAuthentication yes
#PasswordAuthentication yes
PasswordAuthentication no
...

Note: If you choose leave password authentication enabled, be sure PermitEmptyPasswords is set
to "no".

PermitEmptyPasswords no

5. Restart the SSH server to apply new settings

When you have finished updating your SSH server configuration, you must restart the server to apply your new
settings. Restarting your SSH server will not impact currently connected users. To restart your SSH Server, go to
Control Panel > Administrative Tools > Services. Locate the OpenSSH Service and click Restart.
6. Restrict user access
Restricting user access is a critical component of securing your server. When a user's docroot is empty (i.e.
blank), that user has full access to your server's directories and files. To restrict the user, you must set a non-
empty docroot, which automatically changes the user's shell to aspshell (Aspera shell). You can do so from the
product GUI by going to Configuration > Users > Docroot > Absolute Path. Input a path in the blank field and
ensure that Override is checked.
 | Standard Installation | 17

Once you have set the user's docroot, you can further restrict access by disabling read, write and/or browse. You
may do so via the product GUI (as shown in the screenshot above).

Field Description Values

Absolute Path The area of the file system (i.e. path) that is accessible to the Aspera user. Path or blank
The default empty value gives a user access to the entire file system.
Read Allowed Setting this to true allows users to transfer from the designated area of • true
the file system as specified by the Absolute Path value. • false

Write Allowed Setting this to true allows users to transfer to the designated area of the • true
file system as specified by the Absolute Path value. • false

Browse Allowed Setting this to true allows users to browse the directory. • true
• false

7. Review your logs periodically for attacks

Aspera recommends reviewing your SSH log periodically for signs of a potential attack. Launch Control Panel >
Administrative Tools > Event Viewer. To see only SSH Server events, select View > Filter... to bring up the
filter settings. In Application Properties > Filter tab, select sshd in the Event source menu to display only SSH
Server events. You may also apply other conditions when needed.
 | Standard Installation | 18

With a filter applied, you can review the logs in the Event Viewer main window, or select Action > Save Log File
As... to export a log file using .txt or .csv format.
Look for invalid users in the log, especially a series of login attempts with common user names from the same
address, usually in alphabetical order. For example:

...
Mar 10 18:48:02 sku sshd[1496]: Failed password for invalid user alex
from 1.2.3.4 port 1585 ssh2
...
Mar 14 23:25:52 sku sshd[1496]: Failed password for invalid user alice
from 1.2.3.4 port 1585 ssh2
...

If you have identified attacks:

• Double-check the SSH security settings in this topic.
• Report attacker to your ISP's abuse email (e.g. abuse@your-isp).

Testing a Locally Initiated Transfer

Test client functionality by transferring to and from the Aspera Demo Server.
To make sure the software is working properly, follow these steps to test download and upload transfers between your
system and the Aspera Demo Server:
1. Add the Demo Server in the Connection Manager
Launch the application: Start menu > All Programs > Aspera > Enterprise Server > Enterprise Server .
Then click Connections.
 | Standard Installation | 19

Note:
This topic shows a very basic configuration to establish a connection. For more detailed instructions about
Connections, refer to Managing Connections on page 24.
In the Connection Manager, click to add a new connection, and enter the following info, leave other options
with default values or blank:

Field Value
Host demo.asperasoft.com
User aspera
Authentication (Password) demoaspera

2. Test your connection to the remote server

Click Test Connection to determine whether you can reach the remote server with the settings you configured. An
alert box opens and reports whether the connection is successful.
3. Connect to the Demo Server and download test files
From the main window, select the demo server entry and click the Connect button.
 | Standard Installation | 20

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

4. Upload to the Demo Server
When downloaded, try uploading the same files back to the Demo Server. Select the same file (100MB) on the
local file browser (left panel), navigate to the folder /Upload on the server, and click to upload it.

Updating the Product License

Update your product license.
To update the license key, launch the application ( Start Menu > All Programs > Aspera > Enterprise Server >
Enterprise Server ) and go to Menu bar > Tools > License to bring up the License window.
To update your license from the GUI, open Tools > License.
 | Standard Installation | 21

You may click the Import License File... and select the license file, or Paste License Text... to copy-and-paste the
license file's content. When finished, the license information will appear in the window. Verify that it is correct and
click Close.

Lastly, if you are using the Node API, you must reload the asperanoded service.

> asnodeadmin.exe --reload

Uninstall
How to uninstall the Aspera product from your computer.
The un-install can be done in Control Panel, depending on the version of your Windows, choose Add/Remove
Programs or Uninstall a program. Prior to removing the application, close the following applications and services:
• ascp connections
 | Standard Installation | 22

• SSH connections
• User interface
• asperasync Services
 | Transferring Files with the Application | 23

Transferring Files with the Application

Using the desktop application to transfer files.

Application Overview
Desktop application overview.
To launch the application, go to Start menu > All Programs > Aspera > Enterprise Server > Enterprise Server .
Note: The Configuration button shown in the screenshots below is only enabled when the application is run
as an Administrator.

Item Description
A The transfer mode. Reveal the local/remote file browsers.
B The transfer details mode. Show the selected transfer session's details and the transfer control
options.
C Bring up the Connection Manager window to manage the remote endpoints.
D Bring up the Server Configuration window to configure the computer's FASP transfer settings.
E 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.
F Browse the local file system to find files to transfer.
G When not connected, this panel shows connections that lists the saved connections. When
connected, it becomes the remote file browser.
H Display previous, ongoing, and queued transfers. Manage the priority.
I Display all configured Hot Folders. Start or manage Hot Folders.

All options in the File Browser, including the file browser's contextual menu (Mouse right-click):
 | Transferring Files with the Application | 24

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

Managing Connections
Add and manage the remote FASP servers.
To connect to a remote computer or to a server in the cloud, you need to add it to the Connection Manager before
establishing the connection. If you are planning to perform transfers with an S3 bucket, you must meet the following
prerequisites:
• You (username) have permissions to access the S3 bucket.
• You know your username's S3 Access ID and Secret Key.
• To transfer files from and/or to an S3 storage device using an S3-direct connection, you cannot have a docroot. A
local docroot will result in a failed transfer. Be sure to confirm your docroot settings before attempting a transfer.
Start the application: Start menu > All Programs > Aspera > Enterprise Server > Enterprise Server . In the main
window, click Connections to open the Connection Manager.
 | Transferring Files with the Application | 25

In the Connection Manager, click to create a new connection. You can also use to duplicate a selected connection
(i.e. copy all information into a new profile) and to delete a connection profile.
To name or rename a connection, click the orange connection profile name that appears at the top of the screen. The
Rename Connection dialog appears. 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:

 | Transferring Files with the Application | 26

Tab Description
Connection The basic host information, such as the address, login credentials, and connection ports.
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 source files.

The following tables detail all options in these tabs:

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 either password or public key for authentication. To use the key-based
authentication, see Creating SSH Keys on page 30.
Storage Type Use this drop-down menu to configure storage in the cloud. Note that the default option is
local storage.

Storage types include the following:

• Akamai NetStorage
• Amazon S3: Once selected, you will be required to input your Access Id / Secret
Access Key and identify a bucket. Note that 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
• Windows Azure
• Windows Azure SAS

Note: You can only choose special storage if you have full access to that storage on
the cloud-based machine.

Target Directory The default directory when connecting to this computer. When leaving it blank, browsing
the remote host brings up either the user account's document root (docroot), or the last-
 | Transferring Files with the Application | 27

Option Description
visited folder; when specifying a path, connecting to the host always brings up the exact
directory. The default directory is shown in the Connections panel.
Share this Check this box to share this connection with other users on your computer. When a
connection ... connection is authenticated through Public Key, the SSH keys used by this connection
should be shared as well. Refer to Creating SSH Keys on page 30.
Advanced Settings > The TCP network port. Default: 33001. Note that if connecting on 33001 fails, the
SSH Port (TCP) application attempts to establish a connection on port 22. If the connection on 22 succeeds,
the setting is updated to 22.
Advanced Settings > The UDP network port: Default: 33001.
fasp Port (UDP)
Advanced Settings > Time out the connection attempt after the selected time.
Connection Timeout
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 Choose between the following option: Automatically generate allows the user interface to
generate the transfer name; Automatically generate and add prefix uses auto-generated
name with prefix; Specify uses the user-specified name.
Policy Select the FASP transfer policy.
• fixed – Attempts to transfer at the specified target rate, regardless of the actual
network capacity. This policy transfers at a constant rate and finishes in a guaranteed
time. This policy typically occupies most of the network's bandwidth, and is not
recommended in most file transfer scenarios. In fixed mode, a maximum (target) rate
value is required.
• high – Monitors the network and adjusts the transfer rate to fully utilize the available
bandwidth up to the maximum rate. When congestion occurs, a it transfers at a rate twice
of a session with fair policy. In this mode, both the maximum (target) and the minimum
transfer rates are required.
• fair – Monitors the network and adjusts the transfer rate to fully utilize the available
bandwidth up to the maximum rate. When other types of traffic build up and congestion
occurs, it shares bandwidth fairly by transferring at an even rate. In this mode, both the
maximum (target) and the minimum transfer rates are required.
• low – Similar to fair mode, the low policy uses the available bandwidth up to the
maximum rate, but is much less aggressive when sharing bandwidth with other network
traffic. When congestion builds up, the transfer rate is reduced to the minimum rate until
other traffic retreats.

Speed Check this option 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 76.
Retry Check this option to automatically retry the transfer after a recoverable failure. When
checked, set the amount of time the transfer should be retried 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.
 | Transferring Files with the Application | 28

Option Description
• Maximum interval: After the initial interval, the next interval doubles until the
maximum interval is met, and then stops retrying after the retry time is reached. Input in
seconds, minutes or hours.

Example 1:

10s initial interval, 60s maximum interval, retry for 180s

Retry at (seconds): 10s 30s 70s 130s 180s
Interval progression (seconds): 10s 20s 40s 60s 60s 50s

Example 2:

30s initial interval, 120s maximum interval, retry for 600s

Retry at (seconds): 30s 90s 210s 330s 450s 570s 600s
Interval progression (seconds): 30s 60s 120s 120s 120s 120s
30s

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

Tracking

Option Description
Generate delivery Check the option to create the delivery receipt file in the specified location.
confirmation receipt
Send email Send out email notifications based on specified events (start, complete, and error). Refer to
notifications Using Transfer Notifications on page 49 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.

Examples:

Filter Pattern Matched files

*dirName path/to/dirName, another/dirName
*1 a/b/file1, /anotherfile1
*filename path/to/filename, /filename
 | Transferring Files with the Application | 29

Filter Pattern Matched files

path?/file? path1/fileA, pathN/file5

Security

Option Description
Encryption When checked, FASP encrypts files while transferring. Encryption may decrease
performance, especially at higher transfer speeds and with slower computers.
Content Protection Two options: Encrypt uploaded files with a password encrypts the uploaded files with
the specified password. The protected file has the extension .aspera-env appended to
the file name; Decrypt password-protected files downloaded prompts for the decryption
password when downloading encrypted files.

File Handling

Option Description
Resume Check Resume incomplete files to enable the resume feature. Under When checking files
for differences, choose from the following options:
• Compare file attributes only checks whether the existing file is the same size.
• Compare sparse file checksums performs a sparse checksum on the existing file.
• Compare full file checksums perform a full checksum on the existing file.
Under When a complete file already exists at the destination, select an overwrite rule
when the same file exists at the destination.

File Attributes • Enable the Preserve Access Time checkbox to set the access time of the destination file
to the same value as that of the source file.
• Enable the Preserve Modification Time checkbox to set the modification time of the
destination file to the same value as that of the source file.
• Enable the Preserve Source Access Time checkbox 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 Deletion Check Automatically delete source files after transfer to delete successfully transferred
files from the source. Check Delete empty source subdirectories to also remove empty
folders (except a folder specified as the source to transfer).
Source Move To move source files to a separate location after a successful transfer, check Automatically
move source files to a directory after transfer and specify the location.
Note: Only a path to an existing location on the client can be specified.
Note: The GUI has no option to delete empty source subdirectories that may remain after
source files are moved.

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.
To connect to this remote host, double-click the connection from the Connection panel, or select it and click Connect.
 | Transferring Files with the Application | 30

Importing and Exporting Connections

You may also import your connection list to and export your connection list 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:
• 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 and imported by a non-administrator will import as a regular
connection (not as shared).
• Email templates are not exported with the connection.

Creating SSH Keys

Create a key-pair for your computer.
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 133.
1. Create a key pair using the GUI
Start the application by launching Start menu > All Programs > Aspera > Enterprise Server > Enterprise
Server . From the menu bar, select Tools > Manage Keys.
 | Transferring Files with the Application | 31

In the SSH Keys dialog, click to bring up the New SSH Key Pair window.

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

Field Description
Identity Give a name to your key pair, such as your user name.
 | Transferring Files with the Application | 32

Field Description
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 a public key authentication, or a connection that is used
with a Hot Folder, that key should have this option checked.
2. Distribute the public key
Then, you will need to 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. To copy or export the public key, select the key in the Public Key
Manager window, click Copy Public Key to Clipboard, and paste the string into an email and address it to the
server administrator, or click Export to File and save the public key as a file. For information on how to install the
public key on the server, see Setting Up a User's Public Key on page 59; however, keep in mind that the server
could be installed on an operating system that is different from the one where your client is installed.

3. Set up connections using public key authentication

When your public key has been installed on the remote host by its server administrator, click the Connections to
bring up the Connection Manager.

Under the Connection tab, select Public Key from the Authentication pull-down menu and select the key that is
installed on this host.
 | Transferring Files with the Application | 33

Note: When you are sharing a connection with public key authentication (Share this connection with all
users on this computer checkbox is checked), the SSH key should be shared as well.

To import keys created outside the GUI, go to Tools > Manage Keys to open the SSH Keys dialog. Clicking the
button in the upper-left corner of the dialog opens a file browser. You can import the key pair by selecting either the
private key or the public key, to 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, selecting a key and clicking the
button opens the Edit SSH Key Pair dialog. Check the Access box to allow shared connections to use this key. Shared
keys are moved to the Enterprise Server etc directory.

Enabling a Transfer or HTTP Proxy

Setting up your connection if you are behind a proxy server
If, for network-security reasons, you are behind a proxy server or an HTTP proxy server, you can enable these
proxies for file transfer by configuring settings in the Preferences dialog. Preferences can be accessed either from the
Preferences button in the upper-right corner of the desktop client window menu, or from the Tools button in the main
toolbar.

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.
 | Transferring Files with the Application | 34

By default, proxy settings are turned off.

Global Proxy Settings

To enable or adjust proxy settings globally, select Tools > Global Preferences. You must have admin privileges to set
global preferences:

In the Proxy dialog, you can set the following:

Enable transfer proxy
• Check the Enable transfer proxy checkbox.
• Enter the proxy server's hostname or IP address and port number.
• Enable the Secure checkbox if your proxy server allows secure connections.
• Enter your username and password to authenticate with your proxy server.

Enable HTTP proxy

• Check the Enable HTTP proxy checkbox.
• Enter the HTTP proxy's hostname or IP address and port number.
• If your HTTP proxy requires authentication, enable the Authenticated checkbox and enter the username and
password for your HTTP proxy.
 | Transferring Files with the Application | 35

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. Select Tools > Preferences or
click the Preferences link in the upper-right corner of the desktop client window:

Under Proxy, the values inherited from the global proxy settings will be filled in initially. You can set the following:
Enable transfer proxy
• Check or uncheck Enable transfer proxy to enable or disable transfer proxy.
• Enter the proxy server's hostname or IP address and port number.
• Enable the Secure checkbox if your proxy server allows secure connections.
• Enter your username and password to authenticate with your proxy server.
You can also clear your personal settings by clicking Restore Defaults. Your settings will revert to the current global
settings.
If you are an admin, you can access the global proxy dialog by clicking the Global Preferences button.
 | Transferring Files with the Application | 36

Enable HTTP proxy

• Check the Enable HTTP proxy checkbox.
• Enter the HTTP proxy's hostname or IP address and port number.
• If your HTTP proxy requires authentication, enable the Authenticated checkbox and enter the username and
password for your HTTP proxy.

By default, all proxy settings are set to the global values. For personal preferences, clicking Restore Defaults changes
all settings to the global values.
 | Transferring Files with the Application | 37

Transferring Files
Initiate and manage file transfers.
Caution: Do not use the following characters in filenames:

/ \ " : ' ? > < & * |

1. Connect to the remote host

Start the application by launching Start menu > All Programs > Aspera > Enterprise Server > Enterprise
Server , and double-click the connection within the Connection panel, or select it and click Connect.

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
24.
2. Initiate the transfer
To transfer a file to or from the remote computer, select the file to transfer and then click the upload or download
arrow.

3. Transfer files using drag-and-drop or copy-and-paste.

You can transfer files or folders between the right and left browser panels using drag-and-drop or copy-and-paste.
Within either the left or right browser panel, you can move files or folders using drag-and-drop or cut-and-paste,
and you can copy them using copy-and-paste.
You can also initiate an upload using drag-and-drop from Windows Explorer to the right browser panel.
4. Transfer files without browsing the remote host
If you have entered the target directory for this connection (See Managing Connections on page 24), you
can also transfer files without browsing the remote computer. To do so, select the files from the left panel (local),
select the connection name from the right panel (remote) and click to push files to the remote computer's target
directory (as shown in the screenshot), or to pull files from it.
 | Transferring Files with the Application | 38

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.
5. Manage the transfer sessions in the Transfers panel
Once the transfer has been successfully initiated, a progress bar will appear in the Transfers panel. If you have
multiple ongoing transfers, use the and to change the selected transfer's priority. The # field indicates the
transfer's order in the queue. Also the , , and can be used to control the selected transfer session.
6. (Optional) Make adjustments to a transfer session's target rate, minimum rate and/or policy (if allowed)
The Details button provides additional visibility and control (if granted the proper permissions) over transfers.
Select a transfer session from the Transfers panel and click Details to view details and/or adjust settings.

The following items are on the Details display:

 | Transferring Files with the Application | 39

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 – Attempts to transfer at the specified target rate,
regardless of the actual network capacity. This policy transfers
at a constant rate and finishes in a guaranteed time. This policy
typically occupies most of the network's bandwidth, and is not
recommended in most file transfer scenarios. In fixed mode, a
maximum (target) rate value is required.
• high – Monitors the network and adjusts the transfer rate
to fully utilize the available bandwidth up to the maximum
rate. When congestion occurs, a it transfers at a rate twice of
a session with fair policy. In this mode, both the maximum
(target) and the minimum transfer rates are required.
• fair – Monitors the network and adjusts the transfer rate to
fully utilize the available bandwidth up to the maximum rate.
When other types of traffic build up and congestion occurs, it
shares bandwidth fairly by transferring at an even rate. In this
mode, both the maximum (target) and the minimum transfer
rates are required.
• low – Similar to fair mode, the low policy uses the available
bandwidth up to the maximum rate, but is much less aggressive
when sharing bandwidth with other network traffic. When
congestion builds up, the transfer rate is reduced to the
minimum rate until other traffic retreats.
Important: If --policy is not set, ascp uses the server-side
policy setting (fair by default).

D Transfer Monitor The transfer graph. Note that you may use the sliders to adjust the
transfer rate up or down (if allowed).

7. Update preferences for the transfer rate and maximum number of concurrent transfers
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.
 | Transferring Files with the Application | 40

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. For more
advanced bandwidth settings, see Bandwidth on page 66. (Set by administrators
only.)
Default Target Rate The initial download and upload rates for all transfers.
Maximum Active The maximum number of concurrent upload transfers and download transfers.
Transfers

For information about settings under the Email tab, see Configuring Transfer Notifications on page 42.

Advanced Transfer Mode

More options for initiating transfers, such as filters, security, and scheduling.
You can start a transfer in advanced mode to set per-session transfer options 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).

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.
 | Transferring Files with the Application | 41

Tab Description
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
configuration screen. For information on these tabs, see Managing Connections on page 24. The
Scheduling tab is described below.

Scheduling
To enable transfer scheduling, check the box for Schedule this transfer. When finished, click Transfer. The
following scheduling options are available:

Option Description
Time Specify the transfer time.
Transfer repeats Select a repeat mode.
For a single transfer, select Does not repeat and select a time and date.
For a daily transfer, select Daily and select a start time and an end date (either Never or a
date and time).
For a daily transfer on weekdays only, select Monday - Friday and an end date (either
Never or a date and time).
For a weekly transfer, select Weekly, select which day of the week, and specify an end date
(either Never or a date and time). Note that with this option you can specify more than one
day of the week to set specific days when the transfer should repeat.
For transfers that should repeat more frequently than daily, select Periodically and fill in the
number of minutes between transfers.

When submitting a scheduled transfer, you will see it listed under the Transfers tab, along with an icon ( ) under the
# column. To modify the transfer, right-click it and select Edit to reveal the transfer settings.
 | Transferring Files with the Application | 42

Note: When scheduling transfers, ensure that the application is running. Unlike Hot Folders, scheduled
transfers do not run when the application is closed.

Configuring Transfer Notifications

Set up transfer notifications and modify the templates.
Transfer notification emails (which are based on default or customized mail templates) are triggered by three transfer
session events: start, completion and error. Follow the instructions below to configure the SMTP server and/or to
create/modify your email templates.
1. Launch Enterprise Server with Administrator permissions
Configuring transfer notifications requires Administrator permissions. Log into your computer with your
Administrator account and launch the application ( Start menu > All Programs > Aspera > Enterprise Server >
Enterprise Server ).
2. Configure global mail preferences
Note: To configure global mail preferences, you must have Administrator permissions.

To set up global mail preferences, launch the application with Administrator permissions, and select Tools >
Global Preferences.

Click the Mail button to configure settings for email notifications. In the dialog that appears, check Enable
email notifications to turn on email notifications for all users. If enabled, both a from address and outgoing email
server host name are required. To ensure that the mail server information is correct, click Send test email-- a test
message will be sent to the from address.
 | Transferring Files with the Application | 43

To enable notifications on Hot Folder transfers, check Send email notifications for hot folders.

User Mail Preferences

To override all global/default mail settings and enter personal settings for your own account, select Tools > Global
Preferences or click the Preferences link in the upper-right corner of the main application window:
 | Transferring Files with the Application | 44

This opens the My Preferences > Mail dialog. When initially opened, this dialog is populated with the inherited
global default values as set by an admin user. From here you can overwrite the inherited mail settings, including
enabling or disabling notifications. To restore settings to the global values, click the Restore Defaults button.

3. Bring up the Mail Templates window

Templates are used to generate the content of notification emails. You can associate them with connections, hot
folders, and individual transfers. We provide a default template. They can be changed to customize notification
emails.
Click Tools > Mail Templates to bring up the Mail Templates window.
 | Transferring Files with the Application | 45

In the Mail Templates window, click to create a template based on existing ones, or select an existing template
and click to edit it.

The mail template supports MIME (Multipurpose Internet Mail Extensions) multipart messages that includes
both the HTML and plain text versions of the mail body. In the Edit Template window, Enter the template in the
specified field:
 | Transferring Files with the Application | 46

Item Description
Name The template name.
HTML The HTML mail body. Click Insert Image to insert an image into the template. The
selected image will be copied to the template directory. You may preview the template by
clicking Preview.
Text The plain text mail body. You may preview the template by clicking Preview.
Access Check the option Share this template with all users on this computer to allow other
system users to access this template.
4. Modify mail templates
Mail templates serve as models for the email that will be sent.
To modify mail templates, go to Tools > Mail Templates to bring up the template management window.

The templates are rendered using Apache Velocity (Apache Velocity User Guide). Content is generated for an
email according to its template. A conditional statement only generates content if the condition matches. A foreach
loop generates content for each iteration of the loop. Within a template, there are two predefined variables:
• $formatter - Contains some utility methods
• $notifications - Holds the transfer notifications
To iterate over notifications, use a foreach loop:

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

...
#end

This declares a local $event variable that can be used within the for-each loop.
The following conditional statements can be used in the templates:

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

All statements are categorized in four parts: conditional, session information, time, and statistics.
Conditional
 | Transferring Files with the Application | 47

Use these tests in an if statement. For example:

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

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

Session Information

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

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

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

Statement Description
And 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 entered in the notification's "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:
• Replace var with the following two statements; for example,
$event.getStartTime()
• Replace the var with an abbreviate language name; for
example, en for English.
• The format is the display format. Use these symbols:
• yyyy The year. E.g. 2010
• MM Month of the year. E.g. 03
• dd Day of the month. E.g. 28
• HH Hour of the day.
• mm Minute.
• ss Second.
• z Time zone.
• EEE The abbreviated weekday name.
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 transferred.
$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.
 | Transferring Files with the Application | 49

Statement Description
$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.

When configured, you can apply the notifications to a connection host, or a transfer session. For details, see Using
Transfer Notifications on page 49.

Using Transfer Notifications

Use transfer notifications to send emails based on transfer events.
Transfer notifications can be sent for three transfer events: start, complete, and error. Follow these instructions to
select and apply them to your transfer sessions:
1. Preview mail templates
You can preview existing templates to decide which one to use. In the application ( Start menu > All Programs >
Aspera > Enterprise Server > Enterprise Server ), go to Tools > Mail Templates... to bring up the Mail
Template window.

In the Mail Templates window, select an existing template and click to open the edit screen.

Mail templates supports MIME multipart messages, which include both HTML and plain text versions. In the Edit
Template window, click Preview to view the template's output example.
 | Transferring Files with the Application | 50

2. Set up notifications for a connection

You can set up notifications for connections. When transferring with the host, emails will be sent to specified
recipients on selected events.
To do so, click Connections, choose the connection, and select the Tracking tab. Check Send email notifications
to enable this feature. Enter the following information, and then click OK:

Item Description
When Check the events to send notifications for.
To Enter the recipients, comma separated.
Template Select a mail template.
Message Optionally enter a message to include in the notifications.
3. Set up notifications for a transfer
 | Transferring Files with the Application | 51

Email notifications can also be applied to transfer sessions. Right click the file browser and select Upload... or
Download... to open the advanced transfer window, select the Tracking tab, and check Send email notifications
to enable this feature. Refer to the previous section for help on setting the options.

Reporting Checksums
Configure IBM Aspera Enterprise Server to report checksums for transferred files.
Internally, Enterprise Server determines the success of transfers by using checksums to verify that file contents at a
destination match what was read at the source. Enterprise Server can also be configured to report these checksums to
users.
Note: Checksum reporting requires that both the server and client nodes be running Enterprise Server,
Connect Server, or Point-to-Point 3.4.2 or higher.
By default, checksum reporting is turned off. The feature can be enabled and configured on the server using any of the
following methods:
• entering configuration options in aspera.conf
• setting configuration options in the desktop client GUI
• on a per-transfer basis, using a command-line option with ascp
If used, the command-line option overrides settings in aspera.conf and the GUI.
Each method allows you to enable checksum reporting by selecting or setting the following options:
md5 - Calculate and report an MD5 checksum.
sha1 - Calculate and report an SHA-1 checksum.
any - Allow the checksum format to be whichever format the client requests.
Additional options in aspera.conf and the GUI allow you to configure where checksum reports should be saved.
Enabling from aspera.conf
Open the aspera.conf file on your server and add the <file_checksum> option to the <file_system>
section, as in the example below.
Note: The none option is no longer supported as of 3.4.2. If your aspera.conf file has a
<file_checksum> setting of none, transfers will fail with the error "Server aborted Session: Invalid
configuration file".
To enable and configure the file manifest where checksum report data will be stored, add settings for
<file_manifest> and <file_manifest_path>; for example:

<file_system>
...
<file_checksum>md5</file_checksum> <!-- Enable checksum reporting (md5,
sha1, any) -->
<file_manifest>text</file_manifest> <!-- Enable file manifest (text,
disable) -->
<file_manifest_path>C:\Users\Public\reports</file_manifest_path> <!--
Path to manifest file -->
...
 | Transferring Files with the Application | 52

</file_system>

The following table provides details on the configuration options for checksum reporting:

Conf Option / GUI Config Description Values Default

Setting

<file_checksum> Enable checksum reporting, specifying the type of md5, sha1, or any
checksum to calculate for transferred files. any
File checksum method

<file_manifest> When set to text a text file "receipt" of all files text, disable disable
within each transfer session is generated. If set to
File Manifest disable, no file manifest is created. The file manifest
is a file containing a list of everything that was
transferred in a given transfer session. The filename
of the file manifest itself is automatically generated
based on the transfer session's unique ID.

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

Enabling from the GUI

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

To enable the file manifest from the GUI, locate the File Manifest setting. Check the override box and set the
effective value to text.
Locate the File Manifest Path setting on the line just below. Check the override box and set the effective value to a
folder where the manifest files are to be saved.
 | Transferring Files with the Application | 54

In the above examples, when files are transferred, the manifest is generated to a text file called aspera-
transfer-transfer_id-manifest.txt in the folder C:\Users\Public\reports.
For details about the settings for File checksum method, File Manifest, and File Manifest Path, see the table of
configuration options in the previous section.
Enabling from the ascp Command Line
To enable checksum reporting on a per-transfer-session basis, run ascp with the --file-checksum=hash option,
where hash is sha1, md5, or any.
From the ascp command line, you can also enable the manifest with the option --file-manifest=output
where output is either text or none. You can set the path to the manifest file with the option --file-manifest-
path=path.
For example:

> ascp --file-checksum=md5 --file-manifest=text --file-manifest=C:\Users

\Public\reports file [email protected]:/destination_path

Setting up a Pre/Post-processing Script

An alternative to enabling and configuring the file manifest to collect checksum reporting is to set up a pre/post-
processing script to report the values.
The checksum of a successfully transferred file is stored in the pre/post environment variable FILE_CSUM. This
environment variable can be used in pre/post scripts to capture file checksums. For example, the following script
outputs the checksum to the file C:\Users\Public\reports\cksum.log:

if "%TYPE%"=="File" (
if "%STARTSTOP%"=="Stop" (
echo "The file is: %FILE%" >> C:\Users\Public\reports\cksum.log
echo "The file checksum is: %FILE_CSUM%" >> C:\Users\Public\reports
\cksum.log
)
)

For information on how to set up pre- and post-processing scripts such as the above and how to use builtin pre/post
environment variables, see Pre- and Post-Processing (Prepost) on page 110.
 | Managing Users | 55

Managing Users
Add users for the FASP connection authentication, and set up user transfer settings.

Setting Up Users
Set up system user accounts for FASP file transfers.
Warning: If you have upgraded from 2.7.X to 3.X on Windows, you should be aware that starting with 3.X
user names are case sensitive.
Your Aspera server uses your system accounts to authenticate connections. These system accounts must be added and
configured before attempting an Aspera transfer. When creating transfer accounts, you may also specify user-based
settings, including those for bandwidth, document root (docroot) and file handling.
Note: You must create systems accounts for transfer users before they can be configured on your Aspera
server. After these system accounts have been created and initialized on your local host, follow the steps
below to configure their transfer accounts.
1. Add a system user to your Aspera server.
Launch the application (Start menu > All Programs > Aspera > Enterprise Server > Enterprise Server) and
click Configuration.

In Server Configuration, select the Users tab and click the button.

2. Enter user's name and optional domain, and set login requirement.
Within the Add User box, enter the user's name and optional domain, then click OK. Note that for domain users,
you can set a requirement that they must log into their accounts using the DOMAIN\username format (which
is also recommended by Aspera). To set this requirement, click the Options button under the Users tab in the
Server Configuration window. Enable the checkbox to set the requirement for new users and/or click the Convert
existing users button to set the requirement for existing domain accounts.
 | Managing Users | 56

Note: You cannot add a username with the "@" symbol, except when using the user@domain format. For
additional information, see Product Limitations.
3. Set up user's docroot.
You can limit a user's access to a given directory using the document root (docroot). To set it up, click
Configuration>UsersusernameDocroot. Check the Override box for Absolute Path and enter or select an
existing path as the user's docroot -- for example, C:\sandbox\asp1 . Make sure that at least the Read
Allowed and Browse Allowed are set to true. When finished, click OK or Apply.

If there is a pattern in the docroot of each user, for example, C:\sandbox\username, you can take advantage
of a substitutional string. This allows you to assign an independent docroot to each user without setting it
individually for each user.

Substitutional String Definition Example

$(name) The system user's name. C:\sandbox\$(name)
$(DOMAIN) The domain user's domain name. C:\sandbox\$(DOMAIN)\
$(name)

Set up a docroot with a substitutional string as follows: in the Server Configuration dialog, select the Global tab
and the Docroot tab, and enter the docroot into the Absolute Path field. This value will be duplicated in all user
settings.

Test User-Initiated Remote Transfer

Test FASP transfers initiated from a client computer.
Follow the steps below to test your server's incoming connections from a client machine.
Important: These instructions require you to take steps on both the Enterprise Server and a client computer.
Ensure that you are performing the task on the indicated machine. As a prerequisite, Enterprise Server must
have at least one transfer user. For instructions on adding a transfer user, see Setting up Users.
 | Managing Users | 57

1. (On your client machine) Verify your connection to Enterprise Server.

On the client machine, use the ping command in a Command Prompt window to verify connectivity to the host.
In this example, the address of Enterprise Server is 10.0.0.2.

> ping 10.0.0.2

PING 10.0.0.2 (10.0.0.2): 56 data bytes
64 bytes from 10.0.0.2: icmp_seq=0 ttl=64 time=8.432 ms
64 bytes from 10.0.0.2: icmp_seq=1 ttl=64 time=7.121 ms
64 bytes from 10.0.0.2: icmp_seq=2 ttl=64 time=5.116 ms
64 bytes from 10.0.0.2: icmp_seq=3 ttl=64 time=4.421 ms
64 bytes from 10.0.0.2: icmp_seq=4 ttl=64 time=3.050 ms
...

2. (On your client machine) Initiate a transfer to Enterprise Server.

Attempt to establish a connection from your client machine to Enterprise Server. To do so, run the following
command on your client machine (where asp1 is our example transfer user):

> ascp -P 33001 -T --policy=fair -l 10000 -m 1000 /client-dir/

files [email protected]:/dir

Item Value
Host Address 10.0.0.2
Transfer User asp1
Files to upload /client-dir/files
Destination Folder {user's docroot}/dir
Transfer Options • Maximum transfer rate = 10 Mbps (-l 10000)
• Minimum transfer rate = 1 Mbps (-m 1000)
• Change default TCP port used for FASP session initiation = 33001 (-P 33001).
Please note that this command does not alter ascp or your SSH server's configuration.
• Disable encryption (-T)
• Fair transfer policy (--policy=fair)

If you cannot establish a connection to Enterprise Server, see Clients Cannot Establish Connection.

Setting Up Groups
Create system groups on your computer, and set up transfer settings for the group and its members.
You can set up transfer settings based on your system's user groups. If users within a group do not have individual
transfer settings, then the group's transfer settings will be applied. Please note that Enterprise Server doesn't create
user groups on the Operating System for you, so you must ensure that the groups currently exist before adding them
to your Aspera product. Follow the steps below to add user groups to Enterprise Server.
1. Determine the user group(s) that you would like to add to your Aspera transfer product
Ensure that you have an existing user group on your operating system, or create a new user group. For information
on creating user groups, see your operating system documentation.
2. Add the user group to your Aspera transfer product
Launch Enterprise Server (Start menu > All Programs > Aspera > Enterprise Server > Enterprise Server)
and click Configuration.
 | Managing Users | 58

Within the Server Configuration window, select the Groups tab, click and input the user group's name.

3. Configure the group's transfer settings

Go to Configuration and select the Groups tab. Choose your group, and utilize the Docroot, Authorization,
Bandwidth, Network, File Handling and Precedence tabs to configure the transfer settings. Refer to the
hyperlinked topics below for additional information.

Category Description
Document Root on page 61 The document root settings.
Authorization on page 64 Connection permissions, token key, and encryption requirements.
Bandwidth on page 66 Incoming and outgoing transfer bandwidth and policy settings.
Network on page 70 Network IP, port, and socket buffer settings.
File Handling on page 72 File handling settings, such as file block size, overwrite rules, and exclude
pattern.
Configuration Precedence on page When a user is a member of multiple groups, the precedence setting can
58 be used to determine priority.

Configuration Precedence
The priority of user, group, global-level and default settings.
Enterprise Server gives precedence to settings as follows, where user settings have the highest priority and default
settings have the lowest.
(1) User
(2) Group(s) (If a user belongs to more than one group, a precedence can be set for each group.)
(3) Global
(4) Default
If a user is a member of multiple groups, a precedence setting can be assigned to each group. The following table
shows the setting values that a user asp1 is assigned in bold. In this example, asp1 is a member of both the admin
and xfer groups. The admin group's precedence setting is 0, which supersedes the xfer group's setting of 1:

Options User asp1's Group admin's Group xfer's Global Settings Default Settings
Settings Settings Settings
Target rate 5M 10M 15M 40M 45M
 | Managing Users | 59

Options User asp1's Group admin's Group xfer's Global Settings Default Settings
Settings Settings Settings
Min rate n/a 2M 8M 3M 0
Policy n/a n/a Low Fair Fair
Docroot n/a n/a n/a C:\pod\$(name) n/a
Encryption n/a n/a n/a n/a any

You can configure a group's precedence from the GUI or by editing aspera.conf. To configure it from the GUI,
launch the application and click Configuration.

In the Server Configuration dialog, select the Groups tab, choose a group, and select the Precedence tab. (The
Precedence tab does not appear if there are no groups.) Click the Override checkbox to override the inherited value
(default), and enter a precedence number for the group.
Note: A group's precedence setting must be greater than or equal to 0, where 0 is the highest precedence
level.

Before assigning group precedence by editing aspera.conf, first ensure that the groups have already been added in the
application, so that they will appear as entries in aspera.conf.
Locate the aspera.conf file as follows:
C:\Program Files[ (x86)]\Aspera\Enterprise Server\etc\aspera.conf

Setting Up a User's Public Key

Install the public key provided by the clients to their user account.
Public key authentication is an alternative to password authentication, providing a more secure authentication method
that allows users to avoid entering or storing a password, or sending it over the network. It is done by using the client
computer to generate the key-pair (a public key and a private key), provide the public key to the server or the point-to-
point, and have the public key installed on that machine.
1. Obtain the client's public key
The client should send you an e-mail with the public key, either a text string attached in the secure e-mail, or saved
as a text file. In this example, the client's login user account is asp1.
 | Managing Users | 60

For instructions of creating public keys, refer to Creating SSH Keys on page 30, or Creating SSH Keys (Command
Line) on page 133 for command_line instructions.
2. Install the client's public key to its login user account
To install the account's public key, create a folder called .ssh in the user's home directory. This example sets up the
public key for the following user:

Item Value
User name asp1
User's home directory C:\Documents and Settings\asp1

Open a Command Prompt (Start menu > All Programs > Accessories > Command Prompt) and execute the
following commands to create the user's public key folder:

> cd "C:\Documents and Settings\asp1"

> md .ssh

Use a text editor to create the following file, without file extension:
C:\Documents and Settings\asp1\.ssh\authorized_keys
Add the user's public key-string into this file and save it. The user should now be able to establish FASP
connections with public key authentication.
Note:
Some text editors append the file extension automatically, such as .txt. Make sure to remove the file
extension from the file authorized_keys.
 | General Configuration Reference | 61

General Configuration Reference

The general transfer configuration options.
This section covers the general configuration options, which can be used for global, group, and user settings.

Document Root
The document root settings.
The document root (docroot) configuration options can be found in the application's Configuration ( Start menu >
All Programs > Aspera > Enterprise Server > Enterprise Server ), within Global, Groups and Users sections.

The following table lists all configuration options:

Field Description Values Default

Absolute Path The Absolute Path is a path to the docroot, the area of file path or blank
the file system that is accessible to Aspera users. The Amazon S3
default empty value gives users access to the entire URI
file system. In aspera.conf, you can set multiple
docroots and make them conditional based on the IP
address from which the connection is made. To do so, set
the absolute path as follows:

<absolute
peer_ip="ip_address">path</
absolute>

Note:
You may also specify an Amazon S3 docroot
in the following URI format: s3://
MY_ACCESS_ID:MY_SECRET_KEY@s3.
amazonaws.com/my_bucket/my_path
 | General Configuration Reference | 62

Field Description Values Default

(where each of the MY_ACCESS_ID,
MY_SECRET_KEY and my_bucket/
my_path parts must be url_encoded).
S3 server side options are specified through
an additional query part in the URI, as shown
below.
s3://
MY_ACCESS_ID:MY_SECRET_KEY@s3.
amazonaws.com/my_bucket/
my_path?storage-
class=REDUCED_REDUNDANCY&
server-side-encryption=AES256
Valid values are as follows:
• For storage-class: STANDARD (default if
not specified) or REDUCED_REDUNDANCY.
• For server-side-encryption: AES256 is the
only valid value.

Read Allowed Setting this to true allows users to transfer from the • true blank
designated area of the file system as specified by the • false
Absolute Path value.
Write Allowed Setting this to true allows users to transfer to the • true blank
designated area of the file system as specified by the • false
Absolute Path value.
Browse Allowed Setting this to true allows users to browse the • true blank
directory. • false

Configuring Symbolic Links

This section describes how Aspera handles symbolic links in ascp. Both client-side and server-side handling can be
configured using the command-line options and the aspera.conf file respectively.

Client-Side Symbolic Link Handling

See Advanced Symbolic Link Options (ascp) on page 62 for information about configuring client-side handling
for symbolic links.

Server-Side Symbolic Link Handling

See Server-Side Symbolic Link Handling on page 63 for information about configuring server-side handling for
symbolic links.

Advanced Symbolic Link Options (ascp)

Client-side handling of symbolic links is configured from the following ascp command line:

> ascp --symbolic-links=option

The following section describes the possible configuration options:

 | General Configuration Reference | 63

Configuration Options

Option Description
copy Copy only the alias file. If a file with the same name
exists at the destination, the symbolic link will not be
copied.
copy+force Copy only the alias file. If a file with the same name
exists at the destination, the symbolic link will replace
the file. If the file of the same name at the destination is a
symbolic link to a directory, it will not be replaced.
follow Follow symbolic links and transfer the linked files. This
is the default option.
skip Ignore the symbolic link.

Server-Side Symbolic Link Handling

The following section describes how Aspera handle symbolic links in ascp based on settings configured in the
aspera.conf file. The aspera.conf file can be found in the following location:

OS Version File Location

32-bit Windows C:\Program Files (x86)\Aspera\Enterprise Server\etc
\aspera.conf
64-bit Windows C:\Program Files\Aspera\Enterprise Server\etc\aspera.conf

Configuration Options
The following configuration options are set in the <file_system> section of the aspera.conf file:

<file_system>
<symbolic_links>list_of_comma-separated_options</symbolic_links>
</file_system>

Note: If no option is specified, the configuration defaults to create, follow.

Option Description Client Behavior Server Behavior

create Create symbolic links with Skip if not configured. Symbolic links are always
arbitrary targets. This is copied to the server if the
option set by default. client requests.
follow Follow symbolic links Symbolic links are always Skip if not configured.
with targets inside docroot. copied to the server if the Follow symbolic links with
If at any point the path client requests. targets inside the docroot.
goes outside the docroot,
Note: If the Note: If the
ascp will not complete the
docroot is a docroot is a
transfer. This is option set
symbolic link symbolic link
by default.
and is specified and is specified
as the source as the source
or destination: or destination:
As the receiver, As the sender,
follow the target follow the target
widely (no docroot widely (no docroot
constraint) and constraint) and
 | General Configuration Reference | 64

Option Description Client Behavior Server Behavior

unconditionally unconditionally
(regardless (regardless
of symbolic of symbolic
link action(s) link action(s)
configured/ configured/
requested). requested).

follow_wide Follow symbolic links with Symbolic links are always

arbitrary targets, even if copied to the server if the
the targets are outside the client requests.
docroot.
Note: If the
docroot is a
symbolic link
and is specified
as the source
or destination:
As the receiver,
follow the target
widely (no docroot
constraint) and
unconditionally
(regardless
of symbolic
link action(s)
configured/
requested).

none Take no action with the

symbolic link.

Authorization
Connection permissions, token key, and encryption requirements.
The Authorization configuration options can be found in the application's Configuration ( Start menu > All
Programs > Aspera > Enterprise Server > Enterprise Server ), within Global, Groups, and Users sections.
 | General Configuration Reference | 65

The following table lists all configuration options:

Field Description Values Default

Incoming Transfers The default setting of allow enables users to transfer • allow allow
to this computer. Setting this to deny will prevent • deny
transfers to this computer. When set to token, only
• token
transfers initiated with valid tokens will be allowed
to transfer to this computer. Token-based transfers
are typically employed by web applications such as
Faspex and require a Token Encryption Key.
Incoming External Provider The value entered should be the URL of the HTTP URL blank
URL external authorization provider for incoming
transfers. The default empty setting disables external
authorization. Aspera servers can be configured to
check with an external authorization provider. This
SOAP authorization mechanism can be useful to
organizations requiring custom authorization rules.
Incoming External Provider The SOAP action required by the external text string blank
SOAP Action authorization provider for incoming transfers.
Required if External Authorization is enabled.
Outgoing Transfers The default setting of allow enables users to transfer • allow allow
from this computer. Setting this to deny will prevent • deny
transfers from this computer. When set to token, only
• token
transfers initiated with valid tokens will be allowed
to transfer from this computer. Token-based transfers
are typically employed by web applications such as
Faspex and require a Token Encryption Key.
Outgoing External Provider The value entered should be the URL of the HTTP URL blank
URL external authorization provider for outgoing
transfers. The default empty setting disables external
authorization. Aspera servers can be configured to
 | General Configuration Reference | 66

Field Description Values Default

check with an external authorization provider. This
SOAP authorization mechanism can be useful to
organizations requiring custom authorization rules.
Outgoing External Provider The SOAP action required by the external text string blank
Soap Action authorization provider for outgoing transfers.
Required if External Authorization is enabled.
Token Encryption Cipher The cipher used to generate encrypted authorization • aes-128 aes-128
tokens. • aes-192
• aes-256

Token Encryption Key This is the secret text phrase that will be used to text string blank
authorize those transfers configured to require token.
Token generation is part of the Aspera SDK. See
the Aspera Developer's Network (Token-based
Authorization Topic) for more information.
Token Life (seconds) Sets token expiration for users of web-based transfer positive 86400 (24
applications. integer hrs)
Token Filename Hash Which algorithm should filenames inside transfer • sha1 sha1
tokens be hashed with. Use MD5 for backward • MD5
compatibility.
• sha256

Strong Password Required for When set to true, require the password for content • true false
Content Encryption encryption to contain at least 6 characters, of which • false
at least 1 is non-alphanumeric, at least 1 is a letter,
and at least 1 is a digit.
Content Protection Required When set to true, • true false
• Users will be required on upload to enter a • false
password to encrypt the files on the server.
• Users will be given the option when
downloading to decrypt during transfer.

Do encrypted transfers in When set to true, ascp will use a FIPS 140-2- • true false
FIPS-140-2-certified encryption certified encryption module. Note: When this feature • false
mode is enabled, transfer start is delayed while the FIPS
module is verified.
Encryption Allowed Describes the type of transfer encryption accepted by • any any
this computer. When set to any the computer allows • none
both encrypted and non-encrypted transfers. When
• aes-128
set to none the computer restricts transfers to non-
encrypted transfers only. When set to aes-128 the
computer restricts transfers to encrypted transfers
only.

Bandwidth
Incoming and outgoing transfer bandwidth and policy settings.
The Bandwidth configuration options can be found in the application's Configuration ( Start menu > All
Programs > Aspera > Enterprise Server > Enterprise Server ), within Global, Groups and Users sections.
 | General Configuration Reference | 67

The following table lists all configuration options:

Field Description Values Default

Incoming Vlink ID The value sets Vlink ID for incoming pre-defined value 0
transfers. Vlinks are a mechanism to define
aggregate transfer policies. The default setting
of 0 disables Vlinks. One Vlink—the virtual
equivalent of a network trunk—represents a
bandwidth allowance that may be allocated to
a node , a group, or a user. Vlink ID is defined
in each Vlink created in Aspera Console.
Vlink ID is a unique numeric identifier.
Incoming Target Rate Cap The value sets the Target Rate Cap for positive integer unlimited
(Kbps) incoming transfers. The Target Rate Cap is
the maximum target rate that a transfer can
request, in kilobits per second. No transfer
may be adjusted above this setting, at any
time. The default setting of Unlimited
signifies no Target Rate Cap. Clients
requesting transfers with initial rates above
the Target Rate Cap will be denied.
 | General Configuration Reference | 68

Field Description Values Default

Incoming Target Rate This value represents the initial rate for positive integer 10000
Default (Kbps) incoming transfers, in kilobits per second.
Users may be able to modify this rate in real
time as allowed by the software in use. This
setting is not relevant to transfers with a
Policy of Fixed.
Incoming Target Rate Lock After an incoming transfer is started, its target • true false
rate may be modified in real time. The default • false
setting of false gives users the ability to
adjust the transfer rate. A setting of true
prevents real-time modification of the transfer
rate.
Incoming Minimum Rate The value sets the Minimum Rate Cap for positive integer unlimited
Cap (Kbps) incoming transfers. The Minimum Rate Cap
is a level specified in kilobits per second,
below which an incoming transfer will not
slow, despite network congestion or physical
network availability. The default value
of Unlimited effectively turns off the
Minimum Rate Cap.
Incoming Minimum Rate This value represents the initial minimum positive integer 0
Default (Kbps) rate for incoming transfers, in kilobits per
second. Users may be able to modify this rate
in real time as allowed by the software in use.
This setting is not relevant to transfers with a
Policy of Fixed.
Incoming Minimum Rate After an incoming transfer is started, its • true false
Lock minimum rate may be modified in real time. • false
The default setting of false gives users
the ability to adjust the transfer's minimum
rate. A setting of true prevents real-time
modification of the transfer rate. This setting
is not relevant to transfers with a Policy of
Fixed.
Incoming Bandwidth The value chosen sets the default Bandwidth • fixed fair
Policy Default Policy for incoming transfers. The default • high
policy value may be overridden by client
• fair
applications initiating transfers.
(regular)
• low

Incoming Bandwidth The value chosen sets the allowed Bandwidth • fixed any
Policy Allowed Policy for incoming transfers. Aspera • high
transfers use fixed, high, fair and low
• fair
policies to accommodate network-sharing
(regular)
requirements. When set to any, the server
will not deny any transfer based on policy • low
setting. When set to high, transfers with a
Policy of high and less aggressive transfer
policies (e.g. fair or low) will be permitted.
When set to fair, transfers of fair and low will
be permitted, while fixed transfers will be
 | General Configuration Reference | 69

Field Description Values Default

denied. When set to low, only transfers with
a Bandwidth Policy of low will be allowed.
Incoming Bandwidth After an incoming transfer is started, its • true false
Policy Lock Policy may be modified in real time. The • false
default setting of false gives users the
ability to adjust the transfer's Policy. A setting
of true prevents real-time modification of
the Policy.
Outgoing Vlink ID The value sets Vlink ID for outgoing pre-defined value 0
transfers. Vlinks are a mechanism to define
aggregate transfer policies. The default setting
of 0 disables Vlinks. One Vlink—the virtual
equivalent of a network trunk—represents a
bandwidth allowance that may be allocated to
a node , a group, or a user. Vlink ID is defined
in each Vlink created in Aspera Console. The
Vlink ID is a unique numeric identifier.
Outgoing Target Rate Cap The value sets the Target Rate Cap for positive integer unlimited
(Kbps) outgoing transfers. The Target Rate Cap is
the maximum target rate that a transfer can
request, in kilobits per second. No transfer
may be adjusted above this setting, at any
time. The default setting of Unlimited
signifies no Target Rate Cap. Clients
requesting transfers with initial rates above
the Target Rate Cap will be denied.
Outgoing Target Rate This value represents the initial rate for positive integer 10000
Default (Kbps) outgoing transfers, in kilobits per second.
Users may be able to modify this rate in real
time as allowed by the software in use. This
setting is not relevant to transfers with a
Policy of Fixed.
Outgoing Target Rate Lock After an outgoing transfer is started, its target • true false
rate may be modified in real time. The default • false
setting of false gives users the ability to
adjust the transfer rate. A setting of true
prevents real-time modification of the transfer
rate.
Outgoing Minimum Rate The value sets the Minimum Rate Cap for positive integer unlimited
Cap (Kbps) outgoing transfers. The Minimum Rate Cap
is a level specified in kilobits per second,
below which an outgoing transfer will not
slow, despite network congestion or physical
network availability. The default value
of Unlimited effectively turns off the
Minimum Rate Cap.
Outgoing Minimum Rate This value represents the initial minimum positive integer 0
Default rate for outgoing transfers, in kilobits per
second. Users may be able to modify this rate
in real time as allowed by the software in use.
 | General Configuration Reference | 70

Field Description Values Default

This setting is not relevant to transfers with a
Policy of Fixed.
Outgoing Minimum Rate After an outgoing transfer is started, its • true false
Lock minimum rate may be modified in real time. • false
The default setting of false gives users
the ability to adjust the transfer's minimum
rate. A setting of true prevents real-time
modification of the transfer rate. This setting
is not relevant to transfers with a Policy of
Fixed.
Outgoing Bandwidth Policy The value chosen sets the default Bandwidth • fixed fair
Default Policy for outgoing transfers. The default • high
policy value may be overridden by client
• fair
applications initiating transfers.
(regular)
• low

Outgoing Bandwidth Policy The value chosen sets the allowed Bandwidth • fixed any
Allowed Policy for outgoing transfers. Aspera transfers • high
use fixed, high, fair and low policies to
• fair
accommodate network-sharing requirements.
(regular)
When set to any, the server will not deny any
transfer based on policy setting. When set to • low
high, transfers with a Policy of high and less
aggressive transfer policies (e.g. fair or low)
will be permitted. When set to fair, transfers
of fair and low will be permitted, while fixed
transfers will be denied. When set to low,
only transfers with a Bandwidth Policy of
low will be allowed.
Outgoing Bandwidth Policy After an outgoing transfer is started, its Policy • true false
Lock may be modified in real time. The default • false
setting of false gives users the ability to
adjust the transfer's Policy. A setting of true
prevents real-time modification of the Policy.

Network
Network IP, port, and socket buffer settings.
The Network configuration options can be found in the application's Configuration ( Start menu > All Programs >
Aspera > Enterprise Server > Enterprise Server ), within Global, Groups and Users sections.
 | General Configuration Reference | 71

The following table explains all configuration options:

Field Description Values Default

Bind IP Address Specify an IP address for server-side ascp to bind its valid IPv4 blank
UDP connection. If a valid IP address is given, ascp address
sends and receives UDP packets only on the interface
corresponding to that IP address.
Important: The bind address should only be
modified (changed to an address other than
127.0.0.1) if you, as the System Administrator,
understand the security ramifications of doing
so, and have undertaken precautions to secure
the SOAP service.

Bind UDP Port Prevent the client-side ascp process from using the integer 33001
specified UDP port. between 1
and 65535
Disable Packet Batching When set to true, send data packets back to back (no • true false
sending a batch of packets). This results in smoother data • false
traffic at a cost of higher CPU usage.
Maximum Socket Buffer Upper bound the UDP socket buffer of an ascp session positive 0
(bytes) below the input value. The default of 0 will cause the integer
Aspera sender to use its default internal buffer size,
which may be different for different operating systems.
Minimum Socket Buffer Set the minimum UDP socket buffer size for an ascp positive 0
(bytes) session. integer
RTT auto correction Enable auto correction of base (minimum) RTT • true false
measurement. This feature is helpful for maintaining • false
accurate transfer rates in hypervisor-based virtual
environments.
Reverse path congestion Enable reverse path congestion inference, where the • true true
inference default setting of "true" prevents the transfer speed of a • false
session from being adversely affected by congestion in
the reverse (non data-sending) transfer direction. This
feature is useful for boosting speed in bi-directional
transfers.
 | General Configuration Reference | 72

File Handling
File handling settings, such as file block size, overwrite rules, and exclude pattern.
The File Handling configuration options can be found in the application's Configuration ( Start menu > All
Programs > Aspera > Enterprise Server > Enterprise Server ), within Global, Groups and Users sections.

The following table lists all configuration options:

Field Description Values Default

Read Block Size (bytes) This is a performance-tuning parameter for an Aspera positive 0
sender (which only takes effect if the sender is a server). integer,
It represents the maximum number of bytes that can be where
stored within a block as the block is being transferred 500MB or
from the source disk drive to the receiver. The default 524,288,000
of 0 will cause the Aspera sender to use its default bytes bytes
internal buffer size, which may be different for different is the
operating systems. maximum
block size.
Write Block Size (bytes) This is a performance-tuning parameter for an Aspera positive 0
receiver (which only takes effect if the receiver is a integer,
 | General Configuration Reference | 73

Field Description Values Default

server). It represents the maximum bytes within a block where
that an ascp receiver can write to disk. The default 500MB or
of 0 will cause the Aspera receiver to use its default 524,288,000
internal buffer size, which may be different for different bytes bytes
operating systems. is the
maximum
block size.
Number of I/O read threads This is a performance-tuning parameter for an Aspera
sender. It represents the number of threads the Aspera
sender will use to read file contents from the source disk
drive. It takes effect on both client and server, when
acting as a sender. The default of 0 will cause the Aspera
sender to use its internal default, which may be different
for different operating systems.
Number of I/O write This is a performance-tuning parameter for an Aspera
threads receiver. It represents the number of threads the Aspera
receiver will use to write the file contents to the
destination disk drive. It takes effect on both client and
server, when acting as a receiver. The default of 0 causes
the Aspera receiver to use its internal default, which may
be different for different operating systems.
Use File Cache This is a performance tuning parameter for an Aspera • true true
receiver. Enable or disable per-file memory caching at • false
the data receiver. File level memory caching improves
data write speed on Windows platforms in particular, but
will use more memory. We suggest using a file cache on
systems that are transferring data at speeds close to the
performance of their storage device, and disable it for
system with very high concurrency (because memory
utilization will grow with the number of concurrent
transfers).
Max File Cache Buffer This is a performance tuning parameter for an Aspera positive 0
(bytes) receiver. This value corresponds to the maximal size integer
allocated for per-file memory cache (see Use File
Cache). Unit is bytes. The default of 0 will cause the
Aspera receiver to use its internal buffer size, which may
be different for different operating systems.
Resume Suffix File name extension for temporary metadata files used text string .aspx
for resuming incomplete transfers. Each data file in
progress will have a corresponding metadata file with
the same name plus the resume suffix specified by the
receiver. Metadata files in the source of a directory
transfer are skipped if they end with the sender's resume
suffix.
Note: When you change the resume suffix,
you need to restart the Aspera Sync service in
order for hot folders to pick new settings up.
Go to Control Panel > Administrative Tools >
Services and restart Aspera Sync.
 | General Configuration Reference | 74

Field Description Values Default

Symbolic Link Action(s) Actions to be taken upon encountering a symbolic link • none follow,create
on the server side. The action to take depends on both • create
the platform and the particular application context. The
• follow
(combination of) choices are logically or'ed before use.
For instance, use none alone to mean skip, and shut out • follow_wide
other choices; when both follow and follow_wide are • any
present, the latter is recognized. combination
of the
above
delimited
by
commas

Preserve Attributes Configure file creation policy. When set to none, do • none blank
not preserve the timestamp of source files. When set • times
to times, preserve the timestamp of the source files at
destination.
Note: For Limelight storage, only the preservation of
modification time is supported.

Overwrite Overwrite is an Aspera server setting that determines • allow allow

whether Aspera clients are allowed to overwrite files • deny
on the server. By default it is set to allow, meaning that
clients uploading files to the servers will be allowed
to overwrite existing files as long as file permissions
allow that action. If set to deny, clients uploading files
to the server will not be able to overwrite existing files,
regardless of file permissions.
File Manifest When set to text a text file "receipt" of all files within • text none
each transfer session is generated. If set to disable, • disable
no File Manifest is created. The file manifest is a file
containing a list of everything that was transferred in a
given transfer session. The filename of the File Manifest
itself is automatically generated based on the transfer
session's unique ID. The location where each manifest is
written is specified by the File Manifest Path value. If no
File Manifest Path is specified, the file will be generated
under the destination path at the receiver, and under the
first source path at the sender.
File Manifest Path Specify the location to store manifest files. Can be an text string blank
absolute path or a path relative to the transfer user's
home.
Note: File manifests can only be stored locally.
Thus, if you are using S3, or other non-local
storage, you must specify a local manifest path.

File Manifest Suffix Specify the suffix of the manifest file during file transfer. text string .aspera-
inprogress
Pre-Calculate Job Size Configure the policy of calculating total job size before • any any
data transfer. If set to any, follow client configurations • yes
(-o PreCalculateJobSize={yes|no}). If set to no, disable
• no
 | General Configuration Reference | 75

Field Description Values Default

calculating job size before transferring. If set to yes,
enable calculating job size before transferring.
File Exclude Pattern List Exclude files or directories with the specified pattern text entries blank
in the transfer. Add multiple entries for more exclusion
patterns. Two symbols can be used in the setting of
patterns:
• * (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.

Partial File Name Suffix Filename extension on the destination computer while text string blank
the file is being transferred. Once the file has been
completely transferred, this filename extension is
removed.
If hot folders will be used as the upload destination, the
partial filename suffix should be set even if it means
setting it to the default value .partial. Setting it prevents
partial files from being downloaded from a hot folder.
Note: When you change the partial file
name setting, you need to restart the Aspera
Sync service in order for hot folders to pick
up new settings. Go to Control Panel >
Administrative Tools > Services and restart
Aspera Sync.

Note: This option only takes effect when it is

set on the receiver side.

File checksum method The type of checksum to calculate for transferred files.
The content of transfers can be verified by comparing
the checksum value at the destination with the value
read at the source. Check the override box and for the
effective value, select md5, sha1, or any. For details
on configuring and using the checksum feature, see
Reporting Checksums on page 51.
Async Log Directory An alternative location for the Sync server's log files. If
empty, log files go to the default location, or the location
specified by the client with -R.
Async Log Level The amount of detail in the Sync server activity log.
Choices are disable, dbg1, and dbg2.
Async Snapdb Directory An alternative location for the Sync server's snapshot DB
files.
 | Global Transfer Settings | 76

Global Transfer Settings

The system-wide and default FASP transfer settings for your computer.

Global Bandwidth Settings

Allocate the global bandwidth for FASP file transfers.
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. This topic describes how to optimize the transfer rate by
setting up the global rate settings.
To set global FASP bandwidth, bring up the application and select Tools > Global Preferences. Global bandwidth
can be set by administrators only.

In the Global Preferences dialog select Transfers, and enter the download and upload bandwidth values in the
System-Wide Settings field and click the checkboxes to enable the settings.
 | Global Transfer Settings | 77

Item Description
System-Wide Settings The aggregated bandwidth cap for all FASP transfers on this computer. For more
advanced bandwidth settings, see Bandwidth on page 66.
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.

Note:
When setting the global bandwidth, the application is in fact creating virtual links (Vlink) and applying them
to the default transfer settings. For more information about Vlinks, see Setting Up Virtual Links on page
77.

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 My PreferencesTransfers dialog. They can also adjust the default target rate and
maximum number of active transfers.
My Preferences can be opened from Tools > Preferences or from the Preferences button in the upper-right corner of
the application window.

Setting Up Virtual Links

Create and apply the aggregate bandwidth cap.
Virtual link (Vlink) is a feature that allows "virtual" bandwidth caps. Transfer sessions assigned to the same "virtual"
link conform to the aggregate bandwidth cap and attain an equal share of it. This section first shows you how to set up
Vlinks, then explains how to apply it to computers or users.
Follow these steps to configure Vlinks:
1. Create Vlinks
To configure Vlinks, launch the application ( Start menu > All Programs > Aspera > Enterprise Server >
Enterprise Server ) and click Configuration. Select Vlinks tab in the left panel.
 | Global Transfer Settings | 78

Click to add a new Vlink entry, assign a number between 1 and 255.

Here is a list of all Vlink configuration options:

# Field Description Values Default

1 Vlink Name The Vlink name. This value has text string blank
no impact on actual bandwidth
capping.
2 On Select true to activate this Vlink; • true false
select false to deactivate it. • false

3 Capacity (kbps) This value reflects the virtual positive integer in 50000
bandwidth cap in Kbps. When Kbps
applying this Vlink to a transfer
(e.g. Default outgoing), the
transfer's bandwidth will be
restricted by this value.
2. Apply a Vlink to a transfer
You can assign a Vlink to a global, a user, or a group settings. This example assigns a Vlink to a user's incoming
transfer session.
Bring up the Configuration window and select the Users tab, select the user to apply Vlink. In the right panel,
select the Bandwidth tab, check the option Incoming Vlink ID and select the Vlink to apply (choose ID from
drop-down list):
 | Global Transfer Settings | 79

Important: If you have a local firewall on your server (Windows firewall, Linux iptables or Mac ipfw), then
you will need to allow the Vlink UDP port (55001, by default) for multicast traffic.

Transfer Server Configuration

Set up the transfer server and more global/default settings.
Note: To configure the transfer server, you must run the application with admin or root privileges in order to
enable the Configuration screen.
To configure IBM Aspera Enterprise Server, in the application ( Start menu > All Programs > Aspera > Enterprise
Server > Enterprise Server ) click Configuration.

To configure the computer's Aspera Central transfer server, click Global tab in the left panel and select the Transfer
Server.

The Aspera Central transfer server's configuration options:

Field Description Values Default

Address This is the network interface address on which the Valid IPv4 127.0.0.1
transfer server listens. The default value 127.0.0.1 address
enables the transfer server to accept transfer requests
from the local computer; The value 0.0.0.0 allows
the transfer server to accept requests on all network
interfaces for this node. Alternatively, a specific network
interface address may be specified.
Port The port at which the transfer server accepts transfer Positive integer 40001
requests. between 1 and
65535
Persistent Storage Retain data that is stored in the database between reboots • Enable Enable
of Aspera Central.
 | Global Transfer Settings | 80

Field Description Values Default

• Disable

Files per session The maximum number of files that can be retained for Positive integer 1000
persistent storage.
Persistent Storage Path to store data between reboots of Aspera Central. Valid system path C:\Program
Path If the path is currently a directory, then a file is created Files\Aspera
with the default name central-store.db. Otherwise, the \Enterprise
file will be named as specified in the path. Server\var\
(if product is
installed in
default directory)

Maximum age Maximum allowable age (in seconds) of data to be Positive integer 86400
(Seconds) retained in the database.
Exit Central on Terminate the Aspera Central server if an error writing to • Ignore Ignore
storage error the database occurs. • Exit

Compact Enable or disable compacting (vacuuming) the database • Enable Enable

database on when the transfer server starts. • Disable
startup

For the general configuration options (Authorization, Bandwidth, Network, File Handling, and Docroot), refer to the
following sections:

Category Description
Authorization on page 64 Connection permissions, token key, and encryption requirements.
Bandwidth on page 66 Incoming and outgoing transfer bandwidth and policy settings.
Network on page 70 Network IP, port, and socket buffer settings.
File Handling on page 72 File handling settings, such as file block size, overwrite rules, and exclude
pattern.
Document Root on page 61 The document root settings.

For additional Enterprise Server features (Database Logger), refer to the following section:

Category Description
Database Logger Using a MySQL database to keep track of all transfers on your server.
 | Configuring for Other Aspera Products | 81

Configuring for Other Aspera Products

Configuring for Faspex

The steps below describe configuring IBM Aspera Enterprise Server as the transfer server for IBM Aspera Faspex.
1. Install Enterprise/Connect Server.
If you haven't already, follow the steps in Standard Installation on page 6 to install Enterprise Server (the transfer
server).
The transfer server can be set up in either of the following configurations:
• locally, on the same host as Faspex
• remotely, on a separate host

Note: For a local setup, most configuration is taken care of automatically when Faspex is installed in a
later step. For this reason, Enterprise Server/Connect Server should be installed first.
All steps must be performed with administrator permissions.
2. (LOCAL SETUP ONLY) Check aspera.conf settings and adjust if necessary.
In the aspera.conf file (C:\Program Files[ (x86)]\Aspera\Enterprise Server\etc\aspera.conf) check the
following:
• Look for <persistent_store> in the <central_server> section, and be sure that it is set to enable (default
value). This setting allows the retention of historical transfer data used by the stats collector.
• Look for the <dir_allowed> setting for the faspex user, and ensure that it's set to true.
If you change settings, you must restart asperacentral and asperanoded.
To restart these services, go to Control Panel > Administrative Tools > Services, right-click Aspera Central
and Aspera NodeD, and select Restart.
Note:
If you are installing Enterprise Server locally (on the same machine as Faspex), continue by installing
Faspex as described in the Aspera Faspex Admin Guide.
If you are setting up Enterprise Server as a remote transfer server node, continue with the steps below.

3. Create the system user on the transfer-server host.

The system user authenticates the actual ascp transfer and must be an operating system account. To create a new
system user faspex on your Windows system, go to Control Panel>User Accounts. After adding the faspex user,
change the user's password.
4. Create and configure the Faspex packages directory.
Create the directory:
C:\faspex_packages
5. Add the faspex user to Enterprise/Connect Server.
Launch the desktop application and click Configuration.
 | Configuring for Other Aspera Products | 82

In Server Configuration, select the Users tab. Then click the button.

In the Add User dialog that appears, fill in the name "faspex" and click OK; faspex is then added to the user list.
To specify a docroot, make sure faspex is selected in the user list, and open the Docroot tab in the right
panel. For the Absolute Path setting, check the Override box, and under Effective Value fill in /Users/
faspex/faspex_packages. For the read, write, and browse settings, check the Override boxes and select

true.
You can also add and configure the faspex user for Enterprise Server by modifying aspera.conf, instead of using
the application GUI. For details, see Setting Up Users on page 55.
6. Modify aspera.conf.
The aspera.conf file is found in the following location:

C:\Program Files [(x86)]\Aspera\Enterprise Server\etc\aspera.conf

Below is a typical aspera.conf file. Yours may differ, particularly if you have installed other Aspera products.
Copy any absent portions from the example below. Modify the following settings, as necessary:
• Add the Faspex package directory as a docroot. In the file below, look for the <absolute> tag to see how the
docroot has been defined in this installation, and adjust yours accordingly.
 | Configuring for Other Aspera Products | 83

• Look for the <server_name> tag, and ensure that server_ip_or_name has been replaced with the name or IP
address of your server.
• Look for <persistent_store> in the <central_server> section, and be sure that it is set to enable (the default
value).
• Look for the <dir_allowed> setting for the faspex user, and ensure that it's set to true.

<?xml version='1.0' encoding='UTF-8'?>

<CONF version="2">

<central_server>
<address>127.0.0.1</address>
<port>40001</port>
<compact_on_startup>enable</compact_on_startup>
<persistent_store>enable</persistent_store>
<persistent_store_on_error>ignore</persistent_store_on_error>
<persistent_store_max_age>86400</persistent_store_max_age>
<event_buffer_overrun>block</event_buffer_overrun>
</central_server>
<default>
<file_system>
<pre_calculate_job_size>yes</pre_calculate_job_size>
</file_system.
</default>
<aaa.
<realms>
<realm.
<users>
<user.
<name.faspex</name>
<file_system>
<access.
<paths>
<path>
<absolute.C:\faspex_packages</absolute>
<show_as>/</show_as>
<dir_allowed>true</dir_allowed>
</path>
</paths>
</access.
<directory_create_mode>770</directory_create_mode>
<file_create_mode>660</file_create_mode>
</file_system>
<authorization>
<transfer>
<in>
<value>token</value>
</in>
<out>
<value>token</value>
</out>
</transfer>
<token>
<encryption_key>af208360-dbdd-4033-a35b-2370941f37e9</
encryption_key>
</token>
</authorization>
</user>
</users>
</realm>
</realms>
</aaa>
<http_server>
 | Configuring for Other Aspera Products | 84

<http_port>8080</http_port>
<enable_http>1</enable_http>
<https_port>8443</https_port>
<enable_https>1</enable_https>
</http_server>
<server>
<server_name>server_ip_or_name</server_name>
</server>
</CONF>

After modifying aspera.conf, restart Aspera Central and Aspera NodeD services.
You can restart these services from the Windows Computer Management window, accessible from Manage >
Services and Applications > Services.

7. Verify that you have a valid transfer server license installed.

Verify that the transfer server has a valid Faspex-enabled license for Enterprise Server. To check this from the
command line, run ascp -A and review the enabled settings list. For example:

Enabled settings: connect, mobile, cargo, node, proxy,

http_fallback_server,
group_configuration, shared_endpoints, desktop_gui

If the list includes connect and http_fallback_server, you have a Faspex-enabled server license.
You can also check the license from the Enterprise Server desktop client GUI. The License dialog (Tools >
License) includes the fields Connect Clients Enabled and Http Fallback Server Enabled. If both are set to Yes,
you have a Faspex-enabled license.
Because this Faspex configuration uses Enterprise Server as a remote transfer service, it requires the Aspera Node
API. For this reason, whenever you update your Enterprise Server license (see Updating the Product License
on page 20), you must reload the asperanoded service afterwards. Reload the asperanoded service by running
asnodeadmin.exe, found in the following location:
 | Configuring for Other Aspera Products | 85

OS Version File Location

32-bit Windows C:\Program Files\Aspera\Enterprise Server\bin\asnodeadmin.exe
64-bit Windows C:\Program Files (x86)\Aspera\Enterprise Server\bin\asnodeadmin.exe

> asnodeadmin.exe --reload

8. Set up the node user.

Set up the node user and associate it with the faspex user by running the asnodeadmin command, as in the
following example--where node-admin is the node user, s3cur3_p433 is the node user's password, and faspex is
the system user. Then run asnodeadmin again to reload asperanoded.

> asnodeadmin.exe -a -u node-admin -p s3cur3_p433 -x faspex

> asnodeadmin.exe --reload

9. Install the Connect key.

First, locate your Connect key:

C:\Program Files [(x86)]\Aspera\Enterprise Server\var\aspera_id_dsa.pub

Then, create a .ssh folder (if it does not already exist) in the faspex user's home folder:

OS Version Folder Location

Windows XP C:\Documents and Settings\faspex\.ssh
Windows Vista, C:\Users\faspex\.ssh
Windows 7+

Use a text editor to create (or modify) the following file, without the file extension, in the .ssh folder:

authorized_keys

Add the faspex user's key string into this file and save it. Note that some text editors add a .txt extension to the
filename automatically. Be sure to remove the extension if it was added to the filename.
10. Ensure the firewall is set up correctly on your transfer server
For details, see Configuring the Firewall on page 13.
11. Configure your remote transfer server in the Faspex Web GUI.
Follow the instructions in Aspera Faspex Admin Guide: Transfer Server for configuring your remote transfer
server in the Faspex Web GUI underServer > File Storage.

Configuring for Shares

The steps below show how to set up IBM Aspera Enterprise Server as a transfer server for IBM Aspera Shares. The
procedure assumes you have already set up your Shares application. For general information on setting up a transfer
server (using the Node API), see Managing the Node API on page 95.
1. Install Enterprise/Connect Server.
Follow the instructions in Standard Installation on page 6 to install Enterprise Server either locally (on the same
host as Shares) or remotely.
The steps below must be performed with administrator permissions.
 | Configuring for Other Aspera Products | 86

2. Create a Node API username.

Aspera's Web applications authenticate to the remote node service using a Node API username and password. The
following command creates a Node API user/password and associates it with a file transfer user, asp1, which you
will create in the next step. The Node API credentials can then be used to create nodes. Note that different nodes
may use different Node API username/password pairs.

> asnodeadmin.exe -a -u node_api_username -p node_api_passwd -x asp1

Note that adding, modifying, or deleting a node user triggers automatic reloading of the configuration and license
files, as well as the user database.
3. Create a file transfer user.
The file transfer user authenticates the actual ascp transfer, and must be an operating system account on the
node. Create a transfer user—for example, asp1—on your operating system (Control Panel > User Accounts).
(Creating a user account requires administrator permissions.)
Note: After creating a Windows user account, log in as that user as least once in order for Windows to
set up the user's home folder—for example, C:\Users\asp1. Once the user's home folder has been
created, log back in as an administrator and continue the steps below.
After you've created the operating system account, set up this user in Enterprise Server. For instructions on setting
up a user, see .

Note: The file transfer user requires a docroot. After setting a user's docroot, be sure to perform a reload,
as described in aspera.conf for Nodes.
4. Copy the public key to the transfer user’s SSH file.
For example, if the file transfer user is asp1, the standard location for the public key is in the user's home folder,
as follows:

Windows XP, 2003 C:\Documents and Settings\asp1\.ssh\authorized_keys

Windows Vista, 2008, 7, 8 C:\Users\asp1\.ssh\authorized_keys

The Aspera-provided key file is located in:

C:\Program Files [(x86)]\Aspera\Enterprise Server\var\aspera_id_dsa.pub
Open a command prompt window and run the following commands to create the user's public key folder:

> cd user_home_folder
> md .ssh

Use a text editor to create the following file (with no file extension), if the file does not already exist:
user_home_folder\.ssh\authorized_keys
Copy the contents of aspera_id_dsa.pub to the authorized_keys file. Update the folder permissions in Windows
Explorer by right-clicking the .ssh folder, selecting Properties, and then selecting the Security tab. Here, you can
set permissions to read, write, and execute (full control).
 | Configuring for Other Aspera Products | 87

5. (Optional) Change HTTPS port and/or SSL certificate.

The Aspera Node API provides an HTTPS interface for encrypted communication between node machines (on
port 9092, by default). To modify the HTTPS port, see aspera.conf for Nodes. For information on maintaining and
generating a new SSL certificate, see Setting up SSL for your Nodes on page 101.
6. Modify aspera.conf
Make the following changes in the aspera.conf file, located in C:\Program Files [(x86)]\Aspera\Enterprise
Server\etc:
• In the <central_server> section, look for <persistent_store> and be sure that it is set to enable (the default
value). This setting allows the retention of historical transfer data used by the stats collector.
• In the <server> section, look for the <server_name> tag, and replace server_ip_or_name with the name or IP
address of your server. If the <server> section does not exist, create it.
• Ensure there is an <http_server> section and that <enable_http> and <enable_https> are set to
"1" (enabled).

<central_server>
<persistent_store>enable</persistent_store>
</central_server>
<server>
<server_name>server_ip_or_name</server_name>
</server>
<http_server>
<http_port>8080</http_port>
<enable_http>1</enable_http>
<https_port>8443</https_port>
<enable_https>1</enable_https>
</http_server>

Whenever you change these settings, you must restart asperacentral and asperanoded.
To restart these services, go to Control Panel > Administrative Tools > Services, right-click Aspera Central
and Aspera NodeD, and select Restart.
 | Configuring for Other Aspera Products | 88

7. In aspera.conf, enable token authorization for transfer users.

If you haven't done so already, set up the transfer user with an SSH public key as described in Setting Up Token
Authorization on page 143.
In your aspera.conf file, add an authorization section for a transfer user as shown for the user asp1 in the example
below. The authorization section should specify the following:
• a <transfer> section specifying that both incoming and outgoing transfers (in and out) should use token
encryption
• a <token> section with an encryption key, which is a string of random characters (at least 20 characters
recommended).

<user>
<name>asp1</name>
<authorization>
<transfer>
<in>
<value>token</value>
</in>
<out>
<value>token</value>
</out>
</transfer>
<token>
<encryption_key>gj5o930t78m34ejme9dx</encryption_key>
</token>
</authorization>
<file_system>
...
...
</file_system>
</user>

Alternatively, you can configure token-authorization settings in a <group> section to be applied to all users in the
group. Or, you can configure the settings in the <default> section to apply them globally for all users.
For additional details on configuring token authorization, see Setting Up Token Authorization on page 143.
8. Ensure that the firewall is set up correctly on your transfer server
For details, see Configuring the Firewall on page 13.

Configuring for Aspera for SharePoint

This section describes how to set up IBM Aspera Enterprise Server as a transfer server for IBM Aspera for Microsoft
SharePoint. It assumes that you have already set up your Microsoft SharePoint environment and configured
(provisioned) it for SharePoint apps.
Note: In order to use IBM Aspera Enterprise Server as the transfer server for Aspera for SharePoint, you
must run Enterprise Server on Windows 2012 or 2012 R2; or on Linux.
The basic steps are
1. Install the transfer server.
2. Create a system user on the transfer server host.
3. Log in to the host as the system user.
4. Create a folder to be the transfer user's docroot.
5. Create the SSH key for the system user.
6. Add the new system user as a transfer user to Enterprise/Connect Server.
7. Specify a docroot for the new transfer user.
 | Configuring for Other Aspera Products | 89

8. Modify aspera.conf.
9. Ensure that the firewall is set up correctly on your transfer server host.
10. Verify your transfer server license.
11. Set up a node user.
12. Configure the Aspera for SharePoint application.
These steps are described in detail below.
1. Install the transfer server.
If you haven't already, follow the steps in Standard Installation on page 6 to install Enterprise Server.
The transfer server that you will use with Aspera for SharePoint must be installed on a host separate from your
Microsoft SharePoint environment hosts.
Note: Aspera recommends you run Enterprise/Connect Server on a Linux host.

All steps must be performed with administrator permissions.

2. Create a system user on the transfer server host.
The system user authenticates the actual ascp transfer and must be an operating system account.
To create a new system user sharepoint on your Windows system, go to Control Panel > User Accounts. After
adding the sharepoint user, change the user's password.
3. Log in as the sharepoint system user.
This creates the user profile folder for this user. For example, C:Users\sharepoint.
Then log back in as administrator and continue the steps below.
4. Create a folder to be the system user's docroot.
This must be a location owned by the system user.
You will use this location later in the configuration process, at Step 7 on page 91.
5. Create the .ssh folder and public key file for the system user.
The standard location for the public key is in the user profile folder.
The Aspera-provided key file is located in:
C:\Program Files [(x86)]\Aspera\Enterprise Server\var\aspera_id_dsa.pub
1. Open a command prompt window and run the following commands to create the user's public key folder:

> cd user_profile_folder
> md .ssh
2. Use a text editor to create the following file (with no file extension), if the file does not already exist:
users_home_folder\.ssh\authorized_keys
3. Copy the contents of aspera_id_dsa.pub to the authorized_keys file.
4. Update the permissions for the .ssh folder:
In Windows Explorer, right-click the .ssh folder, and select Properties > Security. Set permissions to read,
write, and execute (full control).
 | Configuring for Other Aspera Products | 90

6. Add the sharepoint system user as a transfer user to Enterprise/Connect Server.

Note: This step can also done by modifying aspera.conf, instead of using the application GUI. For
details, see Setting Up Users on page 55.
1. Launch the Enterprise Server desktop application as administrator, and click Configuration.

2. In the Server Configuration dialog, select the Users tab. Then click the button.
 | Configuring for Other Aspera Products | 91

3. In the Add User dialog that appears, type sharepoint and click OK. The system user sharepoint is then added
to the user list.
7. Specify a docroot for the new transfer user sharepoint.
Still in the Server Configuration dialog, select the Users tab and do the following:
1. Make sure sharepoint is selected in the user list.
2. Open the Docroot tab in the right-hand panel.
3. Set the following on the Docroot tab:

Row Override Setting Effective Value Setting

Absolute Path selected (checked) /Users/sharepoint/ or whatever
location you created in Step 4 on page
89
ad Allowed selected (checked) true
Write Allowed selected (checked) true
Browse Allowed selected (checked) true

Note: This step can also be done by modifying aspera.conf, instead of using the application GUI. For
details, see Setting Up Users on page 55.
8. Modify aspera.conf.
The aspera.conf file is found in the following location:
C:\Program Files [(x86)]\Aspera\Enterprise Server\etc\aspera.conf
Below is a typical aspera.conf file. Yours may differ, particularly if you have installed other Aspera products.
1. Modify the following settings, as necessary:
• <persistent_store>
In the <central_server> section, find <persistent_store> and ensure that it is set to enable (the default
value).
This setting allows the retention of the historical transfer data that the stats collector uses.
• <transfer> and <token>
To enable token authorization for the transfer user, add an authorization section that includes:
• a <transfer> section specifying that both incoming and outgoing transfers (in and out) should use
token encryption
• a <token> section with an encryption key, which is a string of random characters (at least 20 characters
recommended).
 | Configuring for Other Aspera Products | 92

See the example below.

Note: Alternatively, you can configure token-authorization settings in a <group> section to be
applied to all users in the group. Or, you can configure the settings in the <default> section to
apply them globally for all users.
For additional details on configuring token authorization, see Setting Up Token Authorization on page
143.
• <dir_allowed>
In the <file_system> section, find <dir_allowed> and ensure that it is set to true.
• server_name
In the server section, find <server_name> and ensure that server_ip_or_name is replaced with the name
or IP address of your server.

<central_server>
<persistent_store>enable</persistent_store>
</central_server>
...
<user>
<name>sharepoint</name>
<authorization>
<transfer>
<in>
<value>token</value>
</in>
<out>
<value>token</value>
</out>
</transfer>
<token>
<encryption_key>gj5o930t78m34ejme9dx</encryption_key>
</token>
</authorization>
<file_system>
<access>
<paths>
<path>
<dir_allowed>true</dir_allowed>
</path>
</paths>
</access>
...
</user>
...
<server>
<server_name>server_ip_or_name</server_name>
</server>
2. After any change to aspera.conf, you must restart the asperacentral and asperanoded services.
To restart these services, go to Control Panel > Administrative Tools > Services, right-click Aspera Central
and Aspera NodeD, and select Restart.
9. Ensure that the firewall is set up correctly on your transfer server host.
For details, see Configuring the Firewall on page 13.
10. Verify your transfer server license.
Verify that your transfer server license is Connect Server-enabled. (Aspera for SharePoint requires a Connect
Server-enabled license.)
To check this from the command line, run ascp -A and review the enabled settings list.
 | Configuring for Other Aspera Products | 93

For example:

Enabled settings: connect, mobile, cargo, node, proxy,

http_fallback_server,
group_configuration, shared_endpoints, desktop_gui

If the list includes connect, you have a Connect Server-enabled license.

You can also check the license from the Enterprise Server desktop client GUI. The License dialog (Tools >
License) includes the Connect Clients Enabled field. If it is set to Yes, you have a Connect Server-enabled
license.
Because this Faspex configuration uses Enterprise Server as a remote transfer service, it requires the Aspera Node
API. For this reason, whenever you update your Enterprise Server license (see Updating the Product License
on page 20), you must reload the asperanoded service afterwards. Reload the asperanoded service by running
asnodeadmin.exe, found in the following location:

OS Version File Location

32-bit Windows C:\Program Files\Aspera\Enterprise Server\bin\asnodeadmin.exe
64-bit Windows C:\Program Files (x86)\Aspera\Enterprise Server\bin\asnodeadmin.exe

> asnodeadmin.exe --reload

11. Set up a node user.

A node user is the entity that Aspera's applications use for authentication between the Web application and the
transfer server.
1. Create a node user, and then associate it with the system user that you created and configured in previous steps.
Run the asnodeadmin command to
• Create the node_sharepoint node user.
• Assign a password of s3cur3_p433 to the node_sharepoint node user.
• Associate the node_sharepoint node user with the sharepoint transfer user.

> asnodeadmin.exe -a -u node_sharepoint -p s3cur3_p433 -x sharepoint

2. Reload the asperanoded service.

> asnodeadmin.exe --reload

3. Verify the node user.
Run the asnodeadmin command to
• Verify that the node user was created.
• Verify the association between the node user and the transfer user.

> asnodeadmin.exe -l

The output for this command should resemble the following:

List of node user(s):

user system/transfer user acls
==================== ======================= ====================
sharepointnode sharepoint []
spnode asp1 []

12. Configure the Aspera for SharePoint application.

 | Configuring for Other Aspera Products | 94

Add the transfer server to your Aspera for SharePoint installation, mapping it to a document library. For details,
see the IBM Aspera for Microsoft SharePoint Administrator's Guide at http://downloads.asperasoft.com/en/
downloads/47.
Note: The transfer server must be installed, configured, and running before you set up Aspera for
SharePoint.
 | Managing the Node API | 95

Managing the Node API

Managing the IBM Aspera Enterprise Server Node API

Overview: Aspera Node API

Capabilities of the Aspera Node API
The Aspera Node API is a feature of IBM Aspera Enterprise Server that provides a RESTful interface for full
programmatic control of the Aspera transfer server environment. The Node API is a daemon that supports APIs for
remote file operations, as well as initiating uploads and downloads.
The Node API includes the following features and functionality:
• An HTTPS (by default port 9092) and HTTP (by default port 9091) interface.
• An API encoded in JSON.
• The API is authenticated and the node daemon uses its own application-level users (node users).
• A node admin utility called “asnodeadmin,” which can be utilized to add and manage node users.
• It logs to C:\Program Files\Aspera\Enterprise Server\var\log or C:\Program Files
(x86)\Aspera\Enterprise Server\var\log.
You can use the Node API to set up the following configurations:
• Set up a remote transfer server for Aspera Faspex. In this configuration, the Aspera Faspex Web UI is on Machine
A, while the transfer server (an Enterprise Server node) is on Machine B. Machine A communicates with Machine
B over HTTPS, by default.
• Set up nodes for Aspera Shares. In this configuration, the Aspera Shares Web UI is on Machine A, while content
nodes (Enterprise Server nodes) are created on Machines B, C and D. Users can then be granted permission to
access specific directories (shares) on nodes B, C and D.

Node API Setup

Setting up the Aspera Node API.
To set up the Aspera Node API, follow the instructions below. These instructions assumed that you have already
installed Enterprise (or Connect) Server 3.0+.
1. Create a Node API username.
Aspera's Web applications authenticate to the remote node service using a Node API username and password. The
following command creates a Node API user/password and associates it with a file transfer user, asp1, which you
will create in the next step. The Node API credentials can then be used to create nodes. Note that different nodes
may use different Node API username/password pairs.

> asnodeadmin.exe -a -u node_api_username -p node_api_passwd -x asp1

Note that adding, modifying, or deleting a node user triggers automatic reloading of the configuration and license
files, as well as the user database.
2. Create a file transfer user.
The file transfer user authenticates the actual ascp transfer, and must be an operating system account on the
node. Create a transfer user—for example, asp1—on your operating system (Control Panel > User Accounts).
(Creating a user account requires administrator permissions.)
 | Managing the Node API | 96

Note: After creating a Windows user account, log in as that user as least once in order for Windows to
set up the user's home folder—for example, C:\Users\asp1. Once the user's home folder has been
created, log back in as an administrator and continue the steps below.
After you've created the operating system account, set up this user in Enterprise Server. For instructions on setting
up a user, see .

Note: The file transfer user requires a docroot. After setting a user's docroot, be sure to perform a reload,
as described in aspera.conf for Nodes.
3. (Optional) Change HTTPS port and/or SSL certificate.
The Aspera Node API provides an HTTPS interface for encrypted communication between node machines (on
port 9092, by default). To modify the HTTPS port, see aspera.conf for Nodes. For information on maintaining and
generating a new SSL certificate, see Setting up SSL for your Nodes on page 101.

Setting up Node Users

Using asnodeadmin to set up node users
The asnodeadmin program can be used to manage (add, modify, delete, and list) node users. For each node user,
you must indicate the following:
• Node username
• Node user's password
• Transfer/system username, which must be an operating system account on the node. This username is critical,
since it's the user who authenticates the actual ascp transfer. If the transfer user is not mapped to the node user,
then you will receive an error.
Recall in the topic "Node API Setup," we created a node user and linked this user to file transfer user "asp1." For
asnodeadmin usage, please refer to the topic "Node Admin Tool."
Important: Note that adding, modifying or deleting a node-user triggers automatic reloading of the conf and
license files, as well as the user database.

Usage Examples
(All short options; use asnodeadmin.exe -h to see the corresponding long options).
1. Add user “usr1” with password “pwd1” (will be prompted to enter if the -p option is not given) and associated
transfer/system user “aspera”:

> asnodeadmin.exe -au usr1 -x aspera [-p pwd1]

2. Add user “usr2” with password “pwd2” and associated system/transfer user “root”:

> asnodeadmin.exe -au usr2 -p pwd2 -x root

3. Modify user “usr1” by assigning it a different password, “pwd1.1”:

> asnodeadmin.exe -mu usr1 -p pwd1.1

4. List users in the current user DB:

> asnodeadmin.exe -l

5. Delete user “usr1”:

> asnodeadmin.exe -du usr1

 | Managing the Node API | 97

Node Admin Tool

Usage Instructions for asnodeadmin
The help file below displays asnodeadmin options, which can be used to configure node users.
Note: Executing asnodeadmin requires admin privileges.

> asnodeadmin.exe -h

Usage: asnodeadmin.exe [options]

Options:
-h,--help Display usage.
-A,--version Display version.
-f conf_file Conf file pathname (default: aspera.conf).
--reload Reload configuration settings, including the
conf file
(also done implicitly upon user add, modify
and delete).
-a,--add Add a user (also reloads configuration).
-d,--del[ete] Delete an existing user (also reloads
configuration).
-m,--mod[ify] Modify an existing user (also reloads
configuration).
--acl-add Add new ACLs for a user. May be used with -m
or -a.
--acl-set Sets ACLs (clears old ACLs) for a user. May
be used with -m or -a.
--acl-del Deletes ACLs for a user. May be used with -m.
--acl-list Lists all current ACLs for a user.
--internal Required for adding, modifying, or deleting
internal users.
-l,--list List users.
-u,--user=username Specify username.
-p,--{pwd|password}=passwd Specify password.
-x,--xuser=xfer_username Specify system transfer user.
-b,--backup=filename Back_up user data to a file.
-r,--restore=filename Restore user data from a file.
-P Display hashed passwords as well when listing
users.
-L local_log_dir Local logging directory (default: no logging).
-D... Debug level (default: no debug output).
--transfer-log-del xnid Delete an individual transfer from the activity
log.
--transfer-log-cleanup Delete all transfers from the activity log
older than activity_retention_hrs.
--db-shutdown Shut down the database.

aspera.conf for Nodes

Editing aspera.conf for your node configuration.
In your aspera.conf file, use the <server> section (shown below) to configure your node machines. The aspera.conf
file is found in the following location:

OS Version File Location

32-bit Windows C:\Program Files (x86)\Aspera\Enterprise Server\etc\aspera.conf
 | Managing the Node API | 98

OS Version File Location

64-bit Windows C:\Program Files\Aspera\Enterprise Server\etc\aspera.conf

Note: Each of the settings below requires certain services to be restarted in order for any changes to take
effect. The services to restart are noted in the To Activate Changes column in the table below, and the
commands to restart these services are given at the end of this topic.

<server>
<server_name>your_hostname</server_name>
<!-- hostname or IP address -->
<http_port>9091</http_port>
<!-- integer (1 - 65535) -->
<https_port>9092</https_port>
<!-- integer (1 - 65535) -->
<enable_http>false</enable_http>
<!-- true | false -->
<enable_https>true</enable_https>
<!-- true | false -->
<cert_file> <!-- full path; .chain file same /path/filename -->
C:\Program Files\Aspera\Enterprise Server\etc\aspera_server_cert.pem
</cert_file>
<max_response_entries>1000</max_response_entries>
<!-- max entries to return in response -->
<max_response_time_sec>10</max_response_time_sec>
<!-- max seconds to wait for long operation -->
<db_dir>C:\Program Files\Aspera\Enterprise Server\var</db_dir>
<!-- path to dir where DB file will be saved -->
<db_port>31415</db_port>
<!-- integer (1 - 65535) -->
<enable_sslv2>true</enable_sslv2>
<!-- boolean true or false -->
<ssl_ciphers>TLS_ECDHE_RSA_WITH_AES_128_CBC_SHA:...</ssl_ciphers>
<!-- ssl_ciphers: see full default list in table
below -->
<ssl_protocol>sslv23</ssl_protocol>
<!-- sslv3, sslv23, tlsv1, tlsv1.1, or tlsv1.2 -->
</server>

Setting Description Default Value To

Activate
Changes...
<server_name> Hostname or IP address. hostname Restart
node
service
<http_port> HTTP service port. 9091 Restart
node
service
<https_port> HTTPS service port. 9092 Restart
node
service
<enable_http> Enable HTTP for the Node API false Restart
services. node
service
 | Managing the Node API | 99

Setting Description Default Value To

Activate
Changes...
<enable_https> Enable HTTPS for the Node API true Restart
services. node
service
<cert_file> Full pathname of SSL certificate C:\ Program Files [(x86)]\Aspera Restart
(.pem and existing support for \Enterprise Server\etc node
.chain). \aspera_server_cert.pem service
<max_response_entries> Maximum number of entries to 1000 Reload
return in a response.. node
configuration.
<max_response_time>s Maximum amount of time to wait 10 Reload
for a long-running operation. node
configuration.
<db_dir> Path to the directory where the C:\Program Files [(x86)]\Aspera Restart
database file is saved. Before \Enterprise Server\var the node
changing this value, you should and DB
back up your database. See Redis services.
DB Backup/Restore on page
101.
<db_port> Database service port. Before 31415 Restart
changing this value, you should the node
back up your database. See Redis and DB
DB Backup/Restore on page services.
101.
<ssl_ciphers> The SSL encryption ciphers All of the following: Restart
that the server will allow, each node
separated by a colon (:). This TLS_ECDHE_RSA_WITH_AES_128_CBC_SHA
service.
option may also be set in the TLS_ECDHE_RSA_WITH_AES_256_CBC_SHA
<client> section, in which case, TLS_ECDHE_RSA_WITH_3DES_EDE_CBC_SHA
when this machine functions as DHE-RSA-AES256-SHA
a client, the specified ciphers DHE-DSS-AES256-SHA
AES256-SHA
are requests to the server. If any
AES128-SHA256
of the ciphers in the server's DHE-RSA-AES128-SHA
allow list coincide with those DHE-DSS-AES128-SHA
in the client's request list, RC2-CBC-MD5
communication is allowed;
otherwise it is denied.
If you override this setting,
the override is always used.
However, if you do not override
it, the default setting depends on
the settings for <ssl_protocol>.
If <ssl_protocol> is set to sslv23,
then a large, relatively weak
selection of suites is allowed.
If the protocol is anything else,
then a smaller, stronger selection
of suites is allowed. Many older
web browsers cannot handle
 | Managing the Node API | 100

Setting Description Default Value To

Activate
Changes...
the stronger set of suites, in
which case you may encounter
compatibility issues.

<ssl_protocol> The SSL protocol versions that sslv23 Restart

the server will allow. This option node
may also be set in the <client> service.
section, in which case, when this
machine is a client, the specified
protocols function as requests to
the server. If any of the protocols
in the server's allow list coincide
with those in the client's request
list, communication is allowed;
otherwise it is denied.
Supported values: sslv3, tlsv1,
tlsv1.1, tlsv1.2, and sslv23.
Despite its name, specifying
sslv23 (the default) allows all
supported protocols, including all
TLS versions.

<enable_sslv2> Setting to true (default) enables true Restart

SSLv2. If <ssl_protocol> node
is not set (or is explicitly set service.
to its default sslv23), setting
<enable_sslv2> to false allows
only SSLv3 and TLSv1.x—that
is, all protocols except SSLv2.
If <ssl_protocol> is set to any
value other than sslv23, settings
for <enable_sslv2> settings have
no effect.

Note: Executing the commands below requires admin privileges.

Restarting the Node Service

> sc stop asperanoded

> sc start asperanoded

Reloading the Node Configuration

> asnodeadmin.exe --reload

Restarting the Node and DB Services

> sc stop asperanoded

> asnodeadmin.exe --db-shutdown
 | Managing the Node API | 101

> sc start asperanoded

Note: The DB service is started automatically when you restart the node service.

Redis DB Backup/Restore
Instructions for backing up and restoring the database.
To back up and restore the Redis database (and your user data up to the point-in-time of the backup operation), follow
the instructions below. Note that the backup and restore operations should be used for the following scenarios:
• If you need to change the Redis database port number (<db_port/> in aspera.conf), you should first back up
the Redis database. Once you have changed the port number, you need to restore the database.
• Basic backup and restore (after a data-loss event).
1. Back up the Redis database.
Use the following command to back up your Redis database (before changing the port number):

> asnodeadmin.exe -b C:\your\backup\dir\database.backup

Important: When backing up the Redis database, all user data up to that point-in-time will be saved to
the backup file. Restoring the database (see Step 2, below) does not delete users added after this snapshot
was taken. Thus, if you added any users after backing up the database, then they will still exist in the
system and will not be affected by the restore operation.
2. Restore the Redis database.
Use the following command to restore your Redis database:

> asnodeadmin.exe -r C:\your\backup\dir\database.backup

Recall the "Important Note" in Step 1, which stated that restoring the database does not delete users added after
the database snapshot was taken. If you do not want to keep users that have been added since the last backup
operation, you can delete them after performing the restore with the asnodeadmin command -du username.
3. Restart the asperanoded service.
Use the following command(s) to restart the asperanoded service (requires a restart rather than a reload):
Windows 32-bit

C:\Program Files (x86)\Aspera\Enterprise Server\bin> sc stop asperanoded

C:\Program Files (x86)\Aspera\Enterprise Server\bin> sc start asperanoded

Windows 64-bit

C:\Program Files\Aspera\Enterprise Server\bin> sc stop asperanoded

C:\Program Files\Aspera\Enterprise Server\bin> sc start asperanoded

Setting up SSL for your Nodes

Communicating with Aspera nodes over HTTPS
The Aspera Node API provides an HTTPS interface for encrypted communication between node machines (on Port
9092, by default). For example, if you are running the Faspex Web UI or the Shares Web UI on Machine A, you can
encrypt the connection (using SSL) with your transfer server or file-storage node on Machine B. Enterprise Server
nodes are pre-configured to use Aspera's default, self-signed certificate (aspera_server_cert.pem), located in
the following directory:
 | Managing the Node API | 102

• (Windows 32-bit) C:\Program Files (x86)\Aspera\Enterprise Server\etc

• (Windows 64-bit) C:\Program Files\Aspera\Enterprise Server\etc
To generate a new certificate, follow the instructions below.
About PEM Files: The PEM certificate format is commonly issued by Certificate Authorities. PEM certificates
have extensions that include .pem, .crt, .cer, and .key, and are Base-64 encoded ASCII files containing "-----BEGIN
CERTIFICATE-----" and "-----END CERTIFICATE-----" statements. Server certificates, intermediate certificates, and
private keys can all be put into the PEM format.
1. Create a working directory
In a Command Prompt window (Start menu > All Programs > Accessories > Command Prompt), create a new
working directory as follows:

> cd c:\
> mkdir ssl
> cd c:\ssl

2. Copy openssl.cnf to your working directory

Enter the following commands in your Command Prompt window:

OS Version Commands
32-bit Windows
> copy "C:\Program Files (x86)\Common Files\Aspera\common
\apache\conf\openssl.cnf" "C:\ssl\"
> cd C:\ssl

64-bit Windows
> copy "C:\Program Files\Common Files\Aspera\common\apache
\conf\openssl.cnf" "C:\ssl\"
> cd C:\ssl

3. Enter the OpenSSL command to generate your Private Key and Certificate Signing Request
In this step, you will generate an RSA Private Key and CSR using OpenSSL. In a Command Prompt window,
enter the following command (where my_key_name.key is the name of the unique key that you are creating and
my_csr_name.csr is the name of your CSR):

> openssl req -config "c:\ssl\openssl.cnf" -new -nodes -

keyout my_key_name.key -out my_csr_name.csr

Note that in the example above, the .key and .csr files will be written to the c:\ssl\ directory.
4. Enter your X.509 certificate attributes
After entering the command in the previous step, you will be prompted to input several pieces of information,
which are the certificate's X.509 attributes.
Important: The common name field must be filled in with the fully qualified domain name of the server
to be protected by SSL. If you are generating a certificate for an organization outside of the US, see http://
www.iso.org/iso/english_country_names_and_code_elements for a list of 2-letter, ISO country codes.

Generating a 1024 bit RSA private key

....................++++++
................++++++
writing new private key to 'my_key_name.key'
-----
You are about to be asked to enter information that will be incorporated
into your certificate request.
 | Managing the Node API | 103

What you are about to enter is what is called a Distinguished Name or a

DN.
There are quite a few fields but you can leave some blank
For some fields there will be a default value,
If you enter '.', the field will be left blank.
-----
Country Name (2 letter code) [US]:Your_2_letter_ISO_country_code
State or Province Name (full name) [Some-
State]:Your_State_Province_or_County
Locality Name (eg, city) []:Your_City
Organization Name (eg, company) [Internet Widgits Pty Ltd]:Your_Company
Organizational Unit Name (eg, section) []:Your_Department
Common Name (i.e., your server's hostname) []:secure.yourwebsite.com
Email Address []:[email protected]

You will also be prompted to input "extra" attributes, including an optional challenge password. Please note that
manually entering a challenge password when starting the server can be problematic in some situations (e.g.,
when starting the server from the system boot scripts). You can skip inputting a challenge password by hitting the
"enter" button.

...
Please enter the following 'extra' attributes
to be sent with your certificate request
A challenge password []:
An optional company name []:

After finalizing the attributes, the private key and CSR will be saved to your root directory.
Important: If you make a mistake when running the OpenSSL command, you may discard the generated
files and run the command again. After successfully generating your key and Certificate Signing Request,
be sure to guard your private key, as it cannot be re-generated.
5. Send CSR to your signing authority
You now need to send your unsigned CSR to a Certifying Authority (CA). Once completed, you will have valid,
signed certificate.
Important: Some Certificate Authorities provide a Certificate Signing Request generation tool on their
Website. Please check with your CA for additional information.
6. (Optional) Generate a Self-Signed Certificate.
At this point, you may need to generate a self-signed certificate because:
• You don't plan on having your certificate signed by a CA
• Or you wish to test your new SSL implementation while the CA is signing your certificate
You may also generate a self-signed certificate through OpenSSL. To generate a temporary certificate (which is
good for 365 days), issue the following command:

openssl x509 -req -days 365 -in my_csr_name.csr -signkey my_key_name.key -

out my_cert_name.crt

7. Create the PEM file.

After generating a new certificate, you must create a pem file that contains both the private key and the
certificate. To do so, copy and paste the entire body of the key and cert files into a single text file and save
the file as aspera_server_cert.pem (before overwriting, be sure to back-up the existing pem file as
aspera_server_cert.old), in the following directory:
• (Windows 32-bit) C:\Program Files\Aspera\Enterprise Server\etc
• (Windows 64-bit) C:\Program Files (x86)\Aspera\Enterprise Server\etc
8. Enable SSL options in aspera.conf
 | Managing the Node API | 104

See aspera.conf for Nodes on page 97 for information about enabling specific SSL protocols with
<ssl_protocol> and enabling specific encryption ciphers with <ssl_ciphers>.
9. Restart the node service.
You must restart (not reload) the Aspera node service after generating a new certificate. To do so, run the
following command(s):
Windows 32-bit

C:\Program Files\Aspera\Enterprise Server\bin> sc stop asperanoded

C:\Program Files\Aspera\Enterprise Server\bin> sc start asperanoded

Windows 64-bit

C:\Program Files (x86)\Aspera\Enterprise Server\bin> sc stop asperanoded

C:\Program Files (x86)\Aspera\Enterprise Server\bin> sc start asperanoded
 | Hot Folders | 105

Hot Folders
Set up the folder synchronization through the FASP transfers.

Setting Up Hot Folders

Configure a local and a remote folder for sychronization.
With hot folders, you can monitor selected (and configured) folders for changes and automatically transfer new
or modified files. Hot folders can be used for one-way replication between two locations or simply as a way
of forwarding files in your workflow. The hot folders feature uses Aspera Sync, which runs as a service in the
background.
To set up the hot folders, use the file browser in the application ( Start menu > All Programs > Aspera > Enterprise
Server > Enterprise Server ) to navigate into the path you wish to set up as the hot folder. Right-click the panel
and select New > Hot Folder to bring up the New Hot Folder dialog. You can also launch it from File > New > Hot
Folder.

The New Hot Folder window includes the following configuration tabs:

Tab Description
Hot Folder Set up the source, the destination, and the synchronization interval.
Transfer The transfer speed and transfer policy.
Tracking Turn on and configure email notification(s) for transfer start, completion and/or error.
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.

Hot Folder

Option Description
Name The hot folder's name. Use the default name or enter your own. The default name is the
name of the Windows folder.
Source Specify the source for the hot folders.
 | Hot Folders | 106

Option Description
Destination Specify the destination for the hot folders.
Send Changes Select when to perform the synchronization. Use Send immediately to synchronize
whenever a file in the folder is changed. Use Daily at to specify a daily time to synchronize.
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.
Use the Periodic scan interval to specify the regularity Aspera Drive scans your hot folders
for updates and changes.
Note: In some scenarios when file notification is not available, this feature must be
activated in order to detect file changes in your hot folders.

Generate This button restores the default setting (if the field was cleared or modified).

Transfer

Option Description
Policy Set the FASP transfer policy.
• fixed – Attempts to transfer at the specified target rate, regardless of the actual
network capacity. This policy transfers at a constant rate and finishes in a guaranteed
time. This policy typically occupies most of the network's bandwidth, and is not
recommended in most file transfer scenarios. In fixed mode, a maximum (target) rate
value is required.
• high – Monitors the network and adjusts the transfer rate to fully utilize the available
bandwidth up to the maximum rate. When congestion occurs, a it transfers at a rate twice
of a session with fair policy. In this mode, both the maximum (target) and the minimum
transfer rates are required.
• fair – Monitors the network and adjusts the transfer rate to fully utilize the available
bandwidth up to the maximum rate. When other types of traffic build up and congestion
occurs, it shares bandwidth fairly by transferring at an even rate. In this mode, both the
maximum (target) and the minimum transfer rates are required.
• low – Similar to fair mode, the low policy uses the available bandwidth up to the
maximum rate, but is much less aggressive when sharing bandwidth with other network
traffic. When congestion builds up, the transfer rate is reduced to the minimum rate until
other traffic retreats.
Important: If --policy is not set, ascp uses the server-side policy setting (fair by
default).

Speed Check this option to specify the transfer rate.

Tracking

Option Description
Send Email Check this box to enable email notifications and to display configuration options. Note that
Notifications notifications are not sent until they are enabled under "Preferences." Please refer to the topic
Configuring Transfer Notifications on page 42 for details.
Important: For hot folder email notifications to work, the GUI has to remain
open.
 | Hot Folders | 107

Option Description
When (not displayed Select one or more events that trigger the notification (transfer start, completion and/or
until checkbox is error).
enabled)
To (not displayed Enter recipients' email address(es).
until checkbox is
enabled)
Template (not Select a notification template from the drop-down list. You may add, delete, edit and
displayed until preview templates by clicking the "Manage Templates" button.
checkbox is enabled)
Message (not Include a custom message with the notification.
displayed until
checkbox is enabled)

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. As shown below, the asterisk (*)
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.

Examples:

Filter Pattern Matched files

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

Note: The temporary files used by Aspera to resume incomplete files are ignored according to the resume
suffix setting of the sender. For more information about the resume suffix, see File Handling on page 72.

Security

Option Description
Encryption When checked, FASP encrypts files while transferring. Encryption may decrease
performance, especially at higher transfer speeds and with slower computers.
Content Protection Two options: Encrypt uploaded files with a password encrypts the uploaded files with
the specified password. The protected file has the extension .aspera-env appended to the file
name; Decrypt password-protected files downloaded prompts for the decryption password
when downloading encrypted files.
 | Hot Folders | 108

File Handling

Option Description
Resume Check Resume incomplete files to enable the resume feature. In the When checking files for
differences options: Compare file attributes only checks if the existing file is the same size;
Compare sparse file checksums performs a sparse checksum on the existing file. Compare
full file checksums perform a full checksum on the existing file.
File Attributes Check Preserve file timestamps to preserve the transferred files' timestamps.
Source Deletion Check Automatically delete source files after transfer to delete the successfully-
transferred files from the source. Check Delete source directories to also remove the folder.
Source Move To move source files to a separate location after a successful transfer, check Automatically
move source files to a directory after transfer and specify the location.
Note: Only a path to an existing location on the client can be specified.
Note: The GUI has no option to delete empty source subdirectories that may remain after
source files are moved.

Important: If you are using a transfer proxy or an HTTP proxy, the hot folders feature uses global proxy
settings only, not the My Preferences proxy settings. For information about enabling a proxy server, see
Enabling a Transfer or HTTP Proxy on page 33.

Note: Any empty folders created in a hot folder are not pushed to the server. However, empty folders that
have been created on the server are pulled to the local destination.

Caution: If File Manifest is enabled, it's a good idea to set the manifest path (Configuration > File
Handling) to some location other than the hot folder location itself, which is the default location for manifest
files. If manifest files are generated to the hot folder location, the manifest files will themselves be treated as
source and transferred, generating yet another manifest file, and the cycle will continue until stopped. You can
also prevent manifest files from being transferred by using the hot-folder Filter tab and specifying which files
should be ignored for hot-folder transfers, *.manifest.txt, for example.

Managing Hot Folders

Monitor and control the configured Hot Folders.
You can manage created Hot Folders in the Hot Folders panel:

In the Hot Folders panel, you can monitor the synchronization status, and use the , , and buttons to control the
Hot Folders' transfer.
To edit existing Hot Folders, right-click the entry in the Hot Folders panel and select Edit... . You can also create a
new one by selecting New....
| Hot Folders | 109
 | Pre- and Post-Processing (Prepost) | 110

Pre- and Post-Processing (Prepost)

Execute scripts before and after the FASP file transfers on your server.

Setting Up Pre/Post
Enable the pre- and post-processing on your server.
Your Aspera server executes a batch script at a pre-defined location.

OS Version Path
32-bit Windows C:\Program Files (x86)\Aspera\Enterprise Server\var
64-bit Windows C:\Program Files\Aspera\Enterprise Server\var

This script is executed as a result of four (4) transfer events:

• Session start
• Session end
• Start of each individual file transfer in the session
• End of each individual file transfer in the session
aspera-prepost.bat can also execute additional batch scripts, Perl scripts, native executables and Java programs.
Aspera sets several environment variables for aspera-prepost.bat, as well as for you to use in your own, custom
scripts. These environment variables are described in detail within the topic Pre/Post Variables on page 111.
Depending on usage, pre_ and post_processing may consume a great amount of system resources. Please evaluate
your own system performance and apply this feature appropriately.
Caution: Please take caution in creating pre- and post-processing scripts, as an unsafe script can compromise
a server. As with CGI scripts, it is recommended that you take precautions in testing a pre/post script before
placing it into use (e.g., taint checking, ensuring proper quotes, etc.). Also note that a pre/post script will run
as the same user who authenticates for the transfer. To prevent a pre/post script from performing an action
with elevated or special user permissions, the script needs to check the $USER variable.
Follow the steps below to set up pre/post processing for your Aspera transfer product.
1. (Optional) Install Perl-script Support
Pre- and post-processing supports the Perl programming language. In a Command Prompt window (Start menu >
All Programs > Accessories > Command Prompt), use the following command to verify if Perl is supported on
your system:

> perl -v

If Perl is supported by your system, you will see a confirmation message displaying the Perl version. If Perl is not
supported, and you would like to use Perl scripts in your pre/post processing, you can download and install Active
Perl from the link http://www.activestate.com/store/activeperl/download/.
2. Set up the batch script file
Navigate to the following directory:

OS Version Path
32-bit Windows C:\Program Files (x86)\Aspera\Enterprise Server\var
64-bit Windows C:\Program Files\Aspera\Enterprise Server\var
 | Pre- and Post-Processing (Prepost) | 111

Locate the following file:

aspera-prepost-email.bat

Important: This file runs the perl script aspera-notif.pl, which is an email notification script that
sends email messages (according to user-defined filters) to recipients. Filters and lists are defined in the
Aspera configuration file aspera.conf, located in \Aspera\Enterprise Server\etc\.
Copy the contents of aspera-prepost-email.bat into a new file, and name it as follows:
aspera-prepost.bat
3. Create your scripts
The pre/post processing script, aspera-prepost.bat, can contain the pre/post processing steps, as well as execute
other programs (including other .bat scripts). Often, aspera-prepost.bat checks for certain conditions (based on the
environment variables) and then calls a specific external executable based on those conditions. Recall that aspera-
prepost.bat is executed as a result of four (4) transfer events:
• Session start
• Session end
• Start of each individual file transfer in the session
• End of each individual file transfer in the session
You can use the variables TYPE and STARTSTOP to specify a particular state. For the complete list of all
variables, refer to Pre/Post Variables on page 111.
4. Include custom commands in aspera-prepost.bat
As a best practice, store your custom scripts in the following directory:

OS Version Path
32-bit Windows C:\Program Files (x86)\Aspera\Enterprise Server\custom
64-bit Windows C:\Program Files \Aspera\Enterprise Server\custom

When you create custom scripts, move them into the suggested directory and add the scripts (as commands) to
the file aspera-prepost.bat. For example, to add the custom script "script1.pl" to your pre/post script, insert the
following line (into aspera-prepost.bat):

...
c:\Perl\bin\perl.exe ..\custom\script1.pl
...

Pre/Post Variables
The predefined variables for setting up the pre- and post-processing.
The following tables list all pre/post variables:
Note: Pre/post variables are case-sensitive.

For Type Session and Type File

Variable Description Values Example

COOKIE The user-defined cookie string. string "%COOKIE%" == "cookie-
string"
 | Pre- and Post-Processing (Prepost) | 112

Variable Description Values Example

DIRECTION The transfer direction. • send "%DIRECTION%" == "send"
• recv

ERRCODE The error code. string "%ERRCODE%" == "1"

ERRSTR The error string. string "%ERRSTR%" == "FASP
error"
MANIFESTFILE The full path to the manifest file. string "%MANIFESTFILE%" == "c:
\log"
PEER The peer name or IP address. string or valid "%PEER%" == "10.0.0.1"
IPv4 address
SECURE Transfer encryption. • yes "%SECURE%" == "no"
• no

SESSIONID The session id. string "%SESSIONID%" == "1"

STARTSTOP The status start or stop. • Start "%STARTSTOP%" == "Start"
• Stop

STATE The transfer state. • started "%STATE%" == "success"

• success
• failed

TOKEN The user-defined security token. string "%TOKEN%" == "token-

string"
TYPE The event type. • Session "%TYPE%" == "Session"
• File

USER The user name string "%USER%" == "asp1"

USERSTR The user string, such as additional string "%USERSTR%" == "-q"
variables.

For Type Session

Variable Description Values Example

FILE_CSUM Destination checksum of the most string "%FILE_CSUM%" ==
recently transferred file. "checksum"
FILE1 The first file. string "%FILE1%" == "first-file"
FILE2 The second file. string "%FILE2%" == "second-file"
FILECOUNT The number of files. positive "%FILECOUNT%" >= "5"
integer
FILELAST The last file. string "%FILELAST%" == "last-file"
LICENSE The license account and serial number. string "%LICENSE%" == "license-
string"
MINRATE The initial minimum rate, in Kbps. positive "%MINRATE%" == "50"
integer
 | Pre- and Post-Processing (Prepost) | 113

Variable Description Values Example

PEERLICENSE The peer's license account and serial string "%PEERLICENSE%" ==
number. "license-string"
RATEMODE The transfer policy. • adapt "%RATEMODE%" == "adapt"
• fixed

SOURCE The full path of the source file. string "%SOURCE%" == "C:\tmp"
TARGET The full path of the target directory. string "%TARGET%" == "."
TARGETRATE The initial target rate, in Kbps. positive "%TARGETRATE%" == "100"
integer
TOTALBYTES The total bytes transferred. positive "%TOTALBYTES%" >=
integer "100000000"
TOTALSIZE The total size of files being transferred positive "%TOTALSIZE%" >=
in bytes. integer "500000000"

For Type File

Variable Description Values Example

DELAY The measured network delay, in positive integer "%DELAY%" <= "1"
ms.
FILE The file name. string "%FILE%" == "file-name"
LOSS The network loss in percentage. double-digit fixed point value "%LOSS%" >= "5.00"
OVERHEAD The total number of duplicate positive integer "%OVERHEAD%" >= "1"
packets.
RATE The transfer rate in Kbps. double-digit fixed point value "%RATE%" >= "10.00"
REXREQS The total number of positive integer "%REXREQS%" >= "3"
retransmission requests.
SIZE The file size in bytes. positive integer "%SIZE%" >= "5000000"
STARTBYTE The start byte if resumed. positive integer "%STARTBYTE%" >=
"100000"

Pre/Post Examples
Pre- and post-processing script examples.

1. Windows batch - Call the Email Notification when files are transferred to a specified host
In Windows batch, call the Email notification function only on files that are destined for a specific host
10.0.114.111:

set DESTINATION=10.0.114.111
if "%TYPE%" == "Session" (
if "%STARTSTOP%"=="Stop" (
if "%PEER%" == "%DESTINATION%" (
"C:\Perl\bin\perl.exe" aspera-notif.pl > nul 2>&1
)
)
 | Pre- and Post-Processing (Prepost) | 114

2. Windows batch - Call the Email Notification when files are larger than 1GB
In Windows batch, call the Email Notification only when the files are larger than 1GB (1073741824 bytes):

set FILESIZE=1073741824
if "%TYPE%" == "Session" (
if "%STARTSTOP%"=="Stop" (
if %TOTALSIZE% GEQ %FILESIZE% (
"C:\Perl\bin\perl.exe" aspera-notif.pl > nul 2>&1
)
)
)

3. Windows batch - Combine the two examples above

In a Windows batch file, call the Email notification function on files that are later than 1GB (1073741824 bytes),
and destined for a specific host 10.0.114.111:

set FILESIZE=1073741824
set DESTINATION=10.0.114.111
if "%TYPE%" == "Session" (
if "%STARTSTOP%"=="Stop" (
if %TOTALSIZE% GEQ %FILESIZE% (
if "%PEER%" == "%DESTINATION%" (
"C:\Perl\bin\perl.exe" aspera-notif.pl > nul 2>&1
)
)
)
)

Setting Up Email Notification

Configure the email notification, a prepost application.
Email Notification is a built-in Pre- and Post-Processing application that generates customized emails based on
transfer events. Your server should have Pre- and Post-Processing configured in order to run this application. Refer
to Setting Up Pre/Post on page 110. Email Notification requires an SMTP server that matches the following
configurations:
• An open SMTP server you can reach on your network
• The SMTP Server must not use any external authentication or SSL.
Follow these steps to set it up:
1. Prepare the Email Notification configuration template
Open the aspera.conf file:

OS Version File Path

32-bit Windows C:\Program Files (x86)\Aspera\Enterprise Server\etc\aspera.conf
64-bit Windows C:\Program Files\Aspera\Enterprise Server\etc\aspera.conf

Locate or create the section <EMAILNOTIF>...</EMAILNOTIF>:

<CONF version="2">
...
<EMAILNOTIF>
<MAILLISTS
 | Pre- and Post-Processing (Prepost) | 115

mylist = "[email protected], [email protected]"

myadminlist = "[email protected]"
/>

<FILTER
MAILLISTS = "mylist"
TARGETDIR = "/content/users"
/>

<MAILCONF
DEBUG = "0"
FROM = "[email protected]"
MAILSERVER = "mail.example.com"
SUBJECT = "Transfer %{SOURCE} %{TARGET} - %{STATE}"
BODYTEXT =
"Aspera transfer: %{STATE}%{NEWLINE}%{TOTALBYTES} bytes in
%{FILECOUNT} files: %{FILE1}, %{FILE2}, ...%{FILELAST}."
/>
</EMAILNOTIF>
</CONF>

You can find the aspera.conf example in this path:

OS Version File Path

32-bit Windows C:\Program Files (x86)\Aspera\Enterprise Server\etc\samples\aspera-email-sample.conf
64-bit Windows C:\Program Files\Aspera\Enterprise Server\etc\samples\aspera-sample-email.conf
2. Set up the basic Notification function in <MAILCONF />
<MAILCONF /> defines the general email configuration, including the sender, the mail server, and the body text.
In the SUBJECT and BODYTEXT options, the Pre- and Post-Processing variables can be used with the format
%{variable}, such as %{STATE} for the variable STATE. For the complete list of the variables, Refer to Pre/Post
Variables on page 111.

MAILCONF Field Description Values Example

FROM Required The e-mail a valid email FROM="[email protected]"
address to send notifications address
from.
MAILSERVER Required The outgoing A valid URL MAILSERVER="mail.example.com"
mail server (SMTP).
SUBJECT General subject of the e- text string SUBJECT="Transfer:%{STATE}"
mail.
BODYTEXT General body of the e-mail. text string BODYTEXT="Transfer has %{STATE}."
DEBUG Print debugging info and "0" = off, "1" DEBUG="0"
write to the logs. = on
3. Create mailing lists in <MAILLISTS />
<MAILLISTS /> defines sets of mailing lists. For example, to create the following mailing list:

Item Value
Mailing list name list1
Emails to include [email protected], [email protected]
 | Pre- and Post-Processing (Prepost) | 116

Specify the mailing list in the form:

<MAILLISTS
list1 = "[email protected], [email protected]"
/>

4. Set up mailing filters in <FILTER />

<FILTER /> defines E-mail Notification conditional filters. When the conditions are met, a customized email will
be sent to the indicated mailing list. Multiple filters are allowed.
The values in the filter are matched as substrings, for example, USER = root means the value would match strings
like root, treeroot, and root1. The Pre- and Post-Processing variables can be used with the format %{variable},
such as %{STATE} for the variable STATE. For the complete list of the variables, Refer to Pre/Post Variables on
page 111.

FILTER Field Description Values Example

MAILLISTS Required The e-mail lists to send to. text string MAILLISTS="mylist"
Separate lists with comma (,).
USER Login name of the user who text string USER="asp1"
transferred the files.
SRCIP Source IP of the files. a valid IPv4 SRCIP="10.0.1.1"
address
DESTIP Destination IP of the files. a valid IPv4 DESTIP="10.0.1.5"
address
SOURCE The top-level directories and files text string SOURCE="/folder1"
that were transferred.
TARGETDIR The directory that the files were sent text string TARGETDIR="/folder2"
to.
SUBJECTPREFIX The Email subject, preceded by the text string SUBJECTPREFIX="Sub"
SUBJECT in <MAILCONF />.
BODYPREFIX The e-mail body, preceded by the text string BODYPREFIX="Txt"
BODYTEXT in <MAILCONF />.
TOTALBYTESOVER Send e-mail when total bytes positive TOTALBYTESOVER="9000"
transferred is over this number. This integer
only applies to e-mails sent at the end
of a transfer.
SENDONSESSION Send e-mail for the entire session. yes / no SENDONSESSION="yes"
SENDONSTART Send e-mail when transfer is yes / no SENDONSTART="yes"
started. This setting is dependent on
SENDONSESSION="yes".
SENDONSTOP Send e-mail when transfer is yes / no SENDONSTOP="yes"
stopped. This setting is dependent on
SENDONSESSION="yes".
SENDONFILE Send e-mail for each file within a yes / no SENDONFILE="yes"
session.
 | Pre- and Post-Processing (Prepost) | 117

Email Notification Examples

Email Notification configuration examples.
This topic demonstrates the Email Notification setup with the following examples:
1. Notify when a transfer session is completed
When a transfer session is finished, an e-mail with brief session summary will be sent to "list1".

<EMAILNOTIF>
<MAILLISTS
list1 ="[email protected], [email protected]"
/>

<MAILCONF
FROM="Aspera Notifier &lt;[email protected]&gt;"
MAILSERVER="smtp.companyemail.com"
BODYTEXT="%{NEWLINE}Powered by Aspera Inc."
/>

<FILTER
MAILLISTS="list1"
SENDONSESSION="yes"
SUBJECTPREFIX="Aspera Transfer - %{USER} "
BODYPREFIX="Status: %{STATE}%{NEWLINE} File Count: %{FILECOUNT}"
/>
</EMAILNOTIF>

2. Notify when a session is initiated and completed

Send a transfer notice e-mail when a transfer is initiated. Send a summary e-mail when finished.

<EMAILNOTIF>
<MAILLISTS
list1 ="[email protected], [email protected]"
/>
<MAILCONF
FROM="Aspera Notifier &lt;[email protected]&gt;"
MAILSERVER="smtp.companyemail.com"
SUBJECT=" by %{USER}"
BODYTEXT="%{NEWLINE}Powered by Aspera Inc."
/>

<FILTER
MAILLISTS="list1"
SENDONSTART="yes"
SENDONSTOP="no"
SUBJECTPREFIX="Transfer Started"
BODYPREFIX="Source: %{PEER}%{NEWLINE} Target: %{TARGET}"
/>

<FILTER
MAILLISTS="list1"
SENDONSTART="no"
SENDONSTOP="yes"
SUBJECTPREFIX="Transfer Completed"
BODYPREFIX="
Status: %{STATE}%{NEWLINE}
File Count: %{FILECOUNT}%{NEWLINE}
Source: %{PEER}%{NEWLINE}
Target: %{TARGET}%{NEWLINE}
Bytes Transferred: %{TOTALBYTES} Bytes%{NEWLINE}
 | Pre- and Post-Processing (Prepost) | 118

"
/>
</EMAILNOTIF>

3. Send different email text for regular transfers and for Aspera Sync transfers
When Aspera Sync triggers a transfer (assuming only Aspera Sync uses the folder /sync-folder), an email
message will be sent to "mediaGroup". When a regular transfer occurs (files are sent to /upload), a different
notification will be sent to "mediaLead" and "adminGroup".

<EMAILNOTIF>
<MAILLISTS
mediaGroup ="[email protected], [email protected]"
mediaLead ="[email protected]"
adminGroup ="[email protected], [email protected]"
/>

<MAILCONF
FROM="Aspera Notifier &lt;[email protected]&gt;"
MAILSERVER="smtp.companyemail.com"
BODYTEXT="%{NEWLINE}Powered by Aspera Inc."
/>

<FILTER
MAILLISTS="mediaGroup"
SENDONSESSION="yes"
DESTIP="192.168.1.10"
TARGETDIR="/sync-folder"
SUBJECTPREFIX="Aspera Sync #1 - From %{PEER}"
BODYPREFIX="Status: %{STATE}%{NEWLINE} File Count: %{FILECOUNT}"
/>

<FILTER
MAILLISTS="mediaLead,adminGroup"
SENDONSESSION="yes"
TARGETDIR="/upload"
SUBJECTPREFIX="Transfer - %{USER}"
BODYPREFIX="
Status: %{STATE}%{NEWLINE}
Source: %{PEER}%{NEWLINE}
File Count: %{FILECOUNT}%{NEWLINE}
Bytes Transferred: %{TOTALBYTES} Bytes%{NEWLINE}
"
/>
</EMAILNOTIF>
 | Transferring from the Command Line | 119

Transferring from the Command Line

Ascp Command Reference

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

General Syntax Guidelines

Item Decription
symbols used in the paths Use single-quote (' ') and forward-slashes (/) on all platforms.
Characters to avoid / \ " : ' ? > < & * |

Environment Variables
If needed, you can set the following environment variables for use with the ascp command:

Item Initiation Command

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

Ascp Usage

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

[[user@]destHost:]target_path

Important: If you do not specify a username for the transfer, the local username will be authenticated (by
default). In the case of a Windows machine and a domain user, the transfer server will strip the domain from
the username (for example, authenticating Administrator, rather than DOMAIN\Administrator).
Thus, you will need to specify a domain explicitly, if applicable to the user.

Special Considerations for URI Paths

URIs are supported in paths, but only under the following restrictions:
• URIs can only be specified on the command line.
• If source paths are specified with a URI, all source paths specified on the command line must be from the same
cloud storage account, and all must include URIs.
• If source paths are specified with a URI, no docroot (download), local docroot (upload), or source prefix can be
specified.
• If a destination path is specified with a URI, no docroot (upload) or local docroot (download) can be specified.
 | Transferring from the Command Line | 120

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

Ascp Options

Option Description
-h, --help Display usage.
-A, --version Display version and license information; then exit.
-T Disable encryption for maximum throughput.
-d Create target directory if it doesn't already exist.
-p Preserve file timestamps for source modification time (mtime) and last access time
(atime).
Important: On Windows, mtime and atime may be affected when the system
automatically adjusts for Daylight Savings Time (DST). For details, see the Microsoft
KB article, http://support.microsoft.com/kb/129574.
Important: On Isilon IQ OneFS systems, last access time (atime) is disabled
by default (see sysctl efs.bam.atime_enabled). You will see atime is
set to be the same as mtime when using -p option. Use the command "sysctl
efs.bam.atime_enabled=1" to enable the preservation of atime on your
Isilon system.
Note: For Limelight, only the preservation of modification time (mtime) is
supported.

-q Quiet mode (to disable progress display).

-v Verbose mode (prints connection and authentication debug messages in the log file).
For information on log files, see Log Files on page 142 Log Files in the user guide
for IBM Aspera Connect Server, Enterprise Server, Point-to-Point Client, or Desktop
Client.
-6 Enable IPv6 address support. When using IPv6, the numeric host can be written inside
brackets. For example, [2001:0:4137:9e50:201b:63d3:ba92:da] or
[fe80::21b:21ff:fe1c:5072%eth1].
-D | -DD | -DDD Specify the debug level, where each D is an additional level of debugging.
-l max_rate Set the target transfer rate in Kbps (default: 10000 Kbps). If the ascp client does not
specify a target rate, it will be acquired from aspera.conf (server-side, as the local
aspera.conf target rate setting doesn't apply). If local or server aspera.conf
rate caps are specified, the "starting" (default) rates will be not higher than the cap.
-m min_rate Set the minimum transfer rate in Kbps (efault: 0. If the ascp client does not
specify a minimum rate, it will be acquired from aspera.conf (server-side, as
the local aspera.conf minimum rate setting doesn't apply). If local or server
aspera.conf rate caps are specified, the "starting" (default) rates will be not higher
than the cap.
-u user_string Apply a user string, such as variables for pre- and post-processing.
-i private_key_file Use public key authentication and specify the private key file. Typically, the private
key file is in the directory $HOME/.ssh/id_[algorithm].
-w{r|f} Test bandwidth from server to client (r) or client to server (f). Currently a beta option.
 | Transferring from the Command Line | 121

Option Description
-K probe_rate Set probing rate (Kbps) when measuring bottleneck bandwidth.
-k{0|1|2|3} Enable resuming partially transferred files at the specified resume level (default: 0).
Note that this must be specified for your first transfer; otherwise, it will not work for
subsequent transfers. Resume levels:
• 0 – Always retransfer the entire file.
• 1 – Check file attributes and resume if the current and original attributes match.
• 2 – Check file attributes and do a sparse file checksum; resume if the current and
original attributes/checksums match.
• 3 – Check file attributes and do a full file checksum; resume if the current and
original attributes/checksums match.
Note that when a complete file exists at the destination (no .aspx), the source file
size is compared with the destination file size. When a partial file and a valid .aspx
file exist at the destination, the source file size is compared with the file size recorded
inside the .aspx file.

-Z dgram_size Specify the datagram size (MTU) for FASP. By default, the detected path MTU is
used. (Range: 296 - 10000 bytes)
Note: As of version 3.3, datagram size can also be enforced by the server using
<datagram_size> in aspera.conf. If size is set with both -Z (client side) and
<datagram_size> (server side), the <datagram_size> setting is used. If the
client-side is pre-3.3, datagram size is determined by the -Z setting, regardless of the
server-side setting for <datagram_size>. In this case, if there is no -Z setting,
datagram size is based on the discovered MTU and the server logs the message "LOG
Peer client doesn't support alternative datagram size".

-g read_size Set the read-block size, a performance-tuning parameter for an Aspera sender (which
only takes effect if the sender is a server). It represents the maximum number of bytes
that can be stored within a block as the block is being transferred from the source disk
drive to the receiver. The default of 0 will cause the Aspera sender to use its default
internal buffer size, which may be different for different operating systems. Note that
500M (524,288,000 bytes) is the maximum block size.
-G write_size This is a performance-tuning parameter for an Aspera receiver (which only takes
effect if the receiver is a server). It represents the maximum bytes within a block that
an ascp receiver can write to disk. The default of 0 will cause the Aspera receiver
to use its default internal buffer size, which may be different for different operating
systems. Note that 500M (524,288,000 bytes) is the maximum block size.
-L local_log_dir Specify a logging directory in the local host, instead of using the default directory.
-R remote_log_dir Specify a logging directory in the remote host, instead of using the default directory.
-S remote_ascp Specify the name of the remote ascp binary (if different).
-e prepost Specify an alternate pre/post command. Be sure to use the complete path and file
name.
-O fasp_port Set the UDP port to be used by FASP for data transfer. (Default: 33001)
-P ssh-port Set the TCP port to be used for FASP session initiation. (Default: 33001)
-C nid:ncount Use parallel transfer on a multi-node/core system. Specify the node id (nid) and count
(ncount) in the format 1:2, 2:2. Assign each participant to an independent UDP port.
 | Transferring from the Command Line | 122

Option Description
-E pattern Exclude files or directories with the specified pattern from the transfer. This option
can be used multiple times to exclude many patterns. Up to 16 patterns can be used by
using -E. Two symbols can be used in the pattern, as shown below.
• * (asterisk) represents zero or more characters in a string, for example *.tmp
matches .tmp and abcde.tmp.
• ? (question mark) represents a single character, for example t?p matches tmp but
not temp.

-f config_file Specify an alternate Aspera configuration file (default is aspera.conf).

-W token_string Specify the token string for the transfer.
- Transfer only part of a file. This option only works when downloading a single
@[range_low:range_high] file and does not support resuming. The argument to "-@" may omit either or both
numbers, and the ":" delimiter. For example, -@3000:6000 transfers bytes between
positions 3000 to 6000; -@1000: transfers from 1000 to the end of the file; and -
@:1000 transfers from beginning to 1000.
-X rexmsg_size Adjust the maximum size in bytes of a retransmission request. (Max: 1440).
--mode=mode Specify the transfer direction, where mode is either send or recv.
--user=username The user name to be authenticated by the transfer server.
Important: If you do not specify a user name for the transfer, the local username
will be authenticated (by default). In the case of a Windows machine and a domain
user, the transfer server will strip the domain from the username (e.g. authenticating
"Administrator," rather than "DOMAIN\Administrator"). Thus, you will
need to explicitly specify a domain, if applicable to the user.

--host=hostname The server's address.

--policy=fixed | Set the FASP transfer policy.
high | fair | low
• fixed – Attempts to transfer at the specified target rate, regardless of the
actual network capacity. This policy transfers at a constant rate and finishes in a
guaranteed time. This policy typically occupies most of the network's bandwidth,
and is not recommended in most file transfer scenarios. In fixed mode, a maximum
(target) rate value is required.
• high – Monitors the network and adjusts the transfer rate to fully utilize the
available bandwidth up to the maximum rate. When congestion occurs, a it
transfers at a rate twice of a session with fair policy. In this mode, both the
maximum (target) and the minimum transfer rates are required.
• fair – Monitors the network and adjusts the transfer rate to fully utilize the
available bandwidth up to the maximum rate. When other types of traffic build up
and congestion occurs, it shares bandwidth fairly by transferring at an even rate. In
this mode, both the maximum (target) and the minimum transfer rates are required.
• low – Similar to fair mode, the low policy uses the available bandwidth up to the
maximum rate, but is much less aggressive when sharing bandwidth with other
network traffic. When congestion builds up, the transfer rate is reduced to the
minimum rate until other traffic retreats.
Important: If --policy is not set, ascp uses the server-side policy setting (fair
by default).

--file-list=filename Take the list of sources to transfer from filename. The file list supports UTF-8 files and
input from standard input through "-". The sources can exist on either the local host or
 | Transferring from the Command Line | 123

Option Description
the remote host (in terms of download), but not on both. Each source must be specified
on a separate line:
src
src2
...
srcN
Use with URIs: The sources listed in the file list cannot be URIs. To use --file-
list with cloud storage, you must specify the cloud storage with a URI in either a
root, source prefix, or command-line destination parameter, subject to the limitations
described above in Special Considerations for URI Paths.
Important: Multiple --file-list and --file-pair-list options are not
supported in a single ascp command. If multiple file lists are specified, all but the last
will be ignored. In addition, you cannot also include file names on the command line
when you use --file-list. Only files from the file list will be transferred.

--file-pair- Take the list of sources and corresponding destinations from filename. Note that there
list=filename is no command-line equivalent. Source and destination arguments in the file list cannot
be URIs. Each source and each destination must be specified on a separate line:
src1
dst1
src2
dst2
...
srcN
dstN
Use with URIs: The sources and destinations listed in the file list cannot be URIs. To
use --file-pair-list with cloud storage, you must specify the cloud storage
with a URI in either a root, source prefix, or command-line destination parameter,
subject to the limitations described above in Special Considerations for URI Paths.
Important: Multiple --file-list and --file-pair-list options are not
supported in a single ascp command. If multiple file lists are specified, all but the
last will be ignored. In addition, you cannot also include file names on the command
line when you use --file-pair-list. Only files from the file-pair list will be
transferred.

--source- Add prefix to the beginning of each source path. This is either a conventional path or it
prefix=prefix can be a URI but only if there is no root defined.
--symbolic- Specify rule to handle symbolic links. This option takes following values: (Default:
links=method follow)
• follow – Follow symbolic links and transfer the linked files.
• copy – Copy only the alias file. If a file with the same name exists on the
destination, the symbolic link will not be copied.
• copy+force – Copy only the alias file. If a file with the same name exists on the
destination, the symbolic link will replace the file. If the file of the same name on
the destination is a symbolic link to a directory, it will not be replaced.
• skip – Skip the symbolic links.

--remove-after- Add this option to remove all source files (excluding the source directory) once the
transfer transfer has completed.
 | Transferring from the Command Line | 124

Option Description
--move-after- Move source files and copy source directories to archivedir after they are successfully
transfer=archivedir transferred. Because directories are copied, the original source tree remains in place.
The archivedir is created if it does not already exist. If the archive directory cannot be
created, the transfer proceeds and the source files remain in their original location.
Example upload:

ascp --move-after-transfer=C:\Users\Bob\Archive C:\Users

\Bob\srcdir\file0012 [email protected]:/

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

ascp --move-after-transfer=Archive [email protected]:/srcdir

C:\Users\Bob

Result:
• srcdir is downloaded to C:\Users\Bob on the current machine.
• srcdir is moved (not copied) from its original location to the archive directory
[email protected]:/Archive on the server.
As with transfers, by default, no portion of the path above the transferred file or
directory is included when the file or directory is moved to the archive (unless --
src-base is specified).
The --src-base=prefix option preserves paths in the archive directory the
same way as it preserves them with transfers. That is, when --src-base=prefix
is specified, files are moved to the archivedir including the portion of the path that
remains when prefix is removed.
Example:

ascp --src-base=C:\Users\Bob --move-after-transfer=C:

\Users\Bob\Archive C:\Users\Bob\srcdir\file0012
[email protected]:/

Result:
• file0012 is transferred to bob's docroot on 10.0.0.1. The file is transferred and
includes the path minus the prefix — that is, to srcdir/file0012.
• file0012 is moved to C:\Users\Bob\Archive. The file is moved and
includes the path minus the prefix — that is, to C:\Users\Bob\Archive
\srcdir\file0012.
Once files have been moved to the archive, the original source directory tree remains
intact. To remove empty source directories that remain after files have been moved,
include the flag --remove-empty-directories on the command line. This
removes empty source directories except for those that are specified as the source to
transfer.
Restrictions:
• archivedir must be on the same file system as the source. If the specified archive is
on a separate file system, it will be created (if it does not exist), but an error will be
 | Transferring from the Command Line | 125

Option Description
generated and files will not be moved to it. For cloud storage, archivedir must be in
the same cloud storage account.
• archivedir is subject to the same docroot restrictions as the source.
• --remove-after-transfer and --move-after-transfer are
mutually exclusive; including both in the same command generates an error.

--remove-empty- Remove empty source directories once the transfer has completed (not including a
directories directory specified as the source to transfer).
--skip-special- Skip special files (for example, devices and pipes).
files
--file- Generate a list of all transferred files, where output is none or text (Default: none)
manifest=output
--file-manifest- Specify the path to the file manifest.
path=directory
Important: File manifests can only be stored locally. Thus, if you are using S3, or
other non-local storage, you must specify a local manifest path.

--file-manifest- Specify the suffix of the file manifest's temporary file.

inprogress-
suffix=suffix
--precalculate- Add this option to calculate total size before transfer. Note that the server side
job-size aspera.conf setting overrides the ascp command-line option.
--overwrite=method Overwrite files with the same name. This option takes following values (Default: diff):
• always – Always overwrite the file.
• never – Never overwrite the file. However, note that if the parent folder is not
empty, its access, modify, and change times may still be updated.
• diff – Overwrite if file is different from the source (i.e., if a complete file exists
at the destination (no .aspx file) and is the same as the source file, then leave it
unmodified (no change on timestamp/attributes either); otherwise re-transfer the
whole source file). Note this policy interacts with the resume policy.
• older – Overwrite if file is older than the source.
Important: When --overwrite=diff, you must also consider the resume
policy (-k{0|1|2|3}). If -k0 (or no -k specified), the source and destination files
are always deemed to be different, thereby implying always overwrite. If -k1, the
source and destination files are compared based on file attributes (currently, just file
size). If -k2, the source and destination files are compared based on sparse checksum.
If -k3, the source and destination files are compared based on full checksum.

--save-before- If a transfer will overwrite an existing file, move the existing file to
overwrite file.yyyy.mm.dd.hh.mm.ss.index.ext, where index is set to 1 at the beginning of each
new second and incremented for each file saved in this manner during the same
second. File attributes are maintained in the renamed file.
Note: This option requires that --partial-file-suffix also be enabled.
With the exception of --overwrite=never, specifying --overwrite with --
save-before-overwrite has no affect. If --overwrite=never, any file
that would be overwritten remains unchanged. If --overwrite is set to any other
value, files that would be overwritten are renamed using the convention described
above.
 | Transferring from the Command Line | 126

Option Description
--file-crypt=crypt Encrypt or decrypt files. Replace crypt with encrypt or decrypt. A passphrase is
required.
--file- Report checksums for transferred files, where hash is sha1, md5, or none.
checksum=hash
--partial-file- Filename extension on the destination computer while the file is being transferred.
suffix=suffix Once the file has been completely transferred, this filename extension will be
removed. (Default: blank)
Note: This option only takes effect when it is set on the receiver side.

--src-base=prefix Specify the prefix to be stripped off from each source object. The remaining portion of
the source path is kept intact at the destination.
For example, the "clips" directory on the remote computer contains the following
folders and files:

/clips/outgoing/file1
/clips/outgoing/folderA/file2
/clips/outgoing/folderB/file3

In this case, to transfer all folders and files within the "outgoing" folder (but not the
"outgoing" folder, itself), run the following command:

> ascp -d --src-base=/clips/outgoing/ [email protected]:/

clips/outgoing/ /incoming

Result: The following folders and files appear in the "incoming" directory at the
destination:

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

Files outside of the source base (for example, /temp/file4) are not transferred,
and warnings are generated.
Without --src-base
If --src-base is not used, and the source item is a folder, the contents of the folder
are transferred, along with the folder itself. For example:

> ascp -d [email protected]:/clips/outgoing/ /incoming

Result:

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

If --src-base is not used, and the source item is a file, only the file is transferred,
not the folders in the file's path. For example:

> ascp -d [email protected]:/clips/outgoing/file1 [email protected]:/clips/

outgoing/folderA/file2 /incoming
 | Transferring from the Command Line | 127

Option Description
Result:

(docroot)/incoming/file1
(docroot)/incoming/file2

For further examples, with and without --src-base, see Ascp File Manipulation
Examples on page 129
Use with URIs
The --src-base option performs a character-to-character match with the source
path specifying a file or directory. Hence for cloud storage, it is necessary that --
src-base specify the URI in the same manner the source parameters are specified
(for example, if the source includes and embedded passphrase, the source base must
also include an embedded passphrase or it will not match the source files/directories).

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

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

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

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

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

--ignore-host-key If you're prompted to accept a host key when connecting to a remote host, ascp
ignores the request.
--check- Check against the server SSH host key fingerprint (for example,
sshfp=fingerprint f74e5de9ed0d62feaf0616ed1e851133c42a0082).
--apply-local- Apply the local docroot. This option is equivalent to setting the environment variable
docroot ASPERA_SCP_DOCROOT.

ascp Options for HTTP Fallback

Option Description
-y {0|1} Enable HTTP Fallback transfer server when UDP connection fails. Set to 1 to enable
(default: 0).
-j {0|1} Encode all HTTP transfers as JPEG files. Set to 1 to enable (default: 0).
-Y key_file The HTTPS transfer's key file name.
-I cert_file The HTTPS certificate's file name.
-t port Specify the port for HTTP Fallback Server.
-x proxy_server Specify the proxy server address used by HTTP Fallback.
 | Transferring from the Command Line | 128

Ascp General Examples

Examples of initiating FASP file transfers using the ascp command.
This topic demonstrates the ascp command with the following examples:
• Fair-policy transfer, without encryption
Transfer with fair rate policy, with maximum rate 100 Mbps and minimum at 1 Mbps:

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

• Fixed-policy transfer, without encryption

Transfer all files in \local-dir\files to 10.0.0.2 with target rate 100 Mbps and encryption OFF:

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

• Specify a UDP port

To perform a transfer with UDP port 42000:

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

• Authenticate with public key

To perform a transfer with public key authentication with key file /Documents and Settings/
asp1/.ssh/asp1:

> ascp -T -l 10m -i "/Documents and Settings/asp1/.ssh/asp1" local-dir/files [email protected]:/

remote-dir

• Authenticate with a login that contains space

Enclose the target in double-quotes when spaces are present in the username and remote path:

> ascp -l 100m local-dir/files "User [email protected]:/remote directory"

• Transfer with a network shared location

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

> ascp local-dir/files [email protected]:"//1.2.3.4/nw-share-dir/"

• Parallel transfer on a multi-core system

Use parallel transfer on a dual-core system, together transferring at the rate 200Mbps, using UDP ports 33001 and
33002. Two commands are executed in different Terminal windows:

> ascp -C 1:2 -O 33001 -l 100m /file [email protected]:/remote-dir &

> ascp -C 2:2 -O 33002 -l 100m /file [email protected]:/remote-dir

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

[email protected]:/remote-dir/

Download from the server 10.0.0.2 and decrypt while transferring:

> set ASPERA_SCP_FILEPASS=secRet&& ascp -l 10m --file-crypt=decrypt [email protected]:/remote-

dir /local-dir
 | Transferring from the Command Line | 129

If the password-protected file is downloaded without descrypting (file1.aspera-env, with aspera-env

appended), on the local computer, decrypt the file as file1:

> set ASPERA_SCP_FILEPASS=secRet&& asunprotect -o file1 file1.aspera-env

Ascp File Manipulation Examples

Examples of manipulating files using the ascp command.
This topic demonstrates file manipulation using the ascp command with the following examples:
1. Upload directory contents to remote computer
Upload the "/content/" directory to the remote server.

> ascp /data/content/ [email protected]:/storage/

Result => /storage/content/*

Upload the "/content/" directory to the remote server, but strip the srcbase path and preserve the rest of the
file structure.

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

Result => /storage/*

2. Upload directory contents to remote computer and create the destination folder if it does not already exist
Upload the "/content/" directory to the remote server and create the "/storage2" folder since it does not
exist.

> ascp -d /data/content/ [email protected]:/storage2/

Result => /storage2/content/*

3. Download directory contents from remote computer
Download the "/content/" directory to the remote server, but strip the srcbase path and preserve the rest of the
file structure.

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

Result => /data/*

4. Upload selected files and directories to a remote computer and preserve directory structure
Upload the selected file and directory to the remote server, but strip the srcbase path and preserve the rest of the
file structure.

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

tuesday/ [email protected]:/storage

Results => /storage/monday/file1 AND /storage/tuesday/*

5. Download selected files and directories from a remote computer and preserve directory structure
Download the selected file and directory from the remote server, but strip the srcbase path and preserve the rest of
the file structure.

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

file1 [email protected]:/storage/content/tuesday/ /data
 | Transferring from the Command Line | 130

Results => /data/monday/file1 AND /data/tuesday/*

6. Remove source files from the local computer after transferring them to the remote computer
Remove the "/content/" directory of the local computer after the contents (excluding partial files) have been
transferred to the remote computer.

> ascp -k2 -E "*.partial" --remove-after-transfer --remove-empty-

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

Result => /storage/content/*

Remove the "/content/" directory of the local computer after the contents (excluding partial files) have been
transferred to the remote computer. Strip the srcbase path and preserve the rest of the file structure

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

--remove-empty-directories /data/content [email protected]:/storage

Result => /storage/*

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

Ascp Transfers to Cloud Storage

Examples of using the ascp command to initiate FASP transfers to cloud storage.
If you have access to cloud storage that is hosted by Aspera On Demand, you can use ascp to transfer to it.

With Docroot Already Configured

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

ascp options myfile username@server:/targetpath

For examples, see Ascp General Examples on page 128.

In some cases, ascp transfers to cloud storage can be made without a preconfigured docroot. See the examples
below.
With No Docroot Configured: S3
If the transfer server account does not have a docroot, you can still transfer to S3 as long as you know your S3 Access
ID and Secret Key and you have an S3 bucket. The syntax is:

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

host=s3_server_addr files_to_send \
 | Transferring from the Command Line | 131

s3://access_id:[email protected]/s3_bucket

For example:

ascp --mode=send --user=bob --host=s3.asperasoft.com myfiles \

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

With No Docroot Configured: Softlayer

If the transfer server account does not have a docroot, you can still transfer with the following syntax:

ascp options --mode=send --user=root --host=ip_addr files_to_send \

swift://softlayer_username:[email protected]/conta

Example Upload:

ascp --mode=send --user=root --host=192.155.218.130 bigfile.txt \

swift://
XYZOS303446-2:bob:[email protected]/
test

Example Download:

ascp --mode=recv --user=root --host=192.155.218.130 \

swift://
XYZOS303446-2:bob:[email protected]/
test/bigfile.txt /tmp/

With No Docroot Configured: Azure

If the transfer server account does not have a docroot, you can still transfer. First set an Aspera environment variable
with the password:
Windows Command Prompt: set ASPERA_SCP_PASS = password
Linux: export ASPERA_SCP_PASS=password
Then run ascp with the following syntax:

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

host=server files_to_send azu://storage:[email protected]/abc

For example:
Windows Command Prompt: set ASPERA_SCP_PASS = fslk47CLwlj
Linux: export ASPERA_SCP_PASS=fslk47CLwlj

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

host=dev920350144d2.azure.asperaondemand.com bigfile.txt \
azu://astransfer:[email protected]/abc
 | Transferring from the Command Line | 132

Token Generation
Usage and examples for astokengen

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

Functionality
• Authorizes uploads of one or more files to a destination
• Authorizes downloads of one or more files or directories
• Authorizes uploads of one or more files as source/destination pairs
• Authorizes downloads of one or more files as source/destination

Usage
1. astokengen --mode=send [OPTS] -u USER --dest=PATH [-v TOKEN]
2. astokengen --mode=send [OPTS] -u USER --file-pair-list=FILENAME --dest=DEST
[-v TOKEN]
3. astokengen --mode=recv [OPTS] -u USER -p PATH [-p PATH …] [-v TOKEN]
4. astokengen --mode=recv [OPTS] -u USER --file-list=FILENAME [-v TOKEN]
5. astokengen --mode=recv [OPTS] -u USER --file-pair-list=FILENAME [-v TOKEN]
6. astokengen -t TOKEN [OPTS]

Option (short form) Option (long form) Description

-A --version Print version information.
--mode=MODE Direction of the transfer mode (send | recv)
-p --path=PATH Source path
--dest=DEST Destination path
-u --user=USER Generate the token for this user name. This name is embedded
in the token and also used to retrieve further information from
aspera.conf (user_value and token_life_seconds).
--file-list=FILE Specifies a file name that contains a list of sources for a
download token. Each line of the file contains a single source and
blank lines are ignored.
--file-pair- Specifies a file name that contains a multiplexed list of source
list=FILE and destination pairs for an upload or download token. Each pair
of lines encodes one source and one destination and blank lines
are ignored.
-v TOKEN Verify token against user and path parameters.
-t TOKEN Display the contents of the token.
-k PASSPHRASE Passphrase to decrypt token. For use with -t.
-b Assume user name and paths are encoded in base64.
 | Transferring from the Command Line | 133

Examples

Description Example
Example file list
/monday/first_thing.txt
/monday/next_thing.txt
/monday/last_thing.txt

Example file-pair
list /monday/first_thing.txt
/archive/monday/texts/first_thing
/monday/next_thing.txt
/archive/monday/texts/next_thing
/monday/last_thing.txt
/archive/monday/texts/last_thing

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

astokengen --user=USER --dest=PATH --mode=send

The destination is encoded into the token. Source paths are not allowed and will cause
astokengen to fail. --path and --file-list are illegal in this case.

Paired upload The destination is pre-pended to each of the destinations in the paired list file and they are all
encoded into the token. The destinations are in each odd numbered line of the file (1, 3, 5, 7,
etc).

astokengen --user=USER --dest=PATH --file-pair-list=FILENAME

--mode=send

--path and --file-list are illegal in this case.

Common The specified paths are encoded into the token.

download
astokengen --user=USER --path=FILE1 --path=FILE2 --mode=recv
astokengen --user=USER --file-list=FILENAME --mode=recv

--dest and --file-pair-list are illegal in this case.

Paired download The source files from the pair list are encoded in the token. The sources are in each even
numbered line of the file (0, 2, 4, 6, 8, etc.).

astokengen --user=USER --file-pair-list=FILENAME --mode=recv

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

Creating SSH Keys (Command Line)

Create a key pair for your computer.
If you are using this machine as a client to connect to other Aspera servers with public key authentication, you can
also create key-pairs in command line. Follow these instructions:
Note: You can also use the application GUI to create SSH keys or import existing keys for use with a
selected user account. For instructions, see Creating SSH Keys on page 30.
1. Create a .ssh in your home directory
 | Transferring from the Command Line | 134

Create a .ssh folder in your user account's home directory if it does not exist:

> md user_home_dir\.ssh

Go to the .ssh folder and continue:

> cd user_home_dir\.ssh

2. Run ssh-keygen to generate an SSH key-pair

Run the following command in the .ssh folder. The program prompts you for the key-pair's filename. Press
ENTER to use the default name id_rsa. For a passphrase, you can either enter a password, or press return twice to
leave it blank:

> ssh-keygen -t rsa

3. Retrieve the public key file

When created, the key-pair can be found in your home directory's .ssh folder (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. The instructions for installing the public key on the server can be found in the Setting Up a
User's Public Key on page 59; however, the server may be installed on an operating system that is different from
the one where your client has been installed.
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

[email protected]:\space

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

Ascp FAQs
This topic lists frequently asked questions regarding ascp command:
1. How do I control the transfer speed?
 | Transferring from the Command Line | 135

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. With the ascp command, use the following flags to
specify transfer policies that are fixed, fair, high, and low:

Policy Command template

Fixed
--policy=fixed -l target_rate

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

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

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

2. What should I expect in terms of transfer speed? 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 will typically occupy the majority of a network's bandwidth. It is recommended that this
test be performed on a dedicated file transfer line or during a time of very low network activity.
On the client machine, start a transfer with fixed policy. Start with a lower transfer rate and increase gradually
toward the network bandwidth (e.g. 1m, 5m, 10m...). Monitor the transfer rate and make sure that it fulfills your
bandwidth:

$ ascp -l 1m source-file destination

To improve the transfer speed, you may also upgrade the following 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.
3. How do I ensure that if the transfer is interrupted / fails to finish, it will resume the transfer without re-transferring
the files?
Use the -k flag to enable resume, and specify a resume rule:
• -k 0 Always retransfer the entire file.
• -k 1 Check file attributes and resume if they match.
• -k 2 Check file attributes and do a sparse file checksum; resume if they match.
• -k 3 Check file attributes and do a full file checksum; resume if they match.
4. How does Aspera handle symbolic links?
ascp command follows symbolic links by default. There is a -o SymbolicLink flag that offers handling
options:
• --symbolic-links=follow: Follow symbolic links and transfer the linked files.
• --symbolic-links=copy: Copy only the alias file.
 | Transferring from the Command Line | 136

• --symbolic-links=skip: Skip the symbolic links.

5. What are my choices regarding file overwrites on the destination computer?
In ascp, you can specify the overwriting rule with the following flags:
• --overwrite=always: Always overwrite the file.
• --overwrite=never: Never overwrite the file.
• --overwrite=diff: Overwrite if file is different from the source.
• --overwrite=older: Overwrite if file is older than the source.

Note: For --overwrite=diff, if a complete file exists on the destination computer (i.e., no .aspx
file) and is the same as the source file, then the destination file will remain unmodified (no change
on timestamp/attributes either). Otherwise the entire source file will be retransferred. Note this policy
interacts with the resume policy.
 | Configuring for the Cloud | 137

Configuring for the Cloud

Cloud Configuration for Enteprise Server Nodes

Configuring aspera.conf for S3

The following example explains how to modify aspera.conf for AWS S3 transfers. You must meet the following
prerequisites before modifying aspera.conf:
• You have permissions to access the S3 bucket.
• You know your username's S3 Access ID and Secret Key.
Note: For Aspera on Demand, you can also enter these settings from Console.

<?xml version='1.0' encoding='UTF-8'?>

<CONF version="2">
<server>
<server_name>aspera.example.com</server_name>
</server>
<aaa>
<realms><realm><users>
<user>
<name>UserName</name>
<authorization>
<transfer>
<in>
<value>token</value>
</in>
<out>
<value>token</value>
</out>
</transfer>
<token>
<encryption_key>YourSuperSecretKey</encryption_key>
</token>
</authorization>
<file_system>
<access>
<paths>
<path>
<absolute></absolute>
<read_allowed>true</read_allowed> <!-- Read Allowed:
boolean true or false -->
<write_allowed>true</write_allowed> <!-- Write Allowed:
boolean true or false -->
<dir_allowed>true</dir_allowed> <!-- Browse Allowed:
boolean true or false -->
<restrictions> <!-- File access
restrictions. Multiple entries are allowed. -->
<restriction>s3://*</restriction>
<restriction>!azu://*</restriction>
</restrictions>
</path>
</paths>
</access>
</file_system>
</user>
</users></realm></realms>
 | Configuring for the Cloud | 138

</aaa>
</CONF>

Docroot Restrictions for URI Paths

A configuration with both a docroot absolute path (docrooted user) and a restriction is not supported.
The primary purpose of restrictions is to allow access to certain storage (for example, Amazon S3) for clients that
have their own storage credentials. In this case, instead of using docroots in aspera.conf, use a docroot restriction.
Configuration:

<paths>
<path>
<restrictions>
<restriction>s3://*</restriction>
</restrictions>
</path>
</paths>

You can also configure restrictions once for all users by setting <restriction> in the default section.
Functionality:
A docroot restriction limits the files a client is allowed to access for browsing and transfers. Files are rejected
unless they match any restrictions that are present. Restrictions work for URI paths (for example, s3://*) and are
processed in the following order:
1. If a restriction starts with "!", any files that match are rejected.
2. If a restriction does not start with a "!", any files that match are kept.
3. If any restrictions other than "!" exist, and the file does not match any of them, the file is rejected.
4. Files that fail restrictions during directory iteration are ignored as if they do not exist.
 | Appendix | 139

Appendix

Updating the Aspera Service Account

Look up or change the user account that runs Aspera services.
On Windows, a special user account, the Aspera service account, is used to run the services for Aspera products. The
services include Aspera Central, Aspera HTTPD, Aspera Sync, and OpenSSH Service (if selected to install). During
installation, you are prompted to create a new Aspera service account or add an existing user account for this purpose.
This topic covers the configuration of the Aspera service account, including updating the existing Aspera service
account's password, and changing the Aspera service account.
• Updating the password for the existing Aspera service account.
During the installation, if you have problems entering the credentials for the existing Aspera service account,
change the user password. With administrative credentials, go to the user accounts area of the Control Panel.
Select the user account that is serving as the Aspera service account (default svcAspera). Click the account name
and select the option for setting or changing the password.
• Changing the Aspera service account
To replace the user account running the Aspera services, open the Command Prompt and run the asuser-
services.bat script. Running the script without arguments displays basic usage information and examples.
On Windows Vista, Windows 2008, or Windows 7, run the script from an Administrator prompt or disable UAC.
Note that in order to replace the existing service account with a domain account, the domain account must already
exist.
Examples:
To use an existing domain user [email protected] run the script as follows:

> asuser-services.bat [email protected] password

If you specify a non-existent user account, the script creates it. For example, to set up a new user as the Aspera
service account:

> asuser-services.bat newUser newUserPassword

If you are running a non-English version of Windows, your administrator group might not be "Administrators".
When updating Aspera service account, add a third parameter that specifies the local admin group. For example:

> asuser-services.bat newUser newUserPassword Administratores

Restarting Aspera Services

Instructions on restarting Aspera services after configuration changes
You may restart Aspera Central and Aspera NodeD within the Computer Management window, which is accessible
via Manage > Services and Applications > Services.
 | Appendix | 140

Optimizing Transfer Performance

Tips about testing and improving your computer's transfer performance.
To verify that your system's FASP transfer can fulfill the maximum bandwidth capacity, prepare a client machine to
connect to this computer, and do the following tests:
1. Start a transfer with Fair transfer policy
On the client machine, open the user interface and start a transfer. Go to the Details to open the Transfer Monitor.
 | Appendix | 141

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. It is recommended that this test be
performed 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.

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.

Setting Policies for OpenSSH User

Setting local security policies (post-Aspera product installation) for the user who runs OpenSSH
Your Aspera transfer product's installer includes the implementation of an SSH Server (OpenSSH) for user
authentication and for the setup of transfer sessions. Alternatively, you can opt not to install OpenSSH (i.e., you
click the Custom button within the installer and then de-select the option for the SSH Server), and choose to set it
up post-install, instead. If you choose to set up OpenSSH, post-Aspera product installation, then you must create a
user account to run the SSH service, and assign the proper permissions. You can set up the SSH service user account
and associated permissions automatically using the script asuser-services.bat, which can be found in the following
location:

Platform Location
32-bit Windows C:\Program Files (x86)\Aspera\Enterprise Server\bin\
64-bit Windows C:\Program Files\Aspera\Enterprise Server\bin\

You may also set up the SSH service user account manually, although you must also manually assign the proper
permissions. You may do so through Administrative Tools > Local [Security] Policy > Local Policies > User
Rights Assignment. The SSH user account must be made a member of the local Administrators group and then
granted the following rights:
 | Appendix | 142

• Act as a part of the Operating System

• Adjust memory quotas
• Create a token
• Log on as a service
• Replace a process level token

Important: If your clients need to access network resources (e.g., transferring files to or from a Windows
share), then you must create a domain account that has proper access to these resources; otherwise, you may
create a local account.

Log Files
Locate the log files related to the Aspera product.
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.

To review logs of other components, click Open Logs Folder to open the folder that contains transfer logs:

OS Version Path
32-bit Windows C:\Program Files (x86)\Aspera\Enterprise Server\var\log
64-bit Windows C:\Program Files\Aspera\Enterprise Server\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 Description

ascmd.log File browsing and manipulation in user interface.
asconfigurator.log Server configuration information.
asperacentral.log A server-side service that handles transfers, web services and database logging.
aspera-scp-transfer.log The FASP transfers.
aspera-scp-http-transfer.log The HTTP Fallback server.
asperasync.log The Hot Folders (File synchronization).

Users can set the logging level for transfers from the My Preferences dialog. My Preferences can be opened from
Tools > Preferences or from the Preferences button in the upper-right corner of the application window.
 | Appendix | 143

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

Setting Up Token Authorization

When accounts on a transfer server are configured to require token authorization, only transfers initiated with a valid
token are allowed to transfer to or from the server. The token authorization requirement can be set for individual
users, entire user groups, or globally for all users. Token authorization can be set independently for incoming transfers
and outgoing transfers.
Token authorization is a requirement for initiating transfers with the Shares product.
Set up token authorization for a transfer user as follows:
1. Choose or create the transfer user on the server.
The examples below use the transfer user asp1.
2. Log in as the user to ensure that any created files are owned by the user.
Create the directory .ssh and the file authorized_keys if they don't already exist. For example:

C:\Users\asp1\.ssh\authorized_keys

3. Append the token-authorization public key to the user's authorized_keys file.

Aspera provides a public key in the file aspera_id_dsa.pub stored in the following location:

C:\Program Files[ (x86)]\Aspera\Enterprise Server\var\aspera_id_dsa.pub

 | Appendix | 144

4. Ensure that .ssh and .ssh/authorized_keys are owned by the user.

Update the directory permissions by right-clicking the .ssh folder and selecting the Security tab. Here, you can set
permissions to read, write, and execute (full control).

5. Make sure the user has no password.

If the system does not allow this, create a very large password.
6. Make sure the user's login shell is aspshell.
For information on setting this, see Securing your SSH Server on page 14.
7. Configure the user for token authorization
To configure user authorization from the GUI, see Configuring Token Authorization from the GUI on page 144.
To configure user authorization from aspera.conf, see Configuring Token Authorization With aspera.conf on page
145.
Note:
Instead of setting authorization for each user individually, you can set it for a group, or set it globally for
all users.
8. Create a node user and associate it with the transfer user.
The examples below use the Node API user nuser.

> asnodeadmin.exe -au nuser -p nuser_passwd -x asp1

Configuring Token Authorization from the GUI

Requirements:
• You have created a transfer user on your server.
• You have set up the transfer user with an SSH public key as described in Setting Up Token Authorization on page
143.
 | Appendix | 145

The examples below use a transfer user called asp1.

1. On the main screen of the desktop client, click the Configuration link (upper right).
This opens the Server Configuration dialog.
2. Select the Users tab and choose a user to configure.
Alternatively, select the Groups tab and choose a group to configure, or select the Global tab to configure options
for all users.
3. In the right panel of the Server Configuration dialog, select the Authorization tab.
4. For Incoming Transfers check the override box. Under Effective Value, select token from the dropdown menu.
5. Similarly, do the same for Outgoing Transfers.
6. For Token Encryption Key, check the override box, and under Effective Value, enter the token encryption key.
The encryption key should be a string of random characters (at least 20 recommended).
7. When you're done, click Apply to save the changes, or click OK to save the changes and close the dialog.
Alternatively, instead of configuring token authorization individually for each user, you can select the Groups tab
and apply these settings to groups of users. Or, you can select the Global tab and apply these settings to all users.

Configuring Token Authorization With aspera.conf

Requirements:
• You have created a transfer user on your server.
• You have set up the transfer user with an SSH public key as described in Setting Up Token Authorization on page
143.
The examples below use a transfer user called asp1.
1. Locate aspera.conf and open it with a plain-text editor

C:\Program Files[ (x86)]\Aspera\Enterprise Server\etc\aspera.conf

2. Add an authorization section for the user

 | Appendix | 146

In the following example, the user section for asp1 contains an <authorization> section that specifies the
following:
• a <transfer> section specifying that both incoming and outgoing transfers (in and out) should use token
encryption
• a <token> section with an encryption key, which should be string of random characters (at least 20
recommended)
Alternatively, you can configure token-authorization settings in a <group> section to be applied to all users in the
group. Or, you can configure the settings in the <default> section to apply them globally for all users.

<user>
<name>asp1</name>
<authorization>
<transfer>
<in>
<value>token</value>
</in>
<out>
<value>token</value>
</out>
</transfer>
<token>
<encryption_key>gj5o930t78m34ejme9dx</encryption_key>
</token>
</authorization>
<file_system>
...
...
</file_system>
</name>
</user>

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

Troubleshooting

Using the Troubleshooter

Troubleshoot a remote client's problem connecting to your server.
You can use the transfer application's troubleshooting tool to verify a user's login problem on your computer.
To use the troubleshooting tool, launch the application. and select Help > Troubleshoot. The troubleshooter will
identify potential problems with your Aspera software configuration.

Error Adding Domain User

Troubleshooting steps for addressing errors encountered while adding domain users.
This topic addresses the following issues:

Issue Error Message

When attempting to add a user via Server Error creating user domain\username: Access Denied (16) -
Configuration > Users, you receive an "Error Unable to check for user domain\username's existence. Access
Adding User" message. denied? Missing Domain?
When attempting to switch the Aspera service [email protected] may not be an existing domain account.
account via asuser-services.bat, you receive a Please create the domain account and re-run. (Windows error:
"User set up error" message. 1722)
During the MSI product installation, you attempt [email protected] may not be an existing domain account.
to define the Aspera service account as a domain Please create the domain account then re-run.
user account and you receive an error message.

If you have encountered any of the preceding issues, follow the troubleshooting steps below.
1. Confirm that you are using a Domain Admin account to perform the actions listed in the table above.
2. Confirm that the Domain Admin account used to perform the actions listed in the table above has Local
Administrator privileges.
If it does not, add the account to the local Administrators group.
 | Troubleshooting | 148

3. In addition to Local Administrator privileges, grant the account GenericRead access to the target user account in
Active Directory. To do so, follow the sub-steps below.
Windows 2003

Step Description
A From a computer and user account that has access to Active Directory, open Active Directory
Users and Computers.
B Click on the domain where the account exists.
C Select Users, right-click the user account, and then click Properties.
D Click the Security tab, then Add the user account performing the actions listed in the table above,
and mark Allow for Read permissions.
E Click Apply and then OK.

Windows 2008 R2

Step Description
A From a computer and user account that has access to Active Directory, go to Administrative
Tools > Active Directory Administrative Center.

Note: The Active Directory Administrative Center is installed when you add the Active
Directory Domain Services (AD DS) server role through the Windows 2008 R2 Server
Manager.

B Select Users, right-click the user account, and then click Properties.
C Select Extensions > Security.
D Add the user account performing the actions listed in the table above, and mark Allow for Read
permissions.
E Click Apply and then OK.

Important: You may need to reboot the server to ensure that the Active Directory changes have been
propagated to the server.
4. Re-attempt the original action(s).

Clients Can't Establish Connection

Troubleshoot the problem that your clients cannot connect to your IBM Aspera Enterprise Server.
The following diagram shows the troubleshooting procedure if clients can't establish a FASP transfer connection to
your Enterprise Server. Follow the instructions to identify and resolve problems:
 | Troubleshooting | 149

1. Test SSH ports

To verify the SSH connection port, on the client machine, open a Terminal or a Command Prompt, and use the
telnet command to test it. For example, to test connection to a computer (10.0.1.1) through a port (TCP/33001),
use this command:

> telnet 10.0.1.1 33001

If the client cannot establish connections to your Enterprise Server, verify the port number and the firewall
configuration on your Enterprise Server machine.
2. Test UDP ports
If you can establish an SSH connection but not a FASP file transfer, there might be a firewall blockage of FASP's
UDP port. Please verify your UDP connection.
3. Verify SSH service status
If there is no firewall blockage between the client and your Enterprise Server, on the client machine, try
establishing a SSH connection in a Terminal or a Command Prompt: (Enterprise Server address: 10.0.1.1,
TCP/33001)

$ ssh [email protected] -p 33001

If the SSH service runs normally, the client should see a message prompting to continue the connection or for
a password. However, if you see a "Connection Refused" message, which indicates that the SSH service isn't
running, review your SSH service status. Ignore the "permission denied" message after entering the password,
which is discussed in next steps.
4. Verify that the user account is added in Enterprise Server
If the client can establish SSH connections, but your Enterprise Server keeps prompting for login credentials,
the user account may not be properly configured for FASP connections. Make sure that the login information is
correct, and refer to Setting Up Users on page 55 to review the user account's configuration.
If you still encounter connection problems after going through these steps, contact Technical Support on page 152.
 | Troubleshooting | 150

Uninstall Version 2.2.1 for Upgrade

Remove problematic releases between version 2.2.1.17909 and 2.2.1.18906.
If you are upgrading or uninstalling a version of IBM Aspera Enterprise Server between 2.2.1.17909 and 2.2.1.18906,
and are not running the SSH server provided as part of the product package, then you may encounter an error while
removing the old installation.
Error 1721: There is a problem with this Windows Installer package. A program required for this install to complete
could not be run. Contact your support personnel or package vendor.
In this case, follow these steps to uninstall it:
1. Locate the cached installer package
To locate the cached installer package, download the msiinv from this link. When downloaded, place the
msiinv.exe under C:\msiinv\ directory.
Open Command Prompt and execute the following command to generate a text file with a list of all installed
applications:

> C:\msiinv\msiinv.exe -p > c:\msiinv\installed_apps.txt

Open this file with a text editor, locate the section that starts with "Aspera Enterprise Server":

Aspera Enterprise Server

Product code: {C040AA04-ABDD-4F82-9BBF-76B4C088CEDC}
Product state: (5) Installed.
...
Version: 2.2.1.18906
...
Local package: C:\WINDOWS\Installer\9a8cc93.msi
...

First, locate the line "Version" and verify that the build number is between 17909 and 18906. Second, locate the
line "Local package" in preparation for Step 2.
2. Locate and modify the cached installer package
Next, download orca, an installer modification tool, from the this link.
When downloaded, double-click the installer, follow the instructions and select the Typical setup type. Open Orca
when finished, select File > Open, enter the path of the cached installer from Step 1:
 | Troubleshooting | 151

When opened, find the InstallExecuteSequence from the Tables column, right-click on StopSSHD from the
Action list and click Drop Row. Click File from the Toolbar and click Save File. When finished, close orca.

3. Remove the old installation

Remove the previous installation through Control Panel > Add/Remove Programs.
 | Technical Support | 152

Technical Support
For further assistance, you may contact Aspera through the following methods:

Contact Info
Email [email protected]
Phone +1 (510) 849-2386 (US), +44 (0) 207 993 6653 (Europe)
Request Form https://support.asperasoft.com/anonymous_requests/new/

The technical support service hours:

Support Type Hour (Pacific Standard Time, GMT-8)

Standard 8:00am – 6:00pm
Premium 8:00am – 12:00am

We are closed on the following days:

Support Unavailable
Dates
Weekends Saturday, Sunday
Aspera Holidays See our Website.
 | Feedback | 153

Feedback
The Aspera Technical Publications department wants to hear from you on how Aspera can improve customer
documentation. To submit feedback about this guide, or any other Aspera product document, visit the Aspera Product
Documentation Feedback Forum.
Through this forum, you can let us know if you find content that is not clear or appears incorrect. Aspera also
invites you to submit ideas for new topics, and for improvements to the documentation for easier reading and
implementation. When you visit the Aspera Product Documentation Feedback Forum, remember the following:
• You must be registered to use the Aspera Support Website at https://support.asperasoft.com/.
• Be sure to read the forum guidelines before submitting a request.
 | Legal Notice | 154

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