Overview

FASP Manager SDK

The Aspera FASP Manager SDK and Aspera Redistributable Package can be used to develop and package custom applications that do not require separate installation of any Aspera product on the target machine. Click here to watch the getting started video for FASP Manager. The FASP Manager class library allows you to initiate, monitor and control FASP based file transfers in your custom applications.  When a custom application acts as an Aspera Server it is usually referred to as an Aspera Embedded Server and when it acts as an Aspera Client it is known as an Aspera Embedded Client.  Depending on your needs you can find step-by-step instructions to get you started using the menu on the left.

 


Embedded Server

Here you will learn how to develop and deploy an Aspera Embedded Server.  

Prerequisites

For an embedded server deployment you need a SSH server installed on the target machine.  For Linux, Solaris and other POSIX systems you can use the SSH server that came with your system.  If you are using Windows you will need to install a SSH server, please reference the SSH server options for Windows or contact us for assistance.  To get your application to act as a server for FASP transfers you will need the following files, all of these files are found in the Aspera Redistributable Package:

  • Aspera Transfer Engine (ascp or ascp.exe) - This is used to initiate the transfers.
  • Aspera Configuration File (aspera.conf) - This is an XML based file that contains the configuration for the server.
  • Aspera License File (aspera-license) - This is the license file that should be used for your setup
  • Aspera SSH port Checker (aspshell.exe) - This is optional, and ensures that the SSH port opened by the Server is not used for anything except the Aspera transfers and browsers.
  • Asper Client Browser (ascmd.exe) - This is optional, but is required if you need to support file browsing for an Aspera Client.
  • Dependencies - This is optional and if needed would be included with the transfer engine found in the Redistributable Package.

In order to use server functionality you need to have an Aspera Server License.  The license file that is available in the Redistributable Package is a free Aspera Connect license that is not capable of supporting server functionality.  To get more information or to obtain a license please contact your Aspera Account Manager.

Deployment

Now that you have your needed files and SSH running you need to package and deploy all of the files to the target machine along with your custom application; you can copy these files to any directory, however, it is imperative that they are all in the same directory.  You will also need to add ascp and ascmd to the system path.  There are several ways to accomplish this, for example:

  • Add the location of ascp and ascmd to the System Path.
  • Copy the files ascp and ascmd to the system directory (this is not recommended).
  • Create a soft symbolic link to ascp and ascmd in the system directory (/usr/bin).

Configuration

All configuration on the server is done by editing the aspera.conf file.  You can learn more about the configuration options by reviewing the aspera.conf example file.  To configure the path to the Aspera transfer engine in your FASP Manager environment you should call one of the following methods (depending on what language you are using), if you do not FASP Manager may be able to detect and use the ascp transfer engine at runtime, however, by setting it manually you ensure it will run successfully and avoid ambiguity if multiple copies of ascp are installed.

//JavaEnvironment.setFasp2ScpPath(path);
//C#Environment.setfaspScpPath(path);
//C++Environment::SetFasp2AscpPath(path);

For example, you could run the following command in C# or Java to set the path to C:\\Program Files\Aspera\Enterprise Server\bin\ascp.exe.

Environment.setFasp2ScpPath("C:\\Program Files\\Aspera\\Enterprise Server\\bin\\ascp.exe");

Additional Options

That is actually all it takes to support FASP transfers.  With the above commands you will be able to connect to the server and perform transfers.  If you wish to take further control over the behavior you can use the following commands.  For the full list of options and methods please see the API Docs.

To subscribe your instance of FASP Manager for notifications about the transfers being initiated to your server by Aspera Clients you can call the following method (depending on the language you are using), if the argument is true FASP Manager will write the management port to a file that is used by ascp, if false FASP Manager will delete the management port file if it already exists.

//JavaFaspManager.listenForServerSessions(true);
//C#FaspManager.listenForServerSessions(true);
//C++Manager.ListenForServerSessions(true);

A potential drawback to the subscription method above is that your server allows transfers even when your custom application is not running. If you would prefer not to let any transfers happen if your application is not running you can either, choose a random local port number on the machine (high numbers are best for this purpose) or use the methods below to set a port. You also need to create a plain text file on the filesystem that contains the port number you have chosen. This file should be named "[your_app_name].port" and should be located in the /var/run/aspera directory of the ascp installation. You should leave this file on the system even when your application is not running.

//JavaFaspManager.setManagementPort(portNum);
//C#FaspManager.setManagementPort(portNum);
//C++Manager.SetManagementPort(port_no);

