aspshell Overview


aspshell Overview

aspshell is a hardened execution environment created by Aspera and provided for use with Aspera Enterprise Server and Point to Point products. aspshell is designed to replace the standard system shells (e.g. bash) as the system user’s default shell. The aspshell intentionally restricts the users functionality on the server system as per the description below. Although it is not required to use aspshell, it is highly recommended.


aspshell can function in two modes: Restricted mode and Loose mode. Restricted mode is designed for environments which only require transfers.   Loose mode is designed for environments where the client also needs to connect to the server and perform basic file operations (see description below).

In restricted mode, aspshell only allows the following commands to be executed:

# ascp -S. -V1
# ascp4 -S.
# ascp --no-mgmt-port-files -M %d -S. -V1 %1s
# async -q -S -s-

Command descriptions

ascp is the core Aspera process that runs during Aspera transfers. The ascp binary can function as either a client (transfer initiation, ssh client, FASP transfer, http fallback) or server side (transfer authorization and FASP transfer). Without the ascp binary, it is not possible to do Aspera FASP transfers.

When functioning as the server, ascp will read and write files within the docroot based on aspera.conf permissions (e.g. read allowed, write allowed). For existing files, and symbolic links, there are configuration options which define its behavior (e.g. Never overwrite, always overwrite, follow symlink, do not follow symlink).  The server ascp is capable of deleting a file after transfer in case of a download (e.g. It can download files and remove them after transfer, if it has sufficient permissions).

If asperacentral is running -- ascp will connect to it and report usage;  If redis is running and aspera.conf configured for redis reporting -- ascp will connect to it and report usage.

Additionally, ascp has the following special features that can be enabled in aspera.conf:

  • validation -- will call a URL defined in aspera.conf (useful for inline file validation)
  • external storage -- will call a URL defined in aspera.conf to get storage info
  • postprocessing -- will call a script called aspera-prepost if present in ../var
  • virtual link -- will broadcast and listen to broadcasts of other ascps (multicast or local broadcast) if configured in aspera.conf
  • management protocol -- if it finds *.port files in ../var/run it will connect to ports designated in the files and report stats
  • pvcl -- if there is a library ../lib/libpvcl*.so it will load it in order to find a virtual storage provider (if files are specified as URIs as in s3://...)

ascp4 is the 4th generation of ascp. It includes significant performance enhancements for ultra small files. Eventually, it will supplant ascp.

async is the synchronization engine that is used by Aspera customers to synchronize file system across wide area networks. The async is only needed for synchronization workflows, and it requires the ascp binary in order to function.  

NOTE: async can be run with accounts that are using aspshell, and aspshell-r, but only if it is enabled in the aspera.conf file  (e.g. async enabled).    

In loose mode, aspshell also allows the execution of ascmd if dir-allowed is set in the config file. In restricted mode (e.g. using aspshell-r as the user's default shell) ascmd cannot be executed. ascmd supports the following options:

Aspera ascmd usage

Command line options


-v Enable verbose logs
-e Enable exit on error
-A, --version Print ascmd version then exit
-V number, --protocol=number Protocol of communication (Max: 2, Default: 1)

Command line options


as_info client_version Get info on the client version
as_ls file_or_directory List the files in the current directory
as_rm file_or_directory Remove the file or directory specified
as_du file_or_directory Determine the size of the file or directory specified                                                             
as_mkdir directory Create a new directory
as_cp source_file_or_directory destination_file_or_directory Copy a file or directory
as_mv source_file_or_directory destination_file_or_directory Move a file or directory
as_df Determine size of disk partition
as_md5sum file Obtain md5sum of file

as_session_init [--host=hostname] [--protocol=number]

[additional parameters are ignored]

Initialize session



  1. Aspera strongly urges everyone to use the aspshell and the 'docroot' configuration. Use of the docroot will contain all user actions to the location defined by the docroot.

  2. aspshell is by default in ‘loose mode’. To enable restricted mode, you can use aspshell-r or disable dir-allowed in aspera.conf

  3. On Windows systems, the only way to enable a user account with the aspshell is to define a docroot using the Aspera GUI.  The Aspera GUI will configure both the docroot and the users default shell.

Powered by Zendesk