Skip to content

Installation🔗

There are several ways to install ascli:

  • Using a Ruby environment directly on the host operating system (Linux, macOS, Windows).

This is the most general method. It consists of installing: - The Ruby language, - The aspera-cli Ruby gem, - Aspera Transfer Daemon (ascp). - As a single file executable

This method is simple, but only a limited number of platforms are supported. - On Linux, as a portable package

This method is simple on Linux: extract and run, without root access. It includes Ruby, gems and ascp. - On Windows, as a portable package

This method is the simplest on Windows: extract and run. It includes Ruby, gems and ascp. - On Windows, with the Chocolatey package (installs Ruby and the gem). - As a container (docker, podman, singularity).

The following sections describe the various installation methods.

An internet connection is required during installation. If you do not have internet access, see Installing in an air-gapped environment.

Single file executable🔗

Warning

Available only on a limited number of platforms.

ascli is available as a single platform-dependent executable in the Releases. This executable includes the Ruby runtime and gems, but not the transfer SDK.

Installing the single file executable🔗

Note

Replace <VERSION> and <PLATFORM> with the values of the downloaded archive, for example: linux-x86_64-glibc2.28-ocran. The archive contains the executable ascli and its README.ascli.md. Installation of ascp is still required separately. See Install ascp.

tar zxvf aspera-cli-<VERSION>-<PLATFORM>.tgz
./ascli transferd install

Linux: Checking the GLIBC version🔗

Warning

On Linux, the executable requires a minimum GLIBC version, specified in the archive name on the download site (for example: glibc2.28). If the minimum version is not met, then executables (ascp, transferd) will exit with error.

On Linux, you can check your system's GLIBC version on this site: repology.org, or check your GLIBC version with ldd:

ldd --version | head -n1
ldd (GNU libc) 2.34

Check an executable's (for example, /bin/bash, ascli, ascp) minimum required GLIBC version:

objdump -p /bin/bash | sed -n 's/^.*GLIBC_//p' | sort -V | tail -n1
2.34

Note

If objdump is not available, then use strings or grep -z 'GLIBC_'|tr \\0 \\n

The required GLIBC version for ascp can be found in the Release Notes of HSTS or on this page.

Linux: Portable package🔗

A ready-to-use archive for Linux (x86_64) is available in the Releases: aspera-cli-<VERSION>-linux-x86_64-glibc2.28-portable.tgz.

It contains the Ruby runtime with the shared libraries it needs, the aspera-cli gem with its dependencies, and the Aspera Transfer SDK (ascp). No installation step, no root access, and no internet access are required. The GLIBC of the system must be at least the version in the archive name, see Checking the GLIBC version.

  1. Extract the archive, for example in ~/.local/share, and check that ascli runs:
tar -xzf aspera-cli-<VERSION>-linux-x86_64-glibc2.28-portable.tgz -C ~/.local/share
~/.local/share/aspera-cli-<VERSION>-linux-x86_64-glibc2.28-portable/ascli -v
  1. Optionally, place a symbolic link to the launcher in a folder of the PATH. Then, ascli can be used from any folder:
ln -s ~/.local/share/aspera-cli-<VERSION>-linux-x86_64-glibc2.28-portable/ascli ~/.local/bin/ascli
ascli -v

Note

The launcher ascli uses the ascp located in folder sdk of the package, unless environment variable ASCLI_SDK_FOLDER is set. So, ascli transferd install is not needed.

The configuration is stored in the main folder, like for other installation methods. To upgrade, extract the new version, and update the symbolic link. To uninstall, delete the folder, and the symbolic link if it was created.

Windows: Portable package🔗

A ready-to-use ZIP archive for Windows (x64) is available in the Releases: aspera-cli-<VERSION>-windows-x86_64-portable.zip.

It contains the Ruby runtime, the aspera-cli gem with its dependencies, and the Aspera Transfer SDK (ascp). Apart from the prerequisite below, no installation step, no administrator rights, and no internet access are required.

Info

The package does not include the Microsoft Visual C++ Redistributable (x64), which ascp requires. If it is not already present on the system, install it from Microsoft Visual C++ Redistributable latest supported downloads (administrator rights required), otherwise transfers fail.

  1. Download the ZIP archive, then right-click on it and select Extract All.... Preferably, extract in a folder writable by the user, for example: %LOCALAPPDATA%\Programs.

  2. In a terminal, in the extracted folder, check that ascli runs:

.\ascli.cmd -v
  1. Optionally, double-click on add_to_path.cmd to add the folder to the user's PATH. Then, in a new terminal, ascli can be used from any folder:
ascli -v
  1. Optionally, activate the shell completion of PowerShell (the folder must be in the PATH).

Note

The launcher ascli.cmd uses the ascp located in folder sdk of the package, unless environment variable ASCLI_SDK_FOLDER is set. So, ascli transferd install is not needed.

The configuration is stored in the main folder, like for other installation methods. To upgrade, extract the new version, and update the PATH if the folder name changed. To uninstall, delete the folder, and remove it from the PATH if it was added.

Windows: Chocolatey package🔗

If you use Chocolatey, ascli can be installed with the aspera-cli package: it installs Ruby (if not already present) and the aspera-cli gem.

In a PowerShell as Administrator:

choco install aspera-cli -y

Then, install the Aspera Transfer Daemon, see Installing ascp through transferd.

Ruby🔗

A Ruby interpreter is required to run ascli.

Required Ruby version is version: >= 3.3.

Warning

The minimum Ruby version will be 3.4 in a future version.

Ruby can be installed using any of the following methods: rpm, yum, dnf, rvm, rbenv, brew, Windows installer, ...

First, refer to the official Ruby documentation:

For convenience, you may refer to the following sections for a proposed method for specific operating systems.

ascli supports a Ruby version until 6 months after its end of official support. The minimum version is increased accordingly, and announced in advance. If only an older Ruby version must be used due to system constraints, use an older version of ascli that supports it; refer to rubygems.org.

The following table summarizes Ruby version life cycles and ascli support status:

Ruby Version Official EOL Date ascli Support End (EOL + 6 mo) ascli Status
4.0 2029-03-31 2029-09-30 Supported (Tested & Packaged)
3.4 2028-03-31 2028-09-30 Supported (Future minimum)
3.3 2027-03-31 2027-09-30 Supported (Current minimum)
3.2 2026-03-31 2026-09-30 End of Support
3.1 2025-03-26 2025-09-26 End of Support
3.0 2024-04-23 2024-10-23 End of Support

Windows: Installer🔗

Manual installation:

  • Navigate to https://rubyinstaller.org/ → Downloads.
  • Download the latest Ruby installer "with devkit". (Msys2 is needed to install some native extensions, such as grpc)
  • Execute the installer, which installs by default in: C:\RubyVV-x64 (VV is the version number)
  • At the end of the installation procedure, the Msys2 installer is automatically executed, select option 3 (Msys2 and mingw)
  • Then install the aspera-cli gem and Aspera Transfer Daemon (see next sections)

Automated installation (with internet access):

The Ruby installer supports silent installation. To see the options, execute it with /help, or refer to the Ruby Installer FAQ.

Download the Ruby installer executable from https://rubyinstaller.org/downloads/ and then install:

rubyinstaller-devkit-3.2.2-1-x64.exe /silent /currentuser /noicons /dir=C:\aspera-cli

Windows: Chocolatey🔗

If you use Chocolatey, then install Ruby with:

choco install ruby

macOS: brew🔗

If you use Homebrew, then install Ruby with:

brew install ruby

Note

This is the recommended method.

Warning

macOS comes with Ruby 2.6. It is an old unsupported version and Apple has deprecated it. It will be removed from macOS in the future. Do not use it. Use the required version of Ruby.

This installs a recent Ruby version suitable for ascli.

After installation, Homebrew's Ruby is not on the PATH by default (this is shown at the end of the brew install ruby output and by brew info ruby). Add it to your shell configuration file:

  • zsh (default shell on macOS; run this once in a terminal):
echo 'PATH="$(brew --prefix ruby)/bin:$($(brew --prefix ruby)/bin/gem env gemdir)/bin:$PATH"' >> ~/.zprofile
source ~/.zprofile
  • bash: replace ~/.zprofile with ~/.bash_profile in the commands above.

Linux: Package🔗

ascli supports Linux distributions that are officially maintained by their vendor (Red Hat for RHEL / UBI, Canonical for Ubuntu LTS).

  • GLIBC Requirement: The Transfer SDK executables (ascp, transferd) and the Linux portable package require glibc >= 2.28.
  • Installation Compatibility:
  • If the OS provides a Ruby package or DNF module stream meeting the required version (≥ 3.3), the aspera-cli gem can be installed directly with gem install.
  • If the OS is under maintenance but ships an older default system Ruby (e.g. Ubuntu 22.04 LTS with Ruby 3.0), ascli is fully supported via the Linux portable package, the container image, or a Ruby version manager (rbenv, rvm).

