Skip to content

Plugin: server: IBM Aspera High Speed Transfer Server (SSH)🔗

The server plugin is used for operations on Aspera HSTS using SSH authentication.

It is the original way of accessing an Aspera Server, often used for server to server transfers. An SSH session is established, authenticated with either a password or an SSH private key. Then, commands ascp (for transfers) and ascmd (for file operations) are executed.

Info

If you have Node API credentials, or Access Key/Secret, use the plugin: node. This plugin is exclusively using SSH credentials.

The URL to be provided with option url shall be like ssh://<SERVER_ADDRESS>:33001, then option username is used to specify the transfer user, and finally either option password or ssh_keys (with one or several paths) for the authentication.

Typically:

ascli server --url=ssh://hsts.example.com:33001 --username=john --password=<PASSWORD> ...
ascli server --url=ssh://hsts.example.com:33001 --username=john --ssh-keys=~/.ssh/id_rsa ...

Tested commands for server🔗

Note

Add ascli server in front of the following commands:

browse /
browse / --password @none: --ssh-options.number_of_password_prompts=0 --ssh-keys=<SERV_KEY_PATH>
browse my_inside_folder/test_file.bin
browse my_upload_folder/target_hot
cp my_inside_folder/test_file.bin my_upload_folder/200KB.2
delete my_inside_folder
delete my_upload_folder/to.delete
df
download my_inside_folder/test_file.bin --to-folder=. --transfer=@json:'{"wss":false,"resume":{"iter_max":1}}'
download my_large_file --to-folder=my_upload_folder --transfer.agent=node --ts.resume_policy=none
du /
health transfer --to-folder=my_upload_folder
health transfer --to-folder=my_upload_folder --format=nagios
info
md5sum my_inside_folder/test_file.bin
mkdir my_inside_folder --logger=stdout
mkdir my_upload_folder/target_hot
mv my_upload_folder/200KB.2 my_upload_folder/to.delete
sync admin file_info --sql='WHERE state=19' /data/local_sync
sync admin file_info /data/local_sync
sync admin overview /data/local_sync
sync admin query --sql='SELECT name FROM sqlite_master WHERE type='table'' /data/local_sync
sync admin status /data/local_sync
sync pull my_inside_folder --to-folder=/data/local_sync @: name=serv_sync_pull_conf
sync pull my_inside_folder --to-folder=/data/local_sync @json:'{"name":"serv_sync_pull_conf","reset":true,"transport":{"target_rate":my_bps}}'
upload 'faux:///test.bin?1k' --to-folder=my_upload_folder
upload --sources=@ts --transfer.ascp_args=@list:,--file-list,file_list.txt --to-folder=my_inside_folder
upload --sources=@ts --transfer.ascp_args=@list:,--file-pair-list,file_pair_list.txt
upload --sources=@ts --ts=@json:'{"paths":[{"source":"test_file.bin","destination":"my_inside_folder/other_name_4"}]}' --transfer.agent=transferd
upload --src-type=pair --sources=@json:'["test_file.bin","my_inside_folder/other_name_3"]' --transfer.quiet=false
upload --src-type=pair test_file.bin my_inside_folder/other_name_2 --notify-to=my_email_external '--transfer.ascp_args=@list: -l 100m'
upload --src-type=pair test_file.bin my_upload_folder/other_name_5 --ts=@json:'{"cipher":"aes-192-gcm","content_protection":"encrypt","content_protection_password":"<PASSWORD>","cookie":"biscuit","create_dir":true,"delete_before_transfer":false,"delete_source":false,"exclude_newer_than":"-1","exclude_older_than":"-10000","fasp_port":33001,"http_fallback":false,"multi_session":0,"overwrite":"diff+older","precalculate_job_size":true,"preserve_access_time":true,"preserve_creation_time":true,"rate_policy":"fair","resume_policy":"sparse_csum"}'
upload --to-folder=my_upload_folder/target_hot --lock-port=50101 --transfer.ascp_args=@list:,--remove-after-transfer,--remove-empty-directories,--exclude-newer-than=-8,--src-base,hot_folder hot_folder
upload /test_file.bin --to-folder=my_upload_folder --transfer.agent=node --transfer.url=http://localhost:12348 --transfer.username=sim --transfer.password=<PASSWORD>
upload test_file.bin --to-folder=my_inside_folder --ts=@json:'{"multi_session":3,"multi_session_threshold":1,"resume_policy":"none","target_rate_kbps":100000}' --transfer=@json:'{"spawn_delay_sec":2.5,"multi_incr_udp":false}' --progress-bar=yes

Authentication on Server with SSH session🔗

