aspera-cli 4.1.0 → 4.3.0

data/docs/README.erb.md

@@ -1,21 +1,44 @@
 [comment1]: # (Do not edit this README.md, edit docs/README.erb.md, for details, read docs/README.md)
-<%
- # check that required env vars exist, and files
-%w{EXENAME GEMSPEC INCL_USAGE INCL_COMMANDS INCL_ASESSION INCL_TRSPEC}.each do |e|
+<% #```ruby
+# check that required env vars exist, and files
+%w{EXENAME GEMSPEC INCL_USAGE INCL_COMMANDS INCL_ASESSION INCL_DIR_GEM}.each do |e|
   raise "missing env var #{e}" unless ENV.has_key?(e)
   raise "missing file #{ENV[e]}" unless File.exist?(ENV[e]) or !e.start_with?('INCL_') #_
 end
-cmd=ENV["EXENAME"] # just command name
+cmd=ENV['EXENAME'] # just command name
 tool='`'+cmd+'`'   # used in text with formatting of command
 evp=cmd.upcase+'_' # prefix for env vars
 opprst='option preset' # just the name for "option preset"
-prst='['+opprst+'](#lprt)'
-prsts='['+opprst+'s](#lprt)'
+prst='['+opprst+'](#lprt)' # name with link
+prsts='['+opprst+'s](#lprt)' # name with link (plural)
 prstt=opprst.capitalize # in title
 gemspec=Gem::Specification::load(ENV["GEMSPEC"]) or raise "error loading #{ENV["GEMSPEC"]}"
 geminstadd=gemspec.version.to_s.match(/\.[^0-9]/)?' --pre':''
+$LOAD_PATH.unshift(ENV["INCL_DIR_GEM"])
+require 'aspera/fasp/parameters'
+def spec_table
+  r='<table><tr><th>Field</th><th>Type</th>'
+  Aspera::Fasp::Parameters::SUPPORTED_AGENTS_SHORT.each do |c|
+      r << '<th>'<<c.to_s.upcase<<'</th>'
+    end
+    r << '<th>Description</th></tr>'
+    Aspera::Fasp::Parameters.man_table.each do |p|
+      p[:description] << (p[:description].empty? ? '' : "\n") << "(" << p[:cli] << ")" unless p[:cli].to_s.empty?
+      p.delete(:cli)
+      p.keys.each{|c|p[c]='&nbsp;' if p[c].to_s.empty?}
+      p[:description].gsub!("\n",'<br/>')
+      p[:type].gsub!(',','<br/>')
+      r << '<tr><td>'<<p[:name]<<'</td><td>'<<p[:type]<<'</td>'
+      Aspera::Fasp::Parameters::SUPPORTED_AGENTS_SHORT.each do |c|
+        r << '<td>'<<p[c]<<'</td>'
+      end
+      r << '<td>'<<p[:description]<<'</td></tr>'
+    end
+    r << '</table>'
+    return r
+end #```
 -%>
-# <%=tool%> : Command Line Interface for IBM Aspera products
+<font size="+12"><center><%=tool%> : Command Line Interface for IBM Aspera products</center></font>
 
 Version : <%= gemspec.version.to_s %>
 