To receive transfer events in your application you need to add a global listener/callback to FASP Manager, this can be accomplished by use the following method.

//JavaFaspManager.addListener(listener);
//C#FaspManager.addListener(listener);
//C++Manager.AddGlobalCallback(callback);

 


Embedded Client

Here you will learn how to develop and deploy an Aspera Embedded Client.  

Prerequisites

To get your application to act as a client for FASP transfers you will need the following files, all of these files are found in the Aspera Redistributable Package:

  • Aspera Transfer Engine (ascp or ascp.exe) - This is used to initiate the transfers.
  • Aspera Configuration File (aspera.conf) - This is an XML based file that contains the configuration for the server.
  • Aspera License File (aspera-license) - This is the license file that should be used for your setup
  • Dependencies - This is optional and if needed would be included with the transfer engine found in the Redistributable Package.

The license file that is available in the Redistributable Package is a free Aspera Connect license.  To use this license you need an Aspera Connect server license on your Aspera server. If you intend to use Aspera Enterprise server license on the server, you need to purchase the client licenses separately from Aspera. Please contact your Aspera Account Manager for more information.

Deployment

Now that you have your needed files you need to package and deploy all of the files to the target machine along with your custom application; you can copy these files to any directory, however, it is imperative that they are all in the same directory. 

Configuration

To configure the path to the Aspera transfer engine in your FASP Manager environment you should call one of the following methods (depending on what language you are using), if you do not FASP Manager may be able to detect and use the ascp transfer engine at runtime, however, by setting it manually you ensure it will run successfully and avoid ambiguity if multiple copies of ascp are installed.

//JavaEnvironment.setFasp2ScpPath(path);
//C#Environment.setfaspScpPath(path);
//C++Environment::SetFasp2AscpPath(path);

For example, you could run the following command in C# or Java to set the path to C:\\Program Files\Aspera\Enterprise Server\bin\ascp.exe.

Environment.setFasp2ScpPath("C:\\Program Files\\Aspera\\Enterprise Server\\bin\\ascp.exe");

 


Reference

Persistent Sessions

A Persistent Session is a FASP session that does not require any predefined source or destination before being initiated.  Instead, the source and destination paths are provided to the Persistent Session through FASP Management commands when it is started.  Persistent Sessions are useful when multiple files will be sent in a session and full control is needed for each file being transferred.  It can also be useful when the paths names length are too long for the Operating System's command line length.

Essentially, when ascp starts a session and has the --keepalive option, it accepts commands on the management port which allows you to perform specific tasks.  For example:

  • You can add a source to the session by specifying the source and destination
    • FASPMGR 2
    • Type: START
    • Source: [source_path]
    • Destination: [dest_path]
  • You can cancel a source that is being transferred in the session
    • FASPMGR 2
    • Type: STOP
    • Source [source_path] - as seen in the management STAT messages
  • You can immediately close a session and stop all active and pending transfers
    • FASPMGR 2
    • Type: DONE
    • Operation: SHUTDOWN (optional)
  • You can close a session with a delay, which will allow all the active and pending transfers to complete
    • FASPMGR 2
    • Type: DONE
    • Operation: LINGER

Persistent Sessions in FASP Manager SDK

The concept of Persistent Sessions has been available since version 2.6. To use it in your application you can set the following parameters and run the following methods.

You will need to set the persist flag to true in the xferParams, you can do this with the following line of code:

xferParams.persist = true

Now that you have the persist parameter set to true you can create a job order without defining any source or destination path. You will then need to implement a transfer listener in your code and submit a transfer job with this listener. You can accomplish this by adding the following to your code (depending on what language you are using).

//Javacom.asperasoft.faspmanager.TransferListener listener = ...
//C++Aspera::FaspManager::CallbackFunctor listener = ...
//.NET C#Aspera::Transfer::FileTransferListener listener = ...

Once the session is reported as being initiated the listen receives a TransferEvent (SESSION_START) in Java and C# or a CallBack Event (F_EVENT_SESSION_START) in C++ which indicates that the session is ready to accept sources. You can start individual file transfers within the session as needed for your application. Normally, the implementation of the listener is a good place for this process. You should also note that the destination path is not mandatory, since if one is not specified the file will be saved in the user's document root path; you should also note that the remote path must be relative to the user's document root path if defined for that user.For example you could:

  • Add all the sources/destinations pairs at once
  • Add sources/destinations pairs back to back (add a subsequent source when the current is reported as completed)
  • Add the sources/destinations pairs following any other protocol