If SSH is the session protocol (by default, that is, not WSS), then the following session authentication methods are supported:

  • password: SSH password
  • ssh_keys: SSH keys (Multiple SSH key paths can be provided.)

If username is not provided then the default transfer user xfer is used.

If neither SSH password nor key is provided and a transfer token is provided in transfer spec (option ts), then the standard SSH bypass keys are used.

Example:

ascli server --url=ssh://<SERVER_ADDRESS>:33001 ... --ts=@json:'{"token":"Basic <TOKEN>"}'

Note

If you need to use the Aspera public keys, then specify an empty token: --ts=@json:'{"token":""}' : Aspera public SSH keys will be used, but the protocol will ignore the empty token.

The value of the ssh_keys option can be a single value or an Array. Each value is a path to a private key and is expanded (~ is replaced with the user's home folder).

Examples:

ascli server --ssh-keys=~/.ssh/id_rsa
ascli server --ssh-keys=@list:,~/.ssh/id_rsa
ascli server --ssh-keys=@json:'["~/.ssh/id_rsa"]'

For file operation commands (browse, delete), the Ruby SSH client library Net::SSH is used and provides several options settable using option ssh_options (additive option like ts).

For a list of SSH client options, refer to the Ruby documentation of Net::SSH.

Among the 50 available SSH options:

  • verbose
  • use_agent
  • passphrase

By default, the SSH library will check if a local ssh-agent is running.

On Linux, if you get an error message such as:

ERROR -- net.ssh.authentication.agent: could not connect to ssh-agent: Agent not configured

Or on Windows:

ERROR -- net.ssh.authentication.agent: could not connect to ssh-agent: pageant process not running

This means that your environment suggests using an agent, but no SSH agent is running. In that case:

  • Check env var: SSH_AUTH_SOCK
  • Check your file: $HOME/.ssh/config
  • Check if the SSH key is protected with a passphrase (then, use the passphrase SSH option)
  • Check the Ruby SSH options in start method
  • To disable the use of ssh-agent, use the option ssh_options like this:
ascli server --ssh-options=@json:'{"use_agent": false}' ...

Tip

This can also be set using a preset.

If one of the SSH private keys is passphrase-protected, then option passphrase can be used. It is equivalent to setting both options ssh_options.passphrase and ts.ssh_private_key_passphrase.

Analyze ascp logs of the server🔗

Command logs analyzes the ascp log files of the server (ascp 4.0 and later), instead of those of the local machine: the files are read over the SSH connection of the plugin (same url, username, password or ssh_keys, and ssh_options), then analyzed like with config ascp logs. It has the same sub-commands (summary, sessions, diagnostics, health, records, ...) and the same option ascp_logs. Paths of the files on the server are mandatory: there is no default location, as it depends on the installation (e.g. a syslog file such as /var/log/aspera.log or /var/log/messages, or a file of the folder given with ascp -L). Files compressed with gzip (rotations) are supported. A folder is not read, give its files.

ascli server --url=ssh://<SERVER_ADDRESS>:33001 --username=root --ssh-keys=~/.ssh/id_rsa logs summary /var/log/aspera.log
ascli server ... logs sessions /var/log/aspera.log /var/log/aspera.log-20261101.gz --select=@json:'{"status":"failed"}'

The user must be allowed to read the files (log files are often readable by root only), and the server shall provide a shell with head (and stat). The files are copied to a temporary folder, removed after the analysis. The size of the files is limited (total of 256 MB by default), to avoid reading huge logs in memory: the limit is the key remote_max_size (in bytes) of option ascp_logs, e.g. --ascp-logs.remote_max_size=1000000000. The modification date of each file is kept, as the year of syslog lines is deduced from it. Not available with --url=local: and https.

Other session channels for server🔗

URL schemes local and https are also supported (mainly for testing purposes). (--url=local:, --url=https://...)

  • local will execute ascmd locally, instead of using an SSH connection.
  • https will use Web Socket Session: This requires the use of a transfer token. For example, a Basic token can be used.

As SSH is used most of the time, if an http scheme is provided without a token, the plugin falls back to SSH and port 33001.

Examples: server🔗

One can test the server application using the well-known demo server:

ascli config initdemo
ascli server browse /aspera-test-dir-large
ascli server download /aspera-test-dir-large/200MB

initdemo creates an Option Preset demoserver and sets it as default for plugin server.

If an SSH private key is used for authentication with a passphrase, the passphrase needs to be provided to both options: ssh_options (for browsing) and ts (for transfers):

ascli server --url=ssh://<SERVER_ADDRESS>:33001 --username=<USERNAME> --ssh-keys=<PRIVATE_KEY_PATH> --passphrase=<PASSPHRASE>