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.
- Extract the archive, for example in
~/.local/share, and check thatascliruns:
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
- Optionally, place a symbolic link to the launcher in a folder of the
PATH. Then,asclican 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.
-
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. -
In a terminal, in the extracted folder, check that
ascliruns:
.\ascli.cmd -v
- Optionally, double-click on
add_to_path.cmdto add the folder to the user'sPATH. Then, in a new terminal,asclican be used from any folder:
ascli -v
- 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". (
Msys2is needed to install some native extensions, such asgrpc) - Execute the installer, which installs by default in:
C:\RubyVV-x64(VVis the version number) - At the end of the installation procedure, the
Msys2installer is automatically executed, select option 3 (Msys2andmingw) - Then install the
aspera-cligem 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
~/.zprofilewith~/.bash_profilein 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 requireglibc >= 2.28. - Installation Compatibility:
- If the OS provides a Ruby package or DNF module stream meeting the required version (≥ 3.3), the
aspera-cligem can be installed directly withgem install. - If the OS is under maintenance but ships an older default system Ruby (e.g. Ubuntu 22.04 LTS with Ruby 3.0),
ascliis 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 asascpor 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_urloption: - If the value is not the default value (
DEF), it directly specifies the archive URL to download. - If the value is
DEF,asclidownloads the YAML file from the URLs specified by thelocations_urloption.- 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
LATESTis given the latest available version is used; otherwise the version tested with this release ofascliis 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_folderoption.
| 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:
-
Get the installation components from a system with internet access:
-
Ruby installation packages (depends on system)
-
Gems
Use the gem pack of the release. It includes the
aspera-cligem. On the air-gapped system, extract the archive and run:gem install *.gem -
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> -
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:
-
Follow the non-root installation procedure with RVM, including gem installation.
-
Archive the main RVM folder (includes ascli):
cd $HOME && tar zcvf rvm-ascli.tgz .rvm
-
Download the Transfer Daemon archive for the target architecture. See Install
ascp. -
Transfer the two archive files to the target system.
-
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>
- 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.
- 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
-
Create a gem archive as described in Packaging gem files and dependencies.
-
Download the Transfer Daemon. See Install
ascp. -
Create a Zip archive containing all the files above and transfer it to the target system.
On the target system:
-
Extract the archive.
-
Run the Ruby installer:
<RUBY_INSTALLER_EXE> /silent /currentuser /noicons /dir=<INSTALL_DIR>
- Install the gems: extract the gem archive, then run:
gem install --force --local *.gem
- 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 anArray(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