Now that you have implemented your listeners and actions you should stop or lock the session when all the files are transferred

 


FASP Management Ports

When ascp starts it is able to establish a socket connection that it can use to send progress reports and accept commands.  This connection is called a management connection.  They are normally used to allow external parties to manage a transfer session and listen for transfer information and take action accordingly.  This page explains how the connection is established and how you can use it.

To establish the connection you can use two options. The Command Line Option or the Management Port File.  You should know that ascp can only establish a maximum of 32 management connections and only 31 started using the Command Line Option and the accepting endpoint of the TCP connection must be up and listening on the port when ascp starts.

  • Command Line Option - "-M" is the option used to specify a management connection address to ascp.  This address can be either host:port or just a port.  If you use this option and it fails to establish the connection ascp will terminate.
  • Management Port File - ascp can look for files that match the pattern "[name].port" or "[name].optport" in the /var/run/aspera directory in the installation folder.  Each of these files, if any, can contain an address to be used for establishing a management connection.  If you use this option and it fails to establish the connection the ascp process will continue.  If you have these files present, but do not wish to use management port files you can start ascp with the option "-no-mgmt-port-files" which will ignore any management port files.

 

 


Download Byte Range of a File

Ascp allows you to download a range of bytes in a file.  This operation consists of specifying the starting and ending byte range to download in the command-line.  For example, the command line option is -@[start_byte]:[end_byte].  This is achieved by setting the range on the remote location when using the FASP Manager SDK.

To demonstrate this, an example in C++ and Java is presented below. Note: When you are developing a transfer application for byte range transfers, this only applies to a download on a single file. Therefore, the remote location must be defined as the source in the job order and only one file can be added.

C++ Byte Range Download

 

Java Byte Range Download

 

 


Documentation

Release Notes: IBM Aspera FASP Manager 3.7.2

Product Release: April 13, 2017
Release Notes Updated: April 13, 2017

Welcome to this release of IBM Aspera FASP Manager for Go, Java, .NET, and Python.

The FASP Manager SDK can be used to develop and package custom applications that do not require separate installation of any Aspera product on the target machine. The FASP Manager class library allows you to initiate, monitor and control FASP-based file transfers in your custom applications.

New Features

This release features the following updates and improvements:

  • SDK-22 - [.NET only] FASP Manager now includes the file checksum option --file-checksum=HASH.

  • SDK-20 - [.NET only] FASP Manager now includes the following options:
    • --apply-local-docroot
    • --delete-before-transfer
    • --ignore-host-key
    • --multi-session-threshold
    • --preserve-access-time and --preserve-source-access-time
    • --preserve-acls and --remote-preserve-acls
    • --preserve-creation-time
    • --preserve-modification-time
    • --preserve-xattrs and --remote-preserve-xattrs
    • --remove-empty-source-directory
    • --skip-dir-traversal-dupes/li>
    • --source-prefix

  • SDK-12 - [Java only] FASP Manager now includes the following options:
    • --delete-before-transfer
    • --ignore-host-key
    • --multi-session-threshold
    • --preserve-access-time and --preserve-source-access-time
    • --preserve-acls and --remote-preserve-acls
    • --preserve-creation-time
    • --preserve-xattrs and --remote-preserve-xattrs
    • --remove-empty-source-directory
    • --skip-dir-traversal-dupes
    • --source-prefix

Issues Fixed in This Release

  • SDK-26 - [Java only] FASP Manager now ensures that numerical values in an invalid format do not break the processing of management messages.
  • SDK-5 - [.NET only] A problem has been fixed that marked the file state as failed after a successful transfer.

Other Resources

Aspera FASP Manager documentation: https://developer.asperasoft.com/desktop/fasp-manager/index

Known Issues

  • SDK-7 - If you use Environment.setAscpPath( ) to set the ascp binary path, it must be called before FaspManager.getInstance( ) is invoked.

Product Support

For on-line support resources for Aspera products, including raising new support tickets, please visit the Aspera Support Portal. Note that you may have an existing account if you contacted the Aspera support team in the past. Before creating a new account, first try setting a password for the email that you use to interact with us. You may also call one of our regional support centers.

API Documentation

To view the API documentation, please select the language under the version that you are using

Version 3.7.2

Version 3.6.2

Version 3.6.1

Version 3.5.2

Version 3.2

 


Downloads

Download

To download the FASP Manager SDK, please choose a version and click Download for the appropriate language.

 


Video player

Video

×