@@ -29,7 +52,7 @@ Ruby Gem: [<%= gemspec.metadata['rubygems_uri'] %>](<%= gemspec.metadata['rubyge
 
 Ruby Doc: [<%= gemspec.metadata['documentation_uri'] %>](<%= gemspec.metadata['documentation_uri'] %>)
 
-Ruby version must be >= <%= gemspec.required_ruby_version %>
+Required Ruby version: <%= gemspec.required_ruby_version %>
 
 # <a name="when_to_use"></a>When to use and when not to use
 
@@ -45,7 +68,8 @@ So it is designed for:
 
 <%=tool%> can be seen as a command line tool integrating:
 
-* a configuration file (config.yaml) and advanced command line options
+* a configuration file (config.yaml)
+* advanced command line options
 * cURL (for REST calls)
 * Aspera transfer (ascp)
 
@@ -106,9 +130,10 @@ Once installation is completed, you can proceed to the first use with a demo ser
 
 If you want to test with Aspera on Cloud, jump to section: [Wizard](#aocwizard)
 
-If you want to test with Aspera demo transfer server, a default configuration is created on first use:
+To test with Aspera demo transfer server, setup the environment and then test:
 
 ```
+$ <%=cmd%> config initdemo
 $ <%=cmd%> server browse /
 :............:...........:......:........:...........................:.......................:
 :   zmode    :   zuid    : zgid :  size  :           mtime           :         name          :
@@ -128,7 +153,7 @@ If you want to use <%=tool%> with another server, and in order to make further c
 * download a file
 
 ```
-$ <%=cmd%> config id myserver update --url=ssh://demo.asperasoft.com:33001 --username=asperaweb --password=demoaspera
+$ <%=cmd%> config id myserver update --url=ssh://demo.asperasoft.com:33001 --username=asperaweb --password=_demo_pass_
 updated: myserver
 $ <%=cmd%> config id default set server myserver
 updated: default&rarr;server to myserver
@@ -162,18 +187,22 @@ Then, follow the section relative to the product you want to interact with ( Asp
 
 # <a name="installation"></a>Installation
 
-It is possible to install *either* as a docker container or step by step on the native host:
+It is possible to install *either* directly on the host operating system (Linux, Windows, Macos) or as a docker container.
 
-* [Ruby](#ruby) version >= <%= gemspec.required_ruby_version %>
+The direct installation is recommended and consists in installing:
+
+* [Ruby](#ruby) version <%= gemspec.required_ruby_version %>
 * [<%= gemspec.name %>](#the_gem)
 * [Aspera SDK (ascp)](#fasp_prot)
 
-The following sections provide information on the installation.
+The following sections provide information on the various installation methods.
 
 An internet connection is required for the installation. If you dont have internet for the installation, refer to section [Installation without internet access](#offline_install).
 
 ## Docker container
 
+Use this method only if you know what you do, else use the standard recommended method as described here above.
+
 This method installs a docker image that contains: Ruby, ascli and the FASP sdk.
 
 Ensure that you have Docker installed.
@@ -197,11 +226,12 @@ $ ./<%=cmd%> install
 
 Start using it !
 
-Note that the tool is run in the container.
+Note that the tool is run in the container, so transfers are also executed in the container, not calling host.
 
-The wrapping script maps the container folder `/usr/src/app/config` to configuration folder `$HOME/.aspera/<%=cmd%>`.
+The wrapping script maps the container folder `/usr/src/app/config` to configuration folder `$HOME/.aspera/<%=cmd%>` on host.
 
 To transfer to/from the native host, you will need to map a volume in docker or use the config folder (already mapped).
+To add local storage as a volume edit the script: ascli and add a `--volume` stanza.
 
 ## <a name="ruby"></a>Ruby
 
@@ -209,15 +239,15 @@ Use this method to install on the native host.
 
 A ruby interpreter is required to run the tool or to use the gem and tool.
 
-Ruby minimum version: <%= gemspec.required_ruby_version %>. Ruby version 3 is also supported.
+Required Ruby version: <%= gemspec.required_ruby_version %>. Ruby version 3 is also supported.
 
-*Any type of Ruby installation can be used* : rpm, yum, dnf, rvm, brew, windows installer, ... .
+*Ruby can be installed using any method* : rpm, yum, dnf, rvm, brew, windows installer, ... .
 
 Refer to the following sections for a proposed method for specific operating systems.
 
 The recommended installation method is `rvm` for systems with "bash-like" shell (Linux, Macos, Windows with cygwin, etc...).
 If the generic install is not suitable (e.g. Windows, no cygwin), you can use one of OS-specific install method.
-If you have a simpler better way to install Ruby version >= <%= gemspec.required_ruby_version %> : use it !
+If you have a simpler better way to install Ruby version <%= gemspec.required_ruby_version %> : use it !
 
 ### Generic: RVM: single user installation (not root)
 
@@ -789,7 +819,7 @@ $ <%=cmd%> config id <<%=opprst%>> set|delete|show|initialize|update
 The command `update` allows the easy creation of <%=prst%> by simply providing the options in their command line format, e.g. :
 
 ```
-$ <%=cmd%> config id demo_server update --url=ssh://demo.asperasoft.com:33001 --username=asperaweb --password=demoaspera --ts=@json:'{"precalculate_job_size":true}'
+$ <%=cmd%> config id demo_server update --url=ssh://demo.asperasoft.com:33001 --username=asperaweb --password=_demo_pass_ --ts=@json:'{"precalculate_job_size":true}'
 ```
 
 * This creates a <%=prst%> `demo_server` with all provided options.
@@ -797,13 +827,13 @@ $ <%=cmd%> config id demo_server update --url=ssh://demo.asperasoft.com:33001 --
 The command `set` allows setting individual options in a <%=prst%>.
 
 ```
-$ <%=cmd%> config id demo_server set password demoaspera
+$ <%=cmd%> config id demo_server set password _demo_pass_
 ```
 
 The command `initialize`, like `update` allows to set several parameters at once, but it deletes an existing configuration instead of updating it, and expects a _[Structured Value](#native)_.
 
 ```
-$ <%=cmd%> config id demo_server initialize @json:'{"url":"ssh://demo.asperasoft.com:33001","username":"asperaweb","password":"demoaspera","ts":{"precalculate_job_size":true}}'
+$ <%=cmd%> config id demo_server initialize @json:'{"url":"ssh://demo.asperasoft.com:33001","username":"asperaweb","password":"_demo_pass_","ts":{"precalculate_job_size":true}}'
 ```
 
 A good practice is to not manually edit the configuration file and use modification commands instead.
@@ -840,11 +870,19 @@ Note that special plugin name: `config` can be associated with a preset that is
 Operations on this preset are done using regular `config` operations:
 
 ```
-$ <%=cmd%> config id default set _plugin_name_ _defauklt_preset_for_plugin_
+$ <%=cmd%> config id default set _plugin_name_ _default_preset_for_plugin_
 $ <%=cmd%> config id default get _plugin_name_
-"_defauklt_preset_for_plugin_"
+"_default_preset_for_plugin_"
 ```
 
+### <a name="lprtdef"></a>Special Plugin: config
+
+Plugin `config` (not to be confused with <%=prstt%> config) is used to configure <%=tool%> but it also contains global options.
+
+When <%=tool%> starts, it lookjs for the `default` <%=prstt%> and if there is a value for `config`, if so, it loads the option values for any plugin used.
+
+If no global default is set by the user, the tool will use `global_common_defaults` when setting global parameters (e.g. `conf ascp use`)
+
 ### Format of file
 
 The configuration file is a hash in a YAML file. Example:
@@ -860,7 +898,7 @@ cli_default:
 demo_server:
   url: ssh://demo.asperasoft.com:33001
   username: asperaweb
-  password: demoaspera
+  password: _demo_pass_
 ```
 
 We can see here:
@@ -929,7 +967,6 @@ A <%=prst%> value can be removed with `unset`:
 $ <%=cmd%> config id cli_default unset interactive
 ```
 
-
 ### Examples
 
 For Faspex, Shares, Node (including ATS, Aspera Transfer Service), Console,
@@ -1049,21 +1086,42 @@ The `config` plugin also allows specification for the use of a local FASP client
 
 ```
 $ <%=cmd%> config ascp show
-/Users/laurent/Applications/Aspera Connect.app/Contents/Resources/ascp
+/Users/laurent/.aspera/ascli/sdk/ascp
+$ <%=cmd%> config ascp info
++--------------------+-----------------------------------------------------------+
+| key                | value                                                     |
++--------------------+-----------------------------------------------------------+
+| ascp               | /Users/laurent/.aspera/ascli/sdk/ascp                     |
+...
 ```
 
 ### Selection of local `ascp`
 
+By default, <%=tool%> uses any found local product with ascp, including SDK.
+
 To temporarily use an alternate ascp path use option `ascp_path` (`--ascp-path=`)
 
-To permanently use another ascp:
+For a permanent change, the command `config ascp use` sets the same parameter for the global default.
+
+Using a POSIX shell:
 
 ```
 $ <%=cmd%> config ascp use '/Users/laurent/Applications/Aspera CLI/bin/ascp'
-saved to default global preset /Users/laurent/Applications/Aspera CLI/bin/ascp
+ascp version: 4.0.0.182279
+Updated: global_common_defaults: ascp_path <- /Users/laurent/Applications/Aspera CLI/bin/ascp
+Saved to default global preset global_common_defaults
 ```
 
-This sets up a global default.
+Windows:
+
+```
+$ <%=cmd%> config ascp use C:\Users\admin\.aspera\ascli\sdk\ascp.exe
+ascp version: 4.0.0.182279
+Updated: global_common_defaults: ascp_path <- C:\Users\admin\.aspera\ascli\sdk\ascp.exe
+Saved to default global preset global_common_defaults
+```
+
+If the path has spaces, read section: [Shell and Command line parsing](#parsing).
 
 ### List locally installed Aspera Transfer products
 
@@ -1150,7 +1208,7 @@ will effectively push files to the related server from the agent node.
 
 ### <a name="direct"></a>Direct (local ascp using FASPManager API)
 
-By default the CLI will use a local FASP protocol, equivalent to specifying `--transfer=direct`.
+By default <%=tool%> uses a local ascp, equivalent to specifying `--transfer=direct`.
 <%=tool%> will detect locally installed Aspera products.
 Refer to section [FASP](#client).
 
@@ -1160,17 +1218,41 @@ To specify a FASP proxy (only supported with the `direct` agent), set the approp
 * `EX_http_proxy_url` (proxy for legacy http fallback)
 * `EX_ascp_args`
 
-The `transfer-info` optionally provides the following auto resume parameters:
+The `transfer-info` accepts the following optional parameters:
 
 <table>
-<tr><th>Name</th><th>Default</th><th>Feature</th><th>Description</th></tr>
-<tr><td>iter_max</td>.    <td>7</td><td>Resume</td><td>Max number of retry on error</td></tr>
-<tr><td>sleep_initial</td><td>2</td><td>Resume</td><td>First Sleep before retry</td></tr>
-<tr><td>sleep_factor</td> <td>2</td><td>Resume</td><td>Multiplier of Sleep</td></tr>
-<tr><td>sleep_max</td>.   <td>60</td><td>Resume</td><td>Maximum sleep</td></tr>
-<tr><td>wss</td>          <td>false</td><td>Web Socket Session</td><td>Enable use of web socket session in case it is available</td></tr>
+<tr><th>Name</th><th>Type</th><th>Default</th><th>Feature</th><th>Description</th></tr>
+<tr><td>spawn_timeout_sec</td><td>Float</td><td>3</td><td>Multi session</td><td>Verification time that ascp is running</td></tr>
+<tr><td>spawn_delay_sec</td><td>Float</td><td>2</td><td>Multi session</td><td>Delay between startup of sessions</td></tr>
+<tr><td>wss</td><td>Bool</td><td>false</td><td>Web Socket Session</td><td>Enable use of web socket session in case it is available</td></tr>
+<tr><td>multi_incr_udp</td><td>Bool</td><td>true</td><td>Multi Session</td><td>Increment UDP port on multi-session<br/>If true, each session will have a different UDP port starting at `fasp_port` (or default 33001)<br/>Else, each session will use `fasp_port` (or `ascp` default)</td></tr>
+<tr><td>resume</td><td>Hash</td><td>nil</td><td>Resumer parameters</td><td>See below</td></tr>
 </table>
 
+Resume parameters:
+
+In case of transfer interruption, the agent will resume a transfer up to `iter_max` time.
+Sleep between iteration is:
+
+```
+max( sleep_max , sleep_initial * sleep_factor ^ (iter_index-1) )
+```
+
+<table>
+<tr><th>Name</th><th>Type</th><th>Default</th><th>Feature</th><th>Description</th></tr>
+<tr><td>iter_max</td><td>int</td><td>7</td><td>Resume</td><td>Max number of retry on error</td></tr>
+<tr><td>sleep_initial</td><td>int</td><td>2</td><td>Resume</td><td>First Sleep before retry</td></tr>
+<tr><td>sleep_factor</td><td>int</td><td>2</td><td>Resume</td><td>Multiplier of Sleep</td></tr>
+<tr><td>sleep_max</td><td>int</td><td>60</td><td>Resume</td><td>Maximum sleep</td></tr>
+</table>
+
+Examples:
+
+```
+$ <%=cmd%> ... --transfer-info=@json:'{"wss":true,"resume":{"iter_max":10}}'
+$ <%=cmd%> ... --transfer-info=@json:'{"spawn_delay_sec":2.5,"multi_incr_udp":false}'
+```
+
 ### IBM Aspera Connect Client GUI
 
 By specifying option: `--transfer=connect`, <%=tool%> will start transfers
@@ -1220,7 +1302,7 @@ is described in a _transfer-spec_ (Transfer Specification), such as:
 
 <%=tool%> builds a default _transfer-spec_ internally, so it is not necessary to provide additional parameters on the command line for this transfer.
 
-If needed, it is possible to modify or add any of the supported _transfer-spec_ parameter using the `ts` option. The `ts` option accepts a [Structured Value](#native) containing one or several _transfer-spec_ parameters.
+If needed, it is possible to modify or add any of the supported _transfer-spec_ parameter using the `ts` option. The `ts` option accepts a [Structured Value](#native) containing one or several _transfer-spec_ parameters. Multiple `ts` options on command line are cummulative.
 
 It is possible to specify ascp options when the `transfer` option is set to `direct` using the special [_transfer-spec_](#transferspec) parameter: `EX_ascp_args`. Example: `--ts=@json:'{"EX_ascp_args":["-l","100m"]}'`. This is espacially useful for ascp command line parameters not supported yet in the transfer spec.
 
@@ -1233,11 +1315,31 @@ A [_transfer-spec_](#transferspec) is a Hash table, so it is described on the co
 
 ## <a name="transferparams"></a>Transfer Parameters
 
-All standard _transfer-spec_ parameters can be overloaded. To display parameters,
-run in debug mode (--log-level=debug). [_transfer-spec_](#transferspec) can
-also be saved/overridden in the config file.
+All standard _transfer-spec_ parameters can be speficied.
+[_transfer-spec_](#transferspec) can also be saved/overridden in the config file.
+
+References:
+
+* [Aspera Node API Documentation](https://developer.ibm.com/apis/catalog?search=%22aspera%20node%20api%22)&rarr;/opt/transfers
+* [Aspera Transfer SDK Documentation](https://developer.ibm.com/apis/catalog?search=%22aspera%20transfer%20sdk%22)&rarr;Guides&rarr;API Ref&rarr;Transfer Spec V1
+
+Parameters can be displayed with commands:
 
-<%= File.read(ENV['INCL_TRSPEC']).gsub(/.*<body>(.*)<\/body>.*/m,'\1') %>
+```
+$ <%=cmd%> config ascp spec
+$ <%=cmd%> config ascp spec --select=@json:'{"f":"Y"}' --fields=-f,n,c
+```
+
+Columns:
+
+* D=Direct (local `ascp` execution)
+* N=Node API
+* C=Connect Client
+* arg=`ascp` argument or environment variable
+
+Fields with EX_ prefix are extensions to transfer agent `direct`. (only in <%=tool%>).
+
+<%= spec_table %>
 
 ### Destination folder for transfers
 
@@ -1319,7 +1421,7 @@ Source files are located on "Aspera on cloud", when :
 
 ### <a name="multisession"></a>Support of multi-session
 
-Multi session, i.e. starting a transfer of a file set using multiple sessions is supported on "direct" and "node" agents, not yet on connect.
+Multi session, i.e. starting a transfer of a file set using multiple sessions (one ascp process per session) is supported on "direct" and "node" agents, not yet on connect.
 
 * when agent=node :
 
@@ -1340,6 +1442,7 @@ shall be preferred.
 
 Multi-session spawn is done by <%=tool%>.
 
+When multi-session is used, one separate UDP port is used per session (refer to `ascp` manual page).
 
 ### Examples
 
@@ -1449,7 +1552,7 @@ For this, specify the option: `--use-generic-client=no`.
 
 This will guide you through the steps to create.
 
-## <a name="aocwizard"></a>Configuration: using manual setup
+## <a name="aocmanual"></a>Configuration: using manual setup
 
 If you used the wizard (recommended): skip this section.
 
@@ -1615,7 +1718,7 @@ To activate default use of JWT authentication for <%=tool%> using the <%=prst%>,
 
 * change auth method to JWT
 * provide location of private key
-* provide username to login as (OAuthg "subject")
+* provide username to login as (OAuth "subject")
 
 Execute:
 
@@ -1713,10 +1816,10 @@ $ <%=cmd%> aoc admin res user list --query='@json:{"q":"dummyuser"}' --fields=id
 : 98398 : dummyuser1@example.com :
 : 98399 : dummyuser2@example.com :
 :.......:........................:
-$ thelist=$(echo $(<%=cmd%> aoc admin res user list --query='@json:{"q":"dummyuser"}' --fields=id,email --field=id --format=csv)|tr ' ' ,)
+$ thelist=$(<%=cmd%> aoc admin res user list --query='@json:{"q":"dummyuser"}' --fields=id --format=json --display=data|jq -cr 'map(.id)')
 $ echo $thelist
-98398,98399
-$ <%=cmd%> aoc admin res user --bulk=yes --id=@json:[$thelist] delete
+["113501","354061"]
+$ <%=cmd%> aoc admin res user --bulk=yes --id=@json:"$thelist" delete
 :.......:.........:
 :  id   : status  :
 :.......:.........:
@@ -1725,6 +1828,14 @@ $ <%=cmd%> aoc admin res user --bulk=yes --id=@json:[$thelist] delete
 :.......:.........:
 ```
 
+* <a name="deactuser"></a>Find deactivated users since more than 2 years
+
+```
+ascli aoc admin res user list --query=@ruby:'{"deactivated"=>true,"q"=>"last_login_at:<#{(DateTime.now.to_time.utc-2*365*86400).iso8601}"}'
+```
+
+To delete them use the same method as before
+
 * Display current user's workspaces
 
 ```
@@ -1966,10 +2077,10 @@ $ <%=cmd%> aoc packages recv --id=ALL --once-only=yes --lock-port=12345
 * `--once-only=yes` keeps memory of any downloaded package in persistency files located in the configuration folder.
 * `--lock-port=12345` ensures that only one instance is started at the same time, to avoid collisions
 
-Typically, one would regularly execute this command on a regular basis, using the method oif your choice:
+Typically, one would regularly execute this command on a regular basis, using the method of your choice:
 
-* Windows scheduler
-* cron
+* Windows: [Task Scheduler](https://docs.microsoft.com/en-us/windows/win32/taskschd/task-scheduler-start-page)
+* Linux/Unix: [cron](https://www.man7.org/linux/man-pages/man5/crontab.5.html)
 * etc...
 
 ## Download Files
@@ -2026,19 +2137,40 @@ The activity app can be queried with:
 $ <%=cmd%> aoc admin analytics transfers
 ```
 
-It can also support filters and send notification email with a template:
+It can also support filters and send notification using option `notif_to`. a template is defined using option `notif_template` :
+
+`mytemplate.erb`:
+
+```
+From: <%='<'%>%=from_name%> <<%='<'%>%=from_email%>>
+To: <<%='<'%>%=ev['user_email']%>>
+Subject: <%='<'%>%=ev['files_completed']%> files received
+
+Dear <%='<'%>%=ev[:user_email.to_s]%>,
+We received <%='<'%>%=ev['files_completed']%> files for a total of <%='<'%>%=ev['transferred_bytes']%> bytes, starting with file:
+<%='<'%>%=ev['content']%>
+
+Thank you.
+```
+The environment provided contains the following additional variable:
+
+* ev : all details on the transfer event
+
+Example:
 
 ```
-$ <%=cmd%> aoc admin analytics transfers --once-only=yes --lock-port=123455 \
+$ <%=cmd%> aoc admin analytics transfers --once-only=yes --lock-port=12345 \
 --query=@json:'{"status":"completed","direction":"receive"}' \
---notify=@json:'{"to":"<''%=transfer[:user_email.to_s]%>","subject":"<''%=transfer[:files_completed.to_s]%> files received","body":"Dear <''%=transfer[:user_email.to_s]%>\nWe received <''%=transfer[:files_completed.to_s]%> files for a total of <''%=transfer[:transferred_bytes.to_s]%> bytes, starting with file:\n<''%=transfer[:content.to_s]%>\n\nThank you."}'
+--notif-to=active --notif-template=@file:mytemplate.erb
 ```
 
+Options:
+
 * `once_only` keep track of last date it was called, so next call will get only new events
 * `query` filter (on API call)
 * `notify` send an email as specified by template, this could be places in a file with the `@file` modifier.
 
-Note this must not be executed in less than 5 minutes because the analytics interface accepts only a period of time between 5 minutes and 6 months. here the period is [date of previous execution]..[now].
+Note this must not be executed in less than 5 minutes because the analytics interface accepts only a period of time between 5 minutes and 6 months. The period is [date of previous execution]..[now].
 
 ## Using specific transfer ports
 
@@ -2099,7 +2231,37 @@ $ <%=cmd%> ats api_key create
 +--------+----------------------------------------------+
 $ <%=cmd%> config id my_ibm_ats update --ats-key=ats_XXXXXXXXXXXXXXXXXXXXXXXX --ats-secret=YYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYY
 ```
+## Cross Organization transfers
+
+It is possible to transfer files directly between organizations without having to first download locally and then upload...
+
+Although optional, the creation of <%=prst%> is recommended to avoid placing all parameters in the command line.
+
+Procedure to send a file from org1 to org2:
+
+* Get access to Organization 1 and create a <%=prst%>: e.g. `org1`, for instance, use the [Wizard](#aocwizard)
+* Check that access works and locate the source file e.g. `mysourcefile`, e.g. using command `files browse`
+* Get access to Organization 2 and create a <%=prst%>: e.g. `org2`
+* Check that access works and locate the destination folder `mydestfolder`
+* execute the following:
+
+```
+$ <%=cmd%> -Porg1 aoc files node_info /mydestfolder --format=json --display=data | <%=cmd%> -Porg2 aoc files upload mysourcefile --transfer=node --transfer-info=@json:@stdin:
+```
+
+Explanation:
+
+* `-Porg1 aoc` use Aspera on Cloud plugin and load credentials for `org1`
+* `files node_info /mydestfolder` generate transfer information including node api credential and root id, suitable for the next command
+* `--format=json` format the output in JSON (instead of default text table)
+* `--display=data` display only the result, and remove other information, such as workspace name
+* `|` the standard output of the first command is fed into the second one
+* `-Porg2 aoc` use Aspera on Cloud plugin and load credentials for `org2`
+* `files upload mysourcefile` upload the file named `mysourcefile` (located in `org1`)
+* `--transfer=node` use transfer agent type `node` instead of default `direct`
+* `--transfer-info=@json:@stdin:` provide `node` transfer agent information, i.e. node API credentials, those are expected in JSON format and read from standard input
 
+Note that when using a POSIX shell, another possibility to write `cmd1 | cmd2 --transfer-info=@json:stdin:` is `cmd2 --transfer-info=@json:$(cmd1)` instead of ``
 ## Examples
 
 Example: create access key on softlayer:
@@ -2189,7 +2351,7 @@ This can also be set as default using a preset
 One can test the "server" application using the well known demo server:
 
 ```
-$ <%=cmd%> config id aspera_demo_server update --url=ssh://demo.asperasoft.com:33001 --username=asperaweb --password=demoaspera
+$ <%=cmd%> config id aspera_demo_server update --url=ssh://demo.asperasoft.com:33001 --username=asperaweb --password=_demo_pass_
 $ <%=cmd%> config id default set server aspera_demo_server
 $ <%=cmd%> server browse /aspera-test-dir-large
 $ <%=cmd%> server download /aspera-test-dir-large/200MB
@@ -2285,16 +2447,19 @@ to download files.
 $ <%=cmd%> node access_key create --value=@json:'{"id":"eudemo-sedemo","secret":"mystrongsecret","storage":{"type":"local","path":"/data/asperafiles"}}'
 ```
 
-# Plugin: IBM Aspera Faspex
+# Plugin: IBM Aspera Faspex5
 
-Notes:
+3 authentication methods are supported:
+
+* jwt
+* web
+* boot
 
-* the command "v4" requires the use of APIv4, refer to the Faspex Admin manual on how to activate.
-* for full details on Faspex API, refer to: [Reference on Developer Site](https://www.ibm.com/products/aspera/developer)
+For JWT, create an API client in Faspex with jwt support, and use: `--auth=jwt`.
 
-## Faspex 5 Beta1
+For web method, create an API client in Faspex, and use: --auth=web
 
-As the web UI does not yet allow adding API client yet, the way to use CLI is:
+For boot method: (will be removed in future)
 
 * open a browser
 * start developer mode
@@ -2307,30 +2472,74 @@ Use it as password and use `--auth=boot`.
 $ <%=cmd%> conf id f5boot update --url=https://localhost/aspera/faspex --auth=boot --password=ABC.DEF.GHI...
 ```
 
-An JWT client can then be created with a private key:
+Ready to use Faspex5 with CLI.
+
+# Plugin: IBM Aspera Faspex (4.x)
+
+Notes:
+
+* The command "v4" requires the use of APIv4, refer to the Faspex Admin manual on how to activate.
+* For full details on Faspex API, refer to: [Reference on Developer Site](https://developer.ibm.com/apis/catalog/?search=faspex)
+
+## Listing Packages
+
+Command: `faspex package list`
+
+### Option `box`
+
+By default it looks in box `inbox`, but the following boxes are also supported: `archive` and `sent`, selected with option `box`.
+
+### Option `recipient`
+
+A user can receive a package because the recipient is:
+
+* the user himself (default)
+* the user is part of a dropbox or a workgroup (select with option `recipient` with value `*<name of WG or DB>`
+
+### Option `query`
+
+As inboxes may be large, it is possible to use the following query parameters:
+
+* `count` : (native) number items in one API call (default=0, equivalent to 10)
+* `page` : (native) id of page in call (default=0)
+* `startIndex` : (native) index of item to start, default=0, oldest index=0
+* `max` : maximum number of items
+* `pmax` : maximum number of pages
+
+(SQL query is `LIMIT <startIndex>, <count>`)
+
+The API is listed in [Faspex 4 API Reference](https://developer.ibm.com/apis/catalog/?search=faspex) under "Services (API v.3)".
+
+If no parameter `max` or `pmax` is provided, then all packages will be listed in the inbox, which result in paged API calls (using parameter: `count` and `page`). By default page is `0` (`10`), it can be increased to have less calls.
+
+### Example
 
 ```
-$ jsonk=$(openssl rsa -in  ~/.aspera/ascli/aspera_on_cloud_key -pubout 2> /dev/null | sed -e :a -e N -e '$!ba' -e 's/\n/\\n/g')
-$ <%=cmd%> faspex5 -Pf5boot auth_client create --value=@json:'{"name":"hello","client_type":"public","redirect_uris":["https://localhost:12345"],"allow_jwt_grant":true,"public_key":"'$jsonk'"}'
+$ <%=cmd%> faspex package list --box=inbox --recipient='*my_dropbox' --query=@json:'{"max":20,"pmax":2,"count":20}'
 ```
 
-or deleted by name:
+List a maximum of 20 items grouped by pages of 20, with maximum 2 pages in received box (inbox) when received in dropbox `*my_dropbox`.
+
+## Receiving a Package
+
+The command is `package recv`, possible methods are:
+
+* provide a package id with option `id`
+* provide a public link with option `link`
+* provide a `faspe:` URI with option `link`
 
 ```
-$ id=$(<%=cmd%> faspex5 auth_client list --select=@json:'{"name":"hello"}' --fields=client_id --format=csv)
-$ <%=cmd%> faspex5 auth_client delete --id=$id
+$ <%=cmd%> faspex package recv --id=12345
+$ <%=cmd%> faspex package recv --link=faspe://...
 ```
 
-Once the API client is created with a client_id and secret (result of create command), create a configuration:
+If the package is in a specific dropbox, add option `recipient` for both the `list` and `recv` commands.
 
 ```
-$ <%=cmd%> conf id f5 update --url=https://localhost/aspera/faspex --auth=jwt --client-id=abcd --client-secret=def --username=pierre@example.com --private-key=@val:@file:~/.aspera/ascli/aspera_on_cloud_key
-$ <%=cmd%> conf id default set faspex5 f5
-``` 
-
-Ready to use Faspex5 with CLI.
+$ <%=cmd%> faspex package list --recipient='*thedropboxname'
+```
 
-Once the graphical registration form exist, ther bootstrap method can be removed.
+if `id` is set to `ALL`, then all packages are downloaded, and if option `once_only`is used, then a persistency file is created to keep track of already downloaded packages.
 
 ## Sending a Package
 
@@ -2349,7 +2558,19 @@ Additional optional parameters in `delivery_info`:
 * Package Note: : `"note":"note this and that"`
 * Package Metadata: `"metadata":{"Meta1":"Val1","Meta2":"Val2"}`
 
-## operation on dropboxes
+## Email notification on transfer
+
+Like for any transfer, a notification can be sent by email using parameters: `notif_to` and `notif_template` .
+
+Example:
+
+```
+$ <%=cmd%> faspex package send --delivery-info=@json:'{"title":"test pkg 1","recipients":["aspera.user1@gmail.com"]}' ~/Documents/Samples/200KB.1 --notif-to=aspera.user1@gmail.com --notif-template=@ruby:'%Q{From: <%='<'%>%=from_name%> <<%='<'%>%=from_email%>>\nTo: <<%='<'%>%=to%>>\nSubject: Package sent: <%='<'%>%=ts["tags"]["aspera"]["faspex"]["metadata"]["_pkg_name"]%> files received\n\nTo user: <%='<'%>%=ts["tags"]["aspera"]["faspex"]["recipients"].first["email"]%>}'
+```
+
+In this example the notification template is directly provided on command line. Package information placed in the message are directly taken from the tags in transfer spec. The template can be placed in a file using modifier: `@file:`
+
+## Operation on dropboxes
 
 Example:
 
@@ -2359,7 +2580,7 @@ $ <%=cmd%> faspex v4 dropbox list
 $ <%=cmd%> faspex v4 dropbox delete --id=36
 ```
 
-## remote sources
+## Remote sources
 
 Faspex lacks an API to list the contents of a remote source (available in web UI). To workaround this,
 the node API is used, for this it is required to add a section ":storage" that links
@@ -2410,29 +2631,38 @@ $ for p in 1 2 3;do <%=cmd%> shares2 admin users list --value=@json:'{"page":'$p
 # Plugin: IBM Cloud Object Storage
 
 The IBM Cloud Object Storage provides the possibility to execute transfers using FASP.
-It uses the same transfer service as Aspera on Cloud.
-see [https://status.aspera.io](https://status.aspera.io)
+It uses the same transfer service as Aspera on Cloud, called Aspera Transfer Service (ATS).
+Available ATS regions: [https://status.aspera.io](https://status.aspera.io)
 
-Required options are either:
+There are two possibilities to provide credentials. If you already have the endpoint, apikey and CRN, use the forst method. If you dont have credentials but have access to the IBM Cloud console, then use the second method.
+
+## Using endpoint, apikey and Ressource Instance ID (CRN)
+
+If you have those parameters already, then following options shall be provided:
 
 * `bucket` bucket name
 * `endpoint` storage endpoint url, e.g. https://s3.hkg02.cloud-object-storage.appdomain.cloud
 * `apikey` API Key
 * `crn` resource instance id
 
-or:
+For example, let us create a default configuration:
 
-* `bucket` bucket name
-* `region` bucket region, e.g. eu-de
-* `service_credentials` see below
+```
+$ <%=cmd%> conf id mycos update --bucket=mybucket --endpoint=https://s3.us-east.cloud-object-storage.appdomain.cloud --apikey=abcdefgh --crn=crn:v1:bluemix:public:iam-identity::a/xxxxxxx
+$ <%=cmd%> conf id default set cos mycos
+```
+
+Then, jump to the transfer example.
 
-Service credentials are directly created using the IBM cloud web ui. Navigate to:
+## Using service credential file
+
+If you are the COS administrator and dont have yet the credential: Service credentials are directly created using the IBM cloud web ui. Navigate to:
 
 Navigation Menu &rarr; Resource List &rarr; Storage &rarr; Cloud Object Storage &rarr; Service Credentials &rarr; &lt;select or create credentials&gt; &rarr; view credentials &rarr; copy
 
 Then save the copied value to a file, e.g. : `$HOME/cos_service_creds.json`
 
-or using the CLI:
+or using the IBM Cloud CLI:
 
 ```
 $ ibmcloud resource service-keys
@@ -2463,37 +2693,42 @@ The field `resource_instance_id` is for option `crn`
 
 The field `apikey` is for option `apikey`
 
-Endpoints for regions can be found by querying the `endpoints` URL.
+(If needed: endpoints for regions can be found by querying the `endpoints` URL.)
+
+The required options for this method are:
+
+* `bucket` bucket name
+* `region` bucket region, e.g. eu-de
+* `service_credentials` see below
 
-For convenience, let us create a default configuration, for example:
+For example, let us create a default configuration:
 
 ```
 $ <%=cmd%> conf id mycos update --bucket=laurent --service-credentials=@val:@json:@file:~/service_creds.json --region=us-south
 $ <%=cmd%> conf id default set cos mycos
 ```
 
-or using direct parameters:
+## Operations, transfers
 
-```
-$ <%=cmd%> conf id mycos update --bucket=mybucket --endpoint=https://s3.us-east.cloud-object-storage.appdomain.cloud --apikey=abcdefgh --crn=crn:v1:bluemix:public:iam-identity::a/xxxxxxx
-$ <%=cmd%> conf id default set cos mycos
-```
+Let's assume you created a default configuration from once of the two previous steps (else specify the access options on command lines).
 
-Now, Ready to do operations, a subset of "node" plugin operations are supported, basically node API:
+A subset of `node` plugin operations are supported, basically node API:
 
 ```
-$ <%=cmd%> cos node browse /
-$ <%=cmd%> cos node upload myfile.txt
+$ <%=cmd%> cos node info
+$ <%=cmd%> cos node upload 'faux:///sample1G?1g'
 ```
 
+Note: we generate a dummy file `sample1G` if size 2GB using the `faux` PVCL (man ascp), but you can of course send a real file by specifying a real file instead.
+
 # Plugin: IBM Aspera Sync
 
-A basic plugin to start an "async" using <%=tool%>. The main advantage is the possibility
-to start from ma configuration file, using <%=tool%> standard options.
+A basic plugin to start an "async" using <%=tool%>.
+The main advantage is the possibility to start from ma configuration file, using <%=tool%> standard options.
 
 # Plugin: Preview
 
-The `preview` generates "previews" of graphical files, i.e. thumbnails (office, images, video) and video previews on an Aspera HSTS for use primarily in the Aspera on Cloud application.
+The `preview` generates "previews" of graphical files, i.e. thumbnails (office, images, video) and video previews on storage for use primarily in the Aspera on Cloud application.
 This is based on the "node API" of Aspera HSTS when using Access Keys only inside it's "storage root".
 Several parameters can be used to tune several aspects:
 
@@ -2622,9 +2857,10 @@ $ <%=cmd%> config id previewconf update --url=https://localhost:9092 --username=
 $ <%=cmd%> config id default set preview previewconf
 ```
 
-Here we assume that Office file generation is disabled, else remove the option. `lock_port` prevents concurrent execution of generation when using a scheduler.
+Here we assume that Office file generation is disabled, else remove this option.
+`lock_port` prevents concurrent execution of generation when using a scheduler.
 
-Once can check if the access key is well configured using:
+One can check if the access key is well configured using:
 
 ```
 $ <%=cmd%> -Ppreviewconf node browse /
@@ -2710,6 +2946,14 @@ $ <%=cmd%> preview scan --skip-folders=@json:'["/not_here"]'
 
 The option `folder_reset_cache` forces the node service to refresh folder contents using various methods.
 
+When scanning the option `value` has the same behaviour as for the `node find` command.
+
+For instance to filter out files beginning with `._` do:
+
+```
+... --value='exec:!f["name"].start_with?("._") or f["name"].eql?(".DS_Store")'
+```
+
 ## Preview File types
 
 Two types of preview can be generated:
@@ -2758,14 +3002,14 @@ Aspera CLI can send email, for that setup SMTP configuration. This is done with
 The `smtp` option is a hash table (extended value) with the following fields:
 <table>
 <tr><th>field</th><th>default</th><th>example</th><th>description</th></tr>
-<tr><td>server</td><td>-</td><td>smtp.gmail.com</td><td>SMTP server address</td></tr>
-<tr><td>tls</td><td>true</td><td>false</td><td>use of TLS</td></tr>
-<tr><td>port</td><td>587 for tls<br/>25 else</td><td>587</td><td>port for service</td></tr>
-<tr><td>domain</td><td>domain of server</td><td>gmail.com</td><td>email domain of user</td></tr>
-<tr><td>username</td><td>-</td><td>john@example.com</td><td>user to authenticate on SMTP server, leave empty for open auth.</td></tr>
-<tr><td>password</td><td>-</td><td>MyP@ssword</td><td>password for above username</td></tr>
-<tr><td>from\_email</td><td>username if defined</td><td>laurent.martin.l@gmail.com</td><td>address used if received replies</td></tr>
-<tr><td>from\_name</td><td>same as email</td><td>John Wayne</td><td>display name of sender</td></tr>
+<tr><td>`server`</td><td>-</td><td>smtp.gmail.com</td><td>SMTP server address</td></tr>
+<tr><td>`tls`</td><td>true</td><td>false</td><td>use of TLS</td></tr>
+<tr><td>`port`</td><td>587 for tls<br/>25 else</td><td>587</td><td>port for service</td></tr>
+<tr><td>`domain`</td><td>domain of server</td><td>gmail.com</td><td>email domain of user</td></tr>
+<tr><td>`username`</td><td>-</td><td>john@example.com</td><td>user to authenticate on SMTP server, leave empty for open auth.</td></tr>
+<tr><td>`password`</td><td>-</td><td>MyP@ssword</td><td>password for above username</td></tr>
+<tr><td>`from_email`</td><td>username if defined</td><td>laurent.martin.l@gmail.com</td><td>address used if received replies</td></tr>
+<tr><td>`from_name`</td><td>same as email</td><td>John Wayne</td><td>display name of sender</td></tr>
 </table>
 
 ## Example of configuration:
@@ -2795,13 +3039,52 @@ $ <%=cmd%> config id cli_default set smtp @val:@preset:smtp_google
 $ <%=cmd%> config id default set config cli_default
 ```
 
+## Email templates
+
+Sent emails are built using a template that uses the [ERB](https://www.tutorialspoint.com/ruby/eruby.htm) syntax.
+
+The template is the full SMTP message, including headers.
+
+The following variables are defined by default:
+
+* from_name
+* from_email
+* to
+
+Other variables are defined depending on context.
+
 ## Test
 
 Check settings with `smtp_settings` command. Send test email with `email_test`.
 
 ```
 $ <%=cmd%> config --smtp=@preset:smtp_google smtp
-$ <%=cmd%> config --smtp=@preset:smtp_google email sample.dest@example.com
+$ <%=cmd%> config --smtp=@preset:smtp_google email --notif-to=sample.dest@example.com
+```
+
+## Notifications for transfer status
+
+An e-mail notification can be sent upon transfer success and failure (one email per transfer job, one job being possibly multi session, and possibly after retry).
+
+To activate, use option `notif_to`.
+
+A default e-mail template is used, but it can be overriden with option `notif_template`.
+
+The environment provided contains the following additional variables:
+
+* subject
+* body
+* global_transfer_status
+* ts
+
+Example of template:
+
+```
+From: <%='<'%>%=from_name%> <<%='<'%>%=from_email%>>
+To: <<%='<'%>%=to%>>
+Subject: <%='<'%>%=subject%>
+
+Transfer is: <%='<'%>%=global_transfer_status%>
 ```
 
 # Tool: `asession`
@@ -2847,7 +3130,7 @@ Note that in addition, many "EX_" [_transfer-spec_](#transferspec) parameters ar
 ## Simple session
 
 ```
-MY_TSPEC='{"remote_host":"demo.asperasoft.com","remote_user":"asperaweb","ssh_port":33001,"remote_password":"demoaspera","direction":"receive","destination_root":"./test.dir","paths":[{"source":"/aspera-test-dir-tiny/200KB.1"}],"resume_level":"none"}'
+MY_TSPEC='{"remote_host":"demo.asperasoft.com","remote_user":"asperaweb","ssh_port":33001,"remote_password":"_demo_pass_","direction":"receive","destination_root":"./test.dir","paths":[{"source":"/aspera-test-dir-tiny/200KB.1"}],"resume_level":"none"}'
 
 echo "${MY_TSPEC}"|asession
 ```
@@ -2860,7 +3143,7 @@ This is particularly useful for a persistent session ( with the [_transfer-spec_
 
 ```
 $ asession
-{"remote_host":"demo.asperasoft.com","ssh_port":33001,"remote_user":"asperaweb","remote_password":"demoaspera","direction":"receive","destination_root":".","keepalive":true,"resume_level":"none"}
+{"remote_host":"demo.asperasoft.com","ssh_port":33001,"remote_user":"asperaweb","remote_password":"_demo_pass_","direction":"receive","destination_root":".","keepalive":true,"resume_level":"none"}
 {"type":"START","source":"/aspera-test-dir-tiny/200KB.2"}
 {"type":"DONE"}
 ```
@@ -2912,7 +3195,7 @@ Interesting ascp features are found in its arguments: (see ascp manual):
 Note that:
 
 * <%=tool%> takes transfer parameters exclusively as a transfer_spec, with `--ts` parameter.
-* not all native ascp arguments are available as standard transfer_spec parameters
+* most, but not all native ascp arguments are available as standard transfer_spec parameters
 * native ascp arguments can be provided with the [_transfer-spec_](#transferspec) parameter: EX_ascp_args (array), only for the "local" transfer agent (not connect or node)
 
 ### server side and configuration
@@ -3009,7 +3292,42 @@ So, it evolved into <%=tool%>:
 
 # Changes (Release notes)
 
-* 4.x
+* <%= gemspec.version.to_s %>
+
+	* new: parameter `multi_incr_udp` for option `transfer_info`: control if UDP port is incremented when multi-session is used on `direct` transfer agent.
+	* new: command `aoc files node_info` to get node information for a given folder in the Files application of AoC. Allows cross-org or cross-workspace transfers.
+
+* 4.2.2
+
+	* new: `faspex package list` retrieves the whole list, not just first page
+	* new: support web based auth to aoc and faspex 5 using HTTPS, new dependency on gem `webrick`
+	* new: the error "Remote host is not who we expected" displays a special remediation message
+	* new: `conf ascp spec` displays supported transfer spec
+	* new: options `notif_to` and `notif_template` to send email notifications on transfer (and other events)
+	* fix: space character in `faspe:` url are precent encoded if needed
+	* fix: `preview scan`: if file_id is unknown, ignore and continue scan
+	* change: for commands that potentially execute several transfers (`package recv --id=ALL`), if one transfer fails then <%=tool%> exits with code 1 (instead of zero=success)
+	* change: (break) option `notify` or `aoc` replaced with `notif_to` and `notif_template`
+
+* 4.2.1
+
+	* new: command `faspex package recv` supports link of type: `faspe:`
+	* new: command `faspex package recv` supports option `recipient` to specify dropbox with leading `*`
+
+* 4.2.0
+
+	* new: command `aoc remind` to receive organization membership by email
+	* new: in `preview` option `value` to filter out on file name
+	* new: `initdemo` to initialize for demo server
+	* new: `direct` transfer agent options: `spawn_timeout_sec` and `spawn_delay_sec`
+	* fix: on Windows `conf ascp use` expects ascp.exe
+	* fix: (break) multi_session_threshold is Integer, not String
+	* fix: `conf ascp install` renames sdk folder if it already exists (leftover shared lib may make fail)
+	* fix: removed replace_illegal_chars from default aspera.conf causing "Error creating illegal char conversion table"
+	* change: (break) `aoc apiinfo` is removed, use `aoc servers` to provide the list of cloud systems
+	* change: (break) parameters for resume in `transfer-info` for `direct` are now in sub-key `"resume"`
+
+* 4.1.0
 
   	* fix: remove keys from transfer spec and command line when not needed
   	* fix: default to create_dir:true so that sending single file to a folder does not rename file if folder does not exist 
@@ -3380,11 +3698,15 @@ Breaking change:
 
   * Breaking change: "files" application renamed to "aspera" (for "Aspera on Cloud"). "repository" renamed to "files". Default is automatically reset, e.g. in config files and change key "files" to "aspera" in <%=prst%> "default".
 
-# BUGS
+# BUGS, FEATURES, CONTRIBUTION
+
+For issues or feature requests use the Github repository and issues.
+
+You can also contribute to this open source project.
 
-* This is best effort code without official support, dont expect full capabilities. This code is not supported by IBM/Aspera. You can contact the author for bugs or features.
+One can also create one's own command nplugin.
 
-## only one value for any option
+## Only one value for any option
 
 Some commands and sub commands may ask for the same option name.
 Currently, since option definition is position independant (last one wins), it is not possible
@@ -3398,7 +3720,8 @@ This happens typically for the `node` sub command, e.g. identify the node by nam
 
 ## ED255519 key not supported
 
-ED255519 keys are deactivated since version 0.9.24 so this type of key will just be ignored.
+ED25519 keys are deactivated since version 0.9.24 so this type of key will just be ignored.
+
 Without this deactivation, if such key was present the following error was generated:
 
 ```
@@ -3408,7 +3731,21 @@ OpenSSH keys only supported if ED25519 is available
 Which meant that you do not have ruby support for ED25519 SSH keys.
 You may either install the suggested Gems, or remove your ed25519 key from your `.ssh` folder to solve the issue.
 
-# TODO
+## Error "Remote host is not who we expected"
+
+Cause: `ascp` >= 4.x checks fingerprint of highest server host key, including ECDSA. `ascp` < 4.0 (3.9.6 and earlier) support only to RSA level (and ignore ECDSA presented by server). `aspera.conf` supports a single fingerprint.
+
+Workaround on client side: To ignore the certificate (SSH fingerprint) add option on client side (this option can also be added permanently to the config file):
+
+```
+--ts=@json:'{"sshfp":null}'
+```
+
+Workaround on server side: Either remove the fingerprint from `aspera.conf`, or keep only RSA host keys in `sshd_config`.
+
+References: ES-1944 in release notes of 4.1 and to [HSTS admin manual section "Configuring Transfer Server Authentication With a Host-Key Fingerprint"](https://www.ibm.com/docs/en/ahts/4.2?topic=upgrades-configuring-ssh-server).
+
+## Miscelaneous
 
 * remove rest and oauth classes and use ruby standard gems:
 
@@ -3424,9 +3761,3 @@ You may either install the suggested Gems, or remove your ed25519 key from your
 * Going through proxy: use env var http_proxy and https_proxy, no_proxy
 
 * easier use with https://github.com/pmq20/ruby-packer
-
-# Contribution
-
-Send comments !
-
-Create your own plugin !