The following table summarizes supported Linux distributions, vendor end of support dates, GLIBC versions, available Ruby streams, and recommended ascli installation modes:

Linux Distribution OS Support End (EOL) GLIBC (>= 2.28) OS Ruby Version(s) ascli Support / Mode
RHEL / UBI 10 2035-05-31 2.39+ (Compatible) >= 3.3 (default) Gem, Portable, Container
RHEL / UBI 9 2032-05-31 2.34 (Compatible) 3.0 (default), 3.1, 3.3 (DNF module) Gem (dnf module enable ruby:3.3), Portable, Container
RHEL / UBI 8 2029-05-31 2.28 (Compatible) 3.1, 3.3 (DNF module) Gem (dnf module enable ruby:3.3), Portable, Container
Ubuntu 26.04 LTS 2031-05-29 2.43+ (Compatible) >= 3.3 (APT package) Gem, Portable, Container
Ubuntu 24.04 LTS 2029-05-31 2.39 (Compatible) 3.2 (APT package) Gem (apt install ruby-full), Portable, Container
Ubuntu 22.04 LTS 2027-06-01 2.35 (Compatible) 3.0 (APT package) Portable, Container, rbenv (OS Ruby < 3.2)

If your Linux distribution provides a standard Ruby package, you can use it provided that the version is supported.

Example: RHEL 8+, Rocky Linux 8+: with extensions to compile native gems:

  • Check available Ruby versions:
dnf module list ruby
  • If Ruby was already installed with an older version, remove it:
dnf module -y reset ruby
  • Install packages needed to build native gems:
dnf install -y make automake gcc gcc-c++ kernel-devel
  • Enable the Ruby version you selected:
dnf module -y enable ruby:3.3

dnf install -y ruby-devel

Example: Ubuntu

apt-get install -y ruby-full

Other examples:

yum install -y ruby ruby-devel rubygems ruby-json
apt install -y ruby ruby-dev rubygems ruby-json

One can remove all installed gems, for example to start fresh:

ls $(gem env gemdir)/gems/|sed -e 's/-[^-]*$//'|sort -u|xargs gem uninstall -axI
rm -f Gemfile.lock

Unix-like: RVM: Single user installation (not root)🔗

Install rvm. Follow https://rvm.io/.

Execute the shell/curl command. As regular user, it installs in the user's home: ~/.rvm.

\curl -sSL https://get.rvm.io | bash -s stable

Follow on-screen instructions to install keys, and then re-execute the command.

Upon RVM installation, open a new terminal or initialize with:

source ~/.rvm/scripts/rvm

It is advised to use one of the precompiled Ruby versions; you can list them with:

rvm list --remote

Install the chosen pre-compiled Ruby version:

rvm install 3.2.2

Ruby is now installed for the user, go to Gem installation.

Alternatively RVM can be installed system-wide, for this execute as root. It then installs by default in /usr/local/rvm for all users and creates /etc/profile.d/rvm.sh. One can install in another location with:

curl -sSL https://get.rvm.io | bash -s -- --path /usr/local

As root, verify that this will not collide with other applications using Ruby (for example, Faspex). If so, one can rename the environment script so that it is not loaded by default:

mv /etc/profile.d/rvm.sh /etc/profile.d/rvm.sh.ok

To activate Ruby (and ascli) later, source it:

source /etc/profile.d/rvm.sh.ok
rvm version

On macOS, one way to force use of OpenSSL 3.0 is:

RUBY_CONFIGURE_OPTS="--with-openssl-dir=$(brew --prefix openssl@3.0)" rvm install 3.4.0

Unix-like: rbenv🔗

If you do not have root access, you can install Ruby in your home directory using rbenv, see rbenv-installer:

curl -fsSL https://github.com/rbenv/rbenv-installer/raw/HEAD/bin/rbenv-installer | bash

Then open a new terminal, or source the shell initialization script:

source ~/.bashrc

Then install Ruby:

rbenv install 3.2.2

Other Unixes (AIX)🔗

Ruby is sometimes made available as an installable package through third party providers. For example for AIX, one can look at:

https://www.ibm.com/support/pages/aix-toolbox-open-source-software-downloads-alpha#R

If your Unix does not provide a pre-built Ruby, you can get it using one of those methods.

For instance, to build from source and install in /opt/ruby:

wget https://cache.ruby-lang.org/pub/ruby/x.y/ruby-x.y.z.tar.gz

gzip -d ruby-x.y.z.tar.gz

tar xvf ruby-x.y.z.tar

cd ruby-x.y.z

./configure --prefix=/opt/ruby

make ruby.imp

make

make install

JRuby🔗

ascli can also run with the JRuby interpreter. All that is needed is a JVM (Java Virtual Machine) on your system (java). The JRuby package comes pre-compiled and does not require compilation of native extensions. Use a version of JRuby compatible with a Ruby version supported by ascli. See the Wikipedia page to match JRuby and Ruby versions. Choose the latest version from:

https://www.jruby.org/download

Warning

The startup time is slightly longer using jruby than the native Ruby. See the JRuby wiki for details. This can be reduced by using the --dev option. The transfer speed is not impacted (executed by ascp binary).

Note

JRuby can be installed using rvm.

Example: Start ascli with JRuby and reduce startup time:

export JRUBY_OPTS=--dev
ascli -v

Or:

JRUBY_OPTS=--dev ascli -v

Installing optional gems🔗

Some additional gems are required for either development or specific runtime features. For JRuby, some of them have a replacement gem, and others are not available. Those are not installed as part of dependencies because they involve compilation of native code but concern less-used features.

See Gemfile:

name version comment
rake ~> 13.0
debug ~> 1.11 (no jruby)
grpc-tools ~> 1.67
reek ~> 6.6.0
rspec ~> 3.0
rubocop ~> 1.75
rubocop-ast ~> 1.4
rubocop-performance ~> 1.10 (no jruby)
rubocop-shopify ~> 3.1
simplecov ~> 1.3
solargraph ~> 0.48 (no jruby)
ferrum ~> 0.20.1 (no jruby)
mcp ~> 1.2 for ascli mcp server (MCP protocol support)
rack ~> 3.0 for ascli mcp server HTTP transport (required by mcp StreamableHTTPTransport)
grpc ~> 1.71 (no jruby) for Aspera Transfer Daemon
sqlite3 ~> 2.7 (no jruby) for async DB
jdbc-sqlite3 ~> 3.46 (jruby) for async DB
sequel ~> 5.96 (jruby) for async DB
bcrypt_pbkdf ~> 1.1 (no jruby) for passphrase-protected OpenSSH private keys (ed25519 is native in net-ssh 8)
syslog ~> 0.3 (no jruby) for logger=syslog
zxcvbn ~> 1.0 for better estimate of secret strength (faspex5 postprocessing secret_token)
keeper_secrets_manager ~> 17.2 for vault of type keeper (Keeper Secrets Manager)
rmagick ~> 7.2 (no jruby) for terminal view

Install like this:

gem install rake -v '~> 13.0'
gem install debug -v '~> 1.11'
gem install grpc-tools -v '~> 1.67'
gem install reek -v '~> 6.6.0'
gem install rspec -v '~> 3.0'
gem install rubocop -v '~> 1.75'
gem install rubocop-ast -v '~> 1.4'
gem install rubocop-performance -v '~> 1.10'
gem install rubocop-shopify -v '~> 3.1'
gem install simplecov -v '~> 1.3'
gem install solargraph -v '~> 0.48'
gem install ferrum -v '~> 0.20.1'
gem install mcp -v '~> 1.2'
gem install rack -v '~> 3.0'
gem install grpc -v '~> 1.71'
gem install sqlite3 -v '~> 2.7'
gem install jdbc-sqlite3 -v '~> 3.46'
gem install sequel -v '~> 5.96'
gem install bcrypt_pbkdf -v '~> 1.1'
gem install syslog -v '~> 0.3'
gem install zxcvbn -v '~> 1.0'
gem install keeper_secrets_manager -v '~> 17.2'
gem install rmagick -v '~> 7.2'

Ruby gem: aspera-cli🔗

Once you have Ruby and rights to install gems, install the aspera-cli gem and its dependencies:

gem install aspera-cli --pre

To upgrade to the latest version:

gem update aspera-cli

During execution, ascli checks weekly whether a new version is available and notifies the user via a WARN log entry. To deactivate this feature, globally set the option version_check_days to 0, or specify a different period in days.

To check if a new version is available (independently of version_check_days):

ascli config check_update

Verifying gem installation signature🔗

The gem is signed with a private key, and the public certificate is available in the GitHub repository (certs/aspera-cli-public-cert.pem). When installing the gem, the signature may optionally be verified.

For secure installation, one can install the gem with the public key:

Import the verification certificate:

gem cert --add <(curl -Ls https://raw.githubusercontent.com/IBM/aspera-cli/main/certs/aspera-cli-public-cert.pem)

The user installs the gem with HighSecurity or MediumSecurity: this will succeed only if the gem is trusted:

gem install -P MediumSecurity aspera-cli

Installing a beta release of the gem🔗

A beta version of the gem can be found here: https://ibm.biz/aspera-cli-beta

On Linux/macOS, install in a terminal:

curl -sLo aspera-cli-beta.gem https://ibm.biz/aspera-cli-beta
gem install aspera-cli-beta.gem

On Windows, download the file aspera-cli-beta.gem from the link, then install it with gem install aspera-cli-beta.gem.

FASP Protocol: ascp🔗

File transfers are primarily performed using the FASP protocol via the ascp utility.

To execute an Aspera transfer, only two additional files are required; both are included with the Aspera Transfer Daemon:

  • ascp - the transfer executable

  • aspera-license - the license file (located in the same directory as ascp or in ../etc)

These components can be installed either by installing the Aspera transfer software or by running the ascli command.

Installing ascp through transferd🔗

The easiest option to install ascp is through the use of the IBM Aspera Transfer Daemon (transferd). Install it using ascli (for the current platform) with:

ascli transferd install

The installation of the transfer binaries follows those steps:

  • Select the SDK package to use. Check the sdk_url option:
  • If the value is not the default value (DEF), it directly specifies the archive URL to download.
  • If the value is DEF, ascli downloads the YAML file from the URLs specified by the locations_url option.
    • URLs are tried in order until one succeeds. All but the last are tried with a short timeout and no retry. By default: https://ibm.biz/sdk_location, then its target on GitHub.
    • This YAML file lists supported architectures (OS, CPU) and Aspera Transfer Daemon versions with their associated package URLs.
    • The SDK version is selected as follows: if an additional positional parameter is provided it specifies the version; if the special value LATEST is given the latest available version is used; otherwise the version tested with this release of ascli is used.
    • The package URL matching the current system architecture is then used.
  • Extract the archive
  • By default, the archive is extracted to $HOME/.aspera/sdk.
  • The destination folder can be changed by setting the sdk_folder option.
Option Description
sdk_url URL to download the Aspera Transfer Daemon archive.
Default: DEF (select from available archives.)
locations_url List of URLs to get download URLs of Aspera Transfer Daemon from IBM official repository, tried in order.
A list given in options replaces the default list.
Default:
- https://ibm.biz/sdk_location
- https://raw.githubusercontent.com/IBM/aspera-cli/refs/heads/main/docs/sdk_location.yaml
sdk_folder Folder where the SDK archive is extracted.
Default: $HOME/.aspera/sdk

Note

Commands config transferd ... and config ascp install are deprecated aliases of transferd ... and transferd install.

Transfer Daemon versions available from locations_url can be listed with: ascli transferd list

To install a specific version, for example, 1.1.3:

ascli transferd install 1.1.3

To get the download URL for a specific platform and version:

ascli transferd list --select.platform=osx-arm64 --select.version=1.1.3 --fields=url

To download it, pipe to config download:

ascli transferd list --select.platform=osx-arm64 --select.version=1.1.3 --fields=url | ascli config download @stdin:

To install from a local file (air-gapped installation) instead of fetching from the internet, specify the location of the SDK file with option sdk_url:

ascli transferd install --sdk-url=file:///macos-arm64-1.1.3-c6c7a2a.zip

The format is: file:///<PATH> (canonical form) or file:<PATH> (short form), where <PATH> can be either a relative path (not starting with /), or an absolute path (starting with /).

Form Relative example Absolute example
Canonical file:///mydir/archive.zip file:////home/user/archive.zip
Short file:mydir/archive.zip file:/home/user/archive.zip

Supported platforms are listed in the Release Notes and archives can be downloaded from Downloads.

Installing ascp through another component🔗

If the embedded method is not used, the following packages are also suitable:

  • IBM Aspera Connect Client (Free, to be deprecated in 2027, use IBM Aspera for Desktop)
  • IBM Aspera Desktop Client (Free)
  • IBM Aspera for Desktop (Free)
  • IBM Aspera High Speed Transfer Server (Licensed)
  • IBM Aspera High Speed Transfer Endpoint (Licensed)

For instance, Aspera Connect Client can be installed by visiting the page: https://www.ibm.com/aspera/connect/.

ascli detects most Aspera transfer products in standard locations and use the first one found by default. See FASP for details on how to select a client or set path to the FASP protocol.

Several methods are provided to start a transfer. Use of a local client (direct transfer agent) is one of them, but other methods are available. See Transfer Agents.

Installing in an air-gapped environment🔗

For an air-gapped installation, two alternatives are available:

  1. Get the installation components from a system with internet access:

  2. Ruby installation packages (depends on system)

  3. Gems

    Use the gem pack of the release. It includes the aspera-cli gem. On the air-gapped system, extract the archive and run:

    gem install *.gem
    
  4. Transfer SDK

    On a system with internet access, retrieve the SDK archive for the target platform and version:

    ascli transferd list --select.platform=<PLATFORM> --select.version=<VERSION> --fields=url | ascli config download @stdin:
    

    On the air-gapped system, install from the downloaded file using option --sdk-url:

    ascli transferd install --sdk-url=file:///<SDK_ARCHIVE_PATH>
    
  5. Retrieve the single file executable from the release, if available, and the SDK (not included) as described above.

Packaging gem files and dependencies🔗

Releases include gem packs: gempack.zip contains the minimal bundle of required gems.

Alternatively, the necessary gems can be packaged into a tar.gz archive as follows:

mkdir temp_folder
gem install aspera-cli:4.29.0.pre --no-document --install-dir temp_folder
find temp_folder
mv temp_folder/cache aspera-cli-4.29.0.pre-gems
rm -fr temp_folder
tar zcvf aspera-cli-4.29.0.pre-gems.tgz aspera-cli-4.29.0.pre-gems

Unix-like: Alternative installation using rvm🔗

The following procedure applies when using RVM for the Ruby installation:

  1. Follow the non-root installation procedure with RVM, including gem installation.

  2. Archive the main RVM folder (includes ascli):

cd $HOME && tar zcvf rvm-ascli.tgz .rvm
  1. Download the Transfer Daemon archive for the target architecture. See Install ascp.

  2. Transfer the two archive files to the target system.

  3. On the target system, run:

cd $HOME
tar zxvf rvm-ascli.tgz
source ~/.rvm/scripts/rvm
ascli transferd install --sdk-url=file:///<SDK_ARCHIVE_PATH>
  1. Add the following line to the shell environment file (.profile):
source ~/.rvm/scripts/rvm

Windows: Installing in an air-gapped environment🔗

Tip

The simplest method is to use the portable package, which requires no internet access on the target system.

The procedure is similar to the internet-connected Windows installation. Copy the required files from a system with internet access, then install them on the target system.

  1. Download the Ruby installer from https://rubyinstaller.org/downloads/:
v=$(curl -s https://rubyinstaller.org/downloads/ | sed -nEe 's|.*(https://.*/releases/download/.*exe).*|\1|p' | head -n 1)
curl -o ${v##*/} $v
  1. Create a gem archive as described in Packaging gem files and dependencies.

  2. Download the Transfer Daemon. See Install ascp.

  3. Create a Zip archive containing all the files above and transfer it to the target system.

On the target system:

  1. Extract the archive.

  2. Run the Ruby installer:

<RUBY_INSTALLER_EXE> /silent /currentuser /noicons /dir=<INSTALL_DIR>
  1. Install the gems: extract the gem archive, then run:
gem install --force --local *.gem
  1. Install the Aspera Transfer Daemon SDK:
ascli transferd install --sdk-url=file:///<SDK_ARCHIVE_PATH>

Container🔗

The container image is: docker.io/martinlaurent/ascli. The container contains: Ruby, ascli and the Aspera Transfer Daemon. To use the container, ensure that you have podman (or docker) installed.

podman --version

Container: Quick start🔗

To start an interactive shell, run:

podman run --rm --tty --interactive --entrypoint bash docker.io/martinlaurent/ascli:latest

Note

This command changes the entry point to an interactive shell instead of direct execution of ascli.

Then, execute individual ascli commands such as:

ascli config initdemo
ascli config preset overview
ascli config ascp info
ascli server ls /

That is simple, but there are limitations:

  • Everything happens in the container.
  • Any file generated in the container, including configuration files and downloaded files, is lost when the container (shell) exits.
  • Files located on the host system cannot be uploaded.

Container: Details🔗

The container image is built from this Dockerfile. The entry point is ascli and the default command is help.

The container can be executed for individual commands like this: (add ascli commands and options at the end of the command line, for example, -v to display the version)

podman run --rm --tty --interactive docker.io/martinlaurent/ascli:latest

For more convenience, you may define a shell alias:

alias ascli='podman run --rm --tty --interactive docker.io/martinlaurent/ascli:latest'

Then, you can execute the container like a local command:

ascli -v
4.29.0.pre

To persist the configuration on the host, specify your user's configuration folder as a volume for the container. To enable write access, a possibility is to run as root in the container (and set the default configuration folder to /home/cliuser/.aspera/ascli). Add options:

--user root --env ASCLI_HOME=/home/cliuser/.aspera/ascli --volume $HOME/.aspera/ascli:/home/cliuser/.aspera/ascli

Note

If you are using a podman machine, for example, on macOS, ensure that the folder is also shared between the VM and the host, so that sharing is:

container → VM → Host: podman machine init ... --volume="/Users:/Users"

As shown in the quick start, if you prefer to keep a running container with a shell and ascli available, you can change the entry point, add option:

--entrypoint bash

Warning

ascli is run inside the container, so transfers are also executed inside the container and do not have access to host storage by default.

You may also want files downloaded in the container to be available on the host. For example, files transferred with ascli through folder /xferfiles (right-hand side) would be available on the host in $HOME/xferdir. In this case, you also need to specify the shared transfer folder as a volume:

--volume $HOME/xferdir:/xferfiles

To combine all the above options:

alias asclish="podman run --rm --tty --interactive --user root --env ASCLI_HOME=/home/cliuser/.aspera/ascli --volume $HOME/.aspera/ascli:/home/cliuser/.aspera/ascli --volume $HOME/xferdir:/xferfiles --entrypoint bash docker.io/martinlaurent/ascli:latest"
export xferdir=$HOME/xferdir
mkdir -p $xferdir
chmod -R 777 $xferdir
mkdir -p $HOME/.aspera/ascli
asclish

Container: Sample start script🔗

A convenience sample script is also provided: download the script dascli from the GitHub repository.

Some environment variables can be set for this script to adapt its behavior:

env var Description Default Example
ASCLI_HOME Configuration folder (persistency) $HOME/.aspera/ascli $HOME/.ascli_config
docker_args Additional options to podman <empty> --volume /Users:/Users
image Container image name docker.io/martinlaurent/ascli n/a
version Container image version Latest 4.8.0.pre

The wrapping script maps the folder $ASCLI_HOME on the host to /home/cliuser/.aspera/ascli in the container (the configuration folder expected in the container). This keeps the configuration persistent on the host.

To add local storage as a volume, you can use the env var docker_args:

Example of use:

curl -o ascli https://raw.githubusercontent.com/IBM/aspera-cli/main/build/container/dascli
chmod a+x ascli
export xferdir=$HOME/xferdir
mkdir -p $xferdir
chmod -R 777 $xferdir
export docker_args="--volume $xferdir:/xferfiles"

./ascli config initdemo

echo 'Local file to transfer' > $xferdir/samplefile.txt
./ascli server upload /xferfiles/samplefile.txt --to-folder=/Upload

Note

The local file path is the one seen from the container (/xferfiles/samplefile.txt), where /xferfiles is mapped to the host folder $HOME/xferdir.

Warning

Do not use too many volumes, as the legacy aufs driver limits their number. Prefer the overlay2 driver.

Container: Installing in an air-gapped environment🔗

  • First create the image archive:
podman pull docker.io/martinlaurent/ascli
podman save docker.io/martinlaurent/ascli|gzip>ascli_image_latest.tar.gz
  • Then, on the air-gapped system:
podman load -i ascli_image_latest.tar.gz

Container: aspera.conf🔗

ascp's configuration file aspera.conf is located in the container at: /ibm_aspera/aspera.conf (see Dockerfile). As the container is immutable, modifying this file is not recommended. To change the configuration, tell ascp to use another file using ascp option -f, for example, by locating it on the host folder $HOME/.aspera/ascli mapped to the container folder /home/cliuser/.aspera/ascli:

echo '<CONF/>' > $HOME/.aspera/ascli/aspera.conf

Then, tell ascp to use that other configuration file:

--transfer=@json:'{"ascp_args":["-f","/home/cliuser/.aspera/ascli/aspera.conf"]}'

Container: Singularity🔗

Singularity is another container runtime.

On Linux install:

dnf install singularity-ce

Build an image like this:

singularity build ascli.sif docker://docker.io/martinlaurent/ascli

Then, start ascli like this:

singularity run ascli.sif

Or get a shell with access to ascli like this:

singularity shell ascli.sif

Configuring the SSL library🔗

ascli uses the Ruby openssl gem which uses by default the system's openssl library and its CA certificate bundle.

To display the version of OpenSSL used in ascli:

ascli config echo @ruby:OpenSSL::OPENSSL_VERSION --format=text

To use another SSL library or version, execute:

gem install openssl -- --with-openssl-dir=[openssl library folder]

Where [openssl library folder] is the path to the folder containing the lib and include folders of the openssl library.

For example, on macOS, to use the openssl@3 library installed with brew:

openssl version -e|sed -n 's|ENGINESDIR: "\(.*\)/lib[^/]*/.*|\1|p'
/opt/homebrew/Cellar/openssl@3/3.3.0

Then install the openssl gem with:

gem install openssl -- --with-openssl-dir=$(openssl version -e|sed -n 's|ENGINESDIR: "\(.*\)/lib[^/]*/.*|\1|p')

Configuring the SSL CA certificate bundle🔗

SSL certificates are validated using a certificate store. By default, it is the one of the system's openssl library.

To display the default trusted certificate store locations:

ascli config echo '@ruby:[OpenSSL::X509::DEFAULT_CERT_DIR,OpenSSL::X509::DEFAULT_CERT_FILE]'

Certificates are checked against the Ruby default certificate store OpenSSL::X509::DEFAULT_CERT_FILE and OpenSSL::X509::DEFAULT_CERT_DIR, which are typically the ones of openssl on Unix-like systems (Linux, macOS, and so on). Ruby's default values can be overridden using env vars: SSL_CERT_FILE and SSL_CERT_DIR. If neither these env vars are set nor the default locations exist (for example, a single executable built on another Linux distribution), ascli sets SSL_CERT_FILE to the first system CA bundle found: /etc/ssl/certs/ca-certificates.crt, /etc/pki/tls/certs/ca-bundle.crt, /etc/ssl/ca-bundle.pem, /etc/ssl/cert.pem.

To get certificate validation, the CA certificate bundle must be up-to-date. Check this repository on how to update the system's CA certificate bundle: https://github.com/millermatt/osca.

For example, on RHEL/Rocky Linux:

dnf install -y ca-certificates
update-ca-trust extract

The SSL CA certificate bundle can be specified using the cert_stores option, which accepts a list of files or directories. By default, Ruby's system certificate store is used.

When cert_stores is provided:

  • It overrides the default locations, which can still be included explicitly using the special value DEF.
  • The option accepts either a String (single path) or an Array (multiple paths).
  • Each use of the option appends to the list of search paths incrementally.
  • If a directory is specified, all files within that directory are automatically included.

Note

JRuby uses its own implementation and CA bundles.

For example, on Linux, to force the use of the system's certificate store:

--cert-stores=$(openssl version -d|cut -f2 -d'"')/cert.pem

ascp also needs to validate certificates when using WSS for transfer TCP part (instead of SSH).

By default, ascp uses a hard-coded root location OPENSSLDIR. Original ascp's hard-coded locations can be found using:

ascli config ascp info --fields=openssldir

For example, on macOS: /Library/Aspera/ssl. Then trusted certificates are taken from [OPENSSLDIR]/cert.pem and files in [OPENSSLDIR]/certs. ascli overrides the default hard-coded location used by ascp for WSS and uses the same locations as specified in cert_stores (using the -i option of ascp).

To update trusted root certificates for ascli, update the system's root certificate store (see the locations displayed above).

An up-to-date version of the certificate bundle can also be retrieved with:

ascli config echo @uri:https://curl.se/ca/cacert.pem --format=text

To download that certificate store:

ascli config echo @uri:https://curl.se/ca/cacert.pem --format=text --out.file=/tmp/cacert.pem

Then, use this store by setting the option cert_stores (or env var SSL_CERT_FILE).

To trust a specific certificate (for example, self-signed), provided that the CN is correct, save the certificate chain to a file:

ascli config remote_certificate chain https://localhost:9092 --insecure=yes --out.file=<SERVER_PRESET_NAME>.pem

Note

Use command name to display the remote common name of the remote certificate.

Then, use this file as certificate store (for example, here, Node API):

ascli config echo @uri:https://localhost:9092/ping --cert-stores=<SERVER_PRESET_NAME>.pem