aspera-cli 4.28.0 → 4.29.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (237) hide show
  1. checksums.yaml +4 -4
  2. checksums.yaml.gz.sig +0 -0
  3. data/BUGS.md +5 -10
  4. data/CHANGELOG.md +143 -2
  5. data/CODE_OF_CONDUCT.md +18 -0
  6. data/CONTRIBUTING.md +135 -56
  7. data/GOVERNANCE.md +30 -0
  8. data/LICENSE +201 -0
  9. data/README.md +103 -26
  10. data/SECURITY.md +70 -0
  11. data/bin/ascli +8 -5
  12. data/bin/asession +9 -6
  13. data/docs/README.md +1633 -609
  14. data/docs/test-mcp-with-ai.md +8 -8
  15. data/lib/aspera/agent/base.rb +23 -2
  16. data/lib/aspera/agent/connect.rb +16 -12
  17. data/lib/aspera/agent/desktop.rb +10 -7
  18. data/lib/aspera/agent/direct.rb +20 -19
  19. data/lib/aspera/agent/factory.rb +6 -3
  20. data/lib/aspera/agent/httpgw.rb +7 -5
  21. data/lib/aspera/agent/node.rb +15 -7
  22. data/lib/aspera/agent/transferd.rb +167 -43
  23. data/lib/aspera/api/alee.rb +4 -1
  24. data/lib/aspera/api/aoc.rb +14 -11
  25. data/lib/aspera/api/ats.rb +4 -2
  26. data/lib/aspera/api/cos_node.rb +7 -4
  27. data/lib/aspera/api/faspex.rb +16 -9
  28. data/lib/aspera/api/httpgw.rb +9 -6
  29. data/lib/aspera/api/node.rb +20 -20
  30. data/lib/aspera/ascmd.rb +8 -5
  31. data/lib/aspera/ascp/installation.rb +71 -65
  32. data/lib/aspera/ascp/log.schema.yaml +1084 -0
  33. data/lib/aspera/ascp/log_analyzer/advice.rb +97 -0
  34. data/lib/aspera/ascp/log_analyzer/diagnostics.rb +344 -0
  35. data/lib/aspera/ascp/log_analyzer/lines.rb +75 -0
  36. data/lib/aspera/ascp/log_analyzer/log_file.rb +593 -0
  37. data/lib/aspera/ascp/log_analyzer/records.rb +379 -0
  38. data/lib/aspera/ascp/log_analyzer/rules.rb +172 -0
  39. data/lib/aspera/ascp/log_analyzer/session.rb +782 -0
  40. data/lib/aspera/ascp/log_analyzer.rb +354 -0
  41. data/lib/aspera/ascp/management.rb +16 -8
  42. data/lib/aspera/ascp/session_errors.rb +217 -0
  43. data/lib/aspera/assert.rb +4 -0
  44. data/lib/aspera/cli/ascp_actions.rb +12 -19
  45. data/lib/aspera/cli/ascp_logs_actions.rb +176 -0
  46. data/lib/aspera/cli/async_transfer_store.rb +7 -4
  47. data/lib/aspera/cli/bootstrapper.rb +37 -33
  48. data/lib/aspera/cli/command_line.rb +24 -6
  49. data/lib/aspera/cli/command_registry.rb +6 -1
  50. data/lib/aspera/cli/command_spec.rb +34 -7
  51. data/lib/aspera/cli/completion/ascli.bash +19 -5
  52. data/lib/aspera/cli/completion/ascli.fish +13 -2
  53. data/lib/aspera/cli/completion/ascli.ps1 +31 -9
  54. data/lib/aspera/cli/completion/ascli.zsh +22 -6
  55. data/lib/aspera/cli/completion_actions.rb +303 -69
  56. data/lib/aspera/cli/context.rb +9 -4
  57. data/lib/aspera/cli/deprecation.rb +5 -2
  58. data/lib/aspera/cli/error.rb +3 -0
  59. data/lib/aspera/cli/extended_value.rb +61 -27
  60. data/lib/aspera/cli/formatter.rb +29 -22
  61. data/lib/aspera/cli/gem_checker.rb +9 -6
  62. data/lib/aspera/cli/hints.rb +22 -10
  63. data/lib/aspera/cli/http.rb +12 -9
  64. data/lib/aspera/cli/info.rb +12 -7
  65. data/lib/aspera/cli/mailer.rb +6 -3
  66. data/lib/aspera/cli/mcp/http_servlet.rb +7 -8
  67. data/lib/aspera/cli/mcp/secrets.rb +8 -5
  68. data/lib/aspera/cli/mcp/tool.rb +15 -14
  69. data/lib/aspera/cli/option_declarator.rb +10 -4
  70. data/lib/aspera/cli/option_registry.rb +6 -3
  71. data/lib/aspera/cli/option_types.rb +17 -2
  72. data/lib/aspera/cli/option_value.rb +65 -12
  73. data/lib/aspera/cli/options.schema.yaml +487 -63
  74. data/lib/aspera/cli/parser.rb +56 -32
  75. data/lib/aspera/cli/plugins/alee.rb +7 -4
  76. data/lib/aspera/cli/plugins/aoc.rb +244 -35
  77. data/lib/aspera/cli/plugins/ats.rb +9 -8
  78. data/lib/aspera/cli/plugins/base.rb +17 -12
  79. data/lib/aspera/cli/plugins/basic_auth.rb +5 -2
  80. data/lib/aspera/cli/plugins/config.rb +198 -103
  81. data/lib/aspera/cli/plugins/console.rb +6 -3
  82. data/lib/aspera/cli/plugins/cos.rb +8 -4
  83. data/lib/aspera/cli/plugins/factory.rb +21 -7
  84. data/lib/aspera/cli/plugins/faspex5.rb +28 -25
  85. data/lib/aspera/cli/plugins/faspio.rb +7 -5
  86. data/lib/aspera/cli/plugins/httpgw.rb +7 -4
  87. data/lib/aspera/cli/plugins/mcp.rb +28 -22
  88. data/lib/aspera/cli/plugins/node.rb +31 -30
  89. data/lib/aspera/cli/plugins/oauth.rb +5 -1
  90. data/lib/aspera/cli/plugins/orchestrator.rb +272 -72
  91. data/lib/aspera/cli/plugins/preview.rb +69 -44
  92. data/lib/aspera/cli/plugins/server.rb +63 -11
  93. data/lib/aspera/cli/plugins/shares.rb +86 -16
  94. data/lib/aspera/cli/plugins/transferd.rb +223 -0
  95. data/lib/aspera/cli/preset_actions.rb +144 -30
  96. data/lib/aspera/cli/preset_manager.rb +52 -18
  97. data/lib/aspera/cli/prompt.rb +4 -1
  98. data/lib/aspera/cli/result.rb +12 -8
  99. data/lib/aspera/cli/runner.rb +69 -46
  100. data/lib/aspera/cli/secret_finder.rb +4 -1
  101. data/lib/aspera/cli/security.rb +79 -9
  102. data/lib/aspera/cli/special_values.rb +4 -1
  103. data/lib/aspera/cli/sync_actions.rb +13 -10
  104. data/lib/aspera/cli/table_fitter.rb +3 -0
  105. data/lib/aspera/cli/terminal_formatter.rb +9 -6
  106. data/lib/aspera/cli/transfer_actions.rb +11 -8
  107. data/lib/aspera/cli/transfer_agent.rb +29 -20
  108. data/lib/aspera/cli/transfer_progress.rb +13 -45
  109. data/lib/aspera/cli/vault_actions.rb +45 -0
  110. data/lib/aspera/cli/vault_manager.rb +188 -42
  111. data/lib/aspera/cli/version.rb +4 -1
  112. data/lib/aspera/cli/web_secret.rb +12 -10
  113. data/lib/aspera/cli/wizard.rb +42 -39
  114. data/lib/aspera/command_line_builder.rb +9 -5
  115. data/lib/aspera/command_line_converter.rb +4 -1
  116. data/lib/aspera/coverage.rb +103 -33
  117. data/lib/aspera/data_repository.rb +4 -1
  118. data/lib/aspera/dot_container.rb +4 -1
  119. data/lib/aspera/duration.rb +5 -2
  120. data/lib/aspera/environment.rb +21 -12
  121. data/lib/aspera/exec_spec.rb +3 -0
  122. data/lib/aspera/faspex_gw.rb +13 -9
  123. data/lib/aspera/faspex_postproc.rb +15 -12
  124. data/lib/aspera/formatter_interface.rb +4 -1
  125. data/lib/aspera/graphql.rb +5 -1
  126. data/lib/aspera/hash_ext.rb +3 -0
  127. data/lib/aspera/id_generator.rb +4 -2
  128. data/lib/aspera/json_rpc/client.rb +6 -5
  129. data/lib/aspera/json_rpc/version.rb +3 -0
  130. data/lib/aspera/line_logger.rb +4 -1
  131. data/lib/aspera/link_header.rb +4 -1
  132. data/lib/aspera/log.rb +18 -5
  133. data/lib/aspera/markdown.rb +5 -2
  134. data/lib/aspera/mime.rb +3 -0
  135. data/lib/aspera/nagios.rb +6 -4
  136. data/lib/aspera/node_emulator.rb +15 -13
  137. data/lib/aspera/oauth/client/base.rb +91 -70
  138. data/lib/aspera/oauth/client/boot.rb +7 -4
  139. data/lib/aspera/oauth/client/factory.rb +6 -3
  140. data/lib/aspera/oauth/client/generic.rb +5 -1
  141. data/lib/aspera/oauth/client/json_credentials.rb +4 -1
  142. data/lib/aspera/oauth/client/jwt.rb +6 -3
  143. data/lib/aspera/oauth/client/shares_web.rb +85 -0
  144. data/lib/aspera/oauth/client/url_json.rb +4 -1
  145. data/lib/aspera/oauth/client/web.rb +39 -12
  146. data/lib/aspera/oauth/server/pkce.rb +6 -5
  147. data/lib/aspera/orchestrator_workflow_checker.rb +119 -1
  148. data/lib/aspera/persistency_action_once.rb +5 -3
  149. data/lib/aspera/persistency_folder.rb +6 -3
  150. data/lib/aspera/preview/file_types.rb +6 -3
  151. data/lib/aspera/preview/generator.rb +9 -5
  152. data/lib/aspera/preview/options.schema.yaml +3 -3
  153. data/lib/aspera/preview/terminal.rb +8 -4
  154. data/lib/aspera/preview/utils.rb +6 -4
  155. data/lib/aspera/products/connect.rb +5 -2
  156. data/lib/aspera/products/desktop.rb +4 -1
  157. data/lib/aspera/products/other.rb +4 -2
  158. data/lib/aspera/products/transferd.rb +6 -2
  159. data/lib/aspera/products/transferd_service.rb +610 -0
  160. data/lib/aspera/proxy_auto_config.js +2 -2
  161. data/lib/aspera/proxy_auto_config.rb +5 -2
  162. data/lib/aspera/rainbow.rb +3 -0
  163. data/lib/aspera/rest/aspera_errors.rb +4 -1
  164. data/lib/aspera/rest/call_error.rb +3 -0
  165. data/lib/aspera/rest/client.rb +22 -29
  166. data/lib/aspera/rest/error_analyzer.rb +5 -2
  167. data/lib/aspera/rest/list.rb +8 -4
  168. data/lib/aspera/rest/parameters.rb +3 -0
  169. data/lib/aspera/rest/util.rb +8 -5
  170. data/lib/aspera/rest.rb +9 -6
  171. data/lib/aspera/schema/IBM Aspera Faspex API-5.0-enhanced.yaml +9 -9
  172. data/lib/aspera/schema/IBM Aspera Orchestrator API-v1-enhanced.yaml +118 -30
  173. data/lib/aspera/schema/IBM Aspera on Cloud API-0.2.6-enhanced.yaml +11 -11
  174. data/lib/aspera/schema/IBM Aspera on Cloud Automation API-1.0.5-enhanced.yaml +2437 -1437
  175. data/lib/aspera/schema/async_tables.yaml +11 -10
  176. data/lib/aspera/schema/documentation.rb +8 -2
  177. data/lib/aspera/schema/reader.rb +7 -0
  178. data/lib/aspera/schema/registry.rb +43 -28
  179. data/lib/aspera/schema/transferd-config.schema.json +333 -0
  180. data/lib/aspera/schema/validator.rb +4 -1
  181. data/lib/aspera/sealed_hash.rb +166 -0
  182. data/lib/aspera/secret/hider.rb +201 -0
  183. data/lib/aspera/secret/reference.rb +150 -0
  184. data/lib/aspera/secret/resolver.rb +212 -0
  185. data/lib/aspera/secret/store/base.rb +153 -0
  186. data/lib/aspera/secret/store/encrypted_hash.rb +329 -0
  187. data/lib/aspera/secret/store/factory.rb +103 -0
  188. data/lib/aspera/secret/store/hashicorp_vault.rb +390 -0
  189. data/lib/aspera/secret/store/keeper.rb +141 -0
  190. data/lib/aspera/secret/store/macos_security.rb +284 -0
  191. data/lib/aspera/secret/store/one_password_api.rb +99 -0
  192. data/lib/aspera/secret/store/one_password_base.rb +42 -0
  193. data/lib/aspera/secret/store/one_password_cli.rb +110 -0
  194. data/lib/aspera/secret/store/secret_service.rb +125 -0
  195. data/lib/aspera/secret/strength.rb +119 -0
  196. data/lib/aspera/servlet_helpers.rb +5 -2
  197. data/lib/aspera/ssh.rb +10 -7
  198. data/lib/aspera/ssl.rb +5 -2
  199. data/lib/aspera/string_ext.rb +3 -0
  200. data/lib/aspera/sync/args.schema.yaml +3 -0
  201. data/lib/aspera/sync/conf.schema.yaml +9 -4
  202. data/lib/aspera/sync/database.rb +3 -0
  203. data/lib/aspera/sync/operations.rb +16 -14
  204. data/lib/aspera/temp_file_manager.rb +8 -4
  205. data/lib/aspera/timer_limiter.rb +3 -0
  206. data/lib/aspera/transfer/error.rb +4 -1
  207. data/lib/aspera/transfer/faux_file.rb +4 -1
  208. data/lib/aspera/transfer/parameters.rb +17 -14
  209. data/lib/aspera/transfer/result.rb +3 -0
  210. data/lib/aspera/transfer/resumer.rb +6 -4
  211. data/lib/aspera/transfer/spec.rb +9 -22
  212. data/lib/aspera/transfer/units.rb +75 -0
  213. data/lib/aspera/uri_reader.rb +57 -7
  214. data/lib/aspera/web_auth/index.html.erb +6 -2
  215. data/lib/aspera/web_auth/paste.rb +109 -0
  216. data/lib/aspera/web_auth/receiver.rb +50 -0
  217. data/lib/aspera/web_auth/relay.rb +76 -0
  218. data/lib/aspera/web_auth/reply.html.erb +150 -0
  219. data/lib/aspera/web_auth/server.rb +47 -10
  220. data/lib/aspera/web_page.rb +7 -2
  221. data/lib/aspera/web_server_simple.rb +6 -3
  222. data/lib/aspera/yaml.rb +5 -1
  223. data/llms.txt +81 -0
  224. data/skills/ascli/SKILL.md +88 -0
  225. data.tar.gz.sig +0 -0
  226. metadata +72 -19
  227. metadata.gz.sig +0 -0
  228. data/lib/aspera/keychain/base.rb +0 -30
  229. data/lib/aspera/keychain/encrypted_hash.rb +0 -192
  230. data/lib/aspera/keychain/factory.rb +0 -58
  231. data/lib/aspera/keychain/hashicorp_vault.rb +0 -77
  232. data/lib/aspera/keychain/macos_security.rb +0 -277
  233. data/lib/aspera/keychain/one_password_api.rb +0 -91
  234. data/lib/aspera/keychain/one_password_base.rb +0 -39
  235. data/lib/aspera/keychain/one_password_cli.rb +0 -100
  236. data/lib/aspera/secret_hider.rb +0 -196
  237. data/lib/aspera/secret_strength.rb +0 -114
data/docs/README.md CHANGED
@@ -10,14 +10,16 @@ EDITING GUIDELINES:
10
10
  ellipsis : ... (not U+2026)
11
11
  - Emphasis style: use **bold** (double asterisks) only. Do not use *single asterisk italic*, _underscore_, or __double underscore__ style.
12
12
  DO NOT EDIT: THIS FILE IS GENERATED, edit docs/README.erb.md.
13
- PANDOC_DEFAULTS_BEGIN
14
- metadata:
15
- subtitle: "ascli 4.28.0"
16
- author: "Laurent Martin"
17
- PANDOC_DEFAULTS_END
18
13
  -->
19
14
  <!-- markdownlint-disable MD033 -->
20
15
 
16
+ <!-- gfm2pdf
17
+ common:
18
+ metadata:
19
+ subtitle: "ascli 4.29.0"
20
+ author: "Laurent Martin"
21
+ -->
22
+
21
23
  <!-- Admonitions: NOTE CAUTION WARNING IMPORTANT TIP INFO -->
22
24
 
23
25
  <!-- markdownlint-disable MD028 -->
@@ -28,9 +30,17 @@ PANDOC_DEFAULTS_END
28
30
 
29
31
  ### Overview
30
32
 
33
+ **The automation interface for IBM Aspera. From command line to AI agents.**
34
+
31
35
  The IBM Aspera Command Line Interface (`ascli`) is an enterprise-grade tool that provides comprehensive command-line access to IBM Aspera's suite of high-speed file transfer products and services.
32
36
  Designed for automation, scripting, and integration scenarios, `ascli` enables organizations to leverage Aspera's FASP technology within their existing workflows and DevOps pipelines.
33
37
 
38
+ > [!TIP]
39
+ > For any question about `ascli` (behavior, options), or to build a command line, give this manual to an AI assistant as a reference and ask it.
40
+ > See [Leveraging AI Assistance](#leveraging-ai-assistance).
41
+
42
+ ![Architecture: transfer agents, IBM Aspera applications and transfer servers](architecture.svg)
43
+
34
44
  ### Key Features
35
45
 
36
46
  **Multi-Product Integration**
@@ -45,6 +55,15 @@ Designed for automation, scripting, and integration scenarios, `ascli` enables o
45
55
  **Configuration Management**
46
56
  : Persistent configuration presets, environment variables, and flexible option handling for streamlined operations.
47
57
 
58
+ **Structured Output**
59
+ : JSON, YAML, CSV or tables, with filtering and JMESPath queries, for scripts, schedulers and CI/CD pipelines.
60
+
61
+ **Secrets Management**
62
+ : Secrets kept in a vault (encrypted file, HashiCorp Vault, Keeper, 1Password, macOS keychain, Linux Secret Service), never in scripts.
63
+
64
+ **AI Assistants and Agents**
65
+ : AI assistants operate IBM Aspera products with `ascli`, in a shell (with `llms.txt` or the agent skill) or through the built-in MCP server, with restrictions and without seeing secrets.
66
+
48
67
  **Developer Friendly**
49
68
  : Comprehensive logging, debugging capabilities, and API exploration tools for development and troubleshooting.
50
69
 
@@ -71,6 +90,16 @@ This manual is organized into the following sections:
71
90
 
72
91
  ### When to use and when not to use
73
92
 
93
+ | Need | Best choice | Why |
94
+ | ---- | ----------- | --- |
95
+ | Script or schedule transfers, packages, file management or administration of Aspera products (shell, `cron`, CI/CD) | `ascli` | One tool for all products, presets and vault per environment, structured output, automatic resume |
96
+ | Let an AI assistant or agent operate Aspera products | `ascli`: in a shell, or its MCP server | Same commands as people, restrictions, secrets never shown (see [Leveraging AI Assistance](#leveraging-ai-assistance)) |
97
+ | Administer, troubleshoot, or analyze `ascp` logs, interactively | `ascli` | Commands for every product, `ascp` log diagnostics |
98
+ | Learn or test an Aspera REST API | `ascli` | Shows the API calls (see [Logging, Debugging](#logging-debugging)) |
99
+ | Simple transfer with an HSTS, where nothing else can be installed | `ascp` | Included with every Aspera transfer product (see [`ascli` or `ascp`?](#ascli-or-ascp)) |
100
+ | Build an application (C/C++, Go, Python, Java, .NET, NodeJS...) | Aspera REST APIs and Transfer Daemon (gRPC) | Better for long-term development and maintenance |
101
+ | Users who transfer files with a graphical interface | IBM Aspera for Desktop, or the web interface of the application | Interactive use, no command line |
102
+
74
103
  > [!NOTE]
75
104
  > If you are scripting or automating transfers from the command line, `ascli` is the right choice.
76
105
  > If you are developing an application, prefer the APIs or SDKs instead.
@@ -166,7 +195,7 @@ This section walks you through your first interaction with `ascli` on Linux.
166
195
 
167
196
  ```shell
168
197
  mkdir -p $HOME/bin
169
- tar -C $HOME/bin -zxvf ascli-4.28.0-linux-x86_64.tgz
198
+ tar -C $HOME/bin -zxvf ascli-4.29.0-linux-x86_64.tgz
170
199
  export PATH=$PATH:$HOME/bin
171
200
  ```
172
201
 
@@ -180,13 +209,13 @@ ascli -v
180
209
  ```
181
210
 
182
211
  ```text
183
- 4.28.0
212
+ 4.29.0
184
213
  ```
185
214
 
186
215
  - Install the Aspera transfer runtime (tested version), as it is not included in the `ascli` package:
187
216
 
188
217
  ```shell
189
- ascli config transferd install
218
+ ascli transferd install
190
219
  ```
191
220
 
192
221
  ### Option A - Test with the Aspera Demo Server
@@ -240,7 +269,7 @@ The steps below create a preset, set it as the default for the server plugin, br
240
269
  - Create a preset with your server's connection details:
241
270
 
242
271
  ```shell
243
- ascli config preset update <SERVER_PRESET_NAME> --url=ssh://hsts.example.com:33001 --username=<USERNAME> --password=<PASSWORD>
272
+ ascli config preset set <SERVER_PRESET_NAME> @: url=ssh://hsts.example.com:33001 username=<USERNAME> password=<PASSWORD>
244
273
  ```
245
274
 
246
275
  ```text
@@ -267,10 +296,34 @@ If you'd prefer to test against Aspera on Cloud, skip ahead to the [AoC Wizard](
267
296
 
268
297
  ### Leveraging AI Assistance
269
298
 
270
- You can significantly accelerate your workflow by using an AI assistant to generate and troubleshoot commands for `ascli`.
271
- For the best results, provide the AI with the most recent documentation as context.
299
+ You can significantly accelerate your workflow by using an AI assistant with `ascli`.
300
+ There are three ways, the first one is the simplest:
301
+
302
+ - **The AI executes commands in a shell** (coding agents): nothing to set up, and no limitation: the AI uses `ascli` as you do, with your configuration.
303
+ Give it the file [`llms.txt`](https://raw.githubusercontent.com/IBM/aspera-cli/refs/heads/main/llms.txt), located at the root of the gem and of the GitHub repository.
304
+ It tells the AI what `ascli` does with IBM Aspera products, and how to discover commands, arguments and options (`config commands`, `help`, `config options`, `config documentation`).
305
+ With an AI client that supports agent skills, install the skill instead: the AI loads it by itself when a request is about IBM Aspera.
306
+ The skill, in the [Agent Skills](https://agentskills.io) format, is the folder `skills/ascli` of the gem (and of the GitHub repository): copy it to the skills folder of the AI client, for example:
307
+
308
+ ```shell
309
+ cp -R "$(gem contents aspera-cli | grep 'skills/ascli/SKILL.md$' | xargs dirname)" ~/.claude/skills/
310
+ ```
311
+
312
+ With Claude Code, install it as a plugin from the GitHub repository, which is also a plugin marketplace: it is updated with the repository.
313
+
314
+ ```text
315
+ /plugin install ascli --marketplace IBM/aspera-cli
316
+ ```
317
+
318
+ - **The AI executes commands through MCP**: for an AI client without a shell, start the [MCP server](#plugin-mcp-model-context-protocol-server) and register it in the AI client.
319
+ The AI discovers commands and their arguments by itself, and executes them.
320
+ By default, the server restricts what the AI can do (see [Security](#security)), and the AI never sees secrets.
321
+
322
+ - **The AI generates commands that you execute** (chat assistant that cannot execute commands): it cannot read the documentation through `ascli`, so provide it as context, as described below.
323
+
324
+ In the first two ways, the AI reads the documentation by itself, one section at a time, with `ascli config documentation`: there is no need to provide the manual.
272
325
 
273
- Recommended Workflow:
326
+ Recommended Workflow for a chat assistant:
274
327
 
275
328
  - **Contextualize**: Download the project manual (this manual in Markdown format, [`docs/README.md`](https://raw.githubusercontent.com/IBM/aspera-cli/refs/heads/main/docs/README.md)) from the GitHub repository.
276
329
 
@@ -347,7 +400,7 @@ This executable includes the Ruby runtime and gems, but not the transfer SDK.
347
400
 
348
401
  ```shell
349
402
  tar zxvf aspera-cli-<VERSION>-<PLATFORM>.tgz
350
- ./ascli config transferd install
403
+ ./ascli transferd install
351
404
  ```
352
405
 
353
406
  #### Linux: Checking the GLIBC version
@@ -406,7 +459,7 @@ The GLIBC of the system must be at least the version in the archive name, see [C
406
459
 
407
460
  > [!NOTE]
408
461
  > The launcher `ascli` uses the `ascp` located in folder `sdk` of the package, unless environment variable `ASCLI_SDK_FOLDER` is set.
409
- > So, `ascli config transferd install` is not needed.
462
+ > So, `ascli transferd install` is not needed.
410
463
 
411
464
  The configuration is stored in the [main folder](#main-configuration-and-persistency-folder), like for other installation methods.
412
465
  To upgrade, extract the new version, and update the symbolic link.
@@ -443,7 +496,7 @@ Apart from the prerequisite below, no installation step, no administrator rights
443
496
 
444
497
  > [!NOTE]
445
498
  > The launcher `ascli.cmd` uses the `ascp` located in folder `sdk` of the package, unless environment variable `ASCLI_SDK_FOLDER` is set.
446
- > So, `ascli config transferd install` is not needed.
499
+ > So, `ascli transferd install` is not needed.
447
500
 
448
501
  The configuration is stored in the [main folder](#main-configuration-and-persistency-folder), like for other installation methods.
449
502
  To upgrade, extract the new version, and update the `PATH` if the folder name changed.
@@ -465,10 +518,10 @@ Then, install the Aspera Transfer Daemon, see [Installing `ascp` through `transf
465
518
 
466
519
  A Ruby interpreter is required to run `ascli`.
467
520
 
468
- Required Ruby version is version: >= 3.2.
521
+ Required Ruby version is version: >= 3.3.
469
522
 
470
523
  > [!WARNING]
471
- > The minimum Ruby version will be 3.3 in a future version.
524
+ > The minimum Ruby version will be 3.4 in a future version.
472
525
 
473
526
  **Ruby can be installed using any of the following methods**: `rpm`, `yum`, `dnf`, `rvm`, `rbenv`, `brew`, Windows installer, ...
474
527
 
@@ -479,10 +532,21 @@ Required Ruby version is version: >= 3.2.
479
532
 
480
533
  For convenience, you may refer to the following sections for a proposed method for specific operating systems.
481
534
 
482
- `ascli` supports a Ruby version until 18 months after its [end of official support](https://www.ruby-lang.org/en/downloads/branches/).
535
+ `ascli` supports a Ruby version until 6 months after its [end of official support](https://www.ruby-lang.org/en/downloads/branches/).
483
536
  The minimum version is increased accordingly, and announced in advance.
484
537
  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](https://rubygems.org/gems/aspera-cli).
485
538
 
539
+ The following table summarizes Ruby version life cycles and `ascli` support status:
540
+
541
+ | Ruby Version | Official EOL Date | ascli Support End (EOL + 6 mo) | ascli Status |
542
+ | ------------ | ----------------- | ------------------------------ | --------------------------------- |
543
+ | 4.0 | 2029-03-31 | 2029-09-30 | **Supported (Tested & Packaged)** |
544
+ | 3.4 | 2028-03-31 | 2028-09-30 | **Supported (Future minimum)** |
545
+ | 3.3 | 2027-03-31 | 2027-09-30 | **Supported (Current minimum)** |
546
+ | 3.2 | 2026-03-31 | 2026-09-30 | End of Support |
547
+ | 3.1 | 2025-03-26 | 2025-09-26 | End of Support |
548
+ | 3.0 | 2024-04-23 | 2024-10-23 | End of Support |
549
+
486
550
  #### Windows: Installer
487
551
 
488
552
  Manual installation:
@@ -545,6 +609,24 @@ Add it to your shell configuration file:
545
609
 
546
610
  #### Linux: Package
547
611
 
612
+ `ascli` supports Linux distributions that are officially maintained by their vendor (Red Hat for RHEL / UBI, Canonical for Ubuntu LTS).
613
+
614
+ - **GLIBC Requirement:** The Transfer SDK executables (`ascp`, `transferd`) and the Linux portable package require **`glibc >= 2.28`**.
615
+ - **Installation Compatibility:**
616
+ - If the OS provides a Ruby package or DNF module stream meeting the required version (≥ 3.3), the `aspera-cli` gem can be installed directly with `gem install`.
617
+ - If the OS is under maintenance but ships an older default system Ruby (e.g. Ubuntu 22.04 LTS with Ruby 3.0), `ascli` is fully supported via the [Linux portable package](#linux-portable-package), the [container image](#container), or a Ruby version manager (`rbenv`, `rvm`).
618
+
619
+ The following table summarizes supported Linux distributions, vendor end of support dates, GLIBC versions, available Ruby streams, and recommended `ascli` installation modes:
620
+
621
+ | Linux Distribution | OS Support End (EOL) | GLIBC (>= 2.28) | OS Ruby Version(s) | ascli Support / Mode |
622
+ | -------------------- | -------------------- | ------------------ | ------------------------------------ | ----------------------------------------------------- |
623
+ | **RHEL / UBI 10** | 2035-05-31 | 2.39+ (Compatible) | >= 3.3 (default) | Gem, Portable, Container |
624
+ | **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 |
625
+ | **RHEL / UBI 8** | 2029-05-31 | 2.28 (Compatible) | 3.1, 3.3 (DNF module) | Gem (`dnf module enable ruby:3.3`), Portable, Container |
626
+ | **Ubuntu 26.04 LTS** | 2031-05-29 | 2.43+ (Compatible) | >= 3.3 (APT package) | Gem, Portable, Container |
627
+ | **Ubuntu 24.04 LTS** | 2029-05-31 | 2.39 (Compatible) | 3.2 (APT package) | Gem (`apt install ruby-full`), Portable, Container |
628
+ | **Ubuntu 22.04 LTS** | 2027-06-01 | 2.35 (Compatible) | 3.0 (APT package) | Portable, Container, rbenv (OS Ruby < 3.2) |
629
+
548
630
  If your Linux distribution provides a standard Ruby package, you can use it provided that the version is supported.
549
631
 
550
632
  **Example:** RHEL 8+, Rocky Linux 8+: with extensions to compile native gems:
@@ -754,30 +836,30 @@ Those are not installed as part of dependencies because they involve compilation
754
836
  See [Gemfile](../Gemfile):
755
837
 
756
838
  | name | version | comment |
757
- |---------------------|-----------|-------------------------------------------------------------------------------|
839
+ | ---------------------- | --------- | -------------------------------------------------------------------------------- |
758
840
  | rake | ~> 13.0 | |
759
841
  | debug | ~> 1.11 | (no jruby) |
760
842
  | grpc-tools | ~> 1.67 | |
761
- | reek | ~> 6.5.0 | |
843
+ | reek | ~> 6.6.0 | |
762
844
  | rspec | ~> 3.0 | |
763
845
  | rubocop | ~> 1.75 | |
764
846
  | rubocop-ast | ~> 1.4 | |
765
847
  | rubocop-performance | ~> 1.10 | (no jruby) |
766
- | rubocop-shopify | ~> 2.0 | |
767
- | simplecov | ~> 0.22 | |
848
+ | rubocop-shopify | ~> 3.1 | |
849
+ | simplecov | ~> 1.3 | |
768
850
  | solargraph | ~> 0.48 | (no jruby) |
769
- | ferrum | ~> 0.19.1 | (no jruby) |
851
+ | ferrum | ~> 0.20.1 | (no jruby) |
770
852
  | mcp | ~> 1.2 | for ascli mcp server (MCP protocol support) |
771
853
  | rack | ~> 3.0 | for ascli mcp server HTTP transport (required by mcp StreamableHTTPTransport) |
772
854
  | grpc | ~> 1.71 | (no jruby) for Aspera Transfer Daemon |
773
855
  | sqlite3 | ~> 2.7 | (no jruby) for async DB |
774
856
  | jdbc-sqlite3 | ~> 3.46 | (jruby) for async DB |
775
857
  | sequel | ~> 5.96 | (jruby) for async DB |
776
- | ed25519 | ~> 1.4 | (no jruby) for ed25519 and OpenSSH file format |
777
- | bcrypt_pbkdf | ~> 1.1 | (no jruby) for ed25519 and OpenSSH file format |
858
+ | bcrypt_pbkdf | ~> 1.1 | (no jruby) for passphrase-protected OpenSSH private keys (ed25519 is native in net-ssh 8) |
778
859
  | syslog | ~> 0.3 | (no jruby) for logger=syslog |
779
860
  | zxcvbn | ~> 1.0 | for better estimate of secret strength (faspex5 postprocessing secret_token) |
780
- | rmagick | ~> 6.1 | (no jruby) for terminal view |
861
+ | keeper_secrets_manager | ~> 17.2 | for vault of type keeper (Keeper Secrets Manager) |
862
+ | rmagick | ~> 7.2 | (no jruby) for terminal view |
781
863
 
782
864
  Install like this:
783
865
 
@@ -785,26 +867,26 @@ Install like this:
785
867
  gem install rake -v '~> 13.0'
786
868
  gem install debug -v '~> 1.11'
787
869
  gem install grpc-tools -v '~> 1.67'
788
- gem install reek -v '~> 6.5.0'
870
+ gem install reek -v '~> 6.6.0'
789
871
  gem install rspec -v '~> 3.0'
790
872
  gem install rubocop -v '~> 1.75'
791
873
  gem install rubocop-ast -v '~> 1.4'
792
874
  gem install rubocop-performance -v '~> 1.10'
793
- gem install rubocop-shopify -v '~> 2.0'
794
- gem install simplecov -v '~> 0.22'
875
+ gem install rubocop-shopify -v '~> 3.1'
876
+ gem install simplecov -v '~> 1.3'
795
877
  gem install solargraph -v '~> 0.48'
796
- gem install ferrum -v '~> 0.19.1'
878
+ gem install ferrum -v '~> 0.20.1'
797
879
  gem install mcp -v '~> 1.2'
798
880
  gem install rack -v '~> 3.0'
799
881
  gem install grpc -v '~> 1.71'
800
882
  gem install sqlite3 -v '~> 2.7'
801
883
  gem install jdbc-sqlite3 -v '~> 3.46'
802
884
  gem install sequel -v '~> 5.96'
803
- gem install ed25519 -v '~> 1.4'
804
885
  gem install bcrypt_pbkdf -v '~> 1.1'
805
886
  gem install syslog -v '~> 0.3'
806
887
  gem install zxcvbn -v '~> 1.0'
807
- gem install rmagick -v '~> 6.1'
888
+ gem install keeper_secrets_manager -v '~> 17.2'
889
+ gem install rmagick -v '~> 7.2'
808
890
  ```
809
891
 
810
892
  ### Ruby gem: `aspera-cli`
@@ -880,7 +962,7 @@ The easiest option to install `ascp` is through the use of the IBM Aspera Transf
880
962
  Install it using `ascli` (for the current platform) with:
881
963
 
882
964
  ```shell
883
- ascli config transferd install
965
+ ascli transferd install
884
966
  ```
885
967
 
886
968
  The installation of the transfer binaries follows those steps:
@@ -903,30 +985,33 @@ The installation of the transfer binaries follows those steps:
903
985
  | `locations_url` | List of URLs to get download URLs of Aspera Transfer Daemon from IBM official repository, tried in order.<br/>A list given in options replaces the default list.<br/>Default:<br/>- `https://ibm.biz/sdk_location`<br/>- `https://raw.githubusercontent.com/IBM/aspera-cli/refs/heads/main/docs/sdk_location.yaml`|
904
986
  | `sdk_folder` | Folder where the SDK archive is extracted.<br/>Default: `$HOME/.aspera/sdk` |
905
987
 
906
- Transfer Daemon versions available from `locations_url` can be listed with: `ascli config transferd list`
988
+ > [!NOTE]
989
+ > Commands `config transferd ...` and `config ascp install` are deprecated aliases of `transferd ...` and `transferd install`.
990
+
991
+ Transfer Daemon versions available from `locations_url` can be listed with: `ascli transferd list`
907
992
 
908
993
  To install a specific version, for example, 1.1.3:
909
994
 
910
995
  ```shell
911
- ascli config transferd install 1.1.3
996
+ ascli transferd install 1.1.3
912
997
  ```
913
998
 
914
999
  To get the download URL for a specific platform and version:
915
1000
 
916
1001
  ```shell
917
- ascli config transferd list --select.platform=osx-arm64 --select.version=1.1.3 --fields=url
1002
+ ascli transferd list --select.platform=osx-arm64 --select.version=1.1.3 --fields=url
918
1003
  ```
919
1004
 
920
1005
  To download it, pipe to `config download`:
921
1006
 
922
1007
  ```shell
923
- ascli config transferd list --select.platform=osx-arm64 --select.version=1.1.3 --fields=url | ascli config download @stdin:
1008
+ ascli transferd list --select.platform=osx-arm64 --select.version=1.1.3 --fields=url | ascli config download @stdin:
924
1009
  ```
925
1010
 
926
1011
  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`:
927
1012
 
928
1013
  ```shell
929
- ascli config transferd install --sdk-url=file:///macos-arm64-1.1.3-c6c7a2a.zip
1014
+ ascli transferd install --sdk-url=file:///macos-arm64-1.1.3-c6c7a2a.zip
930
1015
  ```
931
1016
 
932
1017
  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 `/`).
@@ -942,7 +1027,7 @@ Supported platforms are listed in the [Release Notes](https://developer.ibm.com/
942
1027
 
943
1028
  If the embedded method is not used, the following packages are also suitable:
944
1029
 
945
- - IBM Aspera Connect Client (Free)
1030
+ - IBM Aspera Connect Client (Free, to be deprecated in 2027, use IBM Aspera for Desktop)
946
1031
  - IBM Aspera Desktop Client (Free)
947
1032
  - IBM Aspera for Desktop (Free)
948
1033
  - IBM Aspera High Speed Transfer Server (Licensed)
@@ -980,13 +1065,13 @@ For an air-gapped installation, two alternatives are available:
980
1065
  On a system with internet access, retrieve the SDK archive for the target platform and version:
981
1066
 
982
1067
  ```shell
983
- ascli config transferd list --select.platform=<PLATFORM> --select.version=<VERSION> --fields=url | ascli config download @stdin:
1068
+ ascli transferd list --select.platform=<PLATFORM> --select.version=<VERSION> --fields=url | ascli config download @stdin:
984
1069
  ```
985
1070
 
986
1071
  On the air-gapped system, install from the downloaded file using option `--sdk-url`:
987
1072
 
988
1073
  ```shell
989
- ascli config transferd install --sdk-url=file:///<SDK_ARCHIVE_PATH>
1074
+ ascli transferd install --sdk-url=file:///<SDK_ARCHIVE_PATH>
990
1075
  ```
991
1076
 
992
1077
  2. Retrieve the [single file executable](#single-file-executable) from the release, if available, and the SDK (not included) as described above.
@@ -999,11 +1084,11 @@ Alternatively, the necessary gems can be packaged into a `tar.gz` archive as fol
999
1084
 
1000
1085
  ```shell
1001
1086
  mkdir temp_folder
1002
- gem install aspera-cli:4.28.0 --no-document --install-dir temp_folder
1087
+ gem install aspera-cli:4.29.0 --no-document --install-dir temp_folder
1003
1088
  find temp_folder
1004
- mv temp_folder/cache aspera-cli-4.28.0-gems
1089
+ mv temp_folder/cache aspera-cli-4.29.0-gems
1005
1090
  rm -fr temp_folder
1006
- tar zcvf aspera-cli-4.28.0-gems.tgz aspera-cli-4.28.0-gems
1091
+ tar zcvf aspera-cli-4.29.0-gems.tgz aspera-cli-4.29.0-gems
1007
1092
  ```
1008
1093
 
1009
1094
  #### Unix-like: Alternative installation using `rvm`
@@ -1028,7 +1113,7 @@ The following procedure applies when using RVM for the Ruby installation:
1028
1113
  cd $HOME
1029
1114
  tar zxvf rvm-ascli.tgz
1030
1115
  source ~/.rvm/scripts/rvm
1031
- ascli config transferd install --sdk-url=file:///<SDK_ARCHIVE_PATH>
1116
+ ascli transferd install --sdk-url=file:///<SDK_ARCHIVE_PATH>
1032
1117
  ```
1033
1118
 
1034
1119
  6. Add the following line to the shell environment file (`.profile`):
@@ -1076,7 +1161,7 @@ On the target system:
1076
1161
  4. Install the Aspera Transfer Daemon SDK:
1077
1162
 
1078
1163
  ```shell
1079
- ascli config transferd install --sdk-url=file:///<SDK_ARCHIVE_PATH>
1164
+ ascli transferd install --sdk-url=file:///<SDK_ARCHIVE_PATH>
1080
1165
  ```
1081
1166
 
1082
1167
  ### Container
@@ -1139,7 +1224,7 @@ ascli -v
1139
1224
  ```
1140
1225
 
1141
1226
  ```text
1142
- 4.28.0
1227
+ 4.29.0
1143
1228
  ```
1144
1229
 
1145
1230
  To persist the configuration on the host, specify your user's configuration folder as a volume for the container.
@@ -1464,7 +1549,6 @@ Command line arguments that are not options are referred to as **Positional Argu
1464
1549
 
1465
1550
  For example:
1466
1551
 
1467
-
1468
1552
  ```shell
1469
1553
  ascli plugin command verb --option-name=VAL1 VAL2
1470
1554
  ```
@@ -1474,6 +1558,7 @@ ascli plugin command verb --option-name=VAL1 VAL2
1474
1558
 
1475
1559
  Enumeration values (positional arguments and option names/values) support prefix matching.
1476
1560
  See [Enumerations](#enumerations) for details.
1561
+
1477
1562
  For example `ascli config pre ov --for=c` is the same as `ascli config preset overview --format=csv`.
1478
1563
 
1479
1564
  The value of **Options** and **Command Parameters** is evaluated with the [Extended Value](#extended-value-syntax) syntax.
@@ -1580,7 +1665,6 @@ The following are enumerations:
1580
1665
 
1581
1666
  Examples:
1582
1667
 
1583
-
1584
1668
  - Positional: `ascli config pre ov --for=c` is the same as `ascli config preset overview --format=csv`
1585
1669
  - Option name: `--log-l=debug` is the same as `--log-level=debug`
1586
1670
  - Option value: `--format=c` is the same as `--format=csv`
@@ -1602,7 +1686,7 @@ Understanding this concept once makes it immediately usable everywhere it appear
1602
1686
  | [Option](#options) names | `--opt.key.sub=value` | Input | write |
1603
1687
  | [Positional arguments](#positional-arguments) | `@: key.sub=value ... [END]` | Input | write |
1604
1688
  | [Extended value](#extended-value-syntax) `@preset:` | `@preset:key.sub` | Input | read |
1605
- | [Output field names](#option-fields-selection-of-output-object-fields) | `--fields=key.sub` | Output | read |
1689
+ | [Output field names](#filtering-results) | `--out.fields=key.sub` | Output | read |
1606
1690
 
1607
1691
  A [dot-path](#dot-path-notation) is a `String` where segments are separated by `.` (dot), each segment designating a key in a nested structure:
1608
1692
 
@@ -1666,6 +1750,8 @@ The general syntax for this argument is:
1666
1750
  The optional text after `:` sets the end marker. If it is empty, the marker is `END`.
1667
1751
 
1668
1752
  - `<DOT_PATH>=<VALUE>`: An assignment using the standard [dot-path](#dot-path-notation) notation. Multiple assignments can be provided in sequence to build a complex object.
1753
+ The value is converted like any [dot-path](#dot-path-notation) value, and can be an [Extended Value](#extended-value-syntax), for example `public_key=@file:~/.ssh/id_rsa.pub`.
1754
+ Options placed among the assignments are not collected: they are processed as usual, for example `@: a=1 --format=json b=2`.
1669
1755
 
1670
1756
  - `<MARKER>` (`END` by default): An optional argument that ends the collection.
1671
1757
 
@@ -1838,9 +1924,212 @@ ascli config echo @json:'{"ni":null,"es":"","ea":[],"eh":{}}'
1838
1924
  ╰───────┴────────────────╯
1839
1925
  ```
1840
1926
 
1841
- #### Option: `format`
1927
+ #### Filtering results
1928
+
1929
+ The result of a command can be filtered on the server side, by the API, and then on the client side, by `ascli`.
1930
+ Filtering on the server side reduces the data transferred, while filtering on the client side accepts any condition.
1931
+
1932
+ Options are evaluated in this order:
1933
+
1934
+ ![Order of evaluation of the options that filter results](filtering-order.svg)
1935
+
1936
+ 1. `--query`: parameters sent to the API.
1937
+ 2. `--out.secrets`: secrets are hidden first, so that an expression cannot reveal them.
1938
+ 3. `--out.query`: JMESPath expression or Ruby lambda, applied to the data as returned by the API.
1939
+ 4. `--out.select`: selection of items (rows).
1940
+ 5. `--out.fields`: selection of fields (columns).
1941
+ 6. Display in the format set by `--out.format`.
1942
+
1943
+ | To | Use |
1944
+ |------------------------------------------|------------------------------------------|
1945
+ | Limit what the API returns | `--query`, with parameters `max` and `pmax` |
1946
+ | Filter on any condition, reshape, count | `--out.query` |
1947
+ | Select items by the value of fields | `--out.select` |
1948
+ | Choose the fields displayed | `--out.fields` |
1949
+
1950
+ ##### Option: `--query`: Parameters of the API
1951
+
1952
+ The `query` option can generally be used to add URL parameters to commands that list resources.
1953
+ It takes a `Hash`, corresponding to key/value pairs that appear in the query part of the request.
1954
+
1955
+ For example: `--query=@json:'{"p1":"v1","p2":"v2"}'` leads to query: `?p1=v1&p2=v2`.
1956
+
1957
+ If the same parameter needs to be provided several times, then it is also possible to provide an `Array`.
1958
+
1959
+ For example: `--query=@json:'{"p":["v1","v2"]}'` leads to query: `?p=v1&p=v2`.
1960
+
1961
+ If PHP-style arrays are expected in the API, add `[]` to the name of the parameter.
1962
+
1963
+ For example: `--query=@json:'{"p[]":["v1","v2"]}'` leads to query: `?p[]=v1&p[]=v2`.
1964
+
1965
+ Commands that read a list by pages (for example, `aoc admin user list`) also accept parameters `max` and `pmax`.
1966
+ They are processed by `ascli`, not sent to the API: they limit the number of items (`max`) and of pages (`pmax`) requested.
1967
+
1968
+ For example: `--query.max=10` reads the first 10 items.
1969
+
1970
+ > [!TIP]
1971
+ > Use `--query=help` on any `list` command to display the available query parameters and their types, as documented in the API.
1972
+ > For example: `ascli faspex5 admin accounts list --query=help`
1973
+
1974
+ ##### Option: `--out.query`: JMESPath expression
1975
+
1976
+ Option `--out.query` applies a [JMESPath](https://jmespath.org) expression to the result of a command, when it is an object or a list.
1977
+ JMESPath is a standard query language for JSON, also used by option `--query` of the AWS and Azure CLIs.
1978
+
1979
+ The expression is applied to the data as returned by the API (secrets hidden), before options `--out.select` and `--out.fields`.
1980
+ Its syntax is checked before the command is executed.
1981
+ Results of other types (status, no result) are not changed.
1982
+
1983
+ Examples:
1984
+
1985
+ ```shell
1986
+ # Name and email of ATS administrators
1987
+ ascli aoc admin user list --out.query='[?ats_admin].{name: name, email: email}'
1988
+ # Number of users
1989
+ ascli aoc admin user list --out.query='length(@)'
1990
+ # Email of users, one per line, for use in a shell loop
1991
+ ascli aoc admin user list --out.query='[].email' --format=text
1992
+ ```
1993
+
1994
+ > [!TIP]
1995
+ > Enclose the expression in single quotes for the shell.
1996
+ > In JMESPath, literal values are enclosed in backticks, for example: ``[?size > `1000`]``.
1997
+ > An expression with string literals in single quotes (`'...'`) is enclosed in double quotes, for example: `"[?name=='Ann']"`.
1998
+
1999
+ For processing that JMESPath does not provide (regular expressions, string manipulation, grouping), the value can be a Ruby lambda (`@ruby:`): it is called with the data, and returns the new data, converted to JSON data (for example, symbols and dates become strings).
2000
+ It is refused at [Security Level](#security-level) `medium` and `high`.
2001
+
2002
+ ```shell
2003
+ # Number of users per email domain
2004
+ ascli aoc admin user list --out.query=@ruby:'->(users){users.group_by{|u|u["email"].split("@").last}.transform_values(&:count)}'
2005
+ ```
2006
+
2007
+ The result of the query is displayed according to its type: a list of objects as a table, a list of values with one value per line, a single value as is.
2008
+ A list of lists (for example, `[].[name, email]`) is displayed only with a structured format (`json`, `yaml`, ...): to display a table, or CSV, use a multi-select hash instead, for example, `[].{name: name, email: email}`.
2009
+
2010
+ > [!NOTE]
2011
+ > Option `--query` gives filtering parameters to the API, while option `--out.query` filters and reshapes the result received.
2012
+ > Option `--out.query` is the equivalent of option `--query` of the AWS and Azure CLIs.
2013
+
2014
+ ##### Option: `--out.select`: Selection of items
2015
+
2016
+ A list of objects (`object_list`) can be filtered with option `--out.select` (or `--select`).
2017
+ Its value is either a `Hash` or a `Proc`:
2018
+
2019
+ - `Hash`: an item is selected if each key of the `Hash` is a field of the item with the same value, and the same type: `true` (`Boolean`) is not `"true"` (`String`).
2020
+ - `Proc`: a Ruby lambda called with each item (`Hash`), that returns `true` to select it, or `false` to remove it.
2021
+
2022
+ Example:
2023
+
2024
+ ```shell
2025
+ ascli aoc admin user list --out.fields=name,email,ats_admin --query=@json:'{"sort":"name"}' --out.select=@json:'{"ats_admin":true}'
2026
+ ```
2027
+
2028
+ ```text
2029
+ ╭────────────────┬─────────────────────┬───────────╮
2030
+ │ name │ email │ ats_admin │
2031
+ ╞════════════════╪═════════════════════╪═══════════╡
2032
+ │ John Curtis │ john@example.com │ true │
2033
+ │ Laurent Martin │ laurent@example.com │ true │
2034
+ ╰────────────────┴─────────────────────┴───────────╯
2035
+ ```
2036
+
2037
+ In the above example, the same result is obtained with option:
2038
+
2039
+ ```shell
2040
+ --out.select=@ruby:'->(i){i["ats_admin"]}'
2041
+ ```
2042
+
2043
+ A key can be a [dot-path](#dot-path-notation), for example, `directory_user.type`, with all formats.
2044
+
2045
+ ##### Option: `--out.fields`: Selection of fields
2046
+
2047
+ Depending on the command, results may include by default all fields, or only some selected fields.
2048
+ It is possible to define specific columns to be displayed, by setting option `--out.fields` (or `--fields`).
2049
+
2050
+ The `--out.fields` option is a list that can be either a comma-separated list or an [Extended Value](#extended-value-syntax) `Array`.
2051
+
2052
+ Individual elements of the list can be:
2053
+
2054
+ - **property**: add property to the current list
2055
+ - `-`**property**: remove property from the current list
2056
+ - `DEF`: default list of fields (that is the default, when not set)
2057
+ - `ALL`: all fields
2058
+ - A Ruby `RegEx`: using `@ruby:'/.../'`, or `@re:...` add those matching to the list
2059
+
2060
+ To display a **property** inside a complex structure (`Hash`, `Array`), use [dot-path](#dot-path-notation) notation, only with `--format=table` or `csv` (see option `--out.flat`).
2061
+ With other formats, use a JMESPath multi-select hash with option `--out.query`, for example: `--out.query='[].{name: name, type: directory_user.type}'`.
2062
+
2063
+ Examples:
2064
+
2065
+ - `a,b,c`: the list of attributes specified as a comma-separated list (overrides the default)
2066
+ - `@list:,a,b,c`: `Array` [Extended Value](#extended-value-syntax): same as above
2067
+ - `@json:'["a","b","c"]'`: `Array` [Extended Value](#extended-value-syntax): same as above
2068
+ - `b,DEF,-a`: default property list, remove `a` and add `b` in first position
2069
+ - `@ruby:'/^server/'`: Display all fields whose name begins with `server`
2070
+
2071
+ ##### `--out.select` or `--out.query`
2072
+
2073
+ Option `--out.select` is shorter for a test of equality, while option `--out.query` accepts any condition.
2074
+
2075
+ | Condition | `--out.select` | `--out.query` |
2076
+ |--------------------------|----------------------------------------------------|--------------------------------------------------|
2077
+ | Equal to a `Boolean` | `@json:'{"ats_admin":true}'` | `'[?ats_admin]'` |
2078
+ | Equal to a `String` | `@json:'{"name":"Ann"}'` | `"[?name=='Ann']"` |
2079
+ | Field of a nested object | `@json:'{"directory_user.type":"active_directory"}'` | `"[?directory_user.type=='active_directory']"` |
2080
+ | Several conditions (and) | `@json:'{"ats_admin":true,"name":"Ann"}'` | `"[?ats_admin && name=='Ann']"` |
2081
+ | Negation, or | Ruby lambda (`@ruby:`) | `'[?!ats_admin]'`, or: see [Recipes](#recipes) |
2082
+ | Number comparison | Ruby lambda (`@ruby:`) | ``'[?size > `1000000`]'`` |
2083
+ | Substring | Ruby lambda (`@ruby:`) | ``'[?contains(email, `@example`)]'`` |
2084
+ | Choice of fields | With option `--out.fields` | `'[].{name: name, email: email}'` |
2085
+ | Count | Not possible | `'length(@)'` |
2086
+
2087
+ > [!WARNING]
2088
+ >
2089
+ > - Values are compared with their type. With `--out.select`, `"true"` (`String`) does not match `true` (`Boolean`). In JMESPath, ``[?ats_admin == `true`]`` matches, but `[?ats_admin == 'true']` does not: `'...'` is a string literal.
2090
+ > - After `--out.query`, the default fields of the command no longer apply: all the fields of the result are displayed. Choose fields in the expression (multi-select hash), or with option `--out.fields`.
2091
+ > - Secrets are hidden before `--out.query` is applied, so that the expression cannot reveal them.
2092
+
2093
+ ##### Recipes
2094
+
2095
+ ```shell
2096
+ # Users of Active Directory, with user name and email
2097
+ ascli shares admin user all list --out.query="[?directory_user.type=='active_directory'].{username: username, email: email}"
2098
+ # Users without directory (field missing or null)
2099
+ ascli shares admin user all list --out.query='[?directory_user == null].username'
2100
+ # Number of ATS administrators
2101
+ ascli aoc admin user list --out.query='length([?ats_admin])'
2102
+ # Users who are ATS administrators, or have no email
2103
+ ascli aoc admin user list --out.query='[?ats_admin || !email].name'
2104
+ # Emails of a domain, one per line
2105
+ ascli aoc admin user list --out.query='[?ends_with(email, `@example.com`)].email' --format=text
2106
+ # Largest file of a folder
2107
+ ascli node browse / --out.query='max_by([?type==`file`], &size).path'
2108
+ # Files larger than 1 MB
2109
+ ascli node browse / --out.query='[?size > `1000000`].{path: path, size: size}'
2110
+ # Files modified since a date
2111
+ ascli node browse / --out.query='[?mtime >= `"2025-06-01"`].path'
2112
+ ```
2113
+
2114
+ > [!NOTE]
2115
+ > The JMESPath implementation of `ascli` (gem `jmespath`) also compares strings with `<`, `<=`, `>` and `>=`, which the JMESPath specification defines only for numbers.
2116
+ > Dates in ISO 8601 format, in the same time zone, are compared in chronological order.
1842
2117
 
1843
- The style of output can be set using the `format` option:
2118
+ The result in JSON (`--format=json`) can also be processed by other tools, such as [`jq`](https://jqlang.org), whose language differs from JMESPath: for example, `jq 'map(select(.directory_user.type == "active_directory"))'`.
2119
+
2120
+ ##### Other filters
2121
+
2122
+ Some commands provide their own filters:
2123
+
2124
+ - [Percent selector](#percent-selector) `%<field>:<value>`: selects a single resource by the value of one of its fields.
2125
+ - `find` of plugin `node` (gen4) and `aoc files find`: recursive search of files on the client side, with a glob or a Ruby lambda (see [Operation `find`](#operation-find-on-gen4access-key)).
2126
+ - `faspex5 packages list`: a Ruby lambda as last argument (see [Faspex 5: List packages](#faspex-5-list-packages)).
2127
+ - `console transfer`: query parameter `filter` (see [Transfer filter](#transfer-filter)).
2128
+ - `preview`: options `--filter` and `--skip-folders` (see [Candidate detection](#candidate-detection-for-creation-or-update-or-deletion)).
2129
+
2130
+ #### Option: `--out.format`
2131
+
2132
+ The style of output can be set using option `--out.format` (or `--format`):
1844
2133
 
1845
2134
  | `format` | Output formatting |
1846
2135
  | -------- | -------- |
@@ -1894,7 +2183,7 @@ ascli config echo @json:'[{"name":"foo","id":1},{"name":"bar","id":8}]' --format
1894
2183
 
1895
2184
  This option controls how object fields are displayed for complex objects.
1896
2185
 
1897
- Effective only when `format` is `table` to display `single_object` or `object_list`.
2186
+ Effective only when `format` is `table` or `csv` to display `single_object` or `object_list`.
1898
2187
 
1899
2188
  If value is `no`, then object's `field` names are only the first level keys of the `Hash` result and values that are `Hash` are displayed as such in Ruby syntax.
1900
2189
 
@@ -2076,110 +2365,12 @@ ascli config preset overview --out.colors=no --out.utf8=no
2076
2365
  > [!NOTE]
2077
2366
  > Logs issued before the option is processed (e.g. at startup) use the detected value.
2078
2367
 
2079
- #### Option: `fields`: Selection of output object fields
2080
-
2081
- Depending on the command, results may include by default all fields, or only some selected fields.
2082
- It is possible to define specific columns to be displayed, by setting the `fields` option.
2083
-
2084
- The `fields` option is a list that can be either a comma-separated list or an [Extended Value](#extended-value-syntax) `Array`.
2085
-
2086
- Individual elements of the list can be:
2087
-
2088
- - **property**: add property to the current list
2089
- - `-`**property**: remove property from the current list
2090
- - `DEF`: default list of fields (that is the default, when not set)
2091
- - `ALL`: all fields
2092
- - A Ruby `RegEx`: using `@ruby:'/.../'`, or `@re:...` add those matching to the list
2093
-
2094
- To display a **property** inside a complex structure (`Hash`, `Array`) use [dot-path](#dot-path-notation) notation.
2095
-
2096
- Examples:
2097
-
2098
- - `a,b,c`: the list of attributes specified as a comma-separated list (overrides the default)
2099
- - `@list:,a,b,c`: `Array` [Extended Value](#extended-value-syntax): same as above
2100
- - `@json:'["a","b","c"]'`: `Array` [Extended Value](#extended-value-syntax): same as above
2101
- - `b,DEF,-a`: default property list, remove `a` and add `b` in first position
2102
- - `@ruby:'/^server/'`: Display all fields whose name begins with `server`
2103
-
2104
- #### Option: `select`
2105
-
2106
- Table output (`object_list`) can be filtered using option `select`.
2107
- This option is either a `Hash` or `Proc`.
2108
- The `Proc` takes as argument a line (`Hash`) in the table and is a Ruby lambda expression that shall return `true` to select or `false` to remove an entry.
2109
-
2110
- Example:
2111
-
2112
- ```shell
2113
- ascli aoc admin user list --fields=name,email,ats_admin --query=@json:'{"sort":"name"}' --select=@json:'{"ats_admin":true}'
2114
- ```
2115
-
2116
- ```text
2117
- ╭────────────────┬─────────────────────┬───────────╮
2118
- │ name │ email │ ats_admin │
2119
- ╞════════════════╪═════════════════════╪═══════════╡
2120
- │ John Curtis │ john@example.com │ true │
2121
- │ Laurent Martin │ laurent@example.com │ true │
2122
- ╰────────────────┴─────────────────────┴───────────╯
2123
- ```
2124
-
2125
- > [!NOTE]
2126
- > Option `select` filters elements from the result of command, while the `query` option gives filtering parameters to the API when listing elements.
2127
-
2128
- In the above example, the same result is obtained with option:
2129
-
2130
- ```shell
2131
- --select=@ruby:'->(i){i["ats_admin"]}'
2132
- ```
2133
-
2134
- Option `select` applies the filter after a possible "flattening" with option `--out.flat`.
2135
-
2136
- For comparisons, functions or reshaping of results, use option `--out.query`.
2137
-
2138
- #### Option: `--out.query`
2139
-
2140
- Option `--out.query` applies a [JMESPath](https://jmespath.org) expression to the result of a command, when it is an object or a list.
2141
- JMESPath is a standard query language for JSON, also used by option `--query` of the AWS and Azure CLIs.
2142
-
2143
- The expression is applied to the data as returned by the API, before the options `select` and `fields`, and before flattening with `--out.flat`.
2144
- Its syntax is checked before the command is executed.
2145
- Results of other types (status, no result) are not changed.
2146
-
2147
- Examples:
2148
-
2149
- ```shell
2150
- # Name and email of ATS administrators
2151
- ascli aoc admin user list --out.query='[?ats_admin].{name: name, email: email}'
2152
- # Number of users
2153
- ascli aoc admin user list --out.query='length(@)'
2154
- # Email of users, one per line, for use in a shell loop
2155
- ascli aoc admin user list --out.query='[].email' --format=text
2156
- ```
2157
-
2158
- > [!TIP]
2159
- > Enclose the expression in single quotes for the shell.
2160
- > In JMESPath, literal values are enclosed in backticks, for example: ``[?size > `1000`]``.
2161
-
2162
- For processing that JMESPath does not provide (regular expressions, string manipulation, grouping), the value can be a Ruby lambda (`@ruby:`): it is called with the data, and returns the new data, converted to JSON data (for example, symbols and dates become strings).
2163
- It is refused at [Security Level](#security-level) `medium` and `high`.
2164
-
2165
- ```shell
2166
- # Number of users per email domain
2167
- ascli aoc admin user list --out.query=@ruby:'->(users){users.group_by{|u|u["email"].split("@").last}.transform_values(&:count)}'
2168
- ```
2169
-
2170
- The result of the query is displayed according to its type: a list of objects as a table, a list of values with one value per line, a single value as is.
2171
- A list of lists (for example, `[].[name, email]`) is displayed only with a structured format (`json`, `yaml`, ...): to display a table, or CSV, use a multi-select hash instead, for example, `[].{name: name, email: email}`.
2172
-
2173
- > [!NOTE]
2174
- > Option `--query` gives filtering parameters to the API, while option `--out.query` filters and reshapes the result received.
2175
- > Option `--out.query` is the equivalent of option `--query` of the AWS and Azure CLIs.
2176
-
2177
2368
  ### Exit status
2178
2369
 
2179
2370
  The exit code of `ascli` indicates the category of error, so that scripts can react to it:
2180
2371
 
2181
2372
  | Code | Description |
2182
- |------|----------------------------------------------------------------------------|
2373
+ | ---- | -------------------------------------------------------------------------- |
2183
2374
  | `0` | Success |
2184
2375
  | `1` | Other error |
2185
2376
  | `2` | Command line error: unknown command or option, invalid or missing argument |
@@ -2256,10 +2447,10 @@ The following decoders are supported:
2256
2447
  | `stdin` | `String` | `String` | Read from stdin in text mode. Argument: `<empty>`, `bin` or `chomp`. |
2257
2448
  | `uri` | `String` | `String` | Read value from specified URL. Supported schemes: `http:`, `https:`, `data:`, `file:`. For example, `--fpac=@uri:http://serv/f.pac` or `--key=@uri:file:/path/to/key.pem` |
2258
2449
  | `val` | `String` | `String` | Prevent decoding by the decoders on the right. For example, `--key=@val:@file:foo` sets the option `key` to value `@file:foo`. |
2259
- | `vault` | `String` | `String` | Read a secret from the [Secret Vault](#secret-vault): `<label>.<field>`. For example, `--password=@vault:my_label.password` |
2450
+ | `vault` | `String` | `String` | Read a secret from the [Secret Vault](#secret-vault): `<label>.<field>`, or a [reference](#vault-secret-references) `//<store>/<path>[?<options>][#<field>]`. For example, `--password=@vault:my_label.password` |
2260
2451
  | `yaml` | `String` | Any | Decode YAML. |
2261
2452
  | `zlib` | `String` | `String` | Decompress data using zlib. |
2262
- | `<empty>`| None | Any | The **dot-path** modifier: argument `@:` collects the following positional arguments as `key.subkey=value` assignments and builds a `Hash` or `Array` using [dot-path](#dot-path-notation) notation. Shell-friendly alternative to `@json:` for structured values.<br/>See [Positional Arguments with Dot-path](#positional-arguments-with-dot-path) for full syntax. Use `END` to stop collection when further positional arguments must follow. |
2453
+ | `<empty>`| `String` | Any | The **dot-path** modifier: argument `@:` collects the following positional arguments as `key.subkey=value` assignments and builds a `Hash` or `Array` using [dot-path](#dot-path-notation) notation. Shell-friendly alternative to `@json:` for structured values.<br/>Argument is the end marker: `<empty>` for `END`, or a custom marker (e.g. `@:STOP`). Use the end marker to stop collection when further positional arguments must follow.<br/>See [Positional Arguments with Dot-path](#positional-arguments-with-dot-path) for full syntax. |
2263
2454
 
2264
2455
  > [!NOTE]
2265
2456
  > A few commands support a value of type `Proc` (lambda expression).
@@ -2550,7 +2741,6 @@ Adding `--show-config` to any command line performs a dry run and displays the r
2550
2741
  To display a specific option, add `--fields=<option_name>`.
2551
2742
  Add `--out.flat=no` when the option holds a structured value (`Hash`, `Array`) to display it as-is rather than flattened into dot-path keys:
2552
2743
 
2553
-
2554
2744
  ```shell
2555
2745
  ascli --opt=@json:'{"a":1,"b":"two"}' some_plugin --show-config --fields=opt --out.flat=no
2556
2746
  ascli --opt.a=1 --opt.b=two some_plugin --show-config --fields=opt --out.flat=no
@@ -2588,18 +2778,48 @@ It is a `Hash` with the following keys:
2588
2778
  |-----|-----|-----|-----|
2589
2779
  | `level` | `string` | `low` | `low`, `medium`, or `high` |
2590
2780
  | `allowed_paths` | `Array<string>` | - | With level `medium`: files and folders that `@file:` can read |
2781
+ | `writable_paths` | `Array<string>` | - | With levels `medium` and `high`: folders where files can be written |
2591
2782
 
2592
- | Level | `@file:` | `@ruby:`, `@uri:`, and `@env:` | Secret processed by another extended value |
2593
- |---|---|---|---|
2594
- | `low` | Allowed | Allowed | Allowed |
2595
- | `medium` | Only files in `allowed_paths` | Refused | Refused |
2596
- | `high` | Refused | Refused | Refused |
2783
+ | Level | `@file:` | `@ruby:`, `@uri:`, and `@env:` | Secret processed by another extended value | Write files | Features that execute code |
2784
+ |---|---|---|---|---|---|
2785
+ | `low` | Allowed | Allowed | Allowed | Allowed | Allowed |
2786
+ | `medium` | Only files in `allowed_paths` | Refused | Refused | Only in `writable_paths` | Refused |
2787
+ | `high` | Refused | Refused | Refused | Only in `writable_paths` | Refused |
2597
2788
 
2598
2789
  With level `medium`, the real path of the file is checked: a symbolic link leading outside of `allowed_paths` is refused.
2599
2790
 
2791
+ With levels `medium` and `high`, files are written only in `writable_paths` (none by default): downloaded files (`config download`, and transfers that receive files), because a file written where the client chooses could replace a file that is used later, for example a plugin or a shell startup file.
2792
+ The real path of the folder is checked: neither `..` nor a symbolic link leading outside of `writable_paths` is accepted.
2793
+
2794
+ > [!NOTE]
2795
+ > Reading files is not restricted for transfers: a command that sends files (for example `server upload`) reads the files that it is given, whatever the level.
2796
+ > The security level restricts extended values, not the paths of transfers.
2797
+
2798
+ The same applies to `@file:<path>` in the parameters of stores of option `vault`, and in option `vault_password` (for example, `token`), although the file is read when used, not when the option is evaluated.
2799
+
2600
2800
  A secret (read by `@secret:`, `@vault:`, or `@preset:`) is hidden in results by its value: processed by another extended value, it could be revealed (for example, split by `@list:@vault:...`, or with a short value in a text by `@extend:`).
2601
2801
  With levels `medium` and `high`, a secret must be the whole value of an option or argument, for example `@preset:<PRESET_NAME>.password` for option `password`, and it cannot be a parameter name of `config preset set`.
2602
2802
 
2803
+ Features that execute code (own, or downloaded), load code, or write a file chosen by the client, are available only at level `low`:
2804
+
2805
+ | Feature | Why |
2806
+ |---|---|
2807
+ | Option `notify_template` | ERB template: Ruby code |
2808
+ | Option `fpac` | Proxy auto configuration: JavaScript code |
2809
+ | Option `ui`, key `command` | Command executed to open a URL |
2810
+ | Options `sdk_url` and `locations_url` | The SDK, including `ascp`, is downloaded from this location, then executed |
2811
+ | Option `out`, key `file` (and `output`), option `pid_file` | Write (or truncate, or delete) a file chosen by the client |
2812
+ | Option `home` | Configuration folder: its presets, and its folder `plugins` (Ruby code) are used |
2813
+ | Option `plugin_folder` | Plugins are Ruby code |
2814
+ | Plugins of the folder `plugins` of the configuration folder, and of option `plugin_folder` | Ruby code: not loaded at other levels, also if the file was there before |
2815
+ | Command `config plugins create` | Creates Ruby code, loaded as a plugin |
2816
+ | Command `faspex5 postprocessing` | Executes scripts, or Ruby code |
2817
+
2818
+ At other levels, an option is refused whatever the way it is set (command line, or preset), and a command is not listed by `config commands`.
2819
+ Values from the environment of the process (for example `ASCLI_HOME`) are not restricted: they are set by the one who starts the process, not by a client.
2820
+ A sub-option of an option is restricted in the same way: it is marked `x-security: low` in the schema of the option (for example, `file` of option `out`), and refused when given, by dot notation (`--out.file=...`) or in a `Hash`.
2821
+ A preset is used later, maybe at level `low`: at level `medium` and `high`, `config preset set` refuses such an option, and a value that contains an extended value that the level refuses (for example `@val:@ruby:...`).
2822
+
2603
2823
  Options are evaluated in the order of the command line: place `--security` before options that use extended values.
2604
2824
 
2605
2825
  ```shell
@@ -2607,7 +2827,7 @@ ascli config echo @file:/etc/hosts --security.level=high
2607
2827
  ```
2608
2828
 
2609
2829
  ```text
2610
- ERRR Argument: Evaluation of file for argument: value: @file: extended value is disabled by security level high
2830
+ ERRR Argument: Evaluation of @file: for argument: value: @file: extended value is disabled by security level high: use level medium with the file in security.allowed_paths (option security), or give the value itself
2611
2831
  ```
2612
2832
 
2613
2833
  ### Main, configuration and Persistency Folder
@@ -2740,61 +2960,56 @@ An [Option Preset](#option-preset) is a collection of options and their associat
2740
2960
  A named [Option Preset](#option-preset) can be modified directly using `ascli`, which will update the configuration file:
2741
2961
 
2742
2962
  ```text
2743
- ascli config preset <show|delete|get|unset|set|initialize|update|ask> <PRESET_NAME> ...
2963
+ ascli config preset <show|delete|get|set|ask> <PRESET_NAME> ...
2744
2964
  ```
2745
2965
 
2746
2966
  The syntax of all `config preset` commands, including `list` and `overview`, is displayed with `ascli config commands config preset`.
2747
2967
 
2748
- The command `initialize` allows setting several options at once, but it deletes an existing configuration instead of updating it, and expects a `Hash` [Extended Value](#extended-value-syntax).
2968
+ The command `set` merges values into the configuration, at one of three levels, depending on its arguments:
2749
2969
 
2750
- ```shell
2751
- ascli config preset initialize demo_server @json:'{"url":"ssh://demo.asperasoft.com:33001","username":"asperaweb","password":"<PASSWORD>","ts":{"precalculate_job_size":true}}'
2752
- ```
2970
+ | Arguments | Merged into | Example |
2971
+ | --------- | ----------- | ------- |
2972
+ | `<Hash>` | Presets, by name | `ascli config preset set @: demo_server.url=ssh://demo.asperasoft.com:33001 default.server=demo_server` |
2973
+ | `<preset_name> <Hash>` | Parameters of a preset | `ascli config preset set demo_server @: url=ssh://demo.asperasoft.com:33001 username=asperaweb` |
2974
+ | `<preset_name> <parameter_name> <value>` | One parameter of a preset | `ascli config preset set demo_server password <PASSWORD>` |
2753
2975
 
2754
- One can also use [positional arguments with dot-path](#positional-arguments-with-dot-path):
2976
+ The `Hash` is usually given with [dot-path](#positional-arguments-with-dot-path) (`@:`), or with `@json:`.
2977
+ Parameters have the names of options, without `--`, for example:
2755
2978
 
2756
2979
  ```shell
2757
- ascli config preset initialize demo_server @: url=ssh://demo.asperasoft.com:33001 username=asperaweb password=<PASSWORD> ts.precalculate_job_size=true
2980
+ ascli config preset set demo_server @: url=ssh://demo.asperasoft.com:33001 username=asperaweb password=<PASSWORD> ts.precalculate_job_size=true
2981
+ ascli config preset set demo_server @json:'{"url":"ssh://demo.asperasoft.com:33001","username":"asperaweb","password":"<PASSWORD>","ts":{"precalculate_job_size":true}}'
2758
2982
  ```
2759
2983
 
2760
- The command `update` creates an [Option Preset](#option-preset) from options provided on the command line, for example:
2984
+ A preset is created if needed.
2985
+ Values are **deep-merged** (as JSON Merge Patch, RFC 7396): parameters not given are kept, also in a nested `Hash`: for example, `@: out.level=data` keeps `out.format`.
2761
2986
 
2762
- ```shell
2763
- ascli config preset update demo_server --url=ssh://demo.asperasoft.com:33001 --username=asperaweb --password=<PASSWORD> --ts=@json:'{"precalculate_job_size":true}'
2764
- ```
2765
-
2766
- This creates an [Option Preset](#option-preset) `demo_server` with all provided options.
2767
-
2768
- > [!NOTE]
2769
- > `update` takes **ALL** options provided on the command line (starting with `--` with a value).
2770
-
2771
- The command `set` allows setting individual options in an [Option Preset](#option-preset):
2772
-
2773
- ```text
2774
- ascli config preset set <PRESET_NAME> <PARAMETER_NAME> <PARAMETER_VALUE>
2775
- ```
2776
-
2777
- Example:
2987
+ The value `@none:` (`null` in JSON) **removes** a key: a parameter, a key in a nested `Hash`, or a whole preset (with its default declarations):
2778
2988
 
2779
2989
  ```shell
2780
- ascli config preset set demo_server password <PASSWORD>
2990
+ ascli config preset set GLOBAL out.table.pivot @none:
2991
+ ascli config preset set demo_server @: username=@none: ts.precalculate_job_size=@none:
2992
+ ascli config preset set @: demo_server=@none:
2781
2993
  ```
2782
2994
 
2783
- The parameter name supports **dot-notation** to set nested hash options.
2784
- If an intermediate hash already exists, the new value is **deep-merged** into it (existing sibling keys are preserved).
2995
+ The parameter name of the third form supports **dot-notation** to set nested hash options:
2785
2996
 
2786
2997
  ```shell
2787
2998
  ascli config preset set GLOBAL out.table.pivot single
2788
2999
  ascli config preset set GLOBAL out.level data
2789
3000
  ```
2790
3001
 
2791
- The parameter value is **automatically coerced** to its natural type: integers, floats and booleans (`true`/`yes`/`false`/`no`) are stored as native YAML types rather than strings.
3002
+ Values given on the command line (with `@:`, or the value of the third form) are **automatically coerced** to their natural type: integers, floats and booleans (`true`/`yes`/`false`/`no`) are stored as native YAML types rather than strings.
2792
3003
 
2793
- To **delete** a key from a preset, pass `@none:` as the value (evaluates to `nil`):
3004
+ Options of the command line are not saved in the preset: they apply to the command `set` itself (for example `--log-level`).
3005
+ The section `config` of the configuration file cannot be changed.
2794
3006
 
2795
- ```shell
2796
- ascli config preset set GLOBAL out.table.pivot @none:
2797
- ```
3007
+ > [!NOTE]
3008
+ > Commands `update`, `initialize` and `unset` are deprecated, and show the command to use instead:
3009
+ >
3010
+ > - `update <preset_name> --url=...` is replaced by `set <preset_name> @: url=...`. It takes only the options placed after `update`.
3011
+ > - `initialize <preset_name> <Hash>`, which replaces a preset, is replaced by `delete <preset_name>`, then `set <preset_name> <Hash>`.
3012
+ > - `unset <preset_name> <parameter_name>` is replaced by `set <preset_name> <parameter_name> @none:`.
2798
3013
 
2799
3014
  A full terminal based overview of the configuration can be displayed using:
2800
3015
 
@@ -2822,6 +3037,10 @@ demo_server:
2822
3037
  > [!NOTE]
2823
3038
  > Comment keys are preserved and visible in `config preset overview` for inspection, but are never injected as CLI options.
2824
3039
 
3040
+ By convention, `_comment` holds a short description of the preset.
3041
+ The [shell completion](#shell-completion) of preset names (e.g. `-P <tab>`) shows it next to each name.
3042
+ The wizard sets it for the presets it creates: `_comment: "wizard: <application>"`.
3043
+
2825
3044
  A good practice is to not manually edit the configuration file and use modification commands instead.
2826
3045
  If necessary, the configuration file can be opened in a text editor with:
2827
3046
 
@@ -2894,10 +3113,10 @@ Some temporary files may be needed during runtime, for example the file list of
2894
3113
  The composite option `temp` (use `--temp=help` to display this schema) controls them:
2895
3114
 
2896
3115
  | Field | Type | Description |
2897
- |--------|----------------------|----------------------------------------------------------------------------------|
3116
+ | ------ | -------------------- | -------------------------------------------------------------------------------- |
2898
3117
  | `clean` | `Bool` | Delete temporary files created by the command when it ends. `false` keeps them, e.g. for debugging. Files left by previous commands are still deleted according to `expiry`.<br/>Default: `true`. |
2899
3118
  | `expiry` | `String, Number, Bool` | Age after which file lists of `ascp` left by previous commands (e.g. interrupted) are deleted, when a command starts. They are in folder `filelists` of the main folder (option `home`). A duration, e.g. `5d`, `12h`, `1w`, `1h 30m`, `1d 02:00:00`, a plain number is seconds. `false` or `null` (`@none:`): never delete them. `0`: delete all of them, including file lists of transfers in progress in other executions of ascli. Such a transfer fails if `ascp` reads its file list again: next session of a multi-session transfer, or resume after an error. Use `0` only when no other transfer is in progress, not in a permanent configuration.<br/>Default: `5d`. |
2900
- | `folder` | `String` | Folder for temporary files, e.g. certificate for WSS transfers, logs of `transferd`. `@sys`: temporary folder of the system for the current user (Ruby `Etc.systmpdir`). `@env`: from environment variables, e.g. `TMPDIR` (Ruby `Dir.tmpdir`).<br/>Default: `@sys`. |
3119
+ | `folder` | `String` | Folder for temporary files, e.g. certificate for WSS transfers, logs of `transferd`.<br/>- `@sys`: temporary folder of the system for the current user (Ruby `Etc.systmpdir`).<br/>- `@env`: from environment variables, e.g. `TMPDIR` (Ruby `Dir.tmpdir`).<br/>Default: `@sys`. |
2901
3120
 
2902
3121
  A plain value is the `folder`, for example: `--temp=/data/tmp`.
2903
3122
 
@@ -2918,7 +3137,7 @@ Plugin `config` provides general commands for `ascli`:
2918
3137
  - `wizard`
2919
3138
  - `vault`
2920
3139
  - `ascp`
2921
- - `transferd`
3140
+ - `transferd` (deprecated, use plugin [`transferd`](#plugin-transferd-transfer-daemon))
2922
3141
 
2923
3142
  The default preset for `config` is read for any plugin invocation: this allows setting global options, such as `--log-level` or `--interactive`.
2924
3143
  When `ascli` starts, it looks for the `default` Option Preset and checks the value for `config`.
@@ -2960,6 +3179,9 @@ ascli config preset set GLOBAL version_check_days 0
2960
3179
  > Add `ascli config` in front of the following commands:
2961
3180
 
2962
3181
  ```shell
3182
+ agents jobs cleanup
3183
+ agents jobs list
3184
+ agents jobs status <CONF_ASYNC_NODE_UPLOAD>
2963
3185
  agents list
2964
3186
  agents parameters connect
2965
3187
  agents parameters direct
@@ -2968,9 +3190,6 @@ agents show connect
2968
3190
  agents show direct
2969
3191
  ascp errors
2970
3192
  ascp info --sdk-folder=sdk_test_dir
2971
- ascp install
2972
- ascp install --sdk-folder=sdk_test_dir
2973
- ascp install 1.1.3
2974
3193
  ascp products list
2975
3194
  ascp schema --format=jsonpp
2976
3195
  ascp show
@@ -2985,15 +3204,15 @@ commands
2985
3204
  commands aoc --expand-mounts=yes
2986
3205
  commands aoc files
2987
3206
  commands server
2988
- detect app.example.com
2989
- detect https://f5.example.com/path
2990
- detect https://f5.example.com/path faspex5
2991
- detect https://node.example.com/path
2992
- detect https://server.example.com/path
2993
- detect https://shares.example.com/path shares
2994
- detect https://tst.example.com/path faspio
2995
- detect https://tst.example.com/path httpgw
2996
- detect my_org aoc
3207
+ detect @: url=app.example.com
3208
+ detect @: url=https://f5.example.com/path
3209
+ detect @: url=https://f5.example.com/path plugin=faspex5
3210
+ detect @: url=https://node.example.com/path
3211
+ detect @: url=https://server1.example.com/path
3212
+ detect @: url=https://shares.example.com/path plugin=shares
3213
+ detect @: url=https://tst.example.com/path plugin=faspio
3214
+ detect @: url=https://tst.example.com/path plugin=httpgw
3215
+ detect @: url=my_org plugin=aoc
2997
3216
  doc
2998
3217
  doc github transfer-parameters
2999
3218
  doc local quick-start --ui=text
@@ -3041,18 +3260,19 @@ options server --select=@json:'{"option":"--display"}' --fields=replacement
3041
3260
  plugins create my_command .
3042
3261
  plugins list
3043
3262
  preset delete conf_name
3044
- preset initialize conf_name @json:'{"p1":"v1","p2":"v2"}'
3045
3263
  preset list
3046
3264
  preset overview
3265
+ preset set @: conf_name.p4=v4 conf_name_other.p1=v1
3266
+ preset set @: conf_name_other=@none:
3047
3267
  preset set GLOBAL sdk_folder 'product:IBM Aspera Connect'
3048
- preset set GLOBAL vault @: type=file name=/secure/vault_file
3268
+ preset set GLOBAL vault @: default=local stores.local.type=file stores.local.file=/secure/vault_file
3049
3269
  preset set GLOBAL vault_password <PASSWORD>
3050
3270
  preset set GLOBAL version_check_days 0
3271
+ preset set conf_name @: p1=@none: p2.sub=v2 p3=v3
3272
+ preset set conf_name param @none:
3051
3273
  preset set conf_name param value
3052
3274
  preset set default shares conf_name
3053
3275
  preset show conf_name
3054
- preset unset conf_name param
3055
- preset update conf_name --p1=v1 --p2=v2
3056
3276
  proxy_check --fpac=@file:proxy.pac https://eudemo.asperademo.com --proxy-credentials=@list:,user,pass
3057
3277
  pubkey @file:my_key
3058
3278
  remote_certificate chain https://node.example.com/path
@@ -3062,28 +3282,27 @@ smtp_settings
3062
3282
  sync spec
3063
3283
  tokens flush
3064
3284
  tokens list
3065
- transfer cleanup
3066
- transfer list
3067
- transfer status <conf_async_node_upload>
3068
- transferd install
3069
- transferd list
3285
+ vault check @vault://local/my_label
3070
3286
  vault create @: label=my_label password=<PASSWORD> 'description=my secret'
3071
3287
  vault delete foo --vault.type=system
3072
3288
  vault delete my_label
3289
+ vault field my_label
3073
3290
  vault ids
3074
3291
  vault info
3075
3292
  vault list
3293
+ vault overview
3076
3294
  vault show my_label
3077
- wizard https://console.example.com/path console
3078
- wizard https://f5.example.com/path faspex5 --key-path=my_private_key
3079
- wizard https://node.example.com/path node --username=test --password=<PASSWORD>
3080
- wizard https://orch.example.com/path orchestrator --username=test --password=<PASSWORD>
3081
- wizard https://server.example.com/path server --username=my_username --password=<PASSWORD>
3082
- wizard https://shares.example.com/path shares --username=test --password=<PASSWORD>
3083
- wizard https://tst.example.com/path faspio --override=yes --username=my_username --password=<PASSWORD>
3084
- wizard https://tst.example.com/path httpgw
3085
- wizard my_org aoc --key-path=my_private_key --username=my_user_email --use-generic-client=yes
3086
- wizard my_org aoc mypreset --key-path=my_private_key --username=my_user_email
3295
+ wizard @: url=https://console.example.com/path plugin=console override=yes --username=my_username --password=<PASSWORD>
3296
+ wizard @: url=https://f5.example.com/path plugin=faspex5 override=yes --username=my_username --private-key=@file:<PRIVATE_KEY_FILE> --client-id=<CLIENT_ID> --client-secret=<CLIENT_SECRET>
3297
+ wizard @: url=https://node.example.com/path plugin=node --username=test --password=<PASSWORD>
3298
+ wizard @: url=https://orch.example.com/path plugin=orchestrator --username=test --password=<PASSWORD>
3299
+ wizard @: url=https://server1.example.com/path plugin=server --username=my_username --password=<PASSWORD>
3300
+ wizard @: url=https://shares.example.com/path plugin=shares --username=test --password=<PASSWORD>
3301
+ wizard @: url=https://tst.example.com/path plugin=faspio override=yes --username=my_username --password=<PASSWORD>
3302
+ wizard @: url=https://tst.example.com/path plugin=httpgw
3303
+ wizard @: url=my_org plugin=aoc --username=my_user_email --private-key=@file:<PRIVATE_KEY_FILE> --use-generic-client=yes
3304
+ wizard @: url=my_org plugin=aoc override=yes --username=my_user_email --private-key=@file:<PRIVATE_KEY_FILE> --use-generic-client=no --interactive=yes
3305
+ wizard @: url=my_org plugin=aoc preset=my_preset --username=my_user_email --private-key=@file:<PRIVATE_KEY_FILE>
3087
3306
  ```
3088
3307
 
3089
3308
  #### Evaluation order of options
@@ -3117,10 +3336,10 @@ ascli config preset set cli_default interactive no
3117
3336
  ascli config preset set default config cli_default
3118
3337
  ```
3119
3338
 
3120
- An [Option Preset](#option-preset) value can be removed with `unset`:
3339
+ An [Option Preset](#option-preset) value can be removed with `@none:`:
3121
3340
 
3122
3341
  ```shell
3123
- ascli config preset unset cli_default interactive
3342
+ ascli config preset set cli_default interactive @none:
3124
3343
  ```
3125
3344
 
3126
3345
  Example: Define options using command line:
@@ -3140,6 +3359,9 @@ ascli -N --preset=@json:'{"url":"<URL>","password":"<PASSWORD>","username":"<USE
3140
3359
  `ascli` supports shell tab-completion for **Bash**, **Zsh**, **Fish**, and **PowerShell** (Windows PowerShell 5.1 and PowerShell 7, on any OS).
3141
3360
  The command `ascli config completion <shell>` displays the completion script for the given shell.
3142
3361
 
3362
+ The default shell is Zsh on macOS, Bash on most Linux distributions, and PowerShell on Windows (its prompt starts with `PS`).
3363
+ In Bash and Zsh, `echo $0` displays the name of the running shell.
3364
+
3143
3365
  To activate completion, add the line for your shell to its startup file:
3144
3366
 
3145
3367
  ```bash
@@ -3185,26 +3407,40 @@ In PowerShell, the words proposed are kept for the session, so only the first `T
3185
3407
 
3186
3408
  Once active, press `Tab` to complete:
3187
3409
 
3188
-
3189
3410
  ```bash
3190
3411
  ascli <Tab> # plugins and global options: aoc, server, node, ..., --format, ...
3191
3412
  ascli server <Tab> # sub-commands and options of plugin: upload, download, ls, ..., --url, ...
3192
3413
  ascli aoc admin <Tab> # sub-commands at any depth: user, node, ...
3193
3414
  ascli server ls --u<Tab> # options, after any command: --url, --username, ...
3194
3415
  ascli --format=<Tab> # values of option: --format=json, --format=table, ...
3195
- ascli --ts.<Tab> # keys of option, from its schema: --ts.direction, --ts.target_rate_kbps, ...
3416
+ ascli --ts.<Tab> # keys of option, from its schema: --ts.direction=, --ts.target_rate_kbps=, ...
3417
+ ascli --out.t<Tab> # a sub-structure is followed by a dot: --out.table.
3196
3418
  ascli --ts.direction=<Tab> # values of key: --ts.direction=send, --ts.direction=receive
3419
+ ascli --transfer=<Tab> # plain value of option, key agent: --transfer=direct, --transfer=node, ...
3420
+ ascli faspex5 admin accounts list --query.<Tab> # keys of --query, from the command: --query.limit=, ...
3197
3421
  ascli server upload <Tab> # local files
3198
- ascli config preset show <Tab> # type of expected value, not inserted: <identifier>
3422
+ ascli server download --to-folder <Tab> # local folders
3423
+ ascli config genkey <Tab> # local files, where a local path is expected
3424
+ ascli --temp.folder=<Tab> # local folders, for a key of option
3425
+ ascli --ts=@<Tab> # extended value modifiers: @json:, @file:, @preset:, @:, ...
3426
+ ascli --private-key=@file:<Tab> # local files, after @file: or @path:
3427
+ ascli -P <Tab> # presets: also for config preset show, @preset:
3428
+ ascli config preset get myconf <Tab> # parameters of preset: url, username, ...
3429
+ ascli config agents jobs status <Tab> # asynchronous transfer jobs
3430
+ ascli node access_keys do <Tab> # type of expected value, not inserted: <identifier>
3199
3431
  ascli aoc packages send <Tab> # type, and keys of structure (required ones with *): <Hash> name*, workspace_id*, ...
3200
- ascli aoc packages send @: name=x <Tab> # end marker of structure built with @: END
3432
+ ascli aoc packages send @: <Tab> # keys of structure built with @:, from its schema: name=, workspace_id=, recipients.0., ...
3433
+ ascli aoc packages send @: archived=<Tab> # values of key: archived=true, archived=false
3434
+ ascli aoc packages send @: name=x <Tab> # end marker of structure built with @: END, and the other keys
3201
3435
  ```
3202
3436
 
3203
- Zsh, Fish and PowerShell also display the description of commands and options.
3437
+ No space is inserted after a word that continues: `key=`, `key.`, `@file:`, or a folder (Bash 4 and later).
3438
+ Zsh, Fish and PowerShell also display the description of commands, options, keys and extended value modifiers.
3439
+ In PowerShell, a word starting with `@` is inserted with quotes (e.g. `'@file:README.md'`), as required by PowerShell.
3204
3440
  Zsh lists options once `-` is typed (zsh style `prefix-needed`).
3205
3441
  The type of an expected value is displayed by Bash and Zsh, and by PowerShell in the list of `MenuComplete` (`Ctrl+Space`).
3206
3442
 
3207
- The scripts call `ascli config completion candidates -- [<word>...] <current word>`, which lists the candidates for the word at the cursor, with their description, followed by a directive for the shell.
3443
+ The scripts call `ascli config completion candidates -- [<word>...] <current word>`, which lists the candidates for the word at the cursor, with their description, followed by a directive for the shell: `:files` or `:folders` (local paths, followed by the beginning of the word that is not part of the path, if any, e.g. `:files --private-key=@file:`), `:hint <text>` or `:`.
3208
3444
  The words are not evaluated (e.g. `@env:` is not replaced).
3209
3445
  The command `ascli config completion words [<word>...]` lists the words that can follow the given ones.
3210
3446
  It can be used directly to inspect available commands:
@@ -3217,32 +3453,36 @@ ascli config completion words aoc admin
3217
3453
 
3218
3454
  The wizard is a command that asks the user for information and creates an [Option Preset](#option-preset) with the provided information for a given application.
3219
3455
 
3220
- It takes three optional arguments:
3456
+ It takes one optional argument: a `Hash`, usually given with [`@:`](#positional-arguments-with-dot-path) as `key=value` items, in any order:
3221
3457
 
3222
- |#| Parameter description | If not provided, `ascli` |
3223
- |-|--------------------------------------------|--------------------------------------------|
3224
- |1| **URL** or hostname of the application | ask for it. |
3225
- |2| The **plugin name** to limit search to | tries to detect known plugins from the URL |
3226
- |3| The **preset name** to save in config file | generates a unique preset name |
3458
+ | Key | Description | If not provided, `ascli` |
3459
+ |------------|---------------------------------------------------------------------------------|--------------------------------------------|
3460
+ | `url` | **URL** or hostname of the application | asks for it. |
3461
+ | `plugin` | The **plugin name** to limit search to | tries to detect known plugins from the URL |
3462
+ | `preset` | The **preset name** to save in config file | generates a unique preset name |
3463
+ | `default` | Set the preset as default configuration for the plugin (`yes`/`no`) | `yes` |
3464
+ | `override` | Override the existing default preset of the plugin, if it exists (`yes`/`no`) | `no` |
3227
3465
 
3228
- Options are also available for the wizard:
3466
+ Options of the plugin (for example `--username`, `--password`, `--client-id`, `--private-key`), see the plugin, are given as usual on the command line: they are added to the [Option Preset](#option-preset) created by the wizard.
3467
+ Options that the wizard needs, but that are not provided, are asked.
3468
+ An unknown key in the `Hash` is refused.
3229
3469
 
3230
- | Option | Value | Description |
3231
- |-------------|----------|---------------------------------------------------------------------|
3232
- | `default` | [yes]/no | Set as default configuration for specified plugin. |
3233
- | `override` | yes/[no] | Override existing default preset name for the plugin, if it exists. |
3234
- | `key_path` | path | Path to private key for JWT. |
3470
+ For example:
3471
+
3472
+ ```shell
3473
+ ascli config wizard @: url=<URL> plugin=<PLUGIN> preset=<PRESET>
3474
+ ```
3235
3475
 
3236
- Other plugin-specific options can be provided to the wizard, such as `--username`.
3237
- They are added to the [Option Preset](#option-preset) created by the wizard.
3476
+ The command `config detect` takes the same argument, with keys `url` and `plugin`, and shows the detected applications, without creating a preset.
3477
+ Use `ascli config wizard help` to show the schema of the argument.
3238
3478
 
3239
- The simplest invocation is:
3479
+ The simplest invocation (without argument: the URL is asked) is:
3240
3480
 
3241
3481
  ```shell
3242
3482
  ascli config wizard
3243
3483
  ```
3244
3484
 
3245
- If the application requires a private key, the user can provide the path to it with option `key_path`, or let the wizard generate one.
3485
+ If the application requires a private key, the user can provide it with option `--private-key` (the key, e.g. `@file:<path>`, not only its path), or let the wizard generate one.
3246
3486
  The user is told where to place the associated public key PEM in the application.
3247
3487
 
3248
3488
  #### Example of configuration for a plugin
@@ -3268,13 +3508,13 @@ ascli config preset set shares06 password <PASSWORD>
3268
3508
  This can also be done with one single command:
3269
3509
 
3270
3510
  ```shell
3271
- ascli config preset initialize shares06 @json:'{"url":"https://10.25.0.6","username":"john","password":"<PASSWORD>"}'
3511
+ ascli config preset set shares06 @json:'{"url":"https://10.25.0.6","username":"john","password":"<PASSWORD>"}'
3272
3512
  ```
3273
3513
 
3274
3514
  Or:
3275
3515
 
3276
3516
  ```shell
3277
- ascli config preset update shares06 --url=https://10.25.0.6 --username=john --password=<PASSWORD>
3517
+ ascli config preset set shares06 @: url=https://10.25.0.6 username=john password=<PASSWORD>
3278
3518
  ```
3279
3519
 
3280
3520
  - Define this [Option Preset](#option-preset) as the default [Option Preset](#option-preset) for the specified plugin (`shares`)
@@ -3326,7 +3566,71 @@ export ASCLI_PASSWORD
3326
3566
 
3327
3567
  Another possibility is to retrieve values from a secret vault.
3328
3568
 
3329
- The vault is configured with option `vault` (a `Hash` describing the vault type and parameters, see sections below) and unlocked with option `vault_password`.
3569
+ Option `vault` declares named secret stores (`stores`), and the name of the default store (`default`):
3570
+
3571
+ - `@vault:<label>.<field>` reads field `<field>` of secret `<label>` of the default store, managed with command `config vault` (see [Vault: Operations](#vault-operations)).
3572
+ - `@vault://<store>/<path>[?<options>][#<field>]` reads a secret of any store (see [Vault: Secret references](#vault-secret-references)).
3573
+
3574
+ | Field | Type | Description |
3575
+ | --------- | ------ | -------------------------------------------------------------------------------- |
3576
+ | `cache_ttl` | `Number` | Time in seconds a value read by reference is kept in memory, `0` for no cache.<br/>Default: `60`. |
3577
+ | `default` | `String` | Name of the default store, in `stores`: read by `@vault:<label>.<field>`, managed by `config vault`, unlocked with option `vault_password`. No default store if not set. |
3578
+ | `stores` | `Hash` | Name of store (letters, digits, `_`, `.`, `-`) → parameters of store, with `type`. Secrets are read by reference with `@vault://<store>/<path>[?<options>][#<field>]` from any store.<br/>Required. |
3579
+
3580
+ For example, to use as default store an encrypted file `vault.bin` in the configuration folder (see [Vault: Encrypted file](#vault-encrypted-file)):
3581
+
3582
+ ```shell
3583
+ ascli config preset set GLOBAL vault @json:'{"default":"local","stores":{"local":{"type":"file","file":"vault.bin"}}}'
3584
+ ```
3585
+
3586
+ Parameters of a store, with `type` (see sections below):
3587
+
3588
+ | Field | Type | Description |
3589
+ | ----------------- | ------------- | -------------------------------------------------------------------------------- |
3590
+ | **type** | `String` | `vault`: IBM HashiCorp Vault secret store. Labels of `config vault` and `@vault:<label>.<field>` are in mount `secret` (KV v2). Reference `@vault://<store>/<mount>/<path>#<field>` (field required) in any KV v2 mount, options `version=<n>`, `mount=<mount>` (when the mount contains `/`). |
3591
+ | `allowed_prefixes` | `Array[String]` | Allowed prefixes of `<mount>/<path>` of references: a prefix ending with `/` is a folder, else a path or a folder. All paths are allowed if not set. |
3592
+ | `approle` | `Hash` | AppRole authentication: the token is obtained by login, renewed, and obtained again when refused. |
3593
+ | `approle.mount` | `String` | Mount path of the AppRole auth method.<br/>Default: `approle`. |
3594
+ | `approle.role_id` | `String` | Role ID.<br/>Required. |
3595
+ | `approle.secret_id` | `String` | Secret ID (if the role requires one): the value, or `@file:<path>`. |
3596
+ | `ca_file` | `String` | File with the CA certificates that verify the certificate of the server (HTTPS). |
3597
+ | `namespace` | `String` | Namespace (Vault Enterprise). |
3598
+ | `token` | `String` | The authentication token. Its value, or `@file:<path>` (e.g. written and renewed by Vault Agent), read again when modified. One of `token` or `approle` is required. For the default store, defaults to the value of `vault_password`, unless `approle` is set.<br/>Example: `<TOKEN>`. |
3599
+ | `type` | `Enum[String]` | Vault type selector.<br/>Required.<br/>Allowed values: `vault`. |
3600
+ | `url` | `String` | URL of the HashiCorp Vault server.<br/>Required.<br/>Example: `http://127.0.0.1:8200`. |
3601
+ | **type** | `String` | `system`: macOS system keychain secret store. |
3602
+ | `name` | `String` | Name of the keychain to use (file `<name>.keychain-db` in the keychain search list).<br/>Default: `ascli`. |
3603
+ | `type` | `Enum[String]` | Vault type selector.<br/>Required.<br/>Allowed values: `system`. |
3604
+ | **type** | `String` | `secret_service`: Linux Secret Service secret store (GNOME Keyring, KWallet, KeePassXC...), using `secret-tool`. |
3605
+ | `name` | `String` | Name of the group of secrets (attribute `service` of the items).<br/>Default: `ascli`. |
3606
+ | `type` | `Enum[String]` | Vault type selector.<br/>Required.<br/>Allowed values: `secret_service`. |
3607
+ | **type** | `String` | `file`: Encrypted file secret store. Reference `@vault://<store>/<label>[#<field>]`, field `password` by default. |
3608
+ | `file` | `String` | Path to the encrypted vault file, created when the first secret is added. Relative paths are resolved from the configuration folder. Read when used, and again when modified.<br/>Default: `vault.bin`. |
3609
+ | `name` | `String` | Same as `file` (compatibility). |
3610
+ | `password` | `String` | Password of the vault file: the value, or `@file:<path>`, read again when modified. For the default store, defaults to the value of `vault_password`. |
3611
+ | `type` | `Enum[String]` | Vault type selector.<br/>Required.<br/>Allowed values: `file`. |
3612
+ | **type** | `String` | `1password`: 1Password secret store (Connect REST API or CLI). |
3613
+ | `account` | `String` | Account shorthand for `op` (used when `source` is `cli`). Uses the default account if omitted. |
3614
+ | `source` | `Enum[String]` | Backend source. Use `api` for the Connect REST API, `cli` for the `op` CLI.<br/>Required.<br/>Allowed values: `api`, `cli`.<br/>Default: `api`. |
3615
+ | `token` | `String` | Bearer token for the Connect API (required when `source` is `api`). For the default store, defaults to the value of `vault_password`. |
3616
+ | `type` | `Enum[String]` | Vault type selector.<br/>Required.<br/>Allowed values: `1password`. |
3617
+ | `url` | `String` | Base URL of the 1Password Connect server (required when `source` is `api`).<br/>Example: `http://localhost:8080`. |
3618
+ | `vault` | `String` | Name or ID of the 1Password vault to use with the CLI (used when `source` is `cli`). Uses the default vault if omitted. |
3619
+ | `vault_id` | `String` | ID of the 1Password vault to use (required when `source` is `api`). |
3620
+ | **type** | `String` | `keeper`: Keeper Secrets Manager secret store (Keeper Vault), using gem `keeper_secrets_manager`. A secret is a record shared with the application: its label is its title or its UID. Reference `@vault://<store>/<title or uid>[#<field>]`, field `password` by default: standard field by type (`login`, `password`, `url`...), custom field by label, or `notes`. |
3621
+ | `config` | `String` | Configuration of the client device (base64 or JSON, e.g. from `ksm profile export`): the value, or `@file:<path>`. For the default store, defaults to the value of `vault_password`. |
3622
+ | `folder_uid` | `String` | UID of the shared folder where `config vault create` adds records (not needed to read). |
3623
+ | `type` | `Enum[String]` | Vault type selector.<br/>Required.<br/>Allowed values: `keeper`. |
3624
+
3625
+ > [!NOTE]
3626
+ > The parameters of one store, without `stores` (for example, `{"type":"file","name":"vault.bin"}`), are deprecated: they define a store named after its type (for example, `file`), which is the default store.
3627
+ > Set the store in `stores`, and its name in `default` instead: `{"default":"local","stores":{"local":{"type":"file","file":"vault.bin"}}}`.
3628
+
3629
+ Secrets used to access a store (`token`, `approle.secret_id`, `password`) are the value, or `@file:<path>` (for example, a credential of `systemd`, or a token written by Vault Agent): the file is read when used, and again when it is modified.
3630
+ As for extended value `@file:`, reading the file is restricted by option `security` (see [Security Level](#security-level)).
3631
+ In a YAML file, quote the value: `@` cannot start a plain scalar.
3632
+
3633
+ The secret of the default store (`password` of type `file`, `token` of type `vault` without `approle`, of type `1password` with `source` `api`, and `config` of type `keeper`), if not in its parameters, is the value of option `vault_password`.
3330
3634
  To avoid exposing the vault password in the shell history, provide it via an environment variable:
3331
3635
 
3332
3636
  ```shell
@@ -3352,29 +3656,20 @@ brew install hashicorp/tap/vault
3352
3656
  vault server -dev -dev-root-token-id=<TOKEN>
3353
3657
  ```
3354
3658
 
3355
- | Field | Type | Description |
3356
- |----------|--------|----------------------------------------------------------------------------------|
3357
- | **type** | `String` | `vault`: IBM HashiCorp Vault secret store. |
3358
- | `token` | `String` | Authentication token. Defaults to the value of `vault_password`.<br/>Example: `dev-only-token`. |
3359
- | `type` | `String` | Vault type selector.<br/>Required.<br/>Allowed values: `vault`. |
3360
- | `url` | `String` | URL of the HashiCorp Vault server.<br/>Required.<br/>Example: `http://127.0.0.1:8200`. |
3361
- | **type** | `String` | `system`: macOS system keychain secret store. |
3362
- | `name` | `String` | Name of the keychain to use (file `<name>.keychain-db` in the keychain search list).<br/>Default: `ascli`. |
3363
- | `type` | `String` | Vault type selector.<br/>Required.<br/>Allowed values: `system`. |
3364
- | **type** | `String` | `file`: Encrypted file secret store. |
3365
- | `name` | `String` | Path to the encrypted vault file. Relative paths are resolved from the configuration folder.<br/>Default: `vault.bin`. |
3366
- | `type` | `String` | Vault type selector.<br/>Required.<br/>Allowed values: `file`. |
3367
- | **type** | `String` | `1password`: 1Password secret store (Connect REST API or CLI). |
3368
- | `account` | `String` | Account shorthand for `op` (used when `source` is `cli`). Uses the default account if omitted. |
3369
- | `source` | `String` | Backend source. Use `api` for the Connect REST API, `cli` for the `op` CLI.<br/>Required.<br/>Allowed values: `api`, `cli`.<br/>Default: `api`. |
3370
- | `token` | `String` | Bearer token for the Connect API (required when `source` is `api`). Defaults to the value of `vault_password`. |
3371
- | `type` | `String` | Vault type selector.<br/>Required.<br/>Allowed values: `1password`. |
3372
- | `url` | `String` | Base URL of the 1Password Connect server (required when `source` is `api`).<br/>Example: `http://localhost:8080`. |
3373
- | `vault_id` | `String` | ID of the 1Password vault to use (required when `source` is `api`). |
3374
- | `vault` | `String` | Name or ID of the 1Password vault to use with the CLI (used when `source` is `cli`). Uses the default vault if omitted. |
3659
+ ```shell
3660
+ --vault=@json:'{"default":"corp","stores":{"corp":{"type":"vault","url":"http://127.0.0.1:8200"}}}' --vault-password=<TOKEN>
3661
+ ```
3662
+
3663
+ With a token in a file (for example, written and renewed by Vault Agent), read again when the file is modified:
3664
+
3665
+ ```shell
3666
+ --vault=@json:'{"default":"corp","stores":{"corp":{"type":"vault","url":"https://vault.example.com:8200","token":"@file:/run/vault/token"}}}'
3667
+ ```
3668
+
3669
+ With AppRole authentication, the token is obtained by login, and renewed:
3375
3670
 
3376
3671
  ```shell
3377
- --vault=@json:'{"type":"vault","url":"http://127.0.0.1:8200"}' --vault-password=<TOKEN>
3672
+ --vault=@json:'{"default":"corp","stores":{"corp":{"type":"vault","url":"https://vault.example.com:8200","approle":{"role_id":"<ROLE_ID>","secret_id":"@file:/etc/vault/secret_id"}}}}'
3378
3673
  ```
3379
3674
 
3380
3675
  #### Vault: System keychain
@@ -3386,28 +3681,42 @@ It is possible to manage secrets in macOS keychain.
3386
3681
  Commands `list`, `ids` and `delete` are not supported: use the **Keychain Access** app.
3387
3682
 
3388
3683
  ```shell
3389
- --vault=@json:'{"type":"system","name":"ascli"}'
3684
+ --vault=@json:'{"default":"keychain","stores":{"keychain":{"type":"system","name":"ascli"}}}'
3685
+ ```
3686
+
3687
+ #### Vault: Linux Secret Service
3688
+
3689
+ > [!WARNING]
3690
+ > **Linux only**
3691
+
3692
+ It is possible to manage secrets in the Linux Secret Service (GNOME Keyring, KWallet, KeePassXC...), using the `secret-tool` command of `libsecret` (for example, package `libsecret-tools` on Debian and Ubuntu).
3693
+ A session with an unlocked keyring is required.
3694
+ Secrets are grouped with attribute `service`, which is parameter `name` (default: `ascli`).
3695
+
3696
+ ```shell
3697
+ --vault=@json:'{"default":"keyring","stores":{"keyring":{"type":"secret_service","name":"ascli"}}}'
3390
3698
  ```
3391
3699
 
3392
3700
  #### Vault: Encrypted file
3393
3701
 
3394
- It is possible to store and use secrets encrypted in a file using option `vault` set to:
3702
+ It is possible to store and use secrets encrypted in a file, with a store of type `file`:
3395
3703
 
3396
3704
  ```json
3397
- {"type":"file","name":"vault.bin"}
3705
+ {"default":"local","stores":{"local":{"type":"file","file":"vault.bin"}}}
3398
3706
  ```
3399
3707
 
3400
- To configure the encrypted file vault as the default, set the `vault` option in the global preset:
3708
+ To configure the encrypted file vault as the default store, set the `vault` option in the global preset:
3401
3709
 
3402
3710
  ```shell
3403
- ascli config preset set GLOBAL vault @: type=file name=vault.bin
3711
+ ascli config preset set GLOBAL vault @json:'{"default":"local","stores":{"local":{"type":"file","file":"vault.bin"}}}'
3404
3712
  ```
3405
3713
 
3406
- The vault file is created automatically on first use - no explicit initialization is needed.
3714
+ The vault file is created automatically when the first secret is added - no explicit initialization is needed.
3715
+ It is read when used, and again when it is modified.
3407
3716
 
3408
3717
  > [!WARNING]
3409
3718
  > The `vault_password` option should **not** be stored in the config file: doing so would protect secrets with a password that is itself stored in plain text, defeating the purpose of the vault.
3410
- > Use an environment variable as described above.
3719
+ > Use an environment variable as described above, or parameter `password` with `@file:<path>` (for example, a credential of `systemd`).
3411
3720
 
3412
3721
  #### Vault: 1Password
3413
3722
 
@@ -3428,7 +3737,7 @@ docker run -d --name op-connect \
3428
3737
  ```
3429
3738
 
3430
3739
  ```shell
3431
- --vault=@json:'{"type":"1password","source":"api","url":"http://localhost:8080","vault_id":"<VAULT_ID>"}' \
3740
+ --vault=@json:'{"default":"op","stores":{"op":{"type":"1password","source":"api","url":"http://localhost:8080","vault_id":"<VAULT_ID>"}}}' \
3432
3741
  --vault-password=<CONNECT_TOKEN>
3433
3742
  ```
3434
3743
 
@@ -3448,9 +3757,9 @@ Requires the `op` CLI to be installed and signed in.
3448
3757
  No server to deploy: authentication is handled by the 1Password desktop app (biometric unlock) or by `op signin`.
3449
3758
 
3450
3759
  ```shell
3451
- --vault=@json:'{"type":"1password","source":"cli"}'
3760
+ --vault=@json:'{"default":"op","stores":{"op":{"type":"1password","source":"cli"}}}'
3452
3761
  # or, to target a specific vault and account:
3453
- --vault=@json:'{"type":"1password","source":"cli","vault":"<VAULT_NAME>","account":"<ACCOUNT_SHORTHAND>"}'
3762
+ --vault=@json:'{"default":"op","stores":{"op":{"type":"1password","source":"cli","vault":"<VAULT_NAME>","account":"<ACCOUNT_SHORTHAND>"}}}'
3454
3763
  ```
3455
3764
 
3456
3765
  > [!TIP]
@@ -3469,18 +3778,57 @@ An item can be referenced by its title (label) or by its 1Password ID, in `@vaul
3469
3778
  > [!NOTE]
3470
3779
  > If several items share the same title, use the item ID (or the `vault` parameter to restrict the search).
3471
3780
 
3781
+ #### Vault: Keeper
3782
+
3783
+ <https://docs.keeper.io/keeperpam/secrets-manager/overview>
3784
+
3785
+ Keeper Secrets Manager (KSM) gives an application access to the records of shared folders of a Keeper vault, without the credentials of a user.
3786
+ It requires the optional gem `keeper_secrets_manager`:
3787
+
3788
+ ```shell
3789
+ gem install keeper_secrets_manager
3790
+ ```
3791
+
3792
+ Create an application and a client device in Keeper (see the [Quick Start Guide](https://docs.keeper.io/keeperpam/secrets-manager/quick-start-guide)), share the folders of secrets with the application, and get the configuration of the device (base64 or JSON, for example with `ksm profile export`).
3793
+ Parameter `config` is the value, or `@file:<path>`:
3794
+
3795
+ ```shell
3796
+ --vault=@json:'{"default":"keeper","stores":{"keeper":{"type":"keeper","config":"@file:<KSM_CONFIG_FILE>"}}}'
3797
+ ```
3798
+
3799
+ If `config` is not set in the default store, it is the value of option `vault_password`.
3800
+
3801
+ A secret is a record of the vault: its label is its title, or its UID.
3802
+ The field of a reference is `password` by default: standard field of the record (`login`, `password`, `url`...), custom field by its label, or `notes`.
3803
+ Field `username` is an alias of `login`.
3804
+
3805
+ ```shell
3806
+ --password=@vault:<RECORD_TITLE>.password
3807
+ --password=@vault://keeper/<RECORD_TITLE>#<FIELD>
3808
+ ```
3809
+
3810
+ To create records with `config vault create` (type `login`), set parameter `folder_uid`: UID of the shared folder where records are added.
3811
+ Reading does not need it.
3812
+
3813
+ > [!NOTE]
3814
+ > If several records share the same title, use the UID.
3815
+ > Deleting a record with `config vault delete` requires that the application has edit permission.
3816
+
3472
3817
  #### Vault: Operations
3473
3818
 
3474
- Secrets can be manipulated using the `config vault` command:
3819
+ Secrets of the default store can be manipulated using the `config vault` command:
3475
3820
 
3476
3821
  - `info` : Show vault information
3477
3822
  - `ids` : List secret labels in the vault
3478
3823
  - `list` : List all secrets with full details
3824
+ - `overview` : List labels of all secrets with their field names, without values
3825
+ - `field` : List field names of a secret by label, without values
3479
3826
  - `show` : Show a secret by label (or id)
3480
3827
  - `create` : Add a new secret to the vault
3481
3828
  - `delete` : Delete a secret by label (or id)
3482
3829
  - `password` : Set a new password for the vault
3483
3830
  - `import` : Import secrets from a JSON array (supports `--bulk`)
3831
+ - `check` : Check that a [Secret Reference](#vault-secret-references) can be read, without its value
3484
3832
 
3485
3833
  To add a new password entry in the vault for label `<NAME>`:
3486
3834
 
@@ -3497,10 +3845,10 @@ To migrate all secrets from one vault backend to another (for example, from the
3497
3845
 
3498
3846
  ```shell
3499
3847
  ascli config vault list --format=json --out.level=data --out.secrets=yes \
3500
- --vault=@json:'{"type":"file","name":"<SOURCE_VAULT_FILE>"}' \
3848
+ --vault=@json:'{"default":"local","stores":{"local":{"type":"file","file":"<SOURCE_VAULT_FILE>"}}}' \
3501
3849
  --vault-password=<SOURCE_PASSWORD> | \
3502
3850
  ascli config vault import @json:@stdin: --bulk=yes \
3503
- --vault=@json:'{"type":"1password","url":"<CONNECT_URL>","vault_id":"<VAULT_ID>"}' \
3851
+ --vault=@json:'{"default":"op","stores":{"op":{"type":"1password","url":"<CONNECT_URL>","vault_id":"<VAULT_ID>"}}}' \
3504
3852
  --vault-password=<CONNECT_TOKEN>
3505
3853
  ```
3506
3854
 
@@ -3512,6 +3860,44 @@ The `import` command accepts a JSON array where each element is a vault secret o
3512
3860
  On error (for example a duplicate label), the default behavior is to stop (`--bfail=yes`).
3513
3861
  Pass `--bfail=no` to skip failures and continue with the remaining entries.
3514
3862
 
3863
+ #### Vault: Secret references
3864
+
3865
+ Secrets can also be read by reference, from any store of option `vault`:
3866
+
3867
+ ```text
3868
+ @vault://<store>/<path>[?<options>][#<field>]
3869
+ ```
3870
+
3871
+ - `<store>`: name of a store in `stores` of option `vault`.
3872
+ - `<path>`: path of the secret in the store, and `<field>`: field of the secret. Both are percent-decoded (for example, `%20` for a space).
3873
+ For most types, the path is the label, and the field is `password` by default.
3874
+ For type `vault`, the path is `<mount>/<path>` in a KV v2 secrets engine, and the field is required.
3875
+ - `<options>`: options of the store, as a URL query (for example, `version=2`).
3876
+
3877
+ References only read secrets: they are managed with the tools of the store (for example, `vault kv put` for HashiCorp Vault), or with `config vault` for the default store.
3878
+ Compared to `@vault:<label>.<field>`, several stores can be used in the same command, and a HashiCorp Vault store reads any KV v2 mount, a given version, and limits the paths that can be read by reference (`allowed_prefixes`).
3879
+ Values read by reference are kept in memory for `cache_ttl` seconds.
3880
+ The configuration of stores is the same as in applications that use the library with references `secret://<store>/<path>` (for example, IBM Aspera Orchestrator).
3881
+
3882
+ For example, a HashiCorp Vault server with AppRole authentication, limited to secrets under `kv/aspera/`, and the encrypted file of `config vault` as default store, unlocked with option `vault_password`:
3883
+
3884
+ ```shell
3885
+ --vault=@json:'{"default":"local","stores":{"corp":{"type":"vault","url":"https://vault.example.com:8200","approle":{"role_id":"<ROLE_ID>","secret_id":"@file:/etc/vault/secret_id"},"allowed_prefixes":["kv/aspera/"]},"local":{"type":"file","file":"vault.bin"}}}'
3886
+ ```
3887
+
3888
+ References in a preset: to field `password` of secret `aspera/faspex` in mount `kv`, and to field `password` (default field of type `file`) of label `<VAULT_LABEL>` in the encrypted file:
3889
+
3890
+ ```shell
3891
+ ascli config preset set <PRESET_NAME> @: url=... username=... password=@val:@vault://corp/kv/aspera/faspex#password
3892
+ ascli config preset set <PRESET_NAME> @: url=... username=... password=@val:@vault://local/<VAULT_LABEL>
3893
+ ```
3894
+
3895
+ To check that a reference can be read, without its value (store, version, time of update):
3896
+
3897
+ ```shell
3898
+ ascli config vault check @vault://corp/kv/aspera/faspex#password
3899
+ ```
3900
+
3515
3901
  #### Configuration Finder
3516
3902
 
3517
3903
  When a secret is needed by a sub command, the command can search for existing configurations in the configuration file by setting option `secret` to the special value `PRESET`.
@@ -3524,13 +3910,13 @@ A password can be saved in clear in an [Option Preset](#option-preset) together
3524
3910
  Example:
3525
3911
 
3526
3912
  ```shell
3527
- ascli config preset update <PRESET_NAME> --url=... --username=... --password=...
3913
+ ascli config preset set <PRESET_NAME> @: url=... username=... password=...
3528
3914
  ```
3529
3915
 
3530
3916
  For more secure storage, first create a vault entry (see [Vault: Operations](#vault-operations)), then refer to it in the preset:
3531
3917
 
3532
3918
  ```shell
3533
- ascli config preset update <PRESET_NAME> --url=... --username=... --password=@val:@vault:<VAULT_LABEL>.password
3919
+ ascli config preset set <PRESET_NAME> @: url=... username=... password=@val:@vault:<VAULT_LABEL>.password
3534
3920
  ```
3535
3921
 
3536
3922
  > [!NOTE]
@@ -3549,7 +3935,7 @@ This scans all presets (or a single one if a name is provided) and, for every op
3549
3935
  ascli config preset secure <PRESET_NAME>
3550
3936
  ```
3551
3937
 
3552
- When a vault is configured, the `update`, `set`, and `ask` preset commands automatically move secret values (options ending with `password` or `secret`) into the vault as they are written, so no manual migration is needed.
3938
+ When a vault is configured, the `set` and `ask` preset commands automatically move secret values (options ending with `password` or `secret`) into the vault as they are written, so no manual migration is needed.
3553
3939
  To disable this behavior for a single command, pass `--vault=@none:`.
3554
3940
 
3555
3941
  ### Private Key
@@ -3565,13 +3951,12 @@ The file containing the private key (key pair) can optionally be protected by a
3565
3951
  If the key is protected by a passphrase, then the passphrase is prompted when the key is used.
3566
3952
  Some plugins support option `passphrase`.
3567
3953
 
3568
- By default, `ascli` does not support `ed25519` type, nor OpenSSH encoded keys.
3569
- See section: [Private key type ed25519](#private-key-type-ed25519-not-supported-by-default).
3570
- It requires PEM encoded keys.
3571
- To support `ed25519` and OpenSSH format (default on modern Linux), install those gems:
3954
+ Keys of type `ed25519` and OpenSSH encoded keys (default on modern Linux) are supported.
3955
+ See section: [Private key type ed25519](#private-key-type-ed25519).
3956
+ For OpenSSH encoded keys protected by a passphrase, install gem `bcrypt_pbkdf` (not available for JRuby):
3572
3957
 
3573
3958
  ```shell
3574
- gem install ed25519 bcrypt_pbkdf
3959
+ gem install bcrypt_pbkdf
3575
3960
  ```
3576
3961
 
3577
3962
  The following sample commands use the shell variable `KEY_PAIR_PATH`.
@@ -3650,9 +4035,35 @@ For example: <https://cryptotools.net/rsagen>
3650
4035
 
3651
4036
  ### Web service
3652
4037
 
3653
- Some plugins start a local web server.
3654
- This server can serve HTTP or HTTPS (with certificate).
4038
+ `ascli` is a command-line tool: it runs in a shell, with the credentials and presets of the user who starts it, and it assumes that only this user uses it.
4039
+ It is not intended to be a public-facing web server.
4040
+ When commands come from another program, for example an MCP client, see [Security Level](#security-level).
4041
+
4042
+ Some commands start a web server, for a specific client:
4043
+
4044
+ | Command | Client | Protection required when `url` is not loopback |
4045
+ |---|---|---|
4046
+ | `mcp server`, `http` transport | MCP client | `auth_token`, see [MCP Security](#security) |
4047
+ | `faspex5 postprocessing` | Faspex 5 web hooks | `secret_token` or `allowed_ips`, see [Faspex 4-style post-processing](#faspex-5-faspex-4-style-post-processing) |
4048
+ | `faspex5 gateway`, `aoc gateway` | Faspex 4 client applications | `username` and `password`, see [Faspex 4 Gateway](#faspex-5-faspex-4-gateway) |
4049
+ | `node emulator` | Node API clients, for tests | `username` and `password`, see [Node emulator](#node-emulator) |
4050
+
4051
+ By default, the server listens on a loopback address: `localhost`, an address of `127.0.0.0/8`, or `::1`.
4052
+ It can be reached only from the same host.
4053
+
4054
+ > [!WARNING]
4055
+ > Loopback restricts the host, not the user: on a host shared with other users, they can also reach the server.
4056
+ > On such a host, also set the protection of the command.
4057
+
4058
+ When the host of `url` is not a loopback address, for example `0.0.0.0` (all interfaces), the server can be reached from the network: the command refuses to start without its protection.
4059
+ On a network, use HTTPS (`https://` in `url`) or a reverse proxy with TLS: with HTTP, passwords and tokens are sent in clear.
3655
4060
 
4061
+ Other features listen on a loopback address only, to receive input from the browser of the user:
4062
+
4063
+ - [Web login flow](#web-login-flow): the result of the login, on `redirect_uri`.
4064
+ - `@secret:`, with option `ui` set to `graphical` (see [Secret Vault](#secret-vault)), or with `mcp server` and the `stdio` transport (see [Secrets entered in a web page](#secrets-entered-in-a-web-page)): the secret entered by the user.
4065
+
4066
+ The server serves HTTP, or HTTPS with a certificate.
3656
4067
  The following parameters are supported:
3657
4068
 
3658
4069
  | Parameter | Type | Default | Description |
@@ -3692,7 +4103,7 @@ This feature can be used:
3692
4103
  The following options can be specified in option `--out.img`:
3693
4104
 
3694
4105
  | Field | Type | Description |
3695
- |------------|---------|----------------------------------------------------------------------------------|
4106
+ | ---------- | ------- | -------------------------------------------------------------------------------- |
3696
4107
  | `double` | `Bool` | Use double vertical resolution via half-block characters (Unicode). Default is `true` if the terminal supports Unicode (see `utf8`). |
3697
4108
  | `font_ratio` | `Number` | Terminal font aspect ratio (height divided by width).<br/>Default: `2.3`. |
3698
4109
  | `reserve` | `Integer` | Number of terminal lines reserved for non-image output.<br/>Default: `3`. |
@@ -3726,28 +4137,189 @@ Some actions may require the use of a graphical tool:
3726
4137
  - A browser to enter a secret requested with `@secret:`
3727
4138
  - A text editor for editing the configuration file
3728
4139
 
3729
- By default, `ascli` assumes that a graphical environment is available on Windows; on other systems, it relies on the presence of the `DISPLAY` environment variable.
3730
- The composite option `ui` (use `--ui=help` to display this schema) selects the mode and the browser command:
4140
+ By default, `ascli` assumes that a graphical environment is available on Windows and macOS; on other systems, it relies on the presence of the `DISPLAY` environment variable.
4141
+ The composite option `ui` (use `--ui=help` to display this schema) selects the mode, the way a web login is received, and the browser command:
3731
4142
 
3732
4143
  | Field | Type | Description |
3733
- |---------|---------------|----------------------------------------------------------------------------------|
3734
- | `command` | `Array[String]` | Command that opens a URL, instead of the system default. First item is the executable, then its arguments. The URL is added as last argument. When set, it is used to open URLs, whatever the `mode`. |
3735
- | `mode` | `String` | `auto`: `browser` on Windows and macOS, or if env var `DISPLAY` is set, else `terminal`. `terminal`: URLs and files to open are displayed on terminal, and secrets are entered on terminal. `browser`: a browser opens URLs, secrets are entered on a web page, and a text editor opens files. `text` is an alias for `terminal`, and `graphical` is an alias for `browser`.<br/>Allowed values: `auto`, `terminal`, `browser`, `text`, `graphical`.<br/>Default: `auto`. |
4144
+ | -------- | ------------- | -------------------------------------------------------------------------------- |
4145
+ | `command` | `Array[String]` | Command that opens a URL, instead of the system default. First item is the executable (full path, or name of an executable found in `PATH`), then its arguments. The URL is added as last argument. When set, it is used to open URLs, whatever the `mode`. |
4146
+ | `mode` | `Enum[String]` | - `auto`: `browser` on Windows and macOS, or if env var `DISPLAY` is set, else `terminal`.<br/>- `terminal`: URLs to open are displayed on terminal, and secrets are entered on terminal.<br/>- `browser`: a browser opens URLs, and secrets are entered on a web page.<br/>`text` is an alias for `terminal`, and `graphical` is an alias for `browser`.<br/>Files to edit are always opened with a text editor, whatever the `mode`.<br/>Allowed values: `auto`, `terminal`, `browser`, `text`, `graphical`.<br/>Default: `auto`. |
4147
+ | `web_auth` | `Enum[String]` | How the result of a web login (`--auth=web`, SSO) is received.<br/>- `port`: `ascli` listens on the loopback port of `redirect_uri`, the browser is redirected to it.<br/>- `paste`: no port is opened. After login, the browser shows a connection error on `redirect_uri`: copy the full URL from the address bar of the browser and paste it in the terminal. Use it when the browser cannot reach the host that runs `ascli` and a SSH tunnel is not possible. For `shares`, Shares displays a code (a long text of letters, digits, `-` and `_`) instead: paste it in the terminal.<br/>Allowed values: `port`, `paste`.<br/>Default: `port`. |
4148
+
4149
+ A plain value is the `mode`:
4150
+
4151
+ - `--ui=browser` (or `graphical`) forces a graphical environment: a browser is opened for URLs or secrets.
4152
+ - `--ui=terminal` (or `text`) forces a text environment: the URL to open is displayed on terminal, and secrets are entered on terminal.
4153
+ - `--ui=auto` selects the mode from the environment (default).
4154
+
4155
+ The browser is opened, by priority, with: `--ui.command`, or the system default.
4156
+ The system default is opened with the following command:
4157
+
4158
+ | OS | Command |
4159
+ |---------|------------------------|
4160
+ | macOS | `open <url>` |
4161
+ | Windows | `start explorer "<url>"` |
4162
+ | Linux | `xdg-open <url>` |
4163
+
4164
+ To edit a file (for example `config open`), whatever the `mode`, the editor is, by priority: the command in the environment variable `EDITOR`, else `notepad.exe` on Windows, else the system default above (or `--ui.command` if defined).
4165
+
4166
+ When a command is defined, it is used to open URLs whatever the `mode`.
4167
+ The command is an array: the URL is appended as last argument.
4168
+ The executable is either a full path, or the name of an executable found in the `PATH`.
4169
+ For example, to use Firefox:
4170
+
4171
+ ```bash
4172
+ ascli config echo @secret: --ui=browser --ui.command=@json:'["firefox","--private-window"]'
4173
+ ```
4174
+
4175
+ ### Web login flow
4176
+
4177
+ Authentication methods that need a user login in a browser (`--auth=web`, including for Shares) all work the same way: `ascli` listens on a local port, the browser is redirected to it after login.
4178
+
4179
+ ![Web login flow: `ascli` listens on a loopback port and receives the result of the login from the browser](login-flow.svg)
4180
+
4181
+ 1. `ascli` generates a random `state` and starts a local HTTP server on the loopback address of `redirect_uri` (default: `http://localhost:12345`).
4182
+ 2. `ascli` opens the login URL in the browser (see [Graphical Interactions](#graphical-interactions-browser-and-text-editor)): the authorization endpoint with `redirect_uri` and `state` for `web`, or, for Shares, the SAML login page with `RelayState`.
4183
+ If no graphical environment is available, the URL is displayed, to be opened on any browser of the same host.
4184
+ 3. The user logs in on the server, possibly redirected to an identity provider.
4185
+ 4. The server redirects the browser to `redirect_uri`, with the OAuth code (`web`), or, for Shares, the tokens, and the `state`.
4186
+ 5. The browser sends this request to `ascli`, which checks that `state` is the one it generated, and stops listening.
4187
+ 6. `ascli` requests the token to the server: exchange of the code (`web`) or, for Shares, of the refresh token, and saves it in the cache.
4188
+ For Faspex 5, the code is protected with PKCE: `ascli` sends a challenge with the login URL, and the matching verifier with the code.
4189
+ Next calls use the cached token, renewed if needed without a browser.
4190
+
4191
+ The code or tokens never go to another host than the local one: the host of `redirect_uri` shall be loopback.
4192
+
4193
+ #### Option `ui.web_auth`
4194
+
4195
+ Option `ui.web_auth` (part of the composite option `ui`, see [Graphical Interactions](#graphical-interactions-browser-and-text-editor)) selects how the result of a web login is received:
4196
+
4197
+ | Value | Local port | Use when |
4198
+ |------------------|------------|----------|
4199
+ | `port` (default) | Yes: `ascli` listens on the loopback address of `redirect_uri` | The browser runs on the same system as `ascli`, or an SSH tunnel is possible. |
4200
+ | `paste` | No: `redirect_uri` is only used in the login URL | The browser cannot reach the system that runs `ascli`, and no tunnel is possible. |
4201
+
4202
+ With `paste`, after login the user gives the result to `ascli` through the terminal (nothing is displayed, as it contains a code or tokens):
4203
+
4204
+ - the code displayed by Shares (a long text of letters, digits, `-` and `_`), or the code shown by `ascli config web_login` on the workstation,
4205
+ - or the full URL (or only the query) from the address bar of the browser, which shows a connection error on `redirect_uri`: this is expected.
4206
+
4207
+ In all cases the `state` is checked.
4208
+ Details are in the following sections.
4209
+
4210
+ Example:
4211
+
4212
+ ```shell
4213
+ ascli <PLUGIN> <COMMAND> --ui=terminal --ui.web_auth=paste
4214
+ ```
4215
+
4216
+ #### Web login when the browser is on another system
4217
+
4218
+ The browser sends the result of the login to `redirect_uri`, on the loopback address of the system where the browser runs.
4219
+ If `ascli` runs on another system than the browser (for example, `ascli` is installed on a server, and the user is connected with SSH from a workstation), the redirection does not reach `ascli`.
4220
+
4221
+ To solve this, forward the port of `redirect_uri` from the workstation to the server with an SSH tunnel, and open the login URL in the browser of the workstation:
4222
+
4223
+ 1. On the workstation, open the SSH session with a tunnel (same port on both sides, default `12345`):
4224
+
4225
+ ```shell
4226
+ ssh -L 127.0.0.1:12345:127.0.0.1:12345 <SERVER_USER>@<SERVER_HOST>
4227
+ ```
4228
+
4229
+ 2. In this session, run the command with `--ui=terminal`, so that the login URL is displayed instead of opening a browser on the server (this is the default if the server has no graphical environment):
4230
+
4231
+ ```shell
4232
+ ascli <PLUGIN> <COMMAND> --ui=terminal
4233
+ ```
4234
+
4235
+ 3. Copy the displayed URL in the browser of the workstation, and log in.
4236
+ 4. The browser is redirected to `http://localhost:12345`: the tunnel sends the request to `ascli` on the server, and the flow continues as described above.
4237
+
4238
+ The tunnel only exists as long as the SSH session is open.
4239
+
4240
+ If no tunnel is possible (for example, a jump server between the workstation and the server), use `--ui.web_auth=paste`: `ascli` then opens no local port, and the result of the login is given through the terminal.
4241
+ There are two ways, depending on whether `ascli` is also installed on the workstation.
4242
+
4243
+ With `--ui.web_auth=port` (default), in an SSH session with `--ui=terminal`, a warning reminds this option.
4244
+
4245
+ ##### With `ascli` on the workstation
4246
+
4247
+ `ascli` on the workstation opens the login page, receives the redirection of the browser, and shows a code to paste in the terminal of the server.
4248
+ Nothing else is needed on the workstation: no configuration, no preset, no access to the server of the application.
4249
+ The exchange of the code for a token is done by `ascli` on the server: the secret of the client does not leave it.
3736
4250
 
3737
- A plain value is the `mode`:
4251
+ 1. In the SSH session, run the command with `--ui=terminal --ui.web_auth=paste`:
3738
4252
 
3739
- - `--ui=browser` (or `graphical`) forces a graphical environment: a browser is opened for URLs or secrets, or a text editor for files.
3740
- - `--ui=terminal` (or `text`) forces a text environment, the URL or file path to open is displayed on terminal, and secrets are entered on terminal.
3741
- - `--ui=auto` selects the mode from the environment (default).
4253
+ ```shell
4254
+ ascli <PLUGIN> <COMMAND> --ui=terminal --ui.web_auth=paste
4255
+ ```
3742
4256
 
3743
- The browser is opened, by priority, with: `--ui.command`, or the system default.
3744
- When a command is defined, it is used to open URLs whatever the `mode`.
3745
- The command is an array: the URL is appended as last argument.
3746
- For example, to use Firefox:
4257
+ 2. `ascli` displays a message that proposes the two ways to log in, with the login URL for the first one, and a command to run on the workstation for the second one: it contains a code made of letters, digits, `-` and `_`. Then `ascli` waits:
4258
+
4259
+ ```text
4260
+ USER ACTION: To continue, choose one of these two ways:
4261
+ 1. With any browser (ascli is not needed on the workstation):
4262
+ - Open this URL in a browser and log in:
4263
+ https://...
4264
+ - The browser shows a connection error on http://localhost:12345: this is expected.
4265
+ - Copy the full URL from the address bar of the browser, and paste it in the prompt below.
4266
+ 2. If ascli is installed on the workstation that has the browser:
4267
+ - Run there:
4268
+ ascli config web_login <CODE>
4269
+ - Log in in the page that opens.
4270
+ - Copy the code shown by the browser, and paste it in the prompt below.
4271
+ ```
3747
4272
 
3748
- ```bash
3749
- ascli config echo @secret: --ui=browser --ui.command=@json:'["firefox","--private-window"]'
3750
- ```
4273
+ The command is displayed only if `ascli` does not start the browser itself (`--ui=terminal` without `--ui.command`).
4274
+ If the browser is started by `ascli` (`--ui=graphical`, or `--ui.command`), it is on the same host as `ascli`, and the redirection may be immediate (user already logged in): only the steps to log in, copy the URL from the browser and paste it are displayed.
4275
+
4276
+ 3. On the workstation, run this command.
4277
+ The first time for a login host, `ascli` displays the host of the login page, and asks to trust it (`yes`): it opens a URL that comes from another system.
4278
+ Trusted hosts are saved; without a terminal, an unknown host is refused.
4279
+ `ascli` then opens the browser on the login page and listens on `redirect_uri`.
4280
+ 4. Log in. The browser shows a page "Login Complete" with the code to paste, hidden by default:
4281
+ - The button **Copy** puts the code in the clipboard.
4282
+ - The **eye** button shows or hides the code, to select it manually.
4283
+ 5. Paste the code in the terminal of the server (nothing is displayed). `ascli` on the server checks the `state`, and the flow continues as described above, from step 6.
4284
+
4285
+ The command on the workstation:
4286
+
4287
+ - accepts only a login page in `https`, and a `redirect_uri` on a loopback address; the host shown for confirmation is the one of the URL, not a label given in the code;
4288
+ - is available only at security level `low`;
4289
+ - ends once the browser has received the page with the code; the port of `redirect_uri` shall be free on the workstation (the URL is registered for the login and cannot be changed);
4290
+ - gives to the server only the parameters it needs (the `code` and the `state`).
4291
+
4292
+ The codes are compressed and encrypted with a key that is not secret (derived from a constant and the current time, in slots of 15 minutes): they are hard to read and are valid for 15 to 30 minutes (the clocks of both computers must be correct), but they are **not confidential**: do not keep them, nor send them. The code shown by Shares also uses the random `state` of the login in its key.
4293
+ The codes are authenticated: a code that is incomplete, mistyped or modified is detected.
4294
+ Spaces and line breaks are ignored (letter case matters): a code displayed on several lines can be pasted.
4295
+
4296
+ ##### Without `ascli` on the workstation
4297
+
4298
+ If `ascli` is not installed on the workstation, the URL of the error page is used:
4299
+
4300
+ 1. In the SSH session, run the command with `--ui=terminal --ui.web_auth=paste`.
4301
+ 2. Copy the displayed login URL in the browser of the workstation, and log in.
4302
+ 3. The browser is redirected to `redirect_uri` (for example `http://localhost:12345/?code=...&state=...`) and shows a connection error: this is expected.
4303
+ 4. Copy the full URL from the address bar of the browser, and paste it in the terminal (nothing is displayed, as it contains a code or tokens).
4304
+ The query alone (`code=...&state=...`) is also accepted.
4305
+ The `state` is mandatory: it is checked like in the standard flow, then the flow continues from step 6.
4306
+
4307
+ Both ways accept, at the prompt, the code, the URL or the query.
4308
+ If standard input is not a terminal, the line is read from it.
4309
+ The size of a pasted line may be limited by the terminal: the code of the reply contains only what is needed.
4310
+
4311
+ Notes:
4312
+
4313
+ - For Shares with `--auth=web`, `paste` is simpler: Shares itself displays the code, so neither the tunnel, nor `ascli config web_login`, nor the URL of the error page is used (see [Authentication of SAML users](#authentication-of-saml-users)).
4314
+ - The port must be free on the workstation.
4315
+ To use another port, change it in the tunnel and in `--redirect-uri`, for example `--redirect-uri=http://localhost:23456` and `-L 127.0.0.1:23456:127.0.0.1:23456`.
4316
+ For Aspera on Cloud, this `redirect_uri` shall also be declared in the API client (see [API Client Registration](#api-client-registration)).
4317
+ - The tunnel listens on `127.0.0.1`: if the browser resolves `localhost` to `::1`, use `--redirect-uri=http://127.0.0.1:12345`.
4318
+ - On Windows, `ssh` is the OpenSSH client provided with the system; with PuTTY, add a local port forwarding (Connection &rarr; SSH &rarr; Tunnels) from `127.0.0.1:12345` to `127.0.0.1:12345`.
4319
+ - Another solution is X11 forwarding: run an X server on the workstation (for example `VcXsrv` or X410 on Windows) and connect with `ssh -X`.
4320
+ The browser then runs on the server and is displayed on the workstation, so no tunnel is needed.
4321
+ It is heavier (X server to install, slower display), and the browser is the one of the server.
4322
+ - Without interaction (automation), prefer a method that needs no browser, such as `--auth=jwt` for Aspera on Cloud.
3751
4323
 
3752
4324
  ### Logging, Debugging
3753
4325
 
@@ -3755,11 +4327,11 @@ The gem is equipped with traces, mainly for debugging and learning APIs.
3755
4327
  The composite option `log` groups all logging parameters (use `--log=help` to display this schema):
3756
4328
 
3757
4329
  | Field | Type | Description |
3758
- |---------|--------|---------------------------------------------------------------------------|
3759
- | `format` | `String` | Log line formatter. Use `@ruby:` for a custom lambda.<br/>Allowed values: `default`, `caller`, `standard`.<br/>Default: `default`. |
3760
- | `level` | `String` | Minimum log level displayed.<br/>Allowed values: `trace2`, `trace1`, `debug`, `info`, `warn`, `error`, `fatal`, `unknown`.<br/>Default: `warn`. |
4330
+ | ------- | ------------ | ------------------------------------------------------------------------- |
4331
+ | `format` | `Enum[String]` | Log line formatter. Use `@ruby:` for a custom lambda.<br/>Allowed values: `default`, `caller`, `standard`.<br/>Default: `default`. |
4332
+ | `level` | `Enum[String]` | Minimum log level displayed.<br/>Allowed values: `trace2`, `trace1`, `debug`, `info`, `warn`, `error`, `fatal`, `unknown`.<br/>Default: `warn`. |
3761
4333
  | `secrets` | `Bool` | Show passwords and secrets in logs.<br/>Default: `false`. |
3762
- | `type` | `String` | Log output destination.<br/>Allowed values: `stderr`, `stdout`, `syslog`.<br/>Default: `stderr`. |
4334
+ | `type` | `Enum[String]` | Log output destination.<br/>Allowed values: `stderr`, `stdout`, `syslog`.<br/>Default: `stderr`. |
3763
4335
 
3764
4336
  > [!TIP]
3765
4337
  > Individual options `log_level`, `log_format`, `logger`, and `log_secrets` are also available as aliases for `log.level`, `log.format`, `log.type`, and `log.secrets` respectively.
@@ -3840,7 +4412,7 @@ To disable this warning, set the option `warn_insecure` to `no`.
3840
4412
  HTTP connection parameters (not `ascp` WSS) can be adjusted using option `http_options`:
3841
4413
 
3842
4414
  | Field | Type | Description |
3843
- |-------------------------|---------------|----------------------------------------------------------------------------------|
4415
+ | ----------------------- | ------------- | -------------------------------------------------------------------------------- |
3844
4416
  | `download_partial_suffix` | `String` | File suffix appended to the target filename while a download is in progress. (Rest)<br/>Default: `.http_partial`. |
3845
4417
  | `keep_alive_timeout` | `Number` | Maximum time in seconds to keep an idle persistent connection open. (Net::HTTP)<br/>Default: `2`. |
3846
4418
  | `open_timeout` | `Number` | Maximum time in seconds to wait for a connection to be established. (Net::HTTP)<br/>Default: `60`. |
@@ -3993,7 +4565,7 @@ Or, alternatively, (prefer transfer spec like above, generally):
3993
4565
 
3994
4566
  By default, it uses the `direct` agent, which is a local `ascp`.
3995
4567
  Nevertheless, `ascli` does not come with `ascp` installed.
3996
- This is the reason why it is advised to install the Aspera Transfer Daemon during installation (`ascli config transferd install`).
4568
+ This is the reason why it is advised to install the Aspera Transfer Daemon during installation (`ascli transferd install`).
3997
4569
 
3998
4570
  By default, `ascli` uses the `ascp` binary found in **well known locations**, that is, typical Aspera product installation paths.
3999
4571
 
@@ -4002,7 +4574,7 @@ It provides the following commands for `ascp` sub-command:
4002
4574
 
4003
4575
  - `show` : Show the path of `ascp` used
4004
4576
  - `info` : Show information on `ascp` and its environment
4005
- - `install` : Install the Transfer SDK (same as `config transferd install`)
4577
+ - `install` : Install the Transfer SDK (deprecated, same as `transferd install`)
4006
4578
  - `spec` : List transfer spec parameters supported by `ascp`
4007
4579
  - `schema` : Show the JSON schema of the transfer spec
4008
4580
  - `errors` : List known `ascp` errors and whether they are retry-able
@@ -4011,7 +4583,7 @@ It provides the following commands for `ascp` sub-command:
4011
4583
  #### Selection of `ascp` location for [`direct`](#agent-direct) agent
4012
4584
 
4013
4585
  Option: `sdk_folder` is used to specify the location of `ascp`.
4014
- By default, `ascli` uses `ascp` from the Transfer SDK installed in its configuration folder (see `config ascp install`).
4586
+ By default, `ascli` uses `ascp` from the Transfer SDK installed in its configuration folder (see `transferd install`).
4015
4587
 
4016
4588
  To override and use an alternate `ascp` path, use option `sdk_folder` (`--sdk-folder=`).
4017
4589
 
@@ -4099,7 +4671,7 @@ The following agents are supported and selected with option `transfer`:
4099
4671
  |----------|----------|-------------------------------|
4100
4672
  | [`direct`](#agent-direct) | local | direct execution of `ascp` |
4101
4673
  | [`transferd`](#agent-transfer-daemon) | local | Aspera Transfer Daemon |
4102
- | [`connect`](#agent-connect-client) | local | Aspera Connect Client |
4674
+ | [`connect`](#agent-connect-client) | local | Aspera Connect Client (to be deprecated in 2027, use `desktop`) |
4103
4675
  | [`desktop`](#agent-desktop-client) | local | Aspera for Desktop |
4104
4676
  | [`node`](#agent-node-api) | remote | Aspera Transfer Node |
4105
4677
  | [`httpgw`](#agent-http-gateway) | remote | Aspera HTTP Gateway |
@@ -4154,15 +4726,18 @@ ascli server download /remote/big-file.bin --to-folder=/tmp \
4154
4726
  '--transfer=@json:{"agent":"desktop","asynchronous":true}'
4155
4727
 
4156
4728
  # Poll status later
4157
- ascli config transfer status <job_id>
4729
+ ascli config agents jobs status <job_id>
4158
4730
 
4159
4731
  # List all pending/completed async transfers
4160
- ascli config transfer list
4732
+ ascli config agents jobs list
4161
4733
 
4162
4734
  # Remove completed/failed entries
4163
- ascli config transfer cleanup
4735
+ ascli config agents jobs cleanup
4164
4736
  ```
4165
4737
 
4738
+ > [!NOTE]
4739
+ > `config transfer` (`list`, `status`, `cleanup`) is deprecated after 4.28.0: use `config agents jobs`. It still works, with a warning.
4740
+
4166
4741
  All transfer agents support asynchronous mode:
4167
4742
 
4168
4743
  | Agent | Status source | Persisted across restart |
@@ -4176,16 +4751,16 @@ All transfer agents support asynchronous mode:
4176
4751
 
4177
4752
  For `direct` and `httpgw`, the transfer runs as a Ruby thread inside the `ascli` process.
4178
4753
  The `job_id` is persisted on disk but the live thread state is only available as long as the same process is running.
4179
- If the process is restarted, `config transfer status` returns `unknown` for those jobs.
4754
+ If the process is restarted, `config agents jobs status` returns `unknown` for those jobs.
4180
4755
 
4181
- Parameters of the agent are persisted, except secrets (e.g. `password` of agent `node`): `config transfer status` takes them from the current `transfer` option, if it is for the same agent (e.g. same option on command line, or in a preset).
4756
+ Parameters of the agent are persisted, except secrets (e.g. `password` of agent `node`): `config agents jobs status` takes them from the current `transfer` option, if it is for the same agent (e.g. same option on command line, or in a preset).
4182
4757
 
4183
4758
  > [!NOTE]
4184
4759
  > **`asynchronous` and MCP** - When `ascli` is used as an MCP server, an AI assistant calling
4185
4760
  > a transfer command may time out or cancel the request and retry, causing duplicate transfers.
4186
4761
  > Using `asynchronous: true` eliminates this risk: the transfer is submitted immediately,
4187
4762
  > the `job_id` is returned, and the AI can poll
4188
- > `config transfer status <job_id>` to track progress without any risk of duplication.
4763
+ > `config agents jobs status <job_id>` to track progress without any risk of duplication.
4189
4764
  > This works with all agents, including `direct` and `httpgw`.
4190
4765
 
4191
4766
  #### Agent: Direct
@@ -4200,18 +4775,18 @@ See [FASP](#fasp-configuration).
4200
4775
  The `transfer` option accepts the following optional parameters to control multi-session, Web Socket Session, Resume policy and add any argument to `ascp`:
4201
4776
 
4202
4777
  | Field | Type | Description |
4203
- |----------------------|---------------|----------------------------------------------------------------------------------|
4778
+ | -------------------- | ------------- | -------------------------------------------------------------------------------- |
4204
4779
  | `ascp_args` | `Array[String]` | List of native `ascp` command-line arguments.<br/>Default: `[]`. |
4205
- | `client_ssh_key` | `String` | SSH key type to use for token-based transfers.<br/>Allowed values: `rsa`, `dsa_rsa`, `per_client`.<br/>Default: `rsa`. |
4780
+ | `client_ssh_key` | `Enum[String]` | SSH key type to use for token-based transfers.<br/>Allowed values: `rsa`, `dsa_rsa`, `per_client`.<br/>Default: `rsa`. |
4206
4781
  | `file_list` | `Bool` | If `true`, source paths are written to a temp file passed to `ascp` via `--file-list` or `--file-pair-list`.<br/>If `false`, source paths are placed directly on the `ascp` command line.<br/>Default: `true`. |
4207
4782
  | `monitor` | `Bool` | Enable use of the `ascp` management port for transfer monitoring.<br/>Default: `true`. |
4208
4783
  | `multi_incr_udp` | `Bool` | Multi session - Increment UDP port for each session.<br/>If `true`, each session uses a different UDP port starting at `fasp_port` (default: 33001).<br/>If `false`, all sessions use the same `fasp_port` (or `ascp` default).<br/>Default: `true` on Windows, `false` on other platforms. |
4209
4784
  | `quiet` | `Bool` | Suppress the `ascp` progress bar display.<br/>If `false`, the progress bar of option `progress_bar` is not displayed, unless that option is set.<br/>Default: `true`. |
4785
+ | `resume` | `Hash` | Configuration for automatic transfer resume on interruption. |
4210
4786
  | `resume.iter_max` | `Integer` | Maximum number of retry attempts on error.<br/>Default: `7`. |
4211
4787
  | `resume.sleep_factor` | `Integer` | Multiplier applied to sleep duration between consecutive retry attempts.<br/>Default: `2`. |
4212
4788
  | `resume.sleep_initial` | `Integer` | Initial sleep duration (in seconds) before first retry.<br/>Default: `2`. |
4213
4789
  | `resume.sleep_max` | `Integer` | Maximum sleep duration (in seconds) between retry attempts.<br/>Default: `60`. |
4214
- | `resume` | `Hash` | Configuration for automatic transfer resume on interruption. |
4215
4790
  | `spawn_delay_sec` | `Number` | Multi session - Delay (in seconds) between starting each `ascp` session.<br/>Default: `2`. |
4216
4791
  | `spawn_timeout_sec` | `Number` | Multi session - Maximum time (in seconds) to verify that `ascp` is running.<br/>Default: `2`. |
4217
4792
  | `trusted_certs` | `Array[String]` | List of trusted certificate repositories. |
@@ -4252,6 +4827,12 @@ The list of known protocol errors and retry level can be listed:
4252
4827
  ascli config ascp errors
4253
4828
  ```
4254
4829
 
4830
+ Error codes of sessions (`errcode` in `ascp` logs) are a different numbering, listed with their category and the corresponding error above:
4831
+
4832
+ ```shell
4833
+ ascli config ascp errors session
4834
+ ```
4835
+
4255
4836
  Examples:
4256
4837
 
4257
4838
  ```shell
@@ -4270,6 +4851,104 @@ This is useful to debug if a transfer fails.
4270
4851
 
4271
4852
  To store `ascp` logs in file `aspera-scp-transfer.log` in a folder, use `--transfer=@json:'{"ascp_args":["-L","/path/to/folder"]}'`.
4272
4853
 
4854
+ To analyze `ascp` log files (`ascp` 4.0 and later), give log files, or folders with log files, to `config ascp logs`:
4855
+
4856
+ ```shell
4857
+ ascli config ascp logs summary /path/to/folder
4858
+ ascli config ascp logs sessions /path/to/folder/aspera-scp-transfer.log
4859
+ ```
4860
+
4861
+ | Command | Result |
4862
+ |---------------------|-----------------------------------------------------------------|
4863
+ | `summary` | Statistics of sessions, errors by category, maximum throughput, findings. |
4864
+ | `health` | Health check for monitoring in Nagios format (failed sessions and low efficiency over last N minutes). |
4865
+ | `sessions` | One row per session, with diagnostics. |
4866
+ | `diagnostics` | One row per diagnostic of a session: `id`, `severity` (`error`, `warning`, `info`), `message` and `recommendation` (action to take, when the diagnostic has one). |
4867
+ | `multi_sessions` | Multi-session transfers: sessions grouped by transfer, with aggregate rate. |
4868
+ | `snapshots` | Aggregate rates per period. |
4869
+ | `snapshot_sessions` | Rates of each session per period. |
4870
+ | `peers` | Sessions and errors by peer address. |
4871
+ | `transfers` | Transferred files. |
4872
+ | `licenses` | Licenses of local and peer systems. |
4873
+ | `overdrives` | Sessions with loss due to overdriving of network or storage. |
4874
+ | `records` | Log lines parsed into records: `samples`, `sessions` or `transfers` (see below). |
4875
+ | `fields` | Description of the fields of records: `samples`, `sessions` or `transfers`. |
4876
+
4877
+ Log files compressed with gzip (e.g. rotations `aspera.log-20261101.gz`, `aspera-scp-transfer.1.log.gz`) are read directly, in a folder or given as argument; gzip is detected from the first bytes of the file, not from its name. Argument `-` reads the logs from the standard input, plain or compressed with gzip:
4878
+
4879
+ ```shell
4880
+ ascli config ascp logs summary /var/log/aspera.log-20261101.gz
4881
+ zcat /var/log/aspera.log-2026*.gz | ascli config ascp logs summary -
4882
+ ```
4883
+
4884
+ To analyze the logs of an HSTS read over SSH, instead of files of the local machine, use command `logs` of the plugin [`server`](#analyze-ascp-logs-of-the-server).
4885
+
4886
+ A file must contain `ascp` log lines (`FASP` messages, or lines of process `ascp` in syslog): in a folder, other files are ignored; a file given as argument that is not an `ascp` log is refused.
4887
+
4888
+ When logs of both sides of a session are analyzed (client and server), each session includes the status, error and diagnostics of the other side (`peer_side`, `peer_diagnostics`).
4889
+
4890
+ For example, to list only errors:
4891
+
4892
+ ```shell
4893
+ ascli config ascp logs diagnostics /path/to/folder --select=@json:'{"severity":"error"}'
4894
+ ```
4895
+
4896
+ Besides the default columns, `sessions` rows have context columns to filter sessions (show them with `--fields=ALL`, or select with `--fields=session,product_name,transport,authentication`, or filter with `--select`/`--query`); a column is absent when the log does not give it:
4897
+
4898
+ | Column | Value |
4899
+ |------------------|--------------------------------------------------------------------------------------------------------------------|
4900
+ | `product_name` | Product that wrote the log, from the line `<product> version <version>` (e.g. `Aspera High-Speed Transfer Server`, `Aspera Transfer SDK`, `Aspera Connect`), without `IBM`. |
4901
+ | `transport` | `ssh` if `Session Start` has `tcp_port`, `wss` if it has `wss_port`. |
4902
+ | `authentication` | `token` if `ascp` logs that `ASPERA_AUTH_TOKEN` is set, else `node` if it logs the storage of a node access key. Never the token, the access key or the storage root. |
4903
+ | `proxy` | Address of the proxy (`proxy_ip` of `Session Params`), absent if there is none. |
4904
+ | `fips` | `true` or `false` (`fips_enabled` of `Session Params`). |
4905
+
4906
+ Diagnostics of a session include: category of error (e.g. `udp_setup`, `storage`, `authentication`) with a hint, retry of a failed session, parameters set by the server (cipher, resume policy, virtual link), efficiency and loss of control messages, decline of the rate during the transfer (`rate_decline`: second half of the samples below 70% of the first half, not evaluated if the peer changes the rate, if another transfer session starts meanwhile, or if the session failed), and for a sender, which limit of the receiver (network, disk, virtual link) or reading from storage limits the rate. Other diagnostics: no packet received for some seconds, by the receiver (`reception_interruption`) or by the sender, which gets no feedback of the receiver (`feedback_interruption`); overflow of the retransmission timer (`rex_timer_overflow`: the retransmission RTT is very large); maximum rate of the license of `ascp` below the target rate (`license_rate_limit`); license that expires within `license_expiry_days` (default `30`) of the start of the session, or has expired (`license_expiry`); and many small files transferred (`small_files`): at least `small_files_min_count` (default 100) files with a mean size below `small_files_max_mean` (default 1 MB); path MTU measured by `ascp` below `small_mtu_max` (default 1400, `ascp` measures 1492, 1006, 508 or 296), which suggests a VPN or a tunnel (`small_mtu`). Two configuration messages, which have no effect on the transfer, are not diagnostics but only appear in `findings` of `summary`: OpenSSL modules folder not found (`ossl-modules not found`), and a schedule of virtual link capacity that could not be registered (`unable to submit change event`).
4907
+
4908
+ The `recommendation` of a diagnostic is only in the list `diagnostics` (not in `sessions`, where `diagnostics` is a list of messages, and not in `summary`): it tells what to check or change, with the `ascp` options and `aspera.conf` parameters concerned (e.g. UDP port and firewalls, target and minimum rate, storage write, SSH). Diagnostics without action (e.g. information, or cancelled by the user) have no `recommendation`; the diagnostic of the category of a failed session gives its hint in `message`.
4909
+
4910
+ Option `ascp_logs` (dot-notation) sets `period` (snapshot period in minutes, default `1`), `zero_bytes` (include sessions without transferred bytes), `mtu` (when not found in logs), `resolve` (host names of peers), `timezone`, `health_minutes` (window in minutes for health check command, default `60`), `remote_max_size` (maximum total size in bytes of the log files read from a server with [`server logs`](#analyze-ascp-logs-of-the-server), default `268435456`), and `thresholds` (diagnostic thresholds, including `rate_decline_ratio`, `rate_decline_min_samples`, `rate_decline_delay`, `rate_decline_end_fraction`, `license_expiry_days`, `small_files_min_count`, `small_files_max_mean` and `small_mtu_max`), e.g. `--ascp-logs.period=5` or `--ascp-logs.thresholds.efficiency=95`.
4911
+
4912
+ Times of log lines are read in the time zone of the analyst, and displayed in it. To read the log of another system without shifting it, set the time zone of the log with `timezone`: `UTC` or an offset `+HH:MM`, e.g. `--ascp-logs.timezone=+02:00`. Syslog lines (`Oct 25 00:02:20`) have no year: it is deduced from the modification date of the log file (the current date for the standard input), the log being before this date. So a log from December to January, analyzed in March, has its December lines in the previous year. Keep the modification date of the file when copying it (e.g. `cp -p`, `scp -p`).
4913
+
4914
+ Command `records` gives the log lines parsed into records, with the field names of the log lines, to filter them with `--out.query` (JMESPath):
4915
+
4916
+ | Record | Log lines |
4917
+ |-------------|-------------------------------------------------------------------------------------------------|
4918
+ | `samples` | `Receiver bl` or `Sender bl` line, with the `DS Qs` line that follows it in field `DS`. |
4919
+ | `sessions` | `Session Start`, `Session Params`, `Session Stop` and `Session Statistics` lines of a session, and lines of the process about it (see below). |
4920
+ | `transfers` | `Transfer Start` and `Transfer Stop` lines of a file. |
4921
+
4922
+ A group of a log line becomes an object: for example, `rate t/m/c/n/vl/vr/r=...` becomes `rate.t`, `rate.m`, `rate.c`, etc.
4923
+ Values are numbers when the log value is a number: rates in bps, durations in ms, s or µs, and percentages without `%`.
4924
+ `Session Stop` and `Transfer Stop` have the fields of `Session Start` and `Transfer Start`, with their final values.
4925
+ When several log files are read, field `log_file` gives the log file of each record.
4926
+ Field `cookie` of `Session Params` is never output.
4927
+
4928
+ A session record also has the fields of these lines of the process (`ascp`), when the log has them:
4929
+
4930
+ | Field | Log line |
4931
+ |----------------------------------------------------------------|-------------------------------------------------------------------------------------------------------|
4932
+ | `fasp_version`, `license_max_rate`, `license_expires` | `Initializing FASP version <version>, license expires on <date>, max rate=<N> Mbps, ...`: `license_max_rate` (bps) and `license_expires` are absent if the license is unlimited or has no expiry date. `account no.` and `license no.` are never output. |
4933
+ | `pMTU`, `start_brtt` | `Measured pMTU: <N> Bytes, start_brtt: <N> ms`. |
4934
+ | `datagram_size`, `block_size`, `path_mtu` | `datagram size <N>B, block size <N>B, path MTU <N>B` (no `path_mtu` in old versions). |
4935
+ | `peer_rate_params` | List of `Peer requested rate params adopted` lines, in the order of the log: `time`, `target_rate`, `min_rate` and `transfer_policy` of each change. |
4936
+
4937
+ For example, samples where the calculated rate is lower than the target rate, and sessions with loss of control messages from the receiver:
4938
+
4939
+ ```shell
4940
+ ascli config ascp logs records samples /path/to/aspera-scp-transfer.log --out.query='[?rate.c < rate.t].{time: time, session: uuid, calculated: rate.c, network: rate.n, lost: bl2.l}'
4941
+ ascli config ascp logs records sessions /path/to/folder --out.query='[?rcvr_ctl.lost_pct > `1`]'
4942
+ ```
4943
+
4944
+ Command `fields` gives the type and description (with unit) of each field of a kind of record (`samples`, `sessions` or `transfers`), with its path as used in `--out.query` (e.g. `rate.c`):
4945
+
4946
+ ```shell
4947
+ ascli config ascp logs fields samples
4948
+ ascli config ascp logs fields sessions
4949
+ ascli config ascp logs fields transfers
4950
+ ```
4951
+
4273
4952
  > [!NOTE]
4274
4953
  > When transfer agent [`direct`](#agent-direct) is used, the list of files to transfer is provided to `ascp` using either `--file-list` or `--file-pair-list` and a temp file list, unless `--file-list` or `--file-pair-list` is already provided via `transfer` parameter `ascp_args`.
4275
4954
  > To place source paths directly on the `ascp` command line instead of using a temp file, set `file_list` to `false` in `transfer`: `--transfer.file_list=false`.
@@ -4451,6 +5130,10 @@ So, for example:
4451
5130
 
4452
5131
  #### Agent: Connect Client
4453
5132
 
5133
+ > **Note:** IBM Aspera Connect will be deprecated in 2027.
5134
+ > Use [IBM Aspera for Desktop](#agent-desktop-client) instead: `--transfer=desktop`.
5135
+ > `ascli` displays a warning when the `connect` agent is used.
5136
+
4454
5137
  By specifying option: `--transfer=connect`, `ascli` will start transfers using the locally installed **IBM Aspera Connect Client**.
4455
5138
  There are no specific parameters for option `transfer`.
4456
5139
 
@@ -4467,7 +5150,7 @@ This is especially useful for direct node-to-node transfers.
4467
5150
  Parameters provided in option `transfer` are:
4468
5151
 
4469
5152
  | Field | Type | Description |
4470
- |----------|--------|---------------------------------------------------------------|
5153
+ | -------- | ------ | ------------------------------------------------------------- |
4471
5154
  | `password` | `String` | Password, secret, or bearer token.<br/>Required. |
4472
5155
  | `root_id` | `String` | Root file ID. Mandatory only when `password` is a bearer token. |
4473
5156
  | `url` | `String` | URL of the Node API.<br/>Required. |
@@ -4499,8 +5182,8 @@ By specifying option: `--transfer=httpgw`, `ascli` will start transfers using th
4499
5182
  Parameters provided in option `transfer` are:
4500
5183
 
4501
5184
  | Field | Type | Description |
4502
- |-------------------|---------|---------------------------------------------|
4503
- | `api_version` | `String` | Force use of a specific API version.<br/>Allowed values: `v1`, `v2`.<br/>Default: `v2`. |
5185
+ | ----------------- | ------------ | ------------------------------------------- |
5186
+ | `api_version` | `Enum[String]` | Force use of a specific API version.<br/>Allowed values: `v1`, `v2`.<br/>Default: `v2`. |
4504
5187
  | `synchronous` | `Bool` | Wait for acknowledgment after each message.<br/>Default: `false`. |
4505
5188
  | `upload_chunk_size` | `Integer` | Size in bytes of each upload chunk.<br/>Default: `64000`. |
4506
5189
  | `url` | `String` | URL of the HTTP Gateway.<br/>Required. |
@@ -4524,7 +5207,9 @@ Set option `transfer` to `transferd`.
4524
5207
  Options for `transfer` are:
4525
5208
 
4526
5209
  | Field | Type | Description |
4527
- |-------|--------|----------------------------------------------------------------------------------|
5210
+ | ------- | ------ | -------------------------------------------------------------------------------- |
5211
+ | `api_key` | `String` | API key of an existing daemon (`start` is `false`) that has `authentication` enabled in its configuration. It is sent in the metadata `api_key` of each call. |
5212
+ | `ca_file` | `String` | Path to the certificate authority file (PEM) that signed the certificate of an existing daemon (`start` is `false`) that has `tls` enabled in its configuration. A self-signed certificate is its own authority. |
4528
5213
  | `start` | `Bool` | Start a new daemon instance.<br/>Default: `true`. |
4529
5214
  | `stop` | `Bool` | Stop the daemon when `ascli` exits.<br/>Default: `true`. |
4530
5215
  | `url` | `String` | Address and port listened by the daemon (e.g. `:55002`). If port is `0`, the daemon listens on a random available port. If no address is given, `127.0.0.1` is used.<br/>Default: `:0`. |
@@ -4568,6 +5253,165 @@ On Windows the compilation may fail for various reasons (3.1.1):
4568
5253
 
4569
5254
  <!-- spellchecker: enable -->
4570
5255
 
5256
+ #### Transfer Daemon as a system service
5257
+
5258
+ The Transfer Daemon (`transferd`) can run permanently as a `systemd` service, for applications that use an existing daemon (see [Agent: Transfer Daemon](#agent-transfer-daemon), `start` set to `false`).
5259
+ `ascli` installs the SDK, writes the configuration file of the daemon (`/etc/transferd/transferd.json`) and the `systemd` unit, then enables and starts the service.
5260
+
5261
+ Commands are in `transferd service` (plugin [`transferd`](#plugin-transferd-transfer-daemon)):
5262
+
5263
+ | Command | Action |
5264
+ |-------------|--------|
5265
+ | `spec` | Show the schema of the configuration file of the daemon (`transferd.json`). Works on any system. |
5266
+ | `install` | Install the SDK if it is missing, then do `configure`. |
5267
+ | `configure` | Merge the given configuration into the existing file, validate it, write the file and the unit, reload `systemd`, enable and restart the service, and wait until the daemon listens. |
5268
+ | `status` | Show the version, the state of the service, the endpoint and whether it listens. The API key is never shown. |
5269
+ | `uninstall` | Stop and remove the service. With `purge` set to `true` in `service`, also remove the configuration file and the log folder. |
5270
+ | `use` | Switch to an installed version of the SDK and restart the service (see below). |
5271
+ | `versions` | List the installed versions of the SDK (see below). |
5272
+
5273
+ Except `spec` and `versions`, commands take the optional **last** positional argument `CONFIG`: a `Hash` ([Extended Value](#extended-value-syntax)) with two optional sections:
5274
+
5275
+ - `service`: how the service is installed.
5276
+ - `config`: content of `transferd.json`.
5277
+
5278
+ ```json
5279
+ {
5280
+ "service": {
5281
+ "user": "asperadaemon"
5282
+ },
5283
+ "config": {
5284
+ "address": "127.0.0.1",
5285
+ "port": 55002,
5286
+ "log_directory": "/var/log/aspera-transferd",
5287
+ "workers": {"max_concurrent": 10},
5288
+ "authentication": {"enabled": true}
5289
+ }
5290
+ }
5291
+ ```
5292
+
5293
+ Parameters of section `service`:
5294
+
5295
+ | Field | Type | Description |
5296
+ | ----------- | ------------- | -------------------------------------------------------------------------------- |
5297
+ | `after` | `Array[String]` | Units that shall be started before the daemon (`After=` in the unit).<br/>Default: `["network.target"]`. |
5298
+ | `environment` | `Hash` | Environment variables set in the unit. None is set unless given here. `TRANSFERD_ADDRESS`, `TRANSFERD_PORT`, `TRANSFERD_MGMT_PORT` and `TRANSFERD_MGMT_ADDRESS` override the configuration file. |
5299
+ | `group` | `String` | Group that runs the daemon. Defaults to the primary group of `user`. |
5300
+ | `name` | `String` | Name of the service. The unit file is `<name>.service`.<br/>Default: `aspera-transferd`. |
5301
+ | `purge` | `Bool` | Used by `uninstall`. Also remove the configuration file and the log folder.<br/>Default: `false`. |
5302
+ | `unit_dir` | `String` | Folder where the unit file is created.<br/>Default: `/etc/systemd/system`. |
5303
+ | `user` | `String` | Account that runs the daemon. It must exist, it is not created.<br/>Default: `asperadaemon`. |
5304
+ | `version` | `String` | Version of the SDK to install, used by `install` when the SDK folder is named `current` (versions side by side). Defaults to the SDK version of this tool. |
5305
+
5306
+ Section `config` follows the JSON schema of the daemon, displayed with:
5307
+
5308
+ ```shell
5309
+ ascli transferd service spec
5310
+ ```
5311
+
5312
+ | Field | Type | Description |
5313
+ | ---------------------------------------- | ------------- | -------------------------------------------------------------------------------- |
5314
+ | `$schema` | `String` | Optional URI or path of this schema, used by editors for completion and validation. Ignored by transferd. |
5315
+ | `address` | `String` | IP address or host name on which the gRPC API listens. Use 0.0.0.0 to listen on all IPv4 interfaces (for example in a container); when not listening on a loopback address, consider enabling tls and authentication. Overridden by environment variable TRANSFERD_ADDRESS, and by option --address (-a), which takes precedence.<br/>Default: `127.0.0.1`.<br/>Example: `127.0.0.1`. |
5316
+ | `api_time_settings` | `Hash` | Keepalive and connection lifetime settings of the gRPC API server, in seconds. |
5317
+ | `api_time_settings.max_conn_age` | `Integer` | Maximum lifetime of a client connection, with a random variation of +/-10%; the client must then reconnect. 0 or omitted: no limit.<br/>Default: `0`.<br/>Example: `3600`. |
5318
+ | `api_time_settings.max_conn_age_grace` | `Integer` | Additional time given to ongoing calls once max_conn_age is reached, before the connection is forcibly closed. 0 or omitted: no limit.<br/>Default: `0`.<br/>Example: `10`. |
5319
+ | `api_time_settings.max_conn_idle` | `Integer` | Time after which a client connection with no ongoing call is closed. 0 or omitted: 86400 (24 hours).<br/>Default: `86400`.<br/>Example: `120`. |
5320
+ | `api_time_settings.time` | `Integer` | Time without activity from a client after which the server pings it to check that the connection is still alive. 0 or omitted: 7200 (2 hours).<br/>Default: `7200`.<br/>Example: `60`. |
5321
+ | `api_time_settings.timeout` | `Integer` | Time the server waits for activity after a keepalive ping before closing the connection. 0 or omitted: 20.<br/>Default: `20`.<br/>Example: `3`. |
5322
+ | `authentication` | `Hash` | API key authentication of clients of the gRPC API. |
5323
+ | `authentication.api_key` | `String` | Value that clients must send in gRPC request metadata entry api_key. It is stored in clear text: restrict read access to this file.<br/>Example: `change-me-to-a-long-random-value`. |
5324
+ | `authentication.enabled` | `Bool` | Requires every call to carry the API key; other calls are rejected with status UNAUTHENTICATED. api_key is then required.<br/>Default: `false`. |
5325
+ | `fasp_management` | `Hash` | Management port on which the ascp processes started by transferd report transfer progress. |
5326
+ | `fasp_management.address` | `String` | IP address on which the management server listens. Change it only when ascp must reach transferd through an interface other than loopback. Overridden by environment variable TRANSFERD_MGMT_ADDRESS, and by option --mgmtaddress (-A), which takes precedence.<br/>Default: `127.0.0.1`.<br/>Example: `127.0.0.1`. |
5327
+ | `fasp_management.port` | `Integer` | TCP port of the management server. 0 or omitted: a free port is selected at startup. Overridden by environment variable TRANSFERD_MGMT_PORT, and by option --mgmtport (-P), which takes precedence.<br/>Default: `0`.<br/>Example: `23456`. |
5328
+ | `fasp_management.promiscuous_mode_enabled` | `Bool` | When true, transferd also reports transfers of ascp processes that it did not start. So that those processes find the management port, transferd writes it in file transferd.<port>.optport of directory ../var/run/aspera, relative to the FASP runtime bin directory. Those ascp processes must use the same FASP runtime as transferd (see fasp_runtime).<br/>Default: `false`. |
5329
+ | `fasp_runtime` | `Hash` | FASP runtime (ascp, async, license, aspera.conf) used for transfers. Omitted: the runtime embedded in the SDK is used. When this section is present, set use_embedded explicitly: if it is not true, user_defined is required. |
5330
+ | `fasp_runtime.extra_config` | `Array[Hash]` | Extra command line options added to the executables started for transfers. Does not apply to async. |
5331
+ | `fasp_runtime.extra_config[].command` | `String` | End of the path of the executable to which options are added, for example ascp (ascp.exe on Windows). Only the first matching entry is used.<br/>Required.<br/>Example: `ascp`. |
5332
+ | `fasp_runtime.extra_config[].options` | `Array[String]` | Options added to the command line, one argument per item, before the transfer arguments.<br/>Example: `["--save-before-overwrite"]`. |
5333
+ | `fasp_runtime.force_version` | `String` | Accepted for backward compatibility. Has no effect. |
5334
+ | `fasp_runtime.log` | `Hash` | Default logging of ascp, for transfers whose request configuration does not set localLog or logLevel. Does not apply to async. |
5335
+ | `fasp_runtime.log.dir` | `String` | Directory where ascp writes its log (ascp option -L). Empty or omitted: default location of ascp.<br/>Example: `/var/log/aspera`. |
5336
+ | `fasp_runtime.log.level` | `Integer` | Level of detail of the ascp log: 0 for basic information (files transferred, transfer rate), 1 to 4 for increasingly detailed debug messages (ascp options -D to -DDDD).<br/>Default: `0`. |
5337
+ | `fasp_runtime.use_embedded` | `Bool` | true: use the FASP runtime embedded in the SDK, and ignore user_defined. false: use the runtime located by user_defined. Omitted while the fasp_runtime section is present: false.<br/>Example: `true`. |
5338
+ | `fasp_runtime.user_defined` | `Hash` | Location of a separately installed FASP runtime. Required when use_embedded is not true, ignored otherwise. Both directories must exist at startup. |
5339
+ | `fasp_runtime.user_defined.bin` | `String` | Directory containing the ascp and async executables. A relative path is resolved from the working directory of transferd.<br/>Required.<br/>Example: `/opt/aspera/bin`. |
5340
+ | `fasp_runtime.user_defined.etc` | `String` | Directory containing the license file aspera-license and the configuration file aspera.conf. A relative path is resolved from the working directory of transferd.<br/>Required.<br/>Example: `/opt/aspera/etc`. |
5341
+ | `log_directory` | `String` | Directory of the transferd log file transferd.log (rotated at 10 MiB, 10 files kept). A relative path is resolved from the directory of the transferd executable. The directory is created if missing. Empty or omitted: logs are written to standard output.<br/>Example: `/var/log/aspera`. |
5342
+ | `log_format` | `Enum[String]` | Format of the transferd log: text for human-readable lines, json for one JSON object per line. Any value other than text gives json.<br/>Allowed values: `text`, `json`.<br/>Default: `text`. |
5343
+ | `log_level` | `Enum[String]` | Level of detail of the transferd log, from most (trace) to least (panic) verbose. Omitted or unrecognized value: info.<br/>Allowed values: `trace`, `debug`, `info`, `warning`, `error`, `fatal`, `panic`.<br/>Default: `info`. |
5344
+ | `port` | `Integer` | TCP port on which the gRPC API listens. 0 or omitted: a free port is selected at startup; it is written in the log and in file transferd.<port>.optport of runtime_dir. The configuration file shipped with the SDK sets 55002. Overridden by environment variable TRANSFERD_PORT, and by option --port (-p), which takes precedence.<br/>Default: `0`.<br/>Example: `55002`. |
5345
+ | `reflection` | `Bool` | Enables the gRPC server reflection service, so that tools such as `grpcurl` or `grpcui` can list and call the API without the transferd.proto file. Useful for debugging; leave disabled otherwise.<br/>Default: `false`. |
5346
+ | `runtime_dir` | `String` | Directory for runtime files. When port is 0, transferd writes the selected port in file transferd.<port>.optport there. Created with owner-only permissions if missing. Omitted: ../var/run/aspera relative to the directory of the transferd executable.<br/>Example: `/var/run/aspera`. |
5347
+ | `tls` | `Hash` | TLS for the gRPC API. When enabled, clients must connect using TLS. |
5348
+ | `tls.certificate` | `String` | Path of the PEM server certificate file, which may include intermediate certificates. A relative path is resolved from the working directory of transferd.<br/>Example: `/etc/transferd/server.crt`. |
5349
+ | `tls.enabled` | `Bool` | Enables TLS. certificate and key are then required.<br/>Default: `false`. |
5350
+ | `tls.key` | `String` | Path of the PEM private key file matching certificate. A relative path is resolved from the working directory of transferd.<br/>Example: `/etc/transferd/server.key`. |
5351
+ | `tls.min_tls_version` | `Enum[String]` | Minimum TLS version accepted from clients. Omitted or other value: TLSv12.<br/>Allowed values: `TLSv12`, `TLSv13`.<br/>Default: `TLSv12`. |
5352
+ | `workers` | `Hash` | Transfer execution and retention. |
5353
+ | `workers.max_concurrent` | `Integer` | Maximum number of transfers running at the same time. Additional transfers wait in a queue until a running one ends. 0 or omitted: 100.<br/>Default: `100`.<br/>Example: `10`. |
5354
+ | `workers.transfer_cleaning_period` | `Integer` | Interval, in seconds, at which transferd removes ended transfers older than transfer_max_age. 0 or omitted: 3600 (1 hour).<br/>Default: `3600`. |
5355
+ | `workers.transfer_max_age` | `Integer` | Time, in seconds, during which an ended transfer remains known to transferd (status queries, events) before it can be removed. Removal happens at the next cleaning, so a transfer may remain up to transfer_max_age + transfer_cleaning_period. 0 or omitted: 7200 (2 hours).<br/>Default: `7200`.<br/>Example: `86400`. |
5356
+
5357
+ The configuration is checked before anything is written:
5358
+
5359
+ - Keys not given keep their value in the existing `transferd.json` (deep merge), and a key set to `null` is removed.
5360
+ - An unknown key, a value of a wrong type, or an inconsistent configuration (for example `tls.enabled` without `certificate` and `key`) is refused, with the name of the key and of the file if the faulty key is in the existing file.
5361
+ The daemon itself ignores unknown keys silently.
5362
+ - The section `fasp_runtime` is computed from the SDK folder, and can be overridden.
5363
+ - If `authentication.enabled` is `true` and no `api_key` is given, the key of the existing file is kept, else a random one is generated.
5364
+ The file is written in clear text with mode `0640`, owner `user:group`.
5365
+ To get the key from the [vault](#secret-vault), write `{"config":{"authentication":{"api_key":"@vault:transferd.api_key@"}}}` in an [Extended Value](#extended-value-syntax) `@json:@extend:'...'`.
5366
+
5367
+ Requirements:
5368
+
5369
+ - `systemd` on Linux only.
5370
+ On other systems, or without `systemctl`, commands fail with a message (only `spec` and `--dry-run` work everywhere).
5371
+ - Run as `root`, except with `--dry-run=yes` (option is a boolean), which shows the actions and the files without any change, and `spec` and `versions`.
5372
+ - The account (`asperadaemon` by default) is **not** created by `ascli`.
5373
+ If it does not exist, the command fails and shows the command to create it:
5374
+ `useradd --system --no-create-home --shell /usr/sbin/nologin asperadaemon`.
5375
+ This is the account used by other Aspera products on the same host, so that files have the same owner.
5376
+ - If the version of the SDK installed is different from the version of the schema, then a warning is displayed (it is not an error).
5377
+
5378
+ Example:
5379
+
5380
+ ```shell
5381
+ sudo ascli transferd service install --sdk-folder=/opt/aspera/transferd/current @json:'{"config":{"port":55002,"authentication":{"enabled":true}}}'
5382
+ ```
5383
+
5384
+ ```shell
5385
+ ascli transferd service configure --dry-run=yes @json:'{"config":{"log_level":"debug"}}'
5386
+ ```
5387
+
5388
+ ```shell
5389
+ sudo ascli transferd service status
5390
+ ```
5391
+
5392
+ ```shell
5393
+ sudo ascli transferd service uninstall @json:'{"service":{"purge":true}}'
5394
+ ```
5395
+
5396
+ ##### Versions side by side and rollback
5397
+
5398
+ If the SDK folder (option `sdk_folder`) is named `current`, e.g. `--sdk-folder=/opt/aspera/transferd/current`, then `ascli` uses the layout `<prefix>/<version>` with a link `current` that points to the version in use:
5399
+
5400
+ ```text
5401
+ /opt/aspera/transferd/1.1.9
5402
+ /opt/aspera/transferd/1.1.10
5403
+ /opt/aspera/transferd/current -> 1.1.10
5404
+ ```
5405
+
5406
+ - `service install` installs the version given in `service.version` (default: version tested with this release of `ascli`) in `<prefix>/<version>`, and sets the link `current`.
5407
+ If the installation fails, then the link is set back to the previous version.
5408
+ - The unit and `transferd.json` refer to `current`: switching the link and restarting the service is enough to change the version.
5409
+ - `service versions` lists the installed versions and the one in use.
5410
+ - `service use <VERSION>` switches the link and restarts the service.
5411
+ If the service does not start, then the link is set back to the previous version and the service is restarted.
5412
+
5413
+ Any other folder name is used as is, with no link.
5414
+
4571
5415
  ### Transfer Specification
4572
5416
 
4573
5417
  Some commands lead to file transfer (upload/download).
@@ -4656,7 +5500,7 @@ The description gives the supported agents, if not all, and the corresponding `a
4656
5500
  #### Transfer Specification Reference
4657
5501
 
4658
5502
  | ID | Name |
4659
- |----|-----------|
5503
+ | -- | --------- |
4660
5504
  | A | Direct |
4661
5505
  | C | Connect |
4662
5506
  | D | Desktop |
@@ -4665,61 +5509,61 @@ The description gives the supported agents, if not all, and the corresponding `a
4665
5509
  | T | Transferd |
4666
5510
 
4667
5511
  | Field | Type | Description |
4668
- |--------------------------------|-----------------|----------------------------------------------------------------------------------|
5512
+ | ------------------------------ | --------------- | -------------------------------------------------------------------------------- |
4669
5513
  | `apply_local_docroot` | `Bool` | Apply local docroot to source paths.<br/>(A, T)<br/>(`--apply-local-docroot`) |
4670
5514
  | `authentication` | `String` | Set to `token` for SSH bypass keys, else password asked if not provided.<br/>(C) |
4671
- | `cipher_allowed` | `String` | Returned by node API. Valid literals include `aes-128` and `none`.<br/>Allowed values: `none`, `aes-128`, `aes-192`, `aes-256`, `aes-128-cfb`, `aes-192-cfb`, `aes-256-cfb`, `aes-128-gcm`, `aes-192-gcm`, `aes-256-gcm`.<br/>(C) |
4672
- | `cipher` | `String` | In transit encryption algorithms.<br/>Allowed values: `none`, `aes-128`, `aes-192`, `aes-256`, `aes-128-cfb`, `aes-192-cfb`, `aes-256-cfb`, `aes-128-gcm`, `aes-192-gcm`, `aes-256-gcm`.<br/>Default: `none`.<br/>(`-c (conversion){enum}`) |
5515
+ | `cipher` | `Enum[String]` | In transit encryption algorithms.<br/>Allowed values: `none`, `aes-128`, `aes-192`, `aes-256`, `aes-128-cfb`, `aes-192-cfb`, `aes-256-cfb`, `aes-128-gcm`, `aes-192-gcm`, `aes-256-gcm`.<br/>Default: `none`.<br/>(`-c (conversion){enum}`) |
5516
+ | `cipher_allowed` | `Enum[String]` | Returned by node API. Valid literals include `aes-128` and `none`.<br/>Allowed values: `none`, `aes-128`, `aes-192`, `aes-256`, `aes-128-cfb`, `aes-192-cfb`, `aes-256-cfb`, `aes-128-gcm`, `aes-192-gcm`, `aes-256-gcm`.<br/>(C) |
5517
+ | `content_protection` | `Enum[String]` | Enable client-side content protection (CSEAR, encryption-at-rest).<br/>For uploads, set to `encrypt` to transfer encrypted files and store them on the server with the extension `.aspera-env`. (`aspera.conf` parameter `transfer_encryption_content_protection_extension`). To download and decrypt encrypted files, set to `decrypt`<br/>`content_protection_password` must be specified if this option is set.<br/>Allowed values: `encrypt`, `decrypt`.<br/>(`--file-crypt={enum}`) |
4673
5518
  | `content_protection_password` | `String` | Password for encryption/decryption of transferred assets.<br/>(env:`ASPERA_SCP_FILEPASS`) |
4674
- | `content_protection` | `String` | Enable client-side content protection (CSEAR, encryption-at-rest).<br/>For uploads, set to `encrypt` to transfer encrypted files and store them on the server with the extension `.aspera-env`. (`aspera.conf` parameter `transfer_encryption_content_protection_extension`). To download and decrypt encrypted files, set to `decrypt`<br/>`content_protection_password` must be specified if this option is set.<br/>Allowed values: `encrypt`, `decrypt`.<br/>(`--file-crypt={enum}`) |
4675
5519
  | `cookie` | `String` | Metadata for transfer specified by application.<br/>(env:`ASPERA_SCP_COOKIE`) |
4676
5520
  | `create_dir` | `Bool` | Create target directory if it doesn't already exist.<br/>If **all** the following conditions are met, then the `destination_root` specifies a filename instead of destination folder:<br/>- `create_dir` is `false`<br/>- A single source file is given on **command line**<br/>- The target folder specified by `destination_root` does not exist<br/>In all other cases, `destination_root` specifies a folder, and it is created if it does not already exist. I.e. if **any** of those conditions is met:<br/>- `create_dir` is `true`<br/>- Multiple source files are provided<br/>- List of source files are provided in a file (list or pair), default for Node API and `ascli`.<br/>- The target folder exists<br/>(`-d`) |
4677
5521
  | `delete_before_transfer` | `Bool` | Before transfer, delete files that exist at the destination but not at the source.<br/>The source and destination arguments must be directories that have matching names.<br/>Objects on the destination that have the same name but different type or size as objects on the source are not deleted.<br/>(`--delete-before-transfer`) |
4678
5522
  | `delete_source` | `Bool` | Remove transferred source files after transfer success. Equivalent to `remove_after_transfer` + `remove_empty_directories` + `remove_empty_source_directory`. Take precedence over those.<br/>(A, N, T) |
4679
- | `destination_root_id` | `String` | The file ID of the destination root directory.<br/>Required when using Bearer token auth for the destination node.<br/>(T) |
4680
5523
  | `destination_root` | `String` | Destination root directory.<br/>Required. |
5524
+ | `destination_root_id` | `String` | The file ID of the destination root directory.<br/>Required when using Bearer token auth for the destination node.<br/>(T) |
4681
5525
  | `dgram_size` | `Integer` | UDP datagram size in bytes.<br/>(`-Z {integer}`) |
4682
- | `direction` | `String` | Direction of transfer (on client side).<br/>Required.<br/>Allowed values: `send`, `receive`.<br/>(`--mode=(conversion){enum}`) |
5526
+ | `direction` | `Enum[String]` | Direction of transfer (on client side).<br/>Required.<br/>Allowed values: `send`, `receive`.<br/>(`--mode=(conversion){enum}`) |
4683
5527
  | `exclude_newer_than` | `String` | Exclude files, but not directories, from the transfer if they are newer than the specified number of seconds added to the source computer's epoch.<br/>e.g. `-86400` for newer than a day back.<br/>(`--exclude-newer-than={string}`) |
4684
5528
  | `exclude_older_than` | `String` | Exclude files, but not directories, from the transfer if they are older than the specified number of seconds added to the source computer's epoch.<br/>e.g. `-86400` for older than a day back.<br/>(`--exclude-older-than={string}`) |
4685
5529
  | `fail_bad_filepass` | `Bool` | Fail on bad file decryption passphrase.<br/>(A, T)<br/>(`--fail-bad-filepass`) |
4686
5530
  | `fasp_port` | `Integer` | Specifies fasp (UDP) port.<br/>Default: `33001`.<br/>(`-O {integer}`) |
4687
5531
  | `fasp_proxy` | `Hash` | Proxy for communications between the remote server and the (local) client.<br/>(T) |
4688
- | `file_checksum` | `String` | Enable checksum reporting for transferred files by specifying the hash to use.<br/>Allowed values: `sha-512`, `sha-384`, `sha-256`, `sha1`, `md5`, `none`.<br/>Default: `none`.<br/>(A, N)<br/>(`--file-checksum={enum}`) |
4689
- | `http_fallback_port` | `Integer` | Specifies HTTP port when no cipher is used.<br/>(`-t {integer}`) |
5532
+ | `file_checksum` | `Enum[String]` | Enable checksum reporting for transferred files by specifying the hash to use.<br/>Allowed values: `sha-512`, `sha-384`, `sha-256`, `sha1`, `md5`, `none`.<br/>Default: `none`.<br/>(A, N)<br/>(`--file-checksum={enum}`) |
4690
5533
  | `http_fallback` | `Bool, String` | When true(1), attempts to perform an HTTP transfer if a FASP transfer cannot be performed.<br/>(`-y (conversion){boolean\|string}`) |
5534
+ | `http_fallback_port` | `Integer` | Specifies HTTP port when no cipher is used.<br/>(`-t {integer}`) |
4691
5535
  | `https_fallback_port` | `Integer` | Specifies HTTPS port when cipher is used.<br/>(`-t {integer}`) |
4692
5536
  | `icos` | `Hash` | Configuration parameters for IBM Cloud Object Storage (ICOS).<br/>(T) |
4693
5537
  | `keepalive` | `Bool` | The session is running in persistent session mode.<br/>(A, T)<br/>(`--keepalive`) |
4694
- | `lock_min_rate_kbps` | `Bool` | If `true`, lock the minimum transfer rate to the value set for min_rate_kbps.<br/>If `false`, users can adjust the transfer rate up to the value set for target_rate_cap_kbps.<br/>(C, T) |
4695
5538
  | `lock_min_rate` | `Bool` | n/a<br/>(C) |
5539
+ | `lock_min_rate_kbps` | `Bool` | If `true`, lock the minimum transfer rate to the value set for min_rate_kbps.<br/>If `false`, users can adjust the transfer rate up to the value set for target_rate_cap_kbps.<br/>(C, T) |
4696
5540
  | `lock_rate_policy` | `Bool` | If `true`, lock the rate policy to the default value.<br/>(C, T) |
4697
- | `lock_target_rate_kbps` | `Bool` | If `true`, lock the target transfer rate to the default value set for `target_rate_kbps`.<br/>If `false`, users can adjust the transfer rate up to the value set for `target_rate_cap_kbps`.<br/>(C, T) |
4698
5541
  | `lock_target_rate` | `Bool` | n/a<br/>(C) |
5542
+ | `lock_target_rate_kbps` | `Bool` | If `true`, lock the target transfer rate to the default value set for `target_rate_kbps`.<br/>If `false`, users can adjust the transfer rate up to the value set for `target_rate_cap_kbps`.<br/>(C, T) |
4699
5543
  | `min_rate_cap_kbps` | `Integer` | The highest minimum rate that an incoming transfer can request, in kilobits per second.<br/>Client minimum rate requests that exceed the minimum rate cap are ignored.<br/>The default value of unlimited applies no cap to the minimum rate. (Default: 0)<br/>(C, T) |
4700
5544
  | `min_rate_kbps` | `Integer` | Set the minimum transfer rate in kilobits per second.<br/>Default: `0`.<br/>(`-m {integer}`) |
4701
5545
  | `move_after_transfer` | `String` | Move source files to the specified `archive-dir` directory after they are transferred correctly.<br/>Available as of 3.8.0. Details in `ascp` manual.<br/>Requires write permissions on the source.<br/>If `src_base` is specified, files are moved to `archive-dir`/`path-relative-to-srcbase`.<br/>`archive-dir` must be in the same file system (or cloud storage account) as the source files being transferred.<br/>`archive-dir` is subject to the same docroot restrictions as source files.<br/>`move_after_transfer` and `remove_after_transfer` are mutually exclusive options.<br/>After files have been moved to the archive, the original source directory structure is left in place. Empty directories are not saved to `archive-dir`. To remove empty source directories after a successful move operation, also set `remove_empty_directories` to `true`. When using `remove_empty_directories`, empty directory removal examination starts at the `srcbase` and proceeds down any subdirectories. If no `srcbase` is used and a file path (as opposed to a directory path) is specified, then only the immediate parent directory is examined and removed if it is empty following the move of the source file.<br/>(A, N, T)<br/>(`--move-after-transfer={string}`) |
4702
- | `multi_session_threshold` | `Integer` | Split files across multiple `ascp` sessions if their size in bytes is greater than or equal to the specified value.<br/>(0=no file is split)<br/>(A, N, T)<br/>(`--multi-session-threshold={integer}`) |
4703
5546
  | `multi_session` | `Integer` | Use multi-session transfer. max 128.<br/>Each participant on one host needs an independent UDP (-O) port.<br/>Large files are split between sessions only when transferring with `resume_policy`=`none`.<br/>(special:`-C {integer}`) |
5547
+ | `multi_session_threshold` | `Integer` | Split files across multiple `ascp` sessions if their size in bytes is greater than or equal to the specified value.<br/>(0=no file is split)<br/>(A, N, T)<br/>(`--multi-session-threshold={integer}`) |
4704
5548
  | `obfuscate_file_names` | `Bool` | HTTP Gateway obfuscates file names when set to `true`.<br/>(H) |
4705
- | `overwrite` | `String` | Overwrite files at the destination with source files of the same name based on the policy:<br/>- `always` : Always overwrite the file.<br/>- `never` : Never overwrite the file. If the destination contains partial files that are older or the same as the source files and resume is enabled, the partial files resume transfer. Partial files with checksums or sizes that differ from the source files are not overwritten.<br/>- `diff` : (default) Overwrite the file if it is different from the source, depending on the compare method (default is size). If the destination is object storage, `diff` has the same effect as always. If resume is not enabled, partial files are overwritten if they are different from the source, otherwise they are skipped. If resume is enabled, only partial files with different sizes or checksums from the source are overwritten; otherwise, files resume.<br/>- `diff+older` : Overwrite the file if it is older and different from the source, depending on the compare method (default is size). If resume is not enabled, partial files are overwritten if they are older and different from the source, otherwise they are skipped. If resume is enabled, only partial files that are different and older than the source are overwritten, otherwise they are resumed.<br/>- `older` : Overwrite the file if its timestamp is older than the source timestamp.<br/>If you set an overwrite policy of `diff` or `diff+older`, difference is determined by the value set for `resume_policy`:<br/>`none` : The source and destination files are always considered different and the destination file is always overwritten<br/>`attributes` : The source and destination files are compared based on file attributes <br/>`sparse_checksum` : The source and destination files are compared based on sparse checksums, (currently file size)<br/>`full_checksum` : The source and destination files are compared based on full checksums<br/>Allowed values: `never`, `always`, `diff`, `older`, `diff+older`.<br/>Default: `diff`.<br/>(`--overwrite={enum}`) |
5549
+ | `overwrite` | `Enum[String]` | Overwrite files at the destination with source files of the same name based on the policy:<br/>- `always` : Always overwrite the file.<br/>- `never` : Never overwrite the file. If the destination contains partial files that are older or the same as the source files and resume is enabled, the partial files resume transfer. Partial files with checksums or sizes that differ from the source files are not overwritten.<br/>- `diff` : (default) Overwrite the file if it is different from the source, depending on the compare method (default is size). If the destination is object storage, `diff` has the same effect as always. If resume is not enabled, partial files are overwritten if they are different from the source, otherwise they are skipped. If resume is enabled, only partial files with different sizes or checksums from the source are overwritten; otherwise, files resume.<br/>- `diff+older` : Overwrite the file if it is older and different from the source, depending on the compare method (default is size). If resume is not enabled, partial files are overwritten if they are older and different from the source, otherwise they are skipped. If resume is enabled, only partial files that are different and older than the source are overwritten, otherwise they are resumed.<br/>- `older` : Overwrite the file if its timestamp is older than the source timestamp.<br/>If you set an overwrite policy of `diff` or `diff+older`, difference is determined by the value set for `resume_policy`:<br/>`none` : The source and destination files are always considered different and the destination file is always overwritten<br/>`attributes` : The source and destination files are compared based on file attributes <br/>`sparse_checksum` : The source and destination files are compared based on sparse checksums, (currently file size)<br/>`full_checksum` : The source and destination files are compared based on full checksums<br/>Allowed values: `never`, `always`, `diff`, `older`, `diff+older`.<br/>Default: `diff`.<br/>(`--overwrite={enum}`) |
4706
5550
  | `password` | `String` | Password for local Windows user when transfer user associated with node API user is not the same as the one running `asperanoded`.<br/>Allows impersonating the transfer user and have access to resources (e.g. network shares).<br/>Windows only, node API only.<br/>(N) |
4707
5551
  | `paths` | `Array` | Array of path to the source (required) and a path to the destination (optional).<br/>Required. |
4708
5552
  | `precalculate_job_size` | `Bool` | Specifies whether to precalculate the job size.<br/>(`--precalculate-job-size / --precalculate-disable`) |
4709
5553
  | `preserve_access_time` | `Bool` | Preserve the source-file access timestamps at the destination.<br/>Because source access times are updated by the transfer operation, the timestamp that is preserved is the one just before to the transfer.<br/>(`--preserve-access-time`) |
4710
- | `preserve_acls` | `String` | Preserve access control lists.<br/>Allowed values: `none`, `native`, `metafile`.<br/>Default: `none`.<br/>(A, T)<br/>(`--preserve-acls={enum}`) |
5554
+ | `preserve_acls` | `Enum[String]` | Preserve access control lists.<br/>Allowed values: `none`, `native`, `metafile`.<br/>Default: `none`.<br/>(A, T)<br/>(`--preserve-acls={enum}`) |
4711
5555
  | `preserve_creation_time` | `Bool` | Preserve source-file creation timestamps at the destination.<br/>Only Windows systems retain information about creation time. If the destination is not a Windows computer, this option is ignored.<br/>(`--preserve-creation-time`) |
4712
- | `preserve_extended_attrs` | `String` | Preserve the extended attributes.<br/>Allowed values: `none`, `native`, `metafile`.<br/>Default: `none`.<br/>(A, T)<br/>(`--preserve-xattrs={enum}`) |
5556
+ | `preserve_extended_attrs` | `Enum[String]` | Preserve the extended attributes.<br/>Allowed values: `none`, `native`, `metafile`.<br/>Default: `none`.<br/>(A, T)<br/>(`--preserve-xattrs={enum}`) |
4713
5557
  | `preserve_file_owner_gid` | `Bool` | Preserve the group ID for a file owner.<br/>(A, T)<br/>(`--preserve-file-owner-gid`) |
4714
5558
  | `preserve_file_owner_uid` | `Bool` | Preserve the user ID for a file owner.<br/>(A, T)<br/>(`--preserve-file-owner-uid`) |
4715
5559
  | `preserve_modification_time` | `Bool` | Set the modification time, the last time a file or directory was modified (written), of a transferred file to the modification of the source file or directory.<br/>Preserve source-file modification timestamps at the destination.<br/>(`--preserve-modification-time`) |
4716
- | `preserve_remote_acls` | `String` | Preserve remote access control lists.<br/>Allowed values: `none`, `native`, `metafile`.<br/>Default: `none`.<br/>(A, T)<br/>(`--remote-preserve-acls={enum}`) |
4717
- | `preserve_remote_extended_attrs` | `String` | Preserve remote extended attributes.<br/>Allowed values: `none`, `native`, `metafile`.<br/>Default: `none`.<br/>(A, T)<br/>(`--remote-preserve-xattrs={enum}`) |
5560
+ | `preserve_remote_acls` | `Enum[String]` | Preserve remote access control lists.<br/>Allowed values: `none`, `native`, `metafile`.<br/>Default: `none`.<br/>(A, T)<br/>(`--remote-preserve-acls={enum}`) |
5561
+ | `preserve_remote_extended_attrs` | `Enum[String]` | Preserve remote extended attributes.<br/>Allowed values: `none`, `native`, `metafile`.<br/>Default: `none`.<br/>(A, T)<br/>(`--remote-preserve-xattrs={enum}`) |
4718
5562
  | `preserve_source_access_time` | `Bool` | Preserve the time logged for when the source file was accessed.<br/>(A, T)<br/>(`--preserve-source-access-time`) |
4719
5563
  | `preserve_times` | `Bool` | Preserve file timestamps.<br/>(A, N, T)<br/>(`-p`) |
4720
5564
  | `proxy` | `String` | Specify the address of the Aspera high-speed proxy server.<br/>`dnat(s)://[user[:password]@]server:port`<br/>Default ports for DNAT and DNATS protocols are 9091 and 9092.<br/>Password, if specified here, overrides the value of environment variable `ASPERA_PROXY_PASS`.<br/>(A)<br/>(`--proxy={string}`) |
4721
- | `rate_policy_allowed` | `String` | Specifies most aggressive rate policy that is allowed. Returned by node API.<br/>Allowed values: `low`, `fair`, `high`, `fixed`.<br/>(C) |
4722
- | `rate_policy` | `String` | The transfer rate policy to use when sharing bandwidth. Allowable values:<br/>- `high` : When sharing bandwidth, transfer at twice the rate of a transfer using a fair policy.<br/>- `fair` : (Default) Share bandwidth equally with other traffic.<br/>- `low` : Use only unused bandwidth.<br/>- `fixed` : Transfer at the target rate, regardless of the actual network capacity. Do not share bandwidth. Aspera recommends that you do not use this setting except under special circumstances, otherwise the destination storage can be damaged.<br/>Allowed values: `low`, `fair`, `high`, `fixed`.<br/>(`--policy={enum}`) |
5565
+ | `rate_policy` | `Enum[String]` | The transfer rate policy to use when sharing bandwidth. Allowable values:<br/>- `high` : When sharing bandwidth, transfer at twice the rate of a transfer using a fair policy.<br/>- `fair` : (Default) Share bandwidth equally with other traffic.<br/>- `low` : Use only unused bandwidth.<br/>- `fixed` : Transfer at the target rate, regardless of the actual network capacity. Do not share bandwidth. Aspera recommends that you do not use this setting except under special circumstances, otherwise the destination storage can be damaged.<br/>Allowed values: `low`, `fair`, `high`, `fixed`.<br/>(`--policy={enum}`) |
5566
+ | `rate_policy_allowed` | `Enum[String]` | Specifies most aggressive rate policy that is allowed. Returned by node API.<br/>Allowed values: `low`, `fair`, `high`, `fixed`.<br/>(C) |
4723
5567
  | `remote_access_key` | `String` | The access key ID of the access key that was used to construct the bearer token that is used to authenticate to the remote node.<br/>(T) |
4724
5568
  | `remote_host` | `String` | IP or fully qualified domain name (FQDN) of the remote server.<br/>Required.<br/>(`--host={string}`) |
4725
5569
  | `remote_password` | `String` | SSH session password.<br/>(env:`ASPERA_SCP_PASS`) |
@@ -4729,27 +5573,27 @@ The description gives the supported agents, if not all, and the corresponding `a
4729
5573
  | `remove_empty_source_dir` | `Bool` | Remove empty source subdirectories and remove the source directory itself, if empty.<br/>(T) |
4730
5574
  | `remove_empty_source_directory` | `Bool` | Remove empty source subdirectories and remove the source directory itself, if empty.<br/>(A)<br/>(`--remove-empty-source-directory`) |
4731
5575
  | `remove_skipped` | `Bool` | Must also have `remove_after_transfer` set to `true`. Defaults to `false`. If `true`, skipped files will be removed as well.<br/>(A, C, N)<br/>(`--remove-skipped`) |
4732
- | `resume_policy` | `String` | If a transfer is interrupted or fails to finish, this policy directs the transfer to resume without retransferring the files. Allowable values:<br/>- `none` : Always re-transfer the entire file.<br/>- `attrs` : Compare file attributes and resume if they match, and re-transfer if they do not.<br/>- `sparse_csum` : Compare file attributes and the sparse file checksums; resume if they match, and re-transfer if they do not.<br/>- `full_csum` : Compare file attributes and the full file checksums; resume if they match, and re-transfer if they do not.<br/>Note: transferd uses values: `attributes`, `sparse_checksum`, `full_checksum`.<br/>Allowed values: `none`, `attrs`, `sparse_csum`, `full_csum`.<br/>Default: `faspmgr:none;other:sparse_csum`.<br/>(`-k (conversion){enum}`) |
5576
+ | `resume_policy` | `Enum[String]` | If a transfer is interrupted or fails to finish, this policy directs the transfer to resume without retransferring the files. Allowable values:<br/>- `none` : Always re-transfer the entire file.<br/>- `attrs` : Compare file attributes and resume if they match, and re-transfer if they do not.<br/>- `sparse_csum` : Compare file attributes and the sparse file checksums; resume if they match, and re-transfer if they do not.<br/>- `full_csum` : Compare file attributes and the full file checksums; resume if they match, and re-transfer if they do not.<br/>Note: transferd uses values: `attributes`, `sparse_checksum`, `full_checksum`.<br/>Allowed values: `none`, `attrs`, `sparse_csum`, `full_csum`.<br/>Default: `faspmgr:none;other:sparse_csum`.<br/>(`-k (conversion){enum}`) |
4733
5577
  | `retry_duration` | `Integer, String` | Specifies how long to wait before retrying transfer (e.g. `5min`).<br/>(T) |
4734
5578
  | `save_before_overwrite` | `Bool` | If a transfer would result in an existing file <filename>.<ext> being overwritten, move that file to <filename>.yyyy.mm.dd.hh.mm.ss.index.<ext> (where index is set to 1 at the beginning of each new second and incremented for each file saved in this manner during the same second) in the same directory before writing the new file.<br/>File attributes are maintained in the renamed file.<br/>(A, N, T)<br/>(`--save-before-overwrite`) |
4735
5579
  | `skip_duplicate_check` | `Bool` | Don't check for duplicate files at the destination.<br/>(A, T)<br/>(`--skip-dir-traversal-dupes`) |
4736
5580
  | `skip_special_files` | `Bool` | All assets other than files, directories and symbolic links are considered special. A transfer will fail if the user attempts to transfer special assets. If `true`, `ascp` skips special assets and proceeds with the transfer of all other assets.<br/>(A, T)<br/>(`--skip-special-files`) |
4737
- | `source_root_id` | `String` | The file ID of the source root directory. Required when using Bearer token auth for the source node.<br/>(N, T) |
4738
5581
  | `source_root` | `String` | Path to be prepended to each source path.<br/>This is either a conventional path or it can be a URI but only if there is no root defined.<br/>(`--source-prefix64=(conversion){string}`) |
4739
- | `src_base64` | `String` | The folder name below which the directory structure is preserved (base64 encoded).<br/>(A, T)<br/>(`--src-base64={string}`) |
5582
+ | `source_root_id` | `String` | The file ID of the source root directory. Required when using Bearer token auth for the source node.<br/>(N, T) |
4740
5583
  | `src_base` | `String` | Specify the prefix to be stripped off from each source object.<br/>The remaining portion of the source path is kept intact at the destination.<br/>Special care must be taken when used with cloud storage.<br/>(A, N, T)<br/>(`--src-base64=(conversion){string}`) |
5584
+ | `src_base64` | `String` | The folder name below which the directory structure is preserved (base64 encoded).<br/>(A, T)<br/>(`--src-base64={string}`) |
4741
5585
  | `ssh_args` | `Array` | Add arguments to the command-line arguments passed to the external ssh program (implies -SSH). The arguments are inserted before any key file(s) supplied to `ascp` and before the user/host arguments.<br/>(A, T)<br/>(special:`--ssh-arg={array}`) |
4742
5586
  | `ssh_port` | `Integer` | Specifies SSH (TCP) port.<br/>Default: `direct:22, other:33001`.<br/>(`-P {integer}`) |
5587
+ | `ssh_private_key` | `String` | Private key used for SSH authentication.<br/>Shall look like: -----BEGIN RSA PRIV4TE KEY-----&bsol;nMII...<br/>Note the JSON encoding: &bsol;n for newlines.<br/>(A, T)<br/>(env:`ASPERA_SCP_KEY`) |
4743
5588
  | `ssh_private_key_passphrase` | `String` | The passphrase associated with the transfer user's SSH private key. Available as of 3.7.2.<br/>(A, T)<br/>(env:`ASPERA_SCP_PASS`) |
4744
5589
  | `ssh_private_key_path` | `String` | Path to private key for SSH.<br/>(A, T)<br/>(`-i {string}`) |
4745
- | `ssh_private_key` | `String` | Private key used for SSH authentication.<br/>Shall look like: -----BEGIN RSA PRIV4TE KEY-----&bsol;nMII...<br/>Note the JSON encoding: &bsol;n for newlines.<br/>(A, T)<br/>(env:`ASPERA_SCP_KEY`) |
4746
5590
  | `sshfp` | `String` | Check it against server SSH host key fingerprint.<br/>(`--check-sshfp={string}`) |
4747
- | `symlink_policy` | `String` | Handle source side symbolic links. Refer to HSTS manual for more details.<br/>- `follow`: Follow a symbolic link and transfer the contents of the linked file or directory when the link target is in the user's docroot.<br/>- `copy`: Copy only the symbolic link. If a file with the same name exists at the destination, the symbolic link does not replace the file.<br/>- `skip`: Skip-symbolic links. The link or the file to which it points are not transferred.<br/>- `copy+force`: Copy only the symbolic link. If a file with the same name exists at the destination, the symbolic link replaces the file. If the file of the same name at the destination is a symbolic link to a directory, it is not replaced.<br/>Allowed values: `follow`, `copy`, `copy+force`, `skip`.<br/>Default: `follow`.<br/>(`--symbolic-links={enum}`) |
4748
- | `tags64` | `String` | Base64 string for `tags`.<br/>(A, T)<br/>(`--tags64={string}`) |
5591
+ | `symlink_policy` | `Enum[String]` | Handle source side symbolic links. Refer to HSTS manual for more details.<br/>- `follow`: Follow a symbolic link and transfer the contents of the linked file or directory when the link target is in the user's docroot.<br/>- `copy`: Copy only the symbolic link. If a file with the same name exists at the destination, the symbolic link does not replace the file.<br/>- `skip`: Skip-symbolic links. The link or the file to which it points are not transferred.<br/>- `copy+force`: Copy only the symbolic link. If a file with the same name exists at the destination, the symbolic link replaces the file. If the file of the same name at the destination is a symbolic link to a directory, it is not replaced.<br/>Allowed values: `follow`, `copy`, `copy+force`, `skip`.<br/>Default: `follow`.<br/>(`--symbolic-links={enum}`) |
4749
5592
  | `tags` | `Hash` | Metadata for transfer as JSON. Key `aspera` is reserved. Key `aspera.xfer_retry` specifies a "retry timeout" but is not actually used for node API initiated transfers.<br/>(`--tags64=(conversion){object}`) |
5593
+ | `tags64` | `String` | Base64 string for `tags`.<br/>(A, T)<br/>(`--tags64={string}`) |
5594
+ | `target_rate` | `String, Integer` | Pseudo-parameter: desired transfer rate in bps, with an optional unit suffix. Converted to `target_rate_kbps` (rounded down) before the transfer is started, overriding it if both are present. Also applies to `async` (sync). Accepted formats: integer (bps), or integer followed by `k`/`K` (x1000), `m`/`M` (x1000000), `g`/`G` (x1000000000). Examples: `100000000`, `100000k`, `100m`, `1g`. |
4750
5595
  | `target_rate_cap_kbps` | `Integer` | Maximum target rate for incoming transfers, in kilobits per second. Returned by upload/download_setup node API.<br/>(C, T) |
4751
5596
  | `target_rate_kbps` | `Integer` | Specifies desired speed for the transfer.<br/>(`-l {integer}`) |
4752
- | `target_rate` | `String, Integer` | Pseudo-parameter: desired transfer rate in bps, with an optional unit suffix. Converted to `target_rate_kbps` (rounded down) before the transfer is started, overriding it if both are present. Also applies to `async` (sync). Accepted formats: integer (bps), or integer followed by `k`/`K` (x1000), `m`/`M` (x1000000), `g`/`G` (x1000000000). Examples: `100000000`, `100000k`, `100m`, `1g`. |
4753
5597
  | `title` | `String` | Title of the transfer.<br/>(C, N, T) |
4754
5598
  | `token` | `String` | Authorization token. Type is Bearer, Basic or ATM.<br/>(env:`ASPERA_SCP_TOKEN`) |
4755
5599
  | `use_ascp4` | `Bool` | Specify version of protocol. `ascp4` will be deprecated.<br/>Default: `false`.<br/>(A, N, T) |
@@ -5563,7 +6407,7 @@ If the transfer user has no docroot and the transfer does not use a token, you c
5563
6407
  ```text
5564
6408
  ascli -h
5565
6409
  NAME
5566
- ascli -- a command line tool for Aspera Applications (v4.28.0)
6410
+ ascli -- a command line tool for Aspera Applications (v4.29.0)
5567
6411
 
5568
6412
  SYNOPSIS
5569
6413
  ascli [GLOBAL_OPTIONS] <command> [OPTIONS] [ARGS]
@@ -5574,6 +6418,7 @@ DESCRIPTION
5574
6418
  execute: ascli conf doc
5575
6419
  or visit: https://ibm.biz/ascli-doc
5576
6420
  source repo: https://github.com/IBM/aspera-cli
6421
+ AI assistants: ascli config commands, https://ibm.github.io/aspera-cli/llms.txt
5577
6422
 
5578
6423
  ENVIRONMENT VARIABLES
5579
6424
  Any option can be set as an environment variable, refer to the manual
@@ -5619,7 +6464,7 @@ OPTIONS: global
5619
6464
  -h, --help Show this message
5620
6465
  --show-config Display parameters used for the provided action
5621
6466
  -v, --version Display version
5622
- --ui=HASH User interface (dot-notation: mode, command)
6467
+ --ui=HASH User interface (dot-notation: mode, web_auth, command)
5623
6468
  --invalid-characters=VALUE Replacement character and invalid filename characters
5624
6469
  --log-level=ENUM Log level
5625
6470
  --log-format=VALUE Log formatter
@@ -5628,6 +6473,7 @@ OPTIONS: global
5628
6473
  --security=HASH Security restrictions (dot-notation: level, allowed_paths)
5629
6474
  --lock-port=INT Prevent dual execution of a command, e.g. in cron
5630
6475
  --once-only=yes|no Process only new items (some commands)
6476
+ --dry-run=yes|no Do not perform changes, only show what would be done
5631
6477
  --log-secrets=yes|no Show passwords in logs
5632
6478
  --temp=HASH Temporary files (dot-notation: folder, clean, expiry)
5633
6479
  --clean-temp=yes|no Cleanup temporary files on exit (deprecated after 4.27.5: use --temp.clean)
@@ -5643,6 +6489,7 @@ OPTIONS: global
5643
6489
  --fpac=VALUE Proxy auto configuration script
5644
6490
  --proxy-credentials=LIST HTTP proxy credentials for fpac: user, password
5645
6491
  --sql=VALUE SQL suffix appended to sqlite3 queries for admin subcommands (e.g. WHERE clause)
6492
+ --ascp-logs=HASH Ascp: log analysis (dot-notation: period, zero_bytes, mtu, resolve, thresholds, timezone, health_minutes, remote_max_size)
5646
6493
  -P, --preset=VALUE Load the named option preset from current config file
5647
6494
  --version-check-days=INT Period in days to check new version (zero to disable)
5648
6495
  --plugin-folder=VALUE Folder where to find additional plugins
@@ -5655,9 +6502,6 @@ OPTIONS: global
5655
6502
  --cache-tokens=yes|no Save and reuse OAuth tokens
5656
6503
  --expand-mounts=yes|no Commands: list commands of sub-trees provided by another plugin
5657
6504
  -N, --no-default Do not load default configuration for plugin
5658
- --override=yes|no Wizard: override existing value
5659
- --default=yes|no Wizard: set as default configuration for specified plugin (also: update)
5660
- --key-path=VALUE Wizard: path to private key for JWT
5661
6505
  --insecure=yes|no HTTP/S: Do not validate any certificate
5662
6506
  --ignore-certificate=LIST HTTP/S: Do not validate certificate for these URLs
5663
6507
  --warn-insecure=yes|no HTTP/S: Issue a warning if certificate is ignored
@@ -5689,6 +6533,7 @@ PLUGINS
5689
6533
  preview Preview
5690
6534
  server HSTS Fasp/SSH
5691
6535
  shares Shares
6536
+ transferd Transfer Daemon
5692
6537
 
5693
6538
 
5694
6539
  ```
@@ -5699,25 +6544,6 @@ Bulk creation and deletion of resources are possible using option `bulk` (`yes`,
5699
6544
  In that case, the operation expects an `Array` of `Hash` instead of a simple `Hash` using the [Extended Value](#extended-value-syntax) syntax.
5700
6545
  This option is available only for some resources: if you need it, try and see if the entities you create or delete support this option.
5701
6546
 
5702
- ### Option: `query`
5703
-
5704
- The `query` option can generally be used to add URL parameters to commands that list resources.
5705
- It takes a `Hash`, corresponding to key/value pairs that appear in the query part of the request.
5706
-
5707
- For example: `--query=@json:'{"p1":"v1","p2":"v2"}'` leads to query: `?p1=v1&p2=v2`.
5708
-
5709
- If the same parameter needs to be provided several times, then it is also possible to provide an `Array`.
5710
-
5711
- For example: `--query=@json:'{"p":["v1","v2"]}'` leads to query: `?p=v1&p=v2`.
5712
-
5713
- If PHP-style arrays are expected in the API, add `[]` to the name of the parameter.
5714
-
5715
- For example: `--query=@json:'{"p[]":["v1","v2"]}'` leads to query: `?p[]=v1&p[]=v2`.
5716
-
5717
- > [!TIP]
5718
- > Use `--query=help` on any `list` command to display the available query parameters and their types, as documented in the API.
5719
- > For example: `ascli faspex5 admin accounts list --query=help`
5720
-
5721
6547
  ### Plugins
5722
6548
 
5723
6549
  `ascli` uses a plugin mechanism.
@@ -5761,7 +6587,6 @@ ascli config plugins create foo .
5761
6587
  Created ./foo.rb
5762
6588
  ```
5763
6589
 
5764
-
5765
6590
  ```shell
5766
6591
  ascli --plugin-folder=. foo
5767
6592
  ```
@@ -5834,7 +6659,7 @@ It's up to the program to split arguments:
5834
6659
 
5835
6660
  `ascli` is a Ruby program, so Ruby parses the command line (received with `GetCommandLineW`) into arguments and provides them to the Ruby code (`$0` and `ARGV`).
5836
6661
  Ruby vaguely follows the Microsoft C/C++ parameter parsing rules.
5837
- (See `w32_cmdvector` in Ruby source [`win32.c`](https://github.com/ruby/ruby/blob/master/win32/win32.c#L1766)): <!--cspell:disable-line-->
6662
+ (See `w32_cmdvector` in Ruby source [`win32.c`](https://github.com/ruby/ruby/blob/master/win32/win32.c#L1766)):
5838
6663
 
5839
6664
  - Space characters: split arguments (space, tab, newline)
5840
6665
  - Backslash: `\` escapes a single special character
@@ -6144,11 +6969,13 @@ To complete the setup, you must have:
6144
6969
 
6145
6970
  #### Wizard Invocation
6146
6971
 
6147
- The wizard accepts two optional positional arguments:
6972
+ The wizard accepts an optional argument, a `Hash` with keys:
6148
6973
 
6149
- - **Organization/URL**: The organization name or the full FQDN.
6974
+ - `url`: The organization name or the full FQDN.
6150
6975
 
6151
- - **Plugin Name**: Specify `aoc` to bypass automatic application detection.
6976
+ - `plugin`: Specify `aoc` to bypass automatic application detection.
6977
+
6978
+ - `preset`: Name of the preset to create.
6152
6979
 
6153
6980
  If the URL is omitted, the wizard will prompt for it interactively.
6154
6981
 
@@ -6165,8 +6992,8 @@ Once saved in the UI, return to the terminal and press Enter.
6165
6992
  ```console
6166
6993
  $ ascli config wizard
6167
6994
  Using: Aspera on Cloud at https://<ORG_NAME>.ibmaspera.com
6168
- Path to private RSA key (leave empty to generate):
6169
- option: key_path>
6995
+ Private RSA key, e.g. @file:<path> (leave empty to generate):
6996
+ option: private_key>
6170
6997
  Using existing key:
6171
6998
  /home/john/.aspera/ascli/<PKEY_NAME>.pem
6172
6999
  Please Log in as user john@example.com at: https://<ORG_NAME>.ibmaspera.com
@@ -6191,12 +7018,12 @@ Saving config file.
6191
7018
 
6192
7019
  - **Custom Client Identification**:
6193
7020
  By default, `ascli` uses a pre-registered global client ID.
6194
- To create and use an organization-specific integration, use the `--use-generic-client=no` flag.
7021
+ To create and use an organization-specific integration, give the option `--use-generic-client=no` of plugin `aoc` to the wizard command.
6195
7022
 
6196
7023
  - **Direct Plugin Targeting**: To limit detection to the `aoc` plugin and skip discovery, provide both the URL and plugin name:
6197
7024
 
6198
7025
  ```shell
6199
- ascli config wizard <ORG_NAME> aoc
7026
+ ascli config wizard @: url=<ORG_NAME> plugin=aoc
6200
7027
  ```
6201
7028
 
6202
7029
  #### Verifying the Configuration
@@ -6262,6 +7089,7 @@ To register with web-based authentication (auth=web):
6262
7089
 
6263
7090
  > [!NOTE]
6264
7091
  > For web based authentication, `ascli` listens on a local port (for example, specified by the `redirect_uri` parameter, in this example: `12345`), and the browser will provide the OAuth code there.
7092
+ > See [Web login flow](#web-login-flow).
6265
7093
  > For `ascli`, HTTP is required, and `12345` is the default port.
6266
7094
  > The host of `redirect_uri` shall be loopback: `localhost`, an address of `127.0.0.0/8`, or `[::1]`.
6267
7095
 
@@ -6284,7 +7112,7 @@ updated: <AOC_ORG>
6284
7112
  > [!NOTE]
6285
7113
  > In above example, replace `https://<ORG_NAME>.ibmaspera.com` with your actual AoC URL.
6286
7114
 
6287
- (This can also be done in one line using the command `config preset update <AOC_ORG> --url=...`)
7115
+ (This can also be done in one line using the command `config preset set <AOC_ORG> @: url=...`)
6288
7116
 
6289
7117
  Define this [Option Preset](#option-preset) as default configuration for the `aoc` plugin:
6290
7118
 
@@ -6398,7 +7226,7 @@ To activate default use of JWT authentication for `ascli` using the [Option Pres
6398
7226
  Execute:
6399
7227
 
6400
7228
  ```shell
6401
- ascli config preset update <AOC_ORG> --auth=jwt --private-key=@val:@file:~/.aspera/ascli/<PKEY_NAME> --username=someuser@example.com
7229
+ ascli config preset set <AOC_ORG> @: auth=jwt private_key=@val:@file:~/.aspera/ascli/<PKEY_NAME> username=someuser@example.com
6402
7230
  ```
6403
7231
 
6404
7232
  > [!NOTE]
@@ -6518,7 +7346,7 @@ The following parameters are supported:
6518
7346
  | other | Native | Other specific parameters depending on resource type. |
6519
7347
 
6520
7348
  > [!NOTE]
6521
- > Both `max` and `pmax` are processed internally in `ascli`, not included in actual API call and limit the number of successive pages requested to API.
7349
+ > Both `max` and `pmax` are processed by `ascli` (see [option `--query`](#option---query-parameters-of-the-api)).
6522
7350
  > `ascli` will return all values using paging if not provided.
6523
7351
  > `page` and `per_page` are normally added by `ascli` to build successive API calls to get all values if there are more than 1000
6524
7352
  > (AoC allows a maximum page size of 1000).
@@ -6529,7 +7357,7 @@ The following parameters are supported:
6529
7357
  > For example: `ascli aoc admin user list --query=help`
6530
7358
 
6531
7359
  > [!TIP]
6532
- > The option `select` can also be used to further refine selection, refer to [section earlier](#option-select).
7360
+ > Options `--out.query` and `--out.select` can also be used to further refine selection, refer to [Filtering results](#filtering-results).
6533
7361
 
6534
7362
  Examples:
6535
7363
 
@@ -6785,7 +7613,7 @@ ascli aoc user settings modify <ID> @json:'{"value":"..."}'
6785
7613
  > - **Application identity**: derived from the `client_id` used during authentication.
6786
7614
  >
6787
7615
  > This means that settings stored by one client application (for example, the AoC web UI) are not visible to another (for example, `ascli` using a different `client_id`).
6788
- > By default, `ascli` uses the pre-registered global `client_id` (see `--use-generic-client`).
7616
+ > By default, `ascli` uses the pre-registered global `client_id` (see option `--use-generic-client` of plugin `aoc`).
6789
7617
 
6790
7618
  #### Example: Create a sub access key in a `node`
6791
7619
 
@@ -6954,7 +7782,7 @@ In this example, a user has access to a workspace where two shared folders are l
6954
7782
  First, set up the environment (skip if already done), see [AoC configuration: Using Wizard](#aoc-configuration-using-wizard):
6955
7783
 
6956
7784
  ```shell
6957
- ascli config wizard https://sedemo.ibmaspera.com aoc aoc_sedemo --username=someuser@example.com
7785
+ ascli config wizard @: url=https://sedemo.ibmaspera.com plugin=aoc preset=aoc_sedemo --username=someuser@example.com
6958
7786
  ```
6959
7787
 
6960
7788
  This creates the option preset `aoc_sedemo` to allow seamless command line access and sets it as default for Aspera on Cloud.
@@ -7241,7 +8069,7 @@ The `package_folder` option (`Hash`) controls how downloaded packages are organi
7241
8069
  **Supported Fields**:
7242
8070
 
7243
8071
  | Field | Type | Description |
7244
- |-------|---------------|----------------------------------------------------------------------------------|
8072
+ | ----- | ------------- | -------------------------------------------------------------------------------- |
7245
8073
  | `fld` | `Array[String]` | List of package fields (up to 2) used to build the subfolder name. Field values are joined with `.`.<br/>Example: `["name", "id"]`. |
7246
8074
  | `inf` | `Bool` | If `true`, creates a `<ID>.info.json` sidecar file inside the folder containing package metadata.<br/>Default: `false`. |
7247
8075
  | `opt` | `Bool` | If `false` (default), all fields in `fld` are always used. If `true`, the first field is used unless the folder already exists.<br/>Default: `false`. |
@@ -7723,7 +8551,7 @@ For instructions, refer to section `find` for plugin `node`.
7723
8551
 
7724
8552
  ```shell
7725
8553
  admin analytics application_events
7726
- admin analytics files organization '' <id>
8554
+ admin analytics files organization '' <ID>
7727
8555
  admin analytics transfers organization --query=@json:'{"status":"completed","direction":"receive","limit":2}' --notify-to=my_email_external --notify-template=@ruby:'%Q{From: <%=from_name%> <<%=from_email%>>\nTo: <<%=to%>>\nSubject: <%=ev["files_completed"]%> files received\n\n<%=ev.to_yaml%>}'
7728
8556
  admin analytics transfers users --once-only=yes
7729
8557
  admin application instance list
@@ -7731,8 +8559,8 @@ admin application instance list --query.aspera_app_type=files
7731
8559
  admin application instance list --query.organization_apps=true
7732
8560
  admin application membership list
7733
8561
  admin application types
7734
- admin ats access_key create --cloud=aws --region=my_region @json:'{"id":"ak_aws_aoc","name":"my test key AWS","storage":{"type":"aws_s3","bucket":"my_bucket","credentials":{"access_key_id":"my_access_key","secret_access_key":"my_secret_key"},"path":"/"}}'
7735
- admin ats access_key create --cloud=softlayer --region=my_region @: id=ak1ibmcloud secret=<SECRET> 'name="my test key"' storage.type=ibm-s3 storage.bucket=my_bucket storage.credentials.access_key_id=my_access_key storage.credentials.secret_access_key=my_secret_key storage.path=/
8562
+ admin ats access_key create --cloud=aws --region=my_region @json:'{"id":"ak_aws_aoc","name":"my test key AWS","storage":{"type":"aws_s3","bucket":"my_bucket","credentials":{"access_key_id":"<ACCESS_KEY>","secret_access_key":"<SECRET_KEY>"},"path":"/"}}'
8563
+ admin ats access_key create --cloud=softlayer --region=my_region @: id=ak1ibmcloud secret=<SECRET> 'name="my test key"' storage.type=ibm-s3 storage.bucket=my_bucket storage.credentials.access_key_id=<ACCESS_KEY> storage.credentials.secret_access_key=<SECRET_KEY> storage.path=/
7736
8564
  admin ats access_key delete ak1ibmcloud
7737
8565
  admin ats access_key list --fields=name,id
7738
8566
  admin ats access_key node ak1ibmcloud --secret=<SECRET> browse /
@@ -7745,10 +8573,10 @@ admin bearer_token --out.level=data --out.secrets=yes
7745
8573
  admin client list
7746
8574
  admin client_access_key list
7747
8575
  admin client_registration_token create @json:'{"data":{"name":"test_client_reg1","client_subject_scopes":["alee","aejd"],"client_subject_enabled":true}}'
7748
- admin client_registration_token delete <id>
8576
+ admin client_registration_token delete <ID>
7749
8577
  admin client_registration_token list
7750
8578
  admin configuration_policy list
7751
- admin configuration_policy show <id>
8579
+ admin configuration_policy show <ID>
7752
8580
  admin contact list
7753
8581
  admin dropbox list
7754
8582
  admin dropbox_membership list
@@ -7756,7 +8584,7 @@ admin group list
7756
8584
  admin group_membership list --fields=ALL --query=@json:'{"page":1,"per_page":50,"embed":"member","inherited":false,"workspace_id":11363,"sort":"name"}'
7757
8585
  admin kms_profile list
7758
8586
  admin network_policy list
7759
- admin network_policy show <id>
8587
+ admin network_policy show <ID>
7760
8588
  admin node bearer_token %name:my_node_name user:all
7761
8589
  admin node do %name:my_node_name --secret=<AK_SECRET> browse /
7762
8590
  admin node do %name:my_node_name --secret=<AK_SECRET> browse /folder_sub --node-api.cache=false
@@ -7764,8 +8592,8 @@ admin node do %name:my_node_name --secret=<AK_SECRET> delete /folder1
7764
8592
  admin node do %name:my_node_name --secret=<AK_SECRET> delete /folder_sub
7765
8593
  admin node do %name:my_node_name --secret=<AK_SECRET> mkdir /folder1
7766
8594
  admin node do %name:my_node_name --secret=<AK_SECRET> mkdir /folder_sub
7767
- admin node do %name:my_node_name --secret=<AK_SECRET> v3 access_key create @json:'{"id":"testsub1","storage":{"path":"/folder_sub"}}'
7768
- admin node do %name:my_node_name --secret=<AK_SECRET> v3 access_key delete testsub1
8595
+ admin node do %name:my_node_name --secret=<AK_SECRET> v3 access_key create @json:'{"id":"test-sub-1","storage":{"path":"/folder_sub"}}'
8596
+ admin node do %name:my_node_name --secret=<AK_SECRET> v3 access_key delete test-sub-1
7769
8597
  admin node do %name:my_node_name --secret=<AK_SECRET> v3 events
7770
8598
  admin node do %name:my_node_name delete test_shared_folder
7771
8599
  admin node do %name:my_node_name mkdir test_shared_folder
@@ -7790,12 +8618,15 @@ admin user preferences %name:my_user_email show
7790
8618
  admin workspace dropbox %name:my_other_workspace list
7791
8619
  admin workspace list
7792
8620
  admin workspace shared_folder %name:my_other_workspace list
7793
- admin workspace shared_folder %name:my_other_workspace member <id> list
8621
+ admin workspace shared_folder %name:my_other_workspace member <ID> list
8622
+ admin workspace shared_folder %name:my_other_workspace node <ID> browse /
7794
8623
  admin workspace_membership list
7795
8624
  admin workspace_membership list --fields=ALL --query=@json:'{"page":1,"per_page":50,"embed":"member","inherited":false,"workspace_id":11363,"sort":"name"}'
7796
- automation workflow action <id> create @: name=toto
8625
+ automation workflow action <ID> create @: name=toto
7797
8626
  automation workflow create @: name=test_workflow
7798
- automation workflow delete <id>
8627
+ automation workflow delete <ID>
8628
+ automation workflow details <ID>
8629
+ automation workflow export <ID>
7799
8630
  automation workflow list
7800
8631
  automation workflow list --query.show_org_workflows=@val:true
7801
8632
  automation workflow list --select.name=test_workflow --fields=id
@@ -7803,65 +8634,66 @@ bearer_token --out.level=data --out.secrets=yes
7803
8634
  files bearer /
7804
8635
  files bearer_token_node / --cache-tokens=no
7805
8636
  files browse /
7806
- files browse / --url=my_private_link_shared_folder
7807
- files browse / --url=my_public_link_folder_no_pass
7808
- files browse / --url=my_public_link_folder_with_pass --password=<PUBLIC_LINK_FOLDER_PASSWORD>
8637
+ files browse / --url=<PRIVATE_LINK_SHARED_FOLDER>
8638
+ files browse / --url=<PUBLIC_LINK_FOLDER_NO_PASS>
8639
+ files browse / --url=<PUBLIC_LINK_FOLDER_WITH_PASS> --password=<PUBLIC_LINK_FOLDER_PASSWORD>
7809
8640
  files browse my_remote_file
7810
8641
  files browse my_remote_folder
7811
8642
  files browse my_remote_folder/
7812
- files cat testdst/test_file.bin
7813
- files delete /testsrc
7814
- files download --to-folder=. testdst/test_file.bin testdst/test_file.bin
7815
- files download --transfer.agent=connect testdst/test_file.bin
7816
- files download --transfer.agent=desktop testdst/test_file.bin
8643
+ files cat test-dst/test_file.bin
8644
+ files delete /test-src
8645
+ files download --to-folder=. test-dst/test_file.bin test-dst/test_file.bin
8646
+ files download --transfer.agent=connect test-dst/test_file.bin
8647
+ files download --transfer.agent=desktop test-dst/test_file.bin
7817
8648
  files find /sample_video
7818
8649
  files find /sample_video '\.partial$'
7819
8650
  files find /sample_video @ruby:'->(f){f["type"].eql?("file")}'
7820
- files mkdir /testsrc
8651
+ files mkdir /test-src
7821
8652
  files modify /some_folder @: mount_point=false
7822
8653
  files permission my_test_folder list
7823
- files rename /some_folder testdst
7824
- files short_link /testdst private create
7825
- files short_link /testdst private list
7826
- files short_link /testdst public create @: access_levels.0=mkdir access_levels.1=write --fields=id
7827
- files short_link /testdst public modify <aoc_short_link_pub_create> @: access_levels=edit
7828
- files show %id:<id>
8654
+ files rename /some_folder test-dst
8655
+ files short_link /test-dst private create
8656
+ files short_link /test-dst private list
8657
+ files short_link /test-dst public create @: access_levels.0=mkdir access_levels.1=write --fields=id
8658
+ files short_link /test-dst public modify <AOC_SHORT_LINK_PUB_CREATE> @: access_levels=edit
8659
+ files show %id:<ID>
7829
8660
  files show /
7830
- files show testdst/test_file.bin
8661
+ files show test-dst/test_file.bin
7831
8662
  files sync admin status /data/local_sync
7832
- files sync pull /testdst --to-folder=/data/local_sync @json:'{"reset":true,"transport":{"target_rate":my_bps}}'
8663
+ files sync pull /test-dst --to-folder=/data/local_sync @json:'{"reset":true,"transport":{"target_rate":my_bps}}'
7833
8664
  files thumbnail my_test_folder/video_file.mpg
7834
8665
  files thumbnail my_test_folder/video_file.mpg --query.text=true --query.double=true
7835
- files transfer push /testsrc --to-folder=/testdst test_file.bin
7836
- files upload --to-folder=/ test_file.bin --url=my_public_link_folder_no_pass
7837
- files upload --to-folder=/testsrc test_file.bin
7838
- files upload --to-folder=/testsrc test_file.bin test_file.bin
8666
+ files transfer push /test-src --to-folder=/test-dst test_file.bin
8667
+ files upload --to-folder=/ test_file.bin --url=<PUBLIC_LINK_FOLDER_NO_PASS>
8668
+ files upload --to-folder=/test-src test_file.bin
8669
+ files upload --to-folder=/test-src test_file.bin test_file.bin
7839
8670
  files v3 info
7840
8671
  gateway @: url=https://localhost:12347/aspera/faspex
7841
8672
  organization
7842
8673
  organization --format=image --fields=background_image_url --ui=text
7843
- organization --url=my_public_link_recv_from_aoc_user
7844
- packages browse <id> /
8674
+ organization --url=<PUBLIC_LINK_RECV_FROM_AOC_USER>
8675
+ packages browse <ID> /
7845
8676
  packages list
7846
8677
  packages list --query=@json:'{"dropbox_name":"my_shared_inbox_name","sort":"-received_at","archived":false,"received":true,"has_content":true,"exclude_dropbox_packages":false}'
7847
- packages receive <id> --to-folder=.
7848
- packages receive <id> --to-folder=. /
8678
+ packages receive <ID> --to-folder=.
8679
+ packages receive <ID> --to-folder=. /
7849
8680
  packages receive ALL --once-only=yes --to-folder=. --query.max=5 --lock-port=50101 --package-folder.fld.0=name --package-folder.fld.1=id --package-folder.opt=true
7850
8681
  packages receive ALL --once-only=yes --to-folder=. --query.max=5 --lock-port=50101 --query=@json:'{"dropbox_name":"my_shared_inbox_name","archived":false,"received":true,"has_content":true,"exclude_dropbox_packages":false,"include_draft":false}' --ts=@json:'{"resume_policy":"sparse_csum","target_rate_kbps":50000}'
8682
+ packages receive ALL --url=<PUBLIC_LINK_RECV_FROM_AOC_USER> --to-folder=.
7851
8683
  packages receive INIT --once-only=yes --query.dropbox_name=my_shared_inbox_name
7852
8684
  packages send --workspace=my_workspace_shared_inbox --validate-metadata=yes @json:'{"name":"package title","recipients":["my_shared_inbox_meta"],"metadata":[{"input_type":"single-text","name":"Project Id","values":["123"]},{"input_type":"single-dropdown","name":"Type","values":["Opt2"]},{"input_type":"multiple-checkbox","name":"CheckThose","values":["Check1","Check2"]},{"input_type":"date","name":"Optional Date","values":["2021-01-13T15:02:00.000Z"]}]}' test_file.bin
7853
8685
  packages send --workspace=my_workspace_shared_inbox --validate-metadata=yes @json:'{"name":"package title","recipients":["my_shared_inbox_meta"],"metadata":{"Project Id":"456","Type":"Opt2","CheckThose":["Check1","Check2"],"Optional Date":"2021-01-13T15:02:00.000Z"}}' test_file.bin
7854
8686
  packages send --workspace=my_workspace_shared_inbox @json:'{"name":"package title","recipients":["my_shared_inbox_name"]}' test_file.bin
7855
- packages send @: 'name=package title' END test_file.bin --url=my_public_link_send_aoc_user --password=<PUBLIC_LINK_SEND_USE_PASS>
7856
- packages send @: 'name=package title' END test_file.bin --url=my_public_link_send_shared_inbox
8687
+ packages send @: 'name=package title' END test_file.bin --url=<PUBLIC_LINK_SEND_AOC_USER> --password=<PUBLIC_LINK_SEND_USE_PASS>
8688
+ packages send @: 'name=package title' END test_file.bin --url=<PUBLIC_LINK_SEND_SHARED_INBOX>
7857
8689
  packages send @: 'name=package title' recipients.0=my_username 'note=some notes' END test_file.bin
7858
8690
  packages send @json:'{"name":"package title","recipients":["my_email_external"]}' --new-user-option.package_contact=true test_file.bin
7859
8691
  packages shared_inboxes list
7860
8692
  packages shared_inboxes short_link public %name:my_shared_inbox_name create --fields=id
7861
- packages shared_inboxes short_link public %name:my_shared_inbox_name delete <aoc_shared_inbox_short_link_create>
8693
+ packages shared_inboxes short_link public %name:my_shared_inbox_name delete <AOC_SHARED_INBOX_SHORT_LINK_CREATE>
7862
8694
  packages shared_inboxes short_link public %name:my_shared_inbox_name list
7863
- packages shared_inboxes short_link public %name:my_shared_inbox_name modify <aoc_shared_inbox_short_link_create> @: password=<PUBLIC_LINK_FOLDER_PASSWORD>
7864
- packages shared_inboxes short_link public %name:my_shared_inbox_name show <aoc_shared_inbox_short_link_create>
8695
+ packages shared_inboxes short_link public %name:my_shared_inbox_name modify <AOC_SHARED_INBOX_SHORT_LINK_CREATE> @: password=<PUBLIC_LINK_FOLDER_PASSWORD>
8696
+ packages shared_inboxes short_link public %name:my_shared_inbox_name show <AOC_SHARED_INBOX_SHORT_LINK_CREATE>
7865
8697
  packages shared_inboxes show %name:my_shared_inbox_name
7866
8698
  packages show '%name:package title'
7867
8699
  remind --username=my_user_email --url=https://aoc.example.com/path
@@ -7925,7 +8757,7 @@ Then, to register the key by default for the `ats` plugin, create a preset.
7925
8757
  Execute:
7926
8758
 
7927
8759
  ```shell
7928
- ascli config preset update <PRESET_NAME> --ibm-api-key=<API_KEY>
8760
+ ascli config preset set <PRESET_NAME> @: ibm_api_key=<API_KEY>
7929
8761
  ```
7930
8762
 
7931
8763
  ```shell
@@ -7941,7 +8773,7 @@ aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee
7941
8773
  ```
7942
8774
 
7943
8775
  ```shell
7944
- ascli config preset update <PRESET_NAME> --instance=aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee
8776
+ ascli config preset set <PRESET_NAME> @: instance=aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee
7945
8777
  ```
7946
8778
 
7947
8779
  ```shell
@@ -7958,7 +8790,7 @@ ascli ats api_key create --out.secrets=yes
7958
8790
  ```
7959
8791
 
7960
8792
  ```shell
7961
- ascli config preset update <PRESET_NAME> --ats-key=<ATS_KEY> --ats-secret=<ATS_SECRET>
8793
+ ascli config preset set <PRESET_NAME> @: ats_key=<ATS_KEY> ats_secret=<ATS_SECRET>
7962
8794
  ```
7963
8795
 
7964
8796
  ### ATS Access key creation parameters
@@ -8011,8 +8843,8 @@ The parameters provided to ATS for access key creation are the ones of [ATS API]
8011
8843
 
8012
8844
  ```shell
8013
8845
  access_key cluster ak2ibmcloud --secret=<SECRET>
8014
- access_key create --cloud=aws --region=my_region @json:'{"id":"ak_aws","name":"my test key AWS","storage":{"type":"aws_s3","bucket":"my_bucket","credentials":{"access_key_id":"my_access_key","secret_access_key":"my_secret_key"},"path":"/"}}'
8015
- access_key create --cloud=softlayer --region=my_region @json:'{"id":"ak2ibmcloud","secret":"<SECRET>","name":"my test key","storage":{"type":"ibm-s3","bucket":"my_bucket","credentials":{"access_key_id":"my_access_key","secret_access_key":"my_secret_key"},"path":"/"}}'
8846
+ access_key create --cloud=aws --region=my_region @json:'{"id":"ak_aws","name":"my test key AWS","storage":{"type":"aws_s3","bucket":"my_bucket","credentials":{"access_key_id":"<ACCESS_KEY>","secret_access_key":"<SECRET_KEY>"},"path":"/"}}'
8847
+ access_key create --cloud=softlayer --region=my_region @json:'{"id":"ak2ibmcloud","secret":"<SECRET>","name":"my test key","storage":{"type":"ibm-s3","bucket":"my_bucket","credentials":{"access_key_id":"<ACCESS_KEY>","secret_access_key":"<SECRET_KEY>"},"path":"/"}}'
8016
8848
  access_key delete ak2ibmcloud
8017
8849
  access_key entitlement ak2ibmcloud
8018
8850
  access_key list --fields=name,id
@@ -8059,7 +8891,7 @@ ascli server --url=ssh://hsts.example.com:33001 --username=john --ssh-keys=~/.ss
8059
8891
 
8060
8892
  ```shell
8061
8893
  browse /
8062
- browse / --password @none: --ssh-options.number_of_password_prompts=0 --ssh-keys=<serv_key_path>
8894
+ browse / --password @none: --ssh-options.number_of_password_prompts=0 --ssh-keys=<SERV_KEY_PATH>
8063
8895
  browse my_inside_folder/test_file.bin
8064
8896
  browse my_upload_folder/target_hot
8065
8897
  cp my_inside_folder/test_file.bin my_upload_folder/200KB.2
@@ -8084,6 +8916,7 @@ sync admin status /data/local_sync
8084
8916
  sync pull my_inside_folder --to-folder=/data/local_sync @: name=serv_sync_pull_conf
8085
8917
  sync pull my_inside_folder --to-folder=/data/local_sync @json:'{"name":"serv_sync_pull_conf","reset":true,"transport":{"target_rate":my_bps}}'
8086
8918
  upload 'faux:///test.bin?1k' --to-folder=my_upload_folder
8919
+ upload 'faux:///test.bin?1m' --to-folder=my_upload_folder --ts.target_rate=500m
8087
8920
  upload --sources=@ts --transfer.ascp_args=@list:,--file-list,file_list.txt --to-folder=my_inside_folder
8088
8921
  upload --sources=@ts --transfer.ascp_args=@list:,--file-pair-list,file_pair_list.txt
8089
8922
  upload --sources=@ts --ts=@json:'{"paths":[{"source":"test_file.bin","destination":"my_inside_folder/other_name_4"}]}' --transfer.agent=transferd
@@ -8169,6 +9002,23 @@ ascli server --ssh-options=@json:'{"use_agent": false}' ...
8169
9002
  If one of the SSH private keys is passphrase-protected, then option `passphrase` can be used.
8170
9003
  It is equivalent to setting both options `ssh_options.passphrase` and `ts.ssh_private_key_passphrase`.
8171
9004
 
9005
+ ### Analyze `ascp` logs of the server
9006
+
9007
+ 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`](#agent-direct-transfer). It has the same sub-commands (`summary`, `sessions`, `diagnostics`, `health`, `records`, ...) and the same option `ascp_logs`.
9008
+ 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`).
9009
+ Files compressed with gzip (rotations) are supported. A folder is not read, give its files.
9010
+
9011
+ ```shell
9012
+ ascli server --url=ssh://<SERVER_ADDRESS>:33001 --username=root --ssh-keys=~/.ssh/id_rsa logs summary /var/log/aspera.log
9013
+ ascli server ... logs sessions /var/log/aspera.log /var/log/aspera.log-20261101.gz --select=@json:'{"status":"failed"}'
9014
+ ```
9015
+
9016
+ 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`).
9017
+ The files are copied to a temporary folder, removed after the analysis.
9018
+ 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`.
9019
+ The modification date of each file is kept, as the year of syslog lines is deduced from it.
9020
+ Not available with `--url=local:` and `https`.
9021
+
8172
9022
  ### Other session channels for `server`
8173
9023
 
8174
9024
  URL schemes `local` and `https` are also supported (mainly for testing purposes).
@@ -8655,7 +9505,8 @@ ascli node -N --url=https://... --password="Bearer $(cat bearer.txt)" --root-id=
8655
9505
  ```shell
8656
9506
  --url=http://localhost:12348 --username=sim --password=<PASSWORD> browse / --fields=path --format=csv --select=@json:'{"basename":"test_file.bin"}'
8657
9507
  --url=http://localhost:12348 --username=sim --password=<PASSWORD> transfer list --fields=status
8658
- --url=https://tst.example.com/path --password 'Bearer <nd_bearer_token>' --root-id=<id> access_key do self browse /
9508
+ --url=https://node.example.com:9092 --username=user1 --password=<PASSWORD> --ui=text asperabrowser
9509
+ --url=https://tst.example.com/path --password 'Bearer <ND_BEARER_TOKEN>' --root-id=<ID> access_key do self browse /
8659
9510
  access_key create @json:'{"id":"my_username","secret":"<PASSWORD>","storage":{"type":"local","path":"/"}}'
8660
9511
  access_key delete my_username
8661
9512
  access_key do my_ak_name browse / --secret=<AK_SECRET>
@@ -8673,15 +9524,14 @@ access_key do my_ak_name node_info / --secret=<AK_SECRET>
8673
9524
  access_key do my_ak_name rename /tst_nd_ak test_nd_ak2 --secret=<AK_SECRET>
8674
9525
  access_key do my_ak_name show %id:1 --secret=<AK_SECRET>
8675
9526
  access_key do my_ak_name upload 'faux:///test_nd_ak3?100k' --node-api.standard_ports=false --secret=<AK_SECRET>
8676
- access_key do self permission %id:<id> create @json:'{"access_type":"user","access_id":"666"}'
9527
+ access_key do self permission %id:<ID> create @json:'{"access_type":"user","access_id":"666"}'
8677
9528
  access_key do self permission / delete 1
8678
9529
  access_key do self permission / modify 1 @: 'access_levels=@list: read list'
8679
9530
  access_key do self permission / show 1
8680
9531
  access_key list
8681
- access_key set_bearer_key self @file:my_private_key
9532
+ access_key set_bearer_key self @file:<PRIVATE_KEY_FILE>
8682
9533
  access_key show %id:self
8683
9534
  api_details
8684
- asperabrowser
8685
9535
  async bandwidth %name:my_sync_session_name
8686
9536
  async counters %name:my_sync_session_name
8687
9537
  async delete ALL
@@ -8730,12 +9580,12 @@ sync admin status /data/local_sync
8730
9580
  sync pull /aspera-test-dir-tiny --to-folder=/data/local_sync @: reset=true
8731
9581
  sync pull /aspera-test-dir-tiny --to-folder=/data/local_sync @json:'{"name":"my_sync_session_name","reset":true}'
8732
9582
  transfer bandwidth_average
8733
- transfer cancel <id>
9583
+ transfer cancel <ID>
8734
9584
  transfer list --query.active_only=true
8735
9585
  transfer list --query.reset=true --once-only=yes
8736
- transfer modify <id> @: target_rate_kbps=10000
9586
+ transfer modify <ID> @: target_rate_kbps=10000
8737
9587
  transfer sessions
8738
- transfer show <id>
9588
+ transfer show <ID>
8739
9589
  transport
8740
9590
  upload 'faux:///testfile1?1m' --to-folder=my_local_path
8741
9591
  upload --to-folder=my_upload_folder --sources=@ts --ts=@json:'{"paths":[{"source":"/aspera-test-dir-small/10MB.2"}],"precalculate_job_size":true}' --transfer.agent=node --transfer.url=https://node.example.com/path --transfer.username=my_username --transfer.password=<PASSWORD>
@@ -8767,7 +9617,7 @@ Identify the region and the endpoint URL will be `https://otlp-[region]-saas.ins
8767
9617
  For convenience, those parameters can be provided in a preset, for example, named `otel_default`.
8768
9618
 
8769
9619
  ```shell
8770
- ascli config preset initialize otel_default @json:'{"url":"https://otlp-orange-saas.instana.io:4318","key":"<KEY>","interval":1.1}'
9620
+ ascli config preset set otel_default @json:'{"url":"https://otlp-orange-saas.instana.io:4318","key":"<KEY>","interval":1.1}'
8771
9621
  ```
8772
9622
 
8773
9623
  Then it is invoked like this (assuming a default node is configured):
@@ -8797,13 +9647,13 @@ The emulator starts its own `transferd`, and stops it on exit.
8797
9647
  It takes an optional `Hash` argument with the following parameters:
8798
9648
 
8799
9649
  | Field | Type | Description |
8800
- |-------------------|---------|----------------------------------------------------------------------------------|
9650
+ | ----------------- | ------- | -------------------------------------------------------------------------------- |
8801
9651
  | `cert` | `String` | Path to the TLS certificate file. Accepted formats: PEM (`.pem`) or PKCS12 (`.p12` / `.pfx`).<br/>Example: `/path/to/cert.pem`. |
8802
9652
  | `chain` | `String` | Path to the PEM certificate chain file (appended as extra chain certificates).<br/>Example: `/path/to/chain.pem`. |
8803
9653
  | `docroot` | `String` | Local folder of the node files. Paths of `/files/browse` and local paths of transfers (sources of `send`, destination of `receive`) are relative to it, and confined in it. Defaults to the current working directory.<br/>Example: `/data/aspera`. |
8804
9654
  | `key` | `String` | Path to the PEM private key file, or the PKCS12 passphrase when `cert` is a `.p12`/`.pfx` file.<br/>Example: `/path/to/key.pem`. |
9655
+ | `password` | `String` | Password expected from clients in HTTP Basic authentication, for the above `username`. Generate it with `openssl rand -hex 32`: a weak password is refused (see `password_min_bits`).<br/>Example: `<PASSWORD>`. |
8805
9656
  | `password_min_bits` | `Integer` | Minimum estimated strength of `password`, in bits (log2 of the number of guesses to find it). The strength is estimated with gem `zxcvbn` if installed, else with a built-in estimate that detects repeats, sequences, keyboard rows, words and years. `0` disables the check. A random password of 32 bytes (`openssl rand -hex 32`) is far above the default.<br/>Default: `80`. |
8806
- | `password` | `String` | Password expected from clients in HTTP Basic authentication, for the above `username`. Generate it with `openssl rand -hex 32`: a weak password is refused (see `password_min_bits`).<br/>Example: `my_password`. |
8807
9657
  | `retention_sec` | `Integer` | Time in seconds a transfer stays in the list of transfers after it ended (completed, failed or canceled, and no more retried).<br/>Default: `86400`. |
8808
9658
  | `url` | `String` | Address and port the emulator listens on. Use `https://` with `cert`/`key` for TLS.<br/>Default: `http://localhost:8080`. |
8809
9659
  | `username` | `String` | Username expected from clients in HTTP Basic authentication. Set together with `password`. When not set, requests are accepted without authentication. Mandatory when `url` is not a loopback address (`localhost`, `127.0.0.0/8`, `::1`).<br/>Example: `node_user`. |
@@ -8822,7 +9672,7 @@ ascli node emulator @json:'{"url":"http://localhost:12348","username":"sim","pas
8822
9672
 
8823
9673
  Generate the password with `openssl rand -hex 32`.
8824
9674
  A weak password is refused at startup: its strength is estimated in bits, and shall be at least `password_min_bits`.
8825
- `username` and `password` are mandatory when `url` is not a loopback address (`localhost`, `127.0.0.0/8`, `::1`): anyone reaching the emulator could send the files of the `docroot` to any host.
9675
+ `username` and `password` are mandatory when `url` is not a loopback address (see [Web service](#web-service)): anyone reaching the emulator could send the files of the `docroot` to any host.
8826
9676
 
8827
9677
  Then, in another terminal, use it as a node, for example, to list the files in `/data`:
8828
9678
 
@@ -8903,13 +9753,13 @@ Multiple applications detected:
8903
9753
  product> faspex5
8904
9754
  ```
8905
9755
 
8906
- When Faspex is detected, the wizard asks for the path to a private key.
9756
+ When Faspex is detected, the wizard asks for a private key (a value like `@file:<path>`).
8907
9757
  If you do not have a private key, leave that field blank, and one will be generated or a previously generated key will be used.
8908
9758
 
8909
9759
  ```text
8910
9760
  Using: Faspex at https://faspex5.example.com/aspera/faspex
8911
- Please provide the path to your private RSA key, or nothing to generate one:
8912
- option: key_path>
9761
+ Private RSA key, e.g. @file:<path> (leave empty to generate):
9762
+ option: private_key>
8913
9763
  Using existing key:
8914
9764
  /Users/someuser/.aspera/ascli/my_key
8915
9765
  ```
@@ -9004,7 +9854,7 @@ Typically, users create a preset so they don't have to enter these options each
9004
9854
  Example:
9005
9855
 
9006
9856
  ```shell
9007
- ascli config preset update <F5_PRESET> --auth=jwt --client-id=<CLIENT_ID> --client-secret=<SECRET> --username=<USERNAME> --private-key=@file:.../path/to/key.pem
9857
+ ascli config preset set <F5_PRESET> @: auth=jwt client_id=<CLIENT_ID> client_secret=<SECRET> username=<USERNAME> private_key=@file:.../path/to/key.pem
9008
9858
 
9009
9859
  ascli config preset set default faspex5 <F5_PRESET>
9010
9860
 
@@ -9019,9 +9869,9 @@ For web-based authentication, the administrator must create an **API client** in
9019
9869
  - Do not Activate JWT
9020
9870
  - Set **Redirect URI** to `https://127.0.0.1:8888`
9021
9871
  - Click **Create**
9022
- - Take note of the Client Id (and Client Secret, but not used in current version)
9872
+ - Take note of the Client Id, and of the Client Secret if HTTP basic authentication is enabled on the API client
9023
9873
 
9024
- The user will use the following options:
9874
+ The user will use the following options (`client_secret` only if HTTP basic authentication is enabled on the API client):
9025
9875
 
9026
9876
  ```text
9027
9877
  --auth=web
@@ -9030,6 +9880,9 @@ The user will use the following options:
9030
9880
  --redirect-uri=https://127.0.0.1:8888
9031
9881
  ```
9032
9882
 
9883
+ `ascli` uses PKCE (RFC 7636, method `S256`): the authorization code can be exchanged for a token only by the `ascli` process that requested it.
9884
+ Faspex checks it since version 5.0.16, earlier versions ignore it.
9885
+
9033
9886
  ### Faspex 5 public link authentication
9034
9887
 
9035
9888
  If all you have is a public link received by email or other, you can still do authorized actions with it.
@@ -9052,7 +9905,7 @@ For `boot` method: (will be removed in future)
9052
9905
  Use this token as password and use `--auth=boot`.
9053
9906
 
9054
9907
  ```shell
9055
- ascli config preset update f5boot --url=https://localhost/aspera/faspex --auth=boot --password=<TOKEN>
9908
+ ascli config preset set f5boot @: url=https://localhost/aspera/faspex auth=boot password=<TOKEN>
9056
9909
  ```
9057
9910
 
9058
9911
  ### Tested commands for `faspex5`
@@ -9102,33 +9955,36 @@ gateway @: url=https://localhost:12346/aspera/faspex
9102
9955
  health --url=https://f5.example.com/path
9103
9956
  invitation list
9104
9957
  invitations create @: email_address=aspera.user1+u@gmail.com
9105
- packages browse --url=my_public_link_recv_fr_user /
9106
- packages browse <id> --query.recursive=true
9107
- packages delete <id>
9958
+ packages browse --url=<PUBLIC_LINK_RECV_FR_USER> /
9959
+ packages browse <ID> --query.recursive=true
9960
+ packages delete <ID>
9108
9961
  packages list --box=ALL
9109
9962
  packages list --box=my_shared_box_name
9110
9963
  packages list --box=my_workgroup --group-type=workgroups
9111
9964
  packages list --box=outbox --fields=DEF,sender.email,recipients.0.recipient_type
9112
9965
  packages list --query=@json:'{"mailbox":"inbox","status":"completed"}'
9113
- packages receive --box=my_shared_box_name <id> --to-folder=.
9114
- packages receive --box=my_workgroup --group-type=workgroups <id> --to-folder=.
9115
- packages receive --url=my_public_link_recv_fr_user --to-folder=.
9116
- packages receive --url=my_public_link_recv_fr_user ALL --to-folder=.
9117
- packages receive <id> --to-folder=. --ts.content_protection_password=<PASSWORD>
9118
- packages receive <id> <f5_pack_first_file> --to-folder=. --ts.content_protection_password=<PASSWORD>
9119
- packages receive ALL --once-only=yes --to-folder=. --query.max=5
9966
+ packages receive --box=my_shared_box_name <ID> --to-folder=.
9967
+ packages receive --box=my_workgroup --group-type=workgroups <ID> --to-folder=.
9968
+ packages receive --url=<PUBLIC_LINK_RECV_FR_USER> --to-folder=.
9969
+ packages receive --url=<PUBLIC_LINK_RECV_FR_USER> ALL --to-folder=.
9970
+ packages receive <ID> --to-folder=. --ts.content_protection_password=<PASSWORD>
9971
+ packages receive <ID> <F5_PACK_FIRST_FILE> --to-folder=. --ts.content_protection_password=<PASSWORD>
9972
+ packages receive ALL --once-only=yes --to-folder=.
9973
+ packages receive ALL --once-only=yes --to-folder=. --query.max=5 --ts.content_protection_password=<PASSWORD>
9120
9974
  packages receive INIT --once-only=yes
9121
- packages send --url=my_public_link_send_shared_box @json:'{"title":"test title"}' test_file.bin
9122
- packages send --url=my_public_link_send_to_user @json:'{"title":"test title"}' test_file.bin
9975
+ packages send --url=<PUBLIC_LINK_SEND_SHARED_BOX> @json:'{"title":"test title"}' test_file.bin
9976
+ packages send --url=<PUBLIC_LINK_SEND_TO_USER> @json:'{"title":"test title"}' test_file.bin
9123
9977
  packages send @: 'title=for shared inbox' recipients.0=my_shared_box_name metadata.Options=Opt1 'metadata.TextInput=example text' END test_file.bin
9978
+ packages send @: 'title=test ear' recipients.0.name=my_username END test_file.bin --ts.content_protection=encrypt --ts.content_protection_password=<PASSWORD>
9979
+ packages send @: 'title=test recipient types' recipients.0=my_username recipient_types.0=user END test_file.bin
9124
9980
  packages send @: 'title=test title' recipients.0.name=my_username END test_file.bin --ts.content_protection_password=<PASSWORD>
9125
9981
  packages send @json:'{"title":"test title","recipients":["my_workgroup"]}' test_file.bin
9126
9982
  packages send @json:'{"title":"test_webhook_ascli","recipients":["my_shared_box_name"]}' 'faux:///test1?1m'
9127
- packages show --box=my_shared_box_name <id>
9128
- packages show --box=my_workgroup --group-type=workgroups <id>
9129
- packages show <id>
9130
- packages status <f5_pack_send_shared> @list:,failed,completed
9131
- packages status <id>
9983
+ packages show --box=my_shared_box_name <ID>
9984
+ packages show --box=my_workgroup --group-type=workgroups <ID>
9985
+ packages show <ID>
9986
+ packages status <F5_PACK_SEND_SHARED> @list:,failed,completed
9987
+ packages status <ID>
9132
9988
  postprocessing @: url=https://localhost:8553/asclihook script_folder=/path/to/scripts cert=.../localhost.p12 key=<PASSWORD>
9133
9989
  shared browse %name:my_shared_folder_name
9134
9990
  shared list
@@ -9533,15 +10389,15 @@ ascli faspex5 postprocessing
9533
10389
  An optional positional parameter can be provided as [Extended Value](#extended-value-syntax) `Hash`:
9534
10390
 
9535
10391
  | Field | Type | Description |
9536
- |-----------------------|-----------------------|----------------------------------------------------------------------------------|
10392
+ | --------------------- | --------------------- | -------------------------------------------------------------------------------- |
9537
10393
  | `allowed_ips` | `String, Array[String]` | IP address or network (CIDR, e.g. `10.89.0.0/24`), or list of them, allowed to call the listener. Requests from any other source IP are rejected with HTTP 403. When not set, no IP restriction is applied. This parameter or `secret_token` is required when `url` is not a local address. |
9538
10394
  | `cert` | `String` | Path to the TLS certificate file. Accepted formats: PEM (`.pem`) or PKCS12 (`.p12` / `.pfx`).<br/>Example: `/path/to/cert.pem`. |
9539
10395
  | `chain` | `String` | Path to the PEM certificate chain file (appended as extra chain certificates).<br/>Example: `/path/to/chain.pem`. |
9540
10396
  | `fail_on_error` | `Bool` | When `true`, return HTTP 500 if the script exits with a non-zero status code. When `false` (default), the exit code is reported in the response body but HTTP 200 is returned.<br/>Default: `false`. |
9541
10397
  | `key` | `String` | Path to the PEM private key file, or the PKCS12 passphrase when `cert` is a `.p12`/`.pfx` file.<br/>Example: `/path/to/key.pem`. |
9542
10398
  | `script_folder` | `String` | Folder containing the post-processing scripts. The URL path (after the base path) is appended to this folder to locate the script to execute.<br/>Default: `.`.<br/>Example: `/opt/faspex/scripts`. |
9543
- | `secret_token_min_bits` | `Integer` | Minimum estimated strength of `secret_token`, in bits (log2 of the number of guesses to find it). The strength is estimated with gem `zxcvbn` if installed, else with a built-in estimate that detects repeats, sequences, keyboard rows, words and years. `0` disables the check. A random token of 32 bytes (`openssl rand -hex 32`) is far above the default.<br/>Default: `80`. |
9544
10399
  | `secret_token` | `String` | Shared secret for webhook authentication. When set, every incoming request must include `?token=<value>` in the URL; requests without the correct token are rejected with HTTP 401. Configure the Faspex webhook URL as `http://host:port/path/script.sh?token=<value>`. This parameter or `allowed_ips` is required when `url` is not a local address. Generate it with `openssl rand -hex 32`: a weak token is refused (see `secret_token_min_bits`). |
10400
+ | `secret_token_min_bits` | `Integer` | Minimum estimated strength of `secret_token`, in bits (log2 of the number of guesses to find it). The strength is estimated with gem `zxcvbn` if installed, else with a built-in estimate that detects repeats, sequences, keyboard rows, words and years. `0` disables the check. A random token of 32 bytes (`openssl rand -hex 32`) is far above the default.<br/>Default: `80`. |
9545
10401
  | `timeout_seconds` | `Integer` | Maximum time in seconds to wait for the script to complete before killing it.<br/>Default: `60`. |
9546
10402
  | `url` | `String` | Address and port the server listens on. Use `https://` with `cert`/`key` for TLS.<br/>Default: `http://localhost:8080`. |
9547
10403
 
@@ -9574,8 +10430,8 @@ Instead, one can specify the **IP address of the host** or `host.containers.inte
9574
10430
  So, `ascli` shall listen on an address reachable from the containers: the IP address of the host, or `0.0.0.0` for all interfaces.
9575
10431
 
9576
10432
  > [!NOTE]
9577
- > **Security**: by default the listener binds to loopback (`localhost`) and is not reachable from outside the host.
9578
- > When `url` is not a loopback address (`localhost`, `127.0.0.0/8`, `::1`), at least one of the following protections is required:
10433
+ > **Security**: by default the listener binds to loopback (`localhost`) and is not reachable from outside the host (see [Web service](#web-service)).
10434
+ > When `url` is not a loopback address, at least one of the following protections is required:
9579
10435
  >
9580
10436
  > - **`secret_token`**: include the token in the Faspex webhook URL: `http://host:8080/processing/script1.sh?token=<TOKEN>`. Requests without the correct token are rejected with HTTP 401.
9581
10437
  > - **`allowed_ips`**: restrict the listener to the known Faspex container IPs or network, e.g. `@json:'{"allowed_ips":["192.168.1.10","10.89.0.0/24"]}'`. Requests from other IPs are rejected with HTTP 403.
@@ -9608,15 +10464,17 @@ For legacy Faspex client applications that use the `send` API (only) of Faspex v
9608
10464
  It takes an optional `Hash` argument:
9609
10465
 
9610
10466
  | Field | Type | Description |
9611
- |-------------------|---------|----------------------------------------------------------------------------------|
10467
+ | ----------------- | ------- | -------------------------------------------------------------------------------- |
9612
10468
  | `cert` | `String` | Path to the TLS certificate file. Accepted formats: PEM (`.pem`) or PKCS12 (`.p12` / `.pfx`).<br/>Example: `/path/to/cert.pem`. |
9613
10469
  | `chain` | `String` | Path to the PEM certificate chain file (appended as extra chain certificates).<br/>Example: `/path/to/chain.pem`. |
9614
10470
  | `key` | `String` | Path to the PEM private key file, or the PKCS12 passphrase when `cert` is a `.p12`/`.pfx` file.<br/>Example: `/path/to/key.pem`. |
10471
+ | `password` | `String` | Password expected from clients in HTTP Basic authentication, for the above `username`. Generate it with `openssl rand -hex 32`: a weak password is refused (see `password_min_bits`).<br/>Example: `<PASSWORD>`. |
9615
10472
  | `password_min_bits` | `Integer` | Minimum estimated strength of `password`, in bits (log2 of the number of guesses to find it). The strength is estimated with gem `zxcvbn` if installed, else with a built-in estimate that detects repeats, sequences, keyboard rows, words and years. `0` disables the check. A random password of 32 bytes (`openssl rand -hex 32`) is far above the default.<br/>Default: `80`. |
9616
- | `password` | `String` | Password expected from clients in HTTP Basic authentication, for the above `username`. Generate it with `openssl rand -hex 32`: a weak password is refused (see `password_min_bits`).<br/>Example: `my_password`. |
9617
10473
  | `url` | `String` | Address and port the server listens on. Use `https://` with `cert`/`key` for TLS.<br/>Default: `http://localhost:8080`. |
9618
10474
  | `username` | `String` | Username expected from clients in HTTP Basic authentication. Set together with `password`. When not set, requests are accepted without authentication. Mandatory when `url` is not a loopback address (`localhost`, `127.0.0.0/8`, `::1`).<br/>Example: `fx4_user`. |
9619
10475
 
10476
+ For details on `url` and HTTPS (`cert`, `key`, `chain`), see [Web service](#web-service).
10477
+
9620
10478
  Example:
9621
10479
 
9622
10480
  ```shell
@@ -9626,7 +10484,7 @@ ascli faspex5 gateway @json:'{"url":"https://localhost:12345/aspera/faspex","use
9626
10484
  Clients authenticate with HTTP Basic, as on Faspex 4, with the `username` and `password` of the gateway.
9627
10485
  Generate the password with `openssl rand -hex 32`.
9628
10486
  A weak password is refused at startup: its strength is estimated in bits, and shall be at least `password_min_bits`.
9629
- `username` and `password` are mandatory when `url` is not a loopback address (`localhost`, `127.0.0.0/8`, `::1`): anyone reaching the gateway could send packages to anyone, as the Faspex 5 user.
10487
+ `username` and `password` are mandatory when `url` is not a loopback address (see [Web service](#web-service)): anyone reaching the gateway could send packages to anyone, as the Faspex 5 user.
9630
10488
  When they are not set, requests are accepted without authentication.
9631
10489
 
9632
10490
  There are many limitations:
@@ -9704,6 +10562,43 @@ ascli shares admin user all share_permissions %username:john@example.com list --
9704
10562
  done
9705
10563
  ```
9706
10564
 
10565
+ ### Authentication of SAML users
10566
+
10567
+ By default, `shares` authenticates with `username` and `password`.
10568
+ A user that has only a SAML identity (no local password) can authenticate with a web browser: `--auth=web`.
10569
+
10570
+ ```shell
10571
+ ascli shares --url=https://shares.example.com --auth=web files browse /
10572
+ ```
10573
+
10574
+ Option `ui.web_auth` selects how the result of the login is received (see [Web login flow](#web-login-flow)):
10575
+
10576
+ - `port` (default): automatic when the browser runs on the same system as `ascli`.
10577
+ `ascli` listens on a local port (`--redirect-uri`, default: `http://localhost:12345`), opens the SAML login page of Shares (`/auth/saml`) in the browser with this URL in `RelayState`, and receives the OAuth tokens there.
10578
+ The host of `redirect_uri` shall be loopback: `localhost`, an address of `127.0.0.0/8`, or `[::1]`.
10579
+ - `paste`: the browser may run on another system than `ascli` (for example, `ascli` runs on a server accessed with SSH), without tunnel.
10580
+ No local port is opened and `--redirect-uri` is not used.
10581
+ `ascli` generates a random `state` and opens the SAML login page with `RelayState` `aspera://device-code?state=<state>`.
10582
+ After login, Shares displays a code (a long text of letters, digits, `-` and `_`). The user copies it and pastes it in the terminal (nothing is displayed, as the code contains a token).
10583
+ If standard input is not a terminal, the code is read from it.
10584
+ `ascli` checks that the `state` of the code is the one it generated.
10585
+ The code is valid for **15 to 30 minutes** after its display: it is encrypted with a key derived from the `state` and from the current time in slots of 15 minutes (the previous and the next slot are also accepted).
10586
+ So the clocks of the Shares server and of the system that runs `ascli` shall be correct (less than 15 minutes apart), and the code shall be pasted soon after the login, otherwise `ascli` reports an expired code or a wrong clock, and the login shall be done again.
10587
+ The code is also protected against typing errors and modification.
10588
+
10589
+ The token is saved, and renewed with its refresh token: the browser is opened again only if this fails.
10590
+ Option `username` is optional: with it, the token is saved for this user.
10591
+
10592
+ > [!IMPORTANT]
10593
+ > Shares does not have the OAuth authorization code grant: both ways require a specific patch of Shares, which returns the tokens when `RelayState` is a loopback URL (`port`) or `aspera://device-code?state=<state>` (`paste`).
10594
+ > The patch is the file [`docs/shares/zz_saml_cli_relay_state.rb`](shares/zz_saml_cli_relay_state.rb) of the GitHub repository.
10595
+ > It is temporary code, provided until an equivalent function is officially released in Shares.
10596
+ > It modifies no file of Shares: to install it, copy it to `<shares_rails_root>/config/initializers/` on the Shares server and restart Shares; to remove it, delete the file and restart Shares.
10597
+ > With a Shares without the patch, `ascli` reports that no token was received.
10598
+ > This feature works only with this patch: it is not a standard function of Shares, and it has not been validated on a released version of Shares yet.
10599
+ > It may change with the final implementation in Shares: the `RelayState` values, the format of the code (and so its validity and its encryption) and the returned fields can differ, and `ascli` will then be adapted. Do not rely on the current format outside of `ascli`.
10600
+ > The tokens given by Shares go through the browser (in the URL, or in the code): `ascli` immediately exchanges the refresh token for a new token, so that the tokens that were visible are not valid any more.
10601
+
9707
10602
  ### Tested commands for `shares`
9708
10603
 
9709
10604
  > [!NOTE]
@@ -9737,7 +10632,7 @@ files download --to-folder=. my_share_folder/test_file.bin my_share_folder/test_
9737
10632
  files mkdir my_share_folder/new_folder
9738
10633
  files sync push /data/local_sync --to-folder=my_share_folder/synctst
9739
10634
  files sync push /data/local_sync --to-folder=my_share_folder/synctst @: reset=true
9740
- files upload 'faux:///testfile?1m' --to-folder=my_share_folder --transfer.agent=httpgw --transfer.url=https://tst.example.com/path --transfer.synchronous=true --transfer.api_version=v1 --transfer.upload_chunk_size=100000
10635
+ files upload 'faux:///test-file?1m' --to-folder=my_share_folder --transfer.agent=httpgw --transfer.url=https://tst.example.com/path --transfer.synchronous=true --transfer.api_version=v1 --transfer.upload_chunk_size=100000
9741
10636
  files upload --to-folder=my_share_folder test_file.bin
9742
10637
  files upload --to-folder=my_share_folder test_file.bin --transfer.agent=httpgw --transfer.url=https://tst.example.com/path
9743
10638
  files upload send_folder --to-folder=my_share_folder --transfer.agent=httpgw --transfer.url=https://tst.example.com/path --transfer.synchronous=true --transfer.api_version=v1 --transfer.upload_chunk_size=100000
@@ -9767,40 +10662,41 @@ In addition, it is possible to place a single `query` parameter in the request t
9767
10662
  endpoint list
9768
10663
  health
9769
10664
  ssh_key list
9770
- transfer current files <id>
10665
+ transfer current files <ID>
9771
10666
  transfer current list --query.filter='(transfer_name contain aoc)'
9772
10667
  transfer current list --query=@json:'{"filter1":"transfer_name","comp1":"contain","val1":"aoc"}'
9773
- transfer current show <id>
10668
+ transfer current show <ID>
9774
10669
  transfer smart list
9775
- transfer smart sub my_smart_id @: source.paths.0=my_smart_file source_type=user_selected
10670
+ transfer smart sub <SMART_ID> @: source.paths.0=my_smart_file source_type=user_selected
9776
10671
  ```
9777
10672
 
9778
10673
  ## Plugin: `orchestrator`: IBM Aspera Orchestrator
9779
10674
 
9780
- To write workflow files without the designer, refer to the [Workflow Authoring Guide](https://github.com/laurent-martin/aspera-orchestrator-plugins-doc/blob/main/docs/workflow-authoring-guide.md): file format, graph, execution, examples and REST API.
10675
+ To write workflow files without the designer, refer to the [Aspera Orchestrator Development Guide](https://github.com/laurent-martin/aspera-orchestrator-plugins-doc/blob/main/docs/orchestrator-development-guide.md): file format, graph, execution, examples and REST API.
9781
10676
 
9782
- Command `workflows development` displays the documentation for workflow development, read from GitHub: this guide (`authoring`), or the [Action Template Reference](https://github.com/laurent-martin/aspera-orchestrator-plugins-doc/blob/main/docs/action-template-reference.md) (`templates`).
9783
- With `toc`, it lists the sections of the document, and with the anchor of a section, it displays only that section.
10677
+ Command `workflows development` gives access to the documentation for workflow development, read from GitHub.
10678
+ Without argument, it lists the documents: the guide (`guide`), the [Action Template Reference](https://github.com/laurent-martin/aspera-orchestrator-plugins-doc/blob/main/docs/action-template-reference.md) (`templates`) and the Plugin Manual (`manual`).
10679
+ After the name of a document: `toc` lists its sections, `full` displays the whole document, and `section <anchor>` displays only one section: the guide and the manual are large, use `toc` first.
9784
10680
  It does not require access to Orchestrator.
9785
10681
  The [MCP server](#plugin-mcp-model-context-protocol-server) instructs AI assistants to read it before writing or modifying a workflow.
9786
10682
 
9787
10683
  ```shell
9788
- ascli orchestrator workflows development authoring toc
9789
- ascli orchestrator workflows development templates customruby
10684
+ ascli orchestrator workflows development guide toc
10685
+ ascli orchestrator workflows development templates section customruby
9790
10686
  ```
9791
10687
 
9792
- Command `plugins spec` displays the specifications of action plugins, read from GitHub: [plugins.yml](https://github.com/laurent-martin/aspera-orchestrator-plugins-doc/blob/main/docs/plugins.yml).
10688
+ Commands `plugins spec` display the specifications of action plugins, read from GitHub: [plugins.yml](https://github.com/laurent-martin/aspera-orchestrator-plugins-doc/blob/main/docs/plugins.yml).
9793
10689
  For each plugin: template attributes (label, allowed values, defaults), and inputs and outputs of its steps, with the template settings they depend on.
9794
- The fields are described in section [Plugin specifications](https://github.com/laurent-martin/aspera-orchestrator-plugins-doc/blob/main/docs/workflow-authoring-guide.md#plugin-specifications) of the guide.
9795
- Without argument, it lists the plugins.
9796
- With a plugin name (class name, case insensitive), it displays its specification, or one section: `attributes`, `inputs` or `outputs`.
10690
+ The fields are described in section [Plugin specifications](https://github.com/laurent-martin/aspera-orchestrator-plugins-doc/blob/main/docs/orchestrator-development-guide.md#plugin-specifications) of the guide.
10691
+ `toc` lists the plugins, with the anchor of their section in the Plugin Manual (`manual_anchor`, for `workflows development manual section`).
10692
+ `show` with a plugin name (class name, case insensitive) displays its specification, or one section: `attributes`, `inputs` or `outputs`.
9797
10693
  It does not require access to Orchestrator.
9798
10694
  Option `plugin_specs` gives another URL or path of the file, for example for another version of Orchestrator.
9799
10695
 
9800
10696
  ```shell
9801
- ascli orchestrator plugins spec --select=@json:'{"category":"Triggers"}'
9802
- ascli orchestrator plugins spec AmazonS3Operation --format=yaml
9803
- ascli orchestrator plugins spec ascpclient inputs
10697
+ ascli orchestrator plugins spec toc --select=@json:'{"category":"Triggers"}'
10698
+ ascli orchestrator plugins spec show AmazonS3Operation --format=yaml
10699
+ ascli orchestrator plugins spec show ascpclient inputs
9804
10700
  ```
9805
10701
 
9806
10702
  ### Authentication
@@ -9811,9 +10707,9 @@ The Orchestrator plugin supports different credentials and authentication styles
9811
10707
  - `--auth_style=token` (default): Exchanges credentials for a JWT Bearer token via `/api/login`.
9812
10708
  - `--auth_style=basic`: Standard HTTP Basic Authentication.
9813
10709
  - `--auth_style=query`: Passes credentials in URL query parameters (`?login=...&password=...`).
9814
- - **API Key** (`--apikey`):
10710
+ - **Username / API Key** (`--username` and `--apikey`): the API key is the one of the user, so the user name is required.
9815
10711
  - `--auth_style=token` (default): Exchanges the API key for a JWT Bearer token via `/api/login`.
9816
- - `--auth_style=query`: Passes the API key in URL query parameter (`?apikey=...`).
10712
+ - `--auth_style=query`: Passes the API key in URL query parameters (`?login=...&api_key=...`).
9817
10713
 
9818
10714
  ### Start a workflow
9819
10715
 
@@ -9900,7 +10796,7 @@ An issue has these fields:
9900
10796
 
9901
10797
  Checked: format of the file (YAML, number of elements, plain format layout), attributes, `error_free`, action template keys, XML of the graph, `Start`, `End`, `Fail` and `Error` nodes, unique step names, step template, prerequisites, `Synch_factor`, steps that have no output or no prerequisite, references to outputs and parameters.
9902
10798
 
9903
- With the specifications of plugins (see `plugins spec`), it also checks action templates and the inputs of steps, for the settings of each template:
10799
+ With the specifications of plugins (see `plugins spec show`), it also checks action templates and the inputs of steps, for the settings of each template:
9904
10800
 
9905
10801
  - plugin class name, attributes of the template, and their values (type, allowed values),
9906
10802
  - required inputs not mapped (`step.input_missing`),
@@ -9946,39 +10842,45 @@ Orchestrator does not refuse an incomplete resolution: `workflows import_with_co
9946
10842
  ```shell
9947
10843
  --auth_style=query workflow list
9948
10844
  --auth_style=token workflow list
10845
+ alerts list
9949
10846
  health
9950
10847
  info
9951
10848
  journal files journal --query=@json:'{"details":"false"}'
9952
10849
  monitors list node
9953
10850
  monitors snapshot
9954
10851
  plugins list
9955
- plugins spec --select=@json:'{"category":"Triggers"}'
9956
- plugins spec AmazonS3Operation --format=yaml
9957
- plugins spec ascpclient inputs
10852
+ plugins spec show AmazonS3Operation --format=yaml
10853
+ plugins spec show ascpclient inputs
10854
+ plugins spec toc --select=@json:'{"category":"Triggers"}'
10855
+ portlets list
9958
10856
  processes
9959
10857
  queues list
10858
+ queues stats
10859
+ tasks list
9960
10860
  workflow check_import orch_wf_check.yml
9961
- workflow details my_workflow_id
9962
- workflow export my_workflow_id
9963
- workflow inputs my_workflow_id
10861
+ workflow details <WORKFLOW_ID>
10862
+ workflow export <WORKFLOW_ID>
10863
+ workflow inputs <WORKFLOW_ID>
9964
10864
  workflow list
9965
- workflow outputs my_workflow_id
9966
- workflow start my_sleep_workflow_id --fields=work_order.id
9967
- workflow start my_workflow_id @: 'Param=world !'
9968
- workflow start my_workflow_id @: 'Param=world !' END @: step=ResultStep variable=Complete_status_message
10865
+ workflow outputs <WORKFLOW_ID>
10866
+ workflow start <SLEEP_WORKFLOW_ID> --fields=work_order.id
10867
+ workflow start <WORKFLOW_ID> @: 'Param=world !'
10868
+ workflow start <WORKFLOW_ID> @: 'Param=world !' END @: step=ResultStep variable=Complete_status_message
10869
+ workflow status <WORKFLOW_ID>
9969
10870
  workflow status ALL
9970
- workflow status my_workflow_id
9971
- workflow workorders my_workflow_id
9972
- workflow workorders my_workflow_id --fields=id --query.max_results=1
9973
- workflows development authoring toc
9974
- workflows development templates customruby
9975
- workorder cancel <id>
9976
- workorder output <id>
9977
- workorder reset <id>
9978
- workorder status <id>
9979
- workorder status <orch_wf_start_sleep> --fields=status_details
9980
- workstep cancel <id>
9981
- workstep status <id>
10871
+ workflow workorders <WORKFLOW_ID>
10872
+ workflow workorders <WORKFLOW_ID> --fields=id --query.max_results=1
10873
+ workflows development guide toc
10874
+ workflows development templates section customruby
10875
+ workorder cancel <ID>
10876
+ workorder output <ID>
10877
+ workorder reset <ID>
10878
+ workorder status <ID>
10879
+ workorders stats
10880
+ workorders worksteps <ORCH_WF_START_SLEEP> --select.status='In Progress' --fields=id
10881
+ worksteps cancel <ID>
10882
+ worksteps stats
10883
+ worksteps status <ID>
9982
10884
  ```
9983
10885
 
9984
10886
  ## Plugin: `cos`: IBM Cloud Object Storage
@@ -10010,7 +10912,7 @@ If you already have these parameters, provide the following options to `ascli`:
10010
10912
  Example: Create a Default Configuration
10011
10913
 
10012
10914
  ```shell
10013
- ascli config preset update <COS_PRESET_NAME> --bucket=mybucket --endpoint=https://s3.us-east.cloud-object-storage.appdomain.cloud --apikey=<API_KEY> --crn=<CRN>
10915
+ ascli config preset set <COS_PRESET_NAME> @: bucket=mybucket endpoint=https://s3.us-east.cloud-object-storage.appdomain.cloud apikey=<API_KEY> crn=<CRN>
10014
10916
  ascli config preset set default cos <COS_PRESET_NAME>
10015
10917
  ```
10016
10918
 
@@ -10080,7 +10982,7 @@ The required options for this method are:
10080
10982
  Example: Create a Default Configuration
10081
10983
 
10082
10984
  ```shell
10083
- ascli config preset update <COS_PRESET_NAME> --bucket=mybucket --service-credentials=@val:@json:@file:~/service_creds.json --region=us-south
10985
+ ascli config preset set <COS_PRESET_NAME> @: bucket=mybucket service_credentials=@val:@json:@file:~/service_creds.json region=us-south
10084
10986
  ascli config preset set default cos <COS_PRESET_NAME>
10085
10987
  ```
10086
10988
 
@@ -10104,8 +11006,8 @@ ascli cos node upload 'faux:///sample1G?1g'
10104
11006
 
10105
11007
  ```shell
10106
11008
  node download test_file.bin --to-folder=.
10107
- node info --bucket=my_bucket --endpoint=my_endpoint --apikey=my_api_key --crn=my_resource_instance_id
10108
- node info --bucket=my_bucket --region=my_region --service-credentials=@json:@file:my_cos_svc_cred
11009
+ node info --bucket=my_bucket --endpoint=my_endpoint --apikey=<API_KEY> --crn=<RESOURCE_INSTANCE_ID>
11010
+ node info --bucket=my_bucket --region=my_region --service-credentials=@json:@file:<COS_SVC_CRED_FILE>
10109
11011
  node info --log-level=trace2
10110
11012
  node upload test_file.bin
10111
11013
  ```
@@ -10122,6 +11024,47 @@ health
10122
11024
  info
10123
11025
  ```
10124
11026
 
11027
+ ## Plugin: `transferd`: Transfer Daemon
11028
+
11029
+ Plugin `transferd` installs the IBM Aspera Transfer Daemon (`transferd`, which includes `ascp`) and runs it as a system service.
11030
+ See [Installing `ascp` through `transferd`](#installing-ascp-through-transferd) and [Transfer Daemon as a system service](#transfer-daemon-as-a-system-service).
11031
+
11032
+ The plugin also has client commands for a running daemon (for example one installed with `transferd service install`):
11033
+
11034
+ | Command | Action |
11035
+ |---------------------------------|---------------------------------------------------------------------|
11036
+ | `info` | Version of the API and information on the instance of the daemon. |
11037
+ | `transfers show <transfer_id>` | Status of a transfer: the daemon keeps it for some time after its end. |
11038
+ | `transfers cancel <transfer_id>`| Stop a transfer. |
11039
+
11040
+ They use the options `url` (mandatory, endpoint of the daemon, e.g. `127.0.0.1:55002`), `api_key` (if the daemon enables `authentication`) and `ca_file` (if the daemon enables `tls`).
11041
+ If a key is not given, it is taken from the same key of the option `--transfer`, when its agent is `transferd` (e.g. a preset used for transfers).
11042
+ The options of the plugin have priority.
11043
+ The daemon has no call to list the transfers.
11044
+ These commands require the gem `grpc`: it is loaded only when one of them runs, so that the other commands do not need it.
11045
+ If it is missing: `gem install grpc`.
11046
+
11047
+ ```bash
11048
+ ascli transferd info --url=127.0.0.1:55002 --api-key=@vault:transferd.api_key
11049
+ ```
11050
+
11051
+ > [!NOTE]
11052
+ > Commands `config transferd ...` and `config ascp install` are deprecated aliases of `transferd ...` and `transferd install`.
11053
+
11054
+ ### Tested commands for `transferd`
11055
+
11056
+ > [!NOTE]
11057
+ > Add `ascli transferd` in front of the following commands:
11058
+
11059
+ ```shell
11060
+ install
11061
+ install --sdk-folder=sdk_test_dir
11062
+ install 1.1.3
11063
+ list
11064
+ service configure --dry-run=yes @json:'{"service":{"user":"aspweb"},"config":{"port":55002}}'
11065
+ service spec
11066
+ ```
11067
+
10125
11068
  ## Plugin: `faspio`: Faspio Gateway
10126
11069
 
10127
11070
  IBM Aspera faspio Gateway is a high-performance proxy that bridges traditional TCP/UDP applications with the Aspera FASP protocol, enabling secure, ultra-fast transfers over any network, even with high latency or packet loss.
@@ -10135,7 +11078,7 @@ Using `ascli`, you can remotely create and manage bridges on faspio Gateway, sim
10135
11078
 
10136
11079
  ```shell
10137
11080
  bridges create @json:'{"name":"test1","local":{"protocol":"tcp","tls_enabled":false,"port":"3000","bind_address":"127.0.0.1"},"forward":{"protocol":"fasp","tls_enabled":false,"port":"3994","bind_address":"127.0.0.1","host":["10.0.0.1"]}}'
10138
- bridges delete --bulk=yes @json:<faspio_bclean_list>
11081
+ bridges delete --bulk=yes @json:<FASPIO_BCLEAN_LIST>
10139
11082
  bridges list
10140
11083
  bridges show 1
10141
11084
  health
@@ -10338,7 +11281,7 @@ For example:
10338
11281
  ```shell
10339
11282
  su -s /bin/bash - xfer
10340
11283
 
10341
- ascli config preset update <PREVIEW_PRESET_NAME> --url=https://localhost:9092 --username=<ACCESS_KEY> --password=<SECRET> --skip-types=office --lock-port=12346
11284
+ ascli config preset set <PREVIEW_PRESET_NAME> @: url=https://localhost:9092 username=<ACCESS_KEY> password=<SECRET> skip_types=office lock_port=12346
10342
11285
 
10343
11286
  ascli config preset set default preview <PREVIEW_PRESET_NAME>
10344
11287
  ```
@@ -10359,7 +11302,7 @@ This shall list the contents of the storage root of the access key.
10359
11302
  When generating preview files, the following options can be modified on command line (or in a preset):
10360
11303
 
10361
11304
  | Field | Type | Description |
10362
- |---------------------|---------|----------------------------------------------------------------------------------|
11305
+ | ------------------- | ------------ | -------------------------------------------------------------------------------- |
10363
11306
  | `blend_fps` | `Integer` | MP4 video preview (`blend`): frames per second.<br/>Default: `15`. |
10364
11307
  | `blend_keyframes` | `Integer` | MP4 video preview (`blend`): number of key frames.<br/>Default: `30`. |
10365
11308
  | `blend_pauseframes` | `Integer` | MP4 video preview (`blend`): number of pause frames (repetitions of each key frame).<br/>Default: `3`. |
@@ -10367,17 +11310,17 @@ When generating preview files, the following options can be modified on command
10367
11310
  | `clips_count` | `Integer` | MP4 video preview (`clips`): number of clips.<br/>Default: `5`. |
10368
11311
  | `clips_length` | `Integer` | Video: length (in seconds) of each clip of MP4 video preview (`clips`), and of `animated` PNG thumbnail.<br/>Default: `5`. |
10369
11312
  | `max_size` | `Integer` | Maximum size (in bytes) of a preview file: a warning is logged if exceeded.<br/>Default: `16777216`. |
10370
- | `office_conversion` | `String` | PNG thumbnail of office document: conversion tool.<br/>Allowed values: `soffice`, `unoconv`.<br/>Default: `soffice`. |
11313
+ | `office_conversion` | `Enum[String]` | PNG thumbnail of office document: conversion tool.<br/>Allowed values: `soffice`, `unoconv`.<br/>Default: `soffice`. |
11314
+ | `reencode_ffmpeg` | `Hash` | MP4 video preview (`reencode`): `ffmpeg` options replacing the default ones.<br/>Default: `{}`. |
10371
11315
  | `reencode_ffmpeg.in` | `Array` | Input options. |
10372
11316
  | `reencode_ffmpeg.out` | `Array` | Output options. |
10373
- | `reencode_ffmpeg` | `Hash` | MP4 video preview (`reencode`): `ffmpeg` options replacing the default ones.<br/>Default: `{}`. |
10374
11317
  | `thumb_img_size` | `Integer` | PNG thumbnail of image, PDF, office document or text: size (in pixels).<br/>Default: `800`. |
10375
11318
  | `thumb_text_font` | `String` | PNG thumbnail of text: font name, as listed by `magick identify -list font`.<br/>Default: `Courier`. |
10376
11319
  | `thumb_vid_fraction` | `Number` | PNG thumbnail of video (`fixed`): position of the snapshot, as a fraction of the video duration.<br/>Default: `0.1`. |
10377
11320
  | `thumb_vid_scale` | `String` | PNG thumbnail of video: frame size, as `ffmpeg` scale filter argument.<br/>Default: `-1:min(ih,100)`. |
10378
11321
  | `video_codec` | `String` | MP4 video preview (`reencode`): `ffmpeg` video codec, e.g. `libx264`, `h264_videotoolbox`, `h264_nvenc`. Default: first available H.264 encoder. |
10379
- | `video_conversion` | `String` | MP4 video preview: generation method. `reencode`: re-encode the beginning of the video, `blend`: key frames with transitions, `clips`: concatenation of short clips.<br/>Allowed values: `reencode`, `blend`, `clips`.<br/>Default: `reencode`. |
10380
- | `video_png_conv` | `String` | PNG thumbnail of video: generation method. `fixed`: single frame, `animated`: animated PNG.<br/>Allowed values: `fixed`, `animated`.<br/>Default: `fixed`. |
11322
+ | `video_conversion` | `Enum[String]` | MP4 video preview: generation method. `reencode`: re-encode the beginning of the video, `blend`: key frames with transitions, `clips`: concatenation of short clips.<br/>Allowed values: `reencode`, `blend`, `clips`.<br/>Default: `reencode`. |
11323
+ | `video_png_conv` | `Enum[String]` | PNG thumbnail of video: generation method. `fixed`: single frame, `animated`: animated PNG.<br/>Allowed values: `fixed`, `animated`.<br/>Default: `fixed`. |
10381
11324
  | `video_scale` | `String` | MP4 video preview: frame size, as `ffmpeg` scale filter argument.<br/>Default: `min(iw,360):-2`. |
10382
11325
  | `video_start_sec` | `Integer` | Video: start offset (in seconds) of MP4 video preview and of `animated` PNG thumbnail.<br/>Default: `10`. |
10383
11326
 
@@ -10539,10 +11482,6 @@ trevents --once-only=yes --skip-types=office --log-level=info
10539
11482
 
10540
11483
  ## Plugin: `mcp`: Model Context Protocol server
10541
11484
 
10542
- > [!WARNING]
10543
- > This plugin is **experimental**.
10544
- > The interface, options, and behavior may change in future releases without notice.
10545
-
10546
11485
  The `mcp` plugin starts a [Model Context Protocol (MCP)](https://modelcontextprotocol.io/) server that exposes `ascli` to AI assistants and LLM-based tools.
10547
11486
  The server registers a single tool, `execute_ascli_command`, which executes any `ascli` command in-process and returns the result as text.
10548
11487
 
@@ -10613,6 +11552,8 @@ Keys of a transport are refused with the other transport.
10613
11552
  > [!NOTE]
10614
11553
  > `port` and `bind` are deprecated: use `url`, for example, `url=http://0.0.0.0:8080` instead of `port=8080 bind=0.0.0.0`.
10615
11554
 
11555
+ For the addresses the server listens on, and HTTPS, see [Web service](#web-service).
11556
+
10616
11557
  ### Security
10617
11558
 
10618
11559
  > [!WARNING]
@@ -10623,7 +11564,7 @@ With the `http` transport:
10623
11564
 
10624
11565
  - With `oauth`, the consent page asks for `auth_token` as access code, else anyone reaching the server could approve its own client.
10625
11566
  It shows where the authorization is sent (origin of `redirect_uri`): allow only if it is the expected AI client, for example `http://127.0.0.1:<port>`.
10626
- - For local-only deployments (hosts of `url` and `public_url` are loopback: `localhost`, `127.0.0.0/8`, `::1`), `auth_token` and `oauth` are optional but recommended.
11567
+ - For local-only deployments (hosts of `url` and `public_url` are loopback, see [Web service](#web-service)), `auth_token` and `oauth` are optional but recommended: on a host shared with other users, they can also reach the server.
10627
11568
  Without `auth_token`, the consent page only asks to click **Allow**.
10628
11569
  - `auth_token` and `oauth` can coexist: a request is accepted if it carries a valid static token **or** a valid OAuth access token.
10629
11570
  - A weak `auth_token` is refused at startup (see `auth_token_min_bits`): generate it with `openssl rand -hex 32`.
@@ -10636,9 +11577,12 @@ With both transports:
10636
11577
  - Extended value `@stdin:` is refused.
10637
11578
  - `@secret:` is entered by the user on a web page, see [Secrets entered in a web page](#secrets-entered-in-a-web-page).
10638
11579
  - Secrets are hidden in responses, also a value shorter than 8 characters as a word in a text (for example, a short password in an error message).
10639
- - The [Security Level](#security-level) is `high` by default: `@ruby:`, `@file:`, `@uri:`, and `@env:` are refused, and a secret must be the whole value: hidden in results, it cannot be processed by another extended value.
11580
+ - The [Security Level](#security-level) is `high` by default: `@ruby:`, `@file:` (also in the parameters of stores of option `vault`), `@uri:`, and `@env:` are refused, and a secret must be the whole value: hidden in results, it cannot be processed by another extended value.
10640
11581
  It applies to commands sent by the client, and to presets, because the client can modify presets.
10641
11582
  Commands sent by the client cannot change option `security`.
11583
+ Features that execute code, such as option `notify_template` or command `config plugins create`, plugins, and writing to a file chosen by the client (option `out.file`), are refused, see [Security Level](#security-level).
11584
+ Files can be written (for example by `config download`, or by a transfer that receives files) only in `writable_paths`, none by default: without it, the client cannot download files.
11585
+ It applies to files written on the system that runs the server: not to a transfer with agent `node` (`--transfer=node`), which writes on the node.
10642
11586
 
10643
11587
  To use another level, set option `security` when starting the server, for example:
10644
11588
 
@@ -10646,12 +11590,20 @@ To use another level, set option `security` when starting the server, for exampl
10646
11590
  ascli mcp server --security.level=medium --security.allowed_paths.0=$HOME/.aspera/ascli/my_private_key
10647
11591
  ```
10648
11592
 
11593
+ To let the client download files in a folder, keep the level `high` and give the folder:
11594
+
11595
+ ```shell
11596
+ ascli mcp server --security.writable_paths.0=$HOME/Downloads/ascli
11597
+ ```
11598
+
10649
11599
  > [!NOTE]
10650
11600
  > A level set by option also applies to the parameters of the `server` command: for example, `auth_token=@env:MCP_TOKEN` requires level `low`.
10651
11601
  > Without option `security`, the parameters of the `server` command are not restricted.
10652
11602
  >
10653
11603
  > A preset created by `aoc wizard` or `faspex5 wizard` reads the private key with `@file:`.
10654
11604
  > With level `high`, either store the key in the preset (`ascli config preset set <AOC_ORG> private_key @file:<PATH>`, without `@val:`), or use level `medium` with the key in `allowed_paths`.
11605
+ >
11606
+ > In the same way, a secret of a vault read from a file (for example, `token` of HashiCorp Vault: `@file:<path>`) requires level `medium` with the file in `allowed_paths`.
10655
11607
 
10656
11608
  ### HTTP endpoints
10657
11609
 
@@ -10873,7 +11825,7 @@ For [**IBM Bob**](https://bob.ibm.com/docs/ide/configuration/mcp/mcp-in-bob), ad
10873
11825
  }
10874
11826
  ```
10875
11827
 
10876
- For other clients (Claude Desktop, VS Code, and so on), the configuration is identical.
11828
+ Most other clients (Claude Desktop, Cursor, and so on) use the same `mcpServers` format, VS Code uses `servers` (see below).
10877
11829
 
10878
11830
  ##### Claude Desktop `stdio`
10879
11831
 
@@ -10893,6 +11845,47 @@ Place this section in `mcpServers`:
10893
11845
  }
10894
11846
  ```
10895
11847
 
11848
+ ##### Claude Code `stdio`
11849
+
11850
+ For [**Claude Code**](https://code.claude.com/docs/en/mcp), register the server with the command line (option `--scope user` for all projects):
11851
+
11852
+ ```shell
11853
+ claude mcp add ascli -- ascli mcp server
11854
+ ```
11855
+
11856
+ In a shell, Claude Code can also execute `ascli` directly: install the agent skill instead (see [Leveraging AI Assistance](#leveraging-ai-assistance)).
11857
+
11858
+ ##### VS Code `stdio`
11859
+
11860
+ For **VS Code** (GitHub Copilot agent mode), add to `.vscode/mcp.json` in your workspace (or run command **MCP: Add Server**):
11861
+
11862
+ ```json
11863
+ {
11864
+ "servers": {
11865
+ "ascli": {
11866
+ "type": "stdio",
11867
+ "command": "ascli",
11868
+ "args": ["mcp", "server"]
11869
+ }
11870
+ }
11871
+ }
11872
+ ```
11873
+
11874
+ ##### Cursor `stdio`
11875
+
11876
+ For **Cursor**, add to `.cursor/mcp.json` in your project (or `~/.cursor/mcp.json` for global configuration):
11877
+
11878
+ ```json
11879
+ {
11880
+ "mcpServers": {
11881
+ "ascli": {
11882
+ "command": "ascli",
11883
+ "args": ["mcp", "server"]
11884
+ }
11885
+ }
11886
+ }
11887
+ ```
11888
+
10896
11889
  ##### Development mode for `stdio`
10897
11890
 
10898
11891
  If the `ascli` gem is not installed and you are running directly from the source tree, Ruby will not find the `lib/` directory automatically.
@@ -11131,10 +12124,10 @@ ascli config sync spec
11131
12124
  > The options listed in the **Description** column correspond to the equivalent parameters used by the low-level `async` command.
11132
12125
 
11133
12126
  | Field | Type | Description |
11134
- |------------------------------------------|---------------|----------------------------------------------------------------------------------|
12127
+ | ---------------------------------------- | ------------- | -------------------------------------------------------------------------------- |
11135
12128
  | `ascp_dir` | `String` | Directory containing ascp executable to use. |
11136
12129
  | `assume_no_mods` | `Bool` | Assume that the directory structure has not been modified.<br/>Default: `false`.<br/>(`--assume-no-mods`) |
11137
- | `checksum` | `String` | Use the specified checksum type. Default is none on cloud storage.<br/>Allowed values: `sha1`, `md5`, `sha1_sparse`, `md5_sparse`, `none`.<br/>Default: `sha1_sparse`.<br/>(`--checksum={enum}`)(-k) |
12130
+ | `checksum` | `Enum[String]` | Use the specified checksum type. Default is none on cloud storage.<br/>Allowed values: `sha1`, `md5`, `sha1_sparse`, `md5_sparse`, `none`.<br/>Default: `sha1_sparse`.<br/>(`--checksum={enum}`)(-k) |
11138
12131
  | `clean_excluded` | `Bool` | Removes any existing entries in the snapshot database for excluded paths<br/>Default: `false`.<br/>(`--clean-excluded`) |
11139
12132
  | `cookie` | `String` | User-defined identification string.<br/>(`--cookie={string}`) |
11140
12133
  | `cooloff_max_seconds` | `Integer` | Wait up to the specified time for a file to stop changing before skipping synchronization of the file. 0 for disabled<br/>Default: `0`.<br/>(`--cooloff-max={integer}`) |
@@ -11143,19 +12136,20 @@ ascli config sync spec
11143
12136
  | `db_cache_size` | `Integer` | Specify DB cache size.<br/>Default: `16000`. |
11144
12137
  | `db_journal_off` | `Bool` | Turn off DB journal.<br/>Default: `false`. |
11145
12138
  | `db_sync_on` | `Bool` | Enable synchronous write in DB.<br/>Default: `false`. |
11146
- | `dedup` | `String` | Take the specified action when async detects duplicate files on the source.<br/>Allowed values: `copy`, `inode`, `hardlink`, `none`.<br/>Default: `none`.<br/>(`--dedup={enum}`) |
12139
+ | `dedup` | `Enum[String]` | Take the specified action when async detects duplicate files on the source.<br/>Allowed values: `copy`, `inode`, `hardlink`, `none`.<br/>Default: `none`.<br/>(`--dedup={enum}`) |
11147
12140
  | `delete_before` | `Bool` | Schedule deletes before transfers.<br/>Default: `false`.<br/>(`--delete-before`) |
11148
12141
  | `delete_delay` | `Bool` | Delay actual deletes until the end of the synchronization.<br/>Default: `false`.<br/>(`--delete-delay`) |
11149
- | `direction` | `String` | The direction of replication relative to the local.<br/>Allowed values: `bidi`, `pull`, `push`.<br/>Default: `push`.<br/>(`--direction={enum}`)(-K) |
12142
+ | `direction` | `Enum[String]` | The direction of replication relative to the local.<br/>Allowed values: `bidi`, `pull`, `push`.<br/>Default: `push`.<br/>(`--direction={enum}`)(-K) |
12143
+ | `exclude_dirs_older_than` | `Hash` | Don't scan directories with a recursive modified time older than absolute or async start time - relative_seconds |
11150
12144
  | `exclude_dirs_older_than.absolute` | `String` | UTC timestamp. Empty value for disabled. |
11151
12145
  | `exclude_dirs_older_than.relative_seconds` | `Integer` | Relative to async start time. `-1` for disabled.<br/>Default: `-1`. |
11152
- | `exclude_dirs_older_than` | `Hash` | Don't scan directories with a recursive modified time older than absolute or async start time - relative_seconds |
11153
- | `filters[].rule` | `String` | The rule for the filter.<br/>Required.<br/>Allowed values: `include`, `exclude`, `include_from`, `exclude_from`. |
11154
- | `filters[].value` | `String` | On include or exclude, the filter's pattern. On include_from or exclude_from, the path containing filter specifications<br/>Required. |
11155
12146
  | `filters` | `Array[Hash]` | The filters allow to further specify which files have to be excluded and included from the transfer list. Each filter is defined by a rule and a value. Order of filters matters |
12147
+ | `filters[].rule` | `Enum[String]` | The rule for the filter.<br/>Required.<br/>Allowed values: `include`, `exclude`, `include_from`, `exclude_from`. |
12148
+ | `filters[].value` | `String` | On include or exclude, the filter's pattern. On include_from or exclude_from, the path containing filter specifications<br/>Required. |
11156
12149
  | `ignore_delete` | `Bool` | Do not copy removals to the peer.<br/>Default: `false`.<br/>(`--ignore-delete`) |
11157
12150
  | `ignore_mode` | `Bool` | Source files that have had their mode changed after the initial transfer will not update the destination file mode.<br/>Default: `false`.<br/>(`--ignore-mode`) |
11158
12151
  | `ignore_remote_host_sync_name` | `Bool` | Do not check that the remote host being used for the current transfer matches the host used when the local database was created<br/>Default: `false`. |
12152
+ | `local` | `Hash` | Required. |
11159
12153
  | `local.pass` | `String` | Authenticate the local async with the specified password. |
11160
12154
  | `local.path` | `String` | The directory to be synchronized on the local host.<br/>Required.<br/>(`--local-dir={string}`)(-d) |
11161
12155
  | `local_apply_docroot` | `Bool` | Prepend the docroot to the directory on the local host.<br/>Default: `false`.<br/>(`--apply-local-docroot`) |
@@ -11167,26 +12161,25 @@ ascli config sync spec
11167
12161
  | `local_keep_dir` | `String` | Move deleted files into the specified directory on the local host.<br/>(`--keep-dir-local={string}`) |
11168
12162
  | `local_mount_signature` | `String` | Verify that the file system is mounted by the existence of this file on the local host.<br/>(`--local-mount-signature={string}`) |
11169
12163
  | `local_move_cache_timeout_seconds` | `Integer` | Delay in seconds before aborting moving a file from local cache to final destination. `-1` for disabled.<br/>Default: `-1`.<br/>(`--local-move-cache-timeout={integer}`) |
11170
- | `local_preserve_acls` | `String` | Preserve access control lists on the local host.<br/>Allowed values: `native`, `metafile`, `none`.<br/>Default: `none`.<br/>(`--preserve-acls={enum}`) |
11171
- | `local_preserve_xattrs` | `String` | Preserve extended attributes on the local.<br/>Allowed values: `native`, `metafile`, `none`.<br/>Default: `none`.<br/>(`--preserve-xattrs={enum}`) |
12164
+ | `local_preserve_acls` | `Enum[String]` | Preserve access control lists on the local host.<br/>Allowed values: `native`, `metafile`, `none`.<br/>Default: `none`.<br/>(`--preserve-acls={enum}`) |
12165
+ | `local_preserve_xattrs` | `Enum[String]` | Preserve extended attributes on the local.<br/>Allowed values: `native`, `metafile`, `none`.<br/>Default: `none`.<br/>(`--preserve-xattrs={enum}`) |
11172
12166
  | `local_scan_interval_milliseconds` | `Integer` | Enable periodic scans on the local host during a continuous sync. `-1` for disabled. On the command line, the value is a duration, e.g. `1h 30m`, `2s500ms`, `5:30`, `1d 02:00:00.250`. A plain number is in seconds. Stored in milliseconds.<br/>Default: `-1`.<br/>(`--scan-interval={integer}`) |
11173
12167
  | `local_scan_threads` | `Integer` | Number of directory scanning threads on the local host. Value must be between 1 and 99<br/>Default: `1`.<br/>(`--scan-threads={integer}`) |
11174
12168
  | `local_stat_cache_size` | `Integer` | Set stat cache size on the local host. 0 for disabled.<br/>Default: `0`. |
11175
- | `local` | `Hash` | Required. |
11176
- | `log.level` | `String` | Use the specified log level.<br/>Allowed values: `log`, `dbg1`, `dbg2`.<br/>Default: `log`.<br/>(special:`-D`) |
12169
+ | `log` | `Hash` | |
12170
+ | `log.level` | `Enum[String]` | Use the specified log level.<br/>Allowed values: `log`, `dbg1`, `dbg2`.<br/>Default: `log`.<br/>(special:`-D`) |
11177
12171
  | `log.local_dir` | `String` | Use the specified logging directory on the local host.<br/>(`--alt-logdir={string}`)(-L) |
11178
12172
  | `log.remote_dir` | `String` | Use the specified logging directory on the remote host.<br/>(`--remote-logdir={string}`)(-R) |
11179
- | `log` | `Hash` | |
11180
12173
  | `manifest_path` | `String` | A directory path where ascp will create manifest TEXT files (passed to ascp as --file-manifest-path) |
11181
12174
  | `mirror` | `Bool` | Force the pulling side to be exactly like the pushing side, removing files on the destination that don't exist on the source and resending source files that don't have an exact match on the destination. Cannot be used in bi-directional mode.<br/>Default: `false`.<br/>(`--mirror`) |
11182
- | `mode` | `String` | Specify whether async runs continuously or not. In `one_time` mode, async stops after the first full synchronization. `continuous` supported only if the source is Windows or Linux.<br/>Allowed values: `one_time`, `continuous`.<br/>Default: `one_time`.<br/>(special:`--continuous`)(-C) |
12175
+ | `mode` | `Enum[String]` | Specify whether async runs continuously or not. In `one_time` mode, async stops after the first full synchronization. `continuous` supported only if the source is Windows or Linux.<br/>Allowed values: `one_time`, `continuous`.<br/>Default: `one_time`.<br/>(special:`--continuous`)(-C) |
11183
12176
  | `monitor_buffer_size` | `Integer` | Bytes to allocate for the change monitor buffer. Applies to any Windows machine on either side. `-1` to use the computed value.<br/>Default: `-1`. |
11184
12177
  | `name` | `String` | Name of the synchronization pair.<br/>Required.<br/>(`--name={string}`)(-N) |
11185
12178
  | `no_log` | `String` | Suppress log messages for ITEM. The only currently supported ITEM is 'stats', which suppresses both STATS and PROG log messages.<br/>(`--no-log={string}`) |
11186
12179
  | `no_preserve_root_attrs` | `Bool` | Disable the preservation of attributes on the Sync root.<br/>Default: `false`.<br/>(`--no-preserve-root-attrs`) |
11187
12180
  | `no_scan` | `Bool` | Skip initial scanning.<br/>Default: `false`.<br/>(`--no-scan`) |
11188
12181
  | `notifications_sharing_retry_max` | `Integer` | Retry processing filesystem notifications up to the specified maximum number after a sharing violation.<br/>Default: `3`. |
11189
- | `overwrite` | `String` | Overwrite files according to the specified policy. Default is determined by the direction: `conflict` for `bidi`, otherwise `always`.<br/>Allowed values: `always`, `older`, `conflict`.<br/>(`--overwrite={enum}`)(-o) |
12182
+ | `overwrite` | `Enum[String]` | Overwrite files according to the specified policy. Default is determined by the direction: `conflict` for `bidi`, otherwise `always`.<br/>Allowed values: `always`, `older`, `conflict`.<br/>(`--overwrite={enum}`)(-o) |
11190
12183
  | `pending_max` | `Integer` | Allow the maximum number of files that are pending transfer to be no more than the specified number.<br/>Default: `2000`.<br/>(`--pending-max={integer}`) |
11191
12184
  | `preserve_access_time` | `Bool` | Preserve file access time from the source to the destination.<br/>Default: `false`.<br/>(`--preserve-access-time`) |
11192
12185
  | `preserve_creation_time` | `Bool` | Preserve file creation time from the source to the destination.<br/>Default: `false`.<br/>(`--preserve-creation-time`) |
@@ -11197,21 +12190,22 @@ ascli config sync spec
11197
12190
  | `preserve_object_metadata` | `Bool` | Preserve object metadata from the source to the destination.<br/>Default: `false`.<br/>(`--preserve-object-metadata`) |
11198
12191
  | `preserve_uid` | `Bool` | Preserve the file owner's UID.<br/>Default: `false`.<br/>(`--preserve-uid`)(-u) |
11199
12192
  | `quiet` | `Bool` | Disable progress display.<br/>Default: `true`.<br/>(`--quiet`)(-q) |
11200
- | `remote.connect_mode` | `String` | Define how to connect to the remote.<br/>Allowed values: `ssh`, `ws`.<br/>Default: `ssh`.<br/>(special:`--ws-connect`) |
12193
+ | `remote` | `Hash` | Required. |
12194
+ | `remote.connect_mode` | `Enum[String]` | Define how to connect to the remote.<br/>Allowed values: `ssh`, `ws`.<br/>Default: `ssh`.<br/>(special:`--ws-connect`) |
11201
12195
  | `remote.fingerprint` | `String` | Check it against server SSH host key fingerprint. |
11202
12196
  | `remote.host` | `String` | Use the specified host name or address of the remote host.<br/>Required.<br/>(`--host={string}`) |
11203
12197
  | `remote.pass` | `String` | Authenticate the transfer with the specified password.<br/>(`--pass={string}`)(-w) |
11204
12198
  | `remote.path` | `String` | Synchronize the specified directory on the remote host.<br/>Required.<br/>(`--remote-dir={string}`)(-r) |
11205
12199
  | `remote.port` | `Integer` | Use the specified TCP port for SSH. Used when connect_mode is `ssh`<br/>Default: `22`.<br/>(`--tcp-port={integer}`)(-P) |
11206
12200
  | `remote.private_key_paths` | `Array[String]` | Authenticate with the specified SSH private key file.<br/>(`--private-key-path={array}`)(-i) |
12201
+ | `remote.proxy` | `Hash` | Specify the address of the Aspera high-speed proxy server.<br/>(special:`--proxy={object}`) |
11207
12202
  | `remote.proxy.host` | `String` | Use the specified host name or address of the proxy. |
11208
12203
  | `remote.proxy.pass` | `String` | Authenticate to the proxy with the specified password. |
11209
12204
  | `remote.proxy.port` | `Integer` | Use the specified port. Default is 9091 for dnat, 9092 for dnats. |
11210
- | `remote.proxy.protocol` | `String` | The protocol to be used.<br/>Allowed values: `none`, `dnat`, `dnats`.<br/>Default: `none`. |
12205
+ | `remote.proxy.protocol` | `Enum[String]` | The protocol to be used.<br/>Allowed values: `none`, `dnat`, `dnats`.<br/>Default: `none`. |
11211
12206
  | `remote.proxy.user` | `String` | Authenticate to the proxy with the specified username. |
11212
- | `remote.proxy` | `Hash` | Specify the address of the Aspera high-speed proxy server.<br/>(special:`--proxy={object}`) |
11213
- | `remote.token_node_user` | `String` | Node API user identity associated with the token. Required for node user bearer tokens |
11214
12207
  | `remote.token` | `String` | Token string passed to server's authentication service. |
12208
+ | `remote.token_node_user` | `String` | Node API user identity associated with the token. Required for node user bearer tokens |
11215
12209
  | `remote.user` | `String` | Authenticate the transfer with the specified username.<br/>Required.<br/>(`--user={string}`) |
11216
12210
  | `remote.ws_port` | `Integer` | Use the specified port for Websocket. Used when connect_mode is `ws`.<br/>Default: `9093`. |
11217
12211
  | `remote_checksum_threads` | `Integer` | Maximum number of threads to do checksum on the remote host. Value must be between 1 and 99<br/>Default: `4`.<br/>(`--remote-checksum-threads={integer}`) |
@@ -11222,46 +12216,45 @@ ascli config sync spec
11222
12216
  | `remote_keep_dir` | `String` | Move deleted files into the specified directory on the remote host.<br/>(`--keep-dir-remote={string}`) |
11223
12217
  | `remote_mount_signature` | `String` | Verify that the file system is mounted by the existence of this file on the remote host.<br/>(`--remote-mount-signature={string}`) |
11224
12218
  | `remote_move_cache_timeout_seconds` | `Integer` | Delay in seconds before aborting moving a file from remote cache to final destination. `-1` for disabled.<br/>Default: `-1`.<br/>(`--remote-move-cache-timeout={integer}`) |
11225
- | `remote_preserve_acls` | `String` | Preserve access control lists on the remote host. If not specified, the default behavior is to use the same storage mode as specified by `preserve_acls`.<br/>Allowed values: `native`, `metafile`, `none`.<br/>(`--remote-preserve-acls={enum}`) |
11226
- | `remote_preserve_xattrs` | `String` | Preserve extended attributes on the remote host. If not specified, the default behavior is to use the same storage mode as specified by `preserve_xattrs`.<br/>Allowed values: `native`, `metafile`, `none`.<br/>(`--remote-preserve-xattrs={enum}`) |
12219
+ | `remote_preserve_acls` | `Enum[String]` | Preserve access control lists on the remote host. If not specified, the default behavior is to use the same storage mode as specified by `preserve_acls`.<br/>Allowed values: `native`, `metafile`, `none`.<br/>(`--remote-preserve-acls={enum}`) |
12220
+ | `remote_preserve_xattrs` | `Enum[String]` | Preserve extended attributes on the remote host. If not specified, the default behavior is to use the same storage mode as specified by `preserve_xattrs`.<br/>Allowed values: `native`, `metafile`, `none`.<br/>(`--remote-preserve-xattrs={enum}`) |
11227
12221
  | `remote_scan_interval_milliseconds` | `Integer` | Enable periodic scans on the remote host. `-1` for disabled. On the command line, the value is a duration, e.g. `1h 30m`, `2s500ms`, `5:30`, `1d 02:00:00.250`. A plain number is in seconds. Stored in milliseconds.<br/>Default: `-1`.<br/>(special:`--remote-scan-interval={integer}`) |
11228
12222
  | `remote_scan_threads` | `Integer` | Number of directory scanning threads on the remote host. Value must be between 1 and 99.<br/>Default: `1`.<br/>(`--remote-scan-threads={integer}`) |
11229
12223
  | `remote_stat_cache_size` | `Integer` | Set stat cache size on the remote host. 0 for disabled.<br/>Default: `0`. |
11230
- | `remote` | `Hash` | Required. |
11231
12224
  | `remove_after_transfer` | `Bool` | Remove source files after they are successfully synchronized.<br/>Default: `false`.<br/>(`--remove-after-transfer`) |
11232
12225
  | `reset` | `Bool` | Clear the snapshot database and rescan the synchronized directories and files to create a fresh snapshot<br/>Default: `false`.<br/>(`--reset`)(-x) |
12226
+ | `resume` | `Hash` | Partial transfers may exist if communication disruptions caused the underlying ascp processes to terminate early. Note that transfer resumption can only happen if the `reset` option is disabled. If an async session starts with `reset` enabled and resume enabled, transfers interrupted during that session will be resumable, but only if async is then restarted with 'reset' disabled. |
11233
12227
  | `resume.enabled` | `Bool` | Enable the possibility of resuming individual file transfers between async sessions.<br/>Default: `false`. |
11234
12228
  | `resume.max_age` | `Integer` | Sets the age limit in days for temporary files that will be preserved on cleanup (usually at async's start and stop) for potential transfer resume. Temp files older than the given value will be removed regardless of whether they might be resumable.<br/>Default: `5`.<br/>(`--resume-age-days={integer}`) |
11235
12229
  | `resume.min_size` | `Integer` | This field specifies the minimum size of files that will be allowed to resume.<br/>Default: `1048576`.<br/>(`--support-resume={integer}`) |
11236
12230
  | `resume_scan` | `Bool` | Resume the scan from where the previous execution left off.<br/>Default: `false`.<br/>(`--resume-scan`) |
11237
- | `resume` | `Hash` | Partial transfers may exist if communication disruptions caused the underlying ascp processes to terminate early. Note that transfer resumption can only happen if the `reset` option is disabled. If an async session starts with `reset` enabled and resume enabled, transfers interrupted during that session will be resumable, but only if async is then restarted with 'reset' disabled. |
11238
12231
  | `scan_dir_rename` | `Bool` | Enable the detection of renamed directories and files compared to the previous scan, based on matching inodes<br/>Default: `false`.<br/>(`--scan-dir-rename`) |
11239
12232
  | `scan_file_rename` | `Bool` | Enable the detection of renamed files compared to the previous scan, based on matching inodes.<br/>Default: `false`.<br/>(`--scan-file-rename`) |
11240
- | `scan_intensity` | `String` | Scan at the set intensity. `vlow` minimizes system activity. `vhigh` maximizes system activity by continuously scanning files without rest.<br/>Allowed values: `vlow`, `low`, `medium`, `high`, `vhigh`.<br/>Default: `medium`.<br/>(`--scan-intensity={enum}`)(-H) |
12233
+ | `scan_intensity` | `Enum[String]` | Scan at the set intensity. `vlow` minimizes system activity. `vhigh` maximizes system activity by continuously scanning files without rest.<br/>Allowed values: `vlow`, `low`, `medium`, `high`, `vhigh`.<br/>Default: `medium`.<br/>(`--scan-intensity={enum}`)(-H) |
11241
12234
  | `sharing_retry_max` | `Integer` | Retry synchronizations up to the specified maximum number after a sharing violation.<br/>Default: `3`.<br/>(`--sharing-retry-max={integer}`) |
11242
12235
  | `store_metadata_records` | `Bool` | Store the acls or xattrs in the snapshot database.<br/>Default: `false`.<br/>(`--store-metadata-records`) |
11243
- | `symbolic_links` | `String` | Handle symbolic links with the specified method. Default is `skip` on windows, `copy` otherwise.<br/>Allowed values: `copy`, `skip`, `follow`.<br/>(`--symbolic-links={enum}`)(-n) |
12236
+ | `symbolic_links` | `Enum[String]` | Handle symbolic links with the specified method. Default is `skip` on windows, `copy` otherwise.<br/>Allowed values: `copy`, `skip`, `follow`.<br/>(`--symbolic-links={enum}`)(-n) |
11244
12237
  | `tags` | `Hash` | User-defined metadata tags.<br/>(special:`--tags64={object}`) |
12238
+ | `transfer_threads` | `Array[Hash]` | Use the specified number of dedicated transfer threads to process files smaller or equal to the specified size<br/>(special:`--transfer-threads={array}`) |
11245
12239
  | `transfer_threads[].size` | `Integer` | Upper limit. `-1` for infinity.<br/>Default: `-1`. |
11246
12240
  | `transfer_threads[].threads` | `Integer` | The number of threads.<br/>Required. |
11247
- | `transfer_threads` | `Array[Hash]` | Use the specified number of dedicated transfer threads to process files smaller or equal to the specified size<br/>(special:`--transfer-threads={array}`) |
11248
- | `transport.cipher` | `String` | Specify encryption algorithm for file data.<br/>Allowed values: `none`, `aes128`, `aes192`, `aes256`, `aes128cfb`, `aes192cfb`, `aes256cfb`, `aes128gcm`, `aes192gcm`, `aes256gcm`.<br/>Default: `aes128`.<br/>(`--cipher={enum}`)(-c) |
11249
- | `transport.compression` | `String` | Compress a file before transfer using the specified MODE.<br/>Allowed values: `none`, `zlib`.<br/>Default: `none`.<br/>(`--compression={enum}`) |
12241
+ | `transport` | `Hash` | |
12242
+ | `transport.cipher` | `Enum[String]` | Specify encryption algorithm for file data.<br/>Allowed values: `none`, `aes128`, `aes192`, `aes256`, `aes128cfb`, `aes192cfb`, `aes256cfb`, `aes128gcm`, `aes192gcm`, `aes256gcm`.<br/>Default: `aes128`.<br/>(`--cipher={enum}`)(-c) |
12243
+ | `transport.compression` | `Enum[String]` | Compress a file before transfer using the specified MODE.<br/>Allowed values: `none`, `zlib`.<br/>Default: `none`.<br/>(`--compression={enum}`) |
11250
12244
  | `transport.datagram_size` | `Integer` | Specify the datagram size (MTU) for FASP. By default it uses the detected path MTU.<br/>(`--datagram-size={integer}`)(-Z) |
11251
12245
  | `transport.min_rate` | `Integer` | Attempt to transfer no slower than the specified rate (in bps).<br/>Default: `0`.<br/>(`--min-rate={integer}`)(-m) |
11252
- | `transport.rate_policy` | `String` | Defines how `ascp` will manage the bandwidth.<br/>Allowed values: `fair`, `fixed`, `high`, `low`.<br/>Default: `fair`.<br/>(`--rate-policy={enum}`)(-a) |
12246
+ | `transport.rate_policy` | `Enum[String]` | Defines how `ascp` will manage the bandwidth.<br/>Allowed values: `fair`, `fixed`, `high`, `low`.<br/>Default: `fair`.<br/>(`--rate-policy={enum}`)(-a) |
11253
12247
  | `transport.raw_options` | `Array[String]` | Pass arbitrary arguments to `ascp`.<br/>(special:`--raw-options={array}`) |
11254
12248
  | `transport.read_block_size` | `Integer` | Use the specified block size (in bytes) for reading. Default is determined by `aspera.conf`.<br/>(`--read-block-size={integer}`)(-g) |
11255
12249
  | `transport.rexmsg_size` | `Integer` | Use the specified size (in bytes) for a retransmission request. Default is determined by `aspera.conf`.<br/>(`--rexmsg-size={integer}`)(-X) |
11256
12250
  | `transport.target_rate` | `Integer` | Transfer no faster than the specified rate (in bps). A string with suffix `k`, `m` or `g` is converted to bps by `ascli` (e.g. `100m`).<br/>Default: `10000000`.<br/>(`--target-rate={integer}`)(-l) |
11257
12251
  | `transport.udp_port` | `Integer` | Use the specified UDP port for FASP data transfer.<br/>Default: `33001`.<br/>(`--udp-port={integer}`)(-O) |
11258
12252
  | `transport.write_block_size` | `Integer` | Use the specified block size (in bytes) for writing. Default is determined by `aspera.conf`.<br/>(`--write-block-size={integer}`)(-G) |
11259
- | `transport` | `Hash` | |
11260
- | `watchd.datastore` | `String` | Specify the type of datastore, `none` for disabled.<br/>Allowed values: `none`, `redis`, `scalekv`.<br/>Default: `none`. |
12253
+ | `watchd` | `Hash` | When connection is configured, `asperawatchd` is used to detect the changes on the source directory.<br/>(special:`--watchd={object}`) |
12254
+ | `watchd.datastore` | `Enum[String]` | Specify the type of datastore, `none` for disabled.<br/>Allowed values: `none`, `redis`, `scalekv`.<br/>Default: `none`. |
11261
12255
  | `watchd.domain` | `String` | Specify the domain. Default is the current username. |
11262
12256
  | `watchd.host` | `String` | Use the specified host name or address to connect to the datastore. |
11263
12257
  | `watchd.port` | `Integer` | Use the specified port.<br/>Default: `31415`. |
11264
- | `watchd` | `Hash` | When connection is configured, `asperawatchd` is used to detect the changes on the source directory.<br/>(special:`--watchd={object}`) |
11265
12258
  | `write_gid` | `String` | Try to write files as the specified group.<br/>(`--write-gid={string}`) |
11266
12259
  | `write_uid` | `String` | Try to write files as the specified user.<br/>(`--write-uid={string}`) |
11267
12260
 
@@ -11338,16 +12331,16 @@ ascli ... sync admin file_info <FOLDER> --sql="WHERE state=20 ORDER BY f_meta_pa
11338
12331
  **`sync_snapmeta_table`** - one row per session, written at start and updated at stop:
11339
12332
 
11340
12333
  | Field | Type | Description |
11341
- |-------------------------|---------|----------------------------------------------------------------------------------|
12334
+ | ----------------------- | ------------ | -------------------------------------------------------------------------------- |
11342
12335
  | `ascp_sids` | `String` | Last known FASP (ascp) session IDs. |
11343
12336
  | `byte_peerxfer` | `Integer` | Number of bytes transferred by the peer. |
11344
12337
  | `byte_synced` | `Integer` | Number of bytes successfully synchronized. |
11345
12338
  | `byte_xferres` | `Integer` | Number of bytes for which transfer was resumed. |
11346
- | `checksum` | `String` | Checksum algorithm.<br/>Allowed values: `sha1`, `md5`, `sha1_sparse`, `md5_sparse`, `none`. |
12339
+ | `checksum` | `Enum[String]` | Checksum algorithm.<br/>Allowed values: `sha1`, `md5`, `sha1_sparse`, `md5_sparse`, `none`. |
11347
12340
  | `cip_true_val` | `Integer` | Candidate-in-progress counter true value (internal). |
11348
- | `condition` | `String` | Last known session condition.<br/>Allowed values: `running`, `stopped`. |
12341
+ | `condition` | `Enum[String]` | Last known session condition.<br/>Allowed values: `running`, `stopped`. |
11349
12342
  | `dbversion` | `String` | Database schema version. |
11350
- | `direction` | `String` | Sync direction.<br/>Allowed values: `push`, `pull`, `bidi`. |
12343
+ | `direction` | `Enum[String]` | Sync direction.<br/>Allowed values: `push`, `pull`, `bidi`. |
11351
12344
  | `exclude_dirs_older_than` | `Integer` | Exclude directories with modification time older than this epoch value (0 = disabled). |
11352
12345
  | `file_peerxfer` | `Integer` | Number of files transferred by the peer. |
11353
12346
  | `file_synced` | `Integer` | Number of files successfully synchronized. |
@@ -11371,7 +12364,7 @@ ascli ... sync admin file_info <FOLDER> --sql="WHERE state=20 ORDER BY f_meta_pa
11371
12364
  **`sync_snap_counters_table`** - one row, updated live during a session:
11372
12365
 
11373
12366
  | Field | Type | Description |
11374
- |--------------------------|---------|--------------------------------------------------|
12367
+ | ------------------------ | ------- | ------------------------------------------------ |
11375
12368
  | `conflict` | `Integer` | Number of paths in the `Conflict` state. |
11376
12369
  | `error` | `Integer` | Number of paths in the `Error` state. |
11377
12370
  | `files_conflict` | `Integer` | Number of files in the `Conflict` state. |
@@ -11387,7 +12380,7 @@ ascli ... sync admin file_info <FOLDER> --sql="WHERE state=20 ORDER BY f_meta_pa
11387
12380
  **`sync_snapdb_table`** - one row per tracked file or directory:
11388
12381
 
11389
12382
  | Field | Type | Description |
11390
- |------------------------|---------|----------------------------------------------------------------------------------|
12383
+ | ---------------------- | ------- | -------------------------------------------------------------------------------- |
11391
12384
  | `c_cont_csum` | `String` | Current content — checksum. |
11392
12385
  | `c_cont_mtime` | `Integer` | Current content — modification time (epoch). |
11393
12386
  | `c_cont_size` | `Integer` | Current content — file size in bytes. |
@@ -11405,8 +12398,8 @@ ascli ... sync admin file_info <FOLDER> --sql="WHERE state=20 ORDER BY f_meta_pa
11405
12398
  | `c_meta_path` | `String` | Current metadata — file path as known to the snapshot. |
11406
12399
  | `c_meta_type` | `Integer` | Current metadata — file type (file, directory, …). |
11407
12400
  | `c_meta_uid` | `Integer` | Current metadata — user ID (Unix). |
11408
- | `c_meta_xattrs_cksum` | `String` | Current metadata — checksum of extended attributes. |
11409
12401
  | `c_meta_xattrs` | `Integer` | Current metadata — extended attributes (not used). |
12402
+ | `c_meta_xattrs_cksum` | `String` | Current metadata — checksum of extended attributes. |
11410
12403
  | `candidate_in_prog` | `Integer` | Set to 1 when this record is currently in the candidate transfer list. |
11411
12404
  | `commit_version` | `Integer` | Local commit version for this entry. |
11412
12405
  | `f_cont_csum` | `String` | Filesystem content — checksum. |
@@ -11426,8 +12419,8 @@ ascli ... sync admin file_info <FOLDER> --sql="WHERE state=20 ORDER BY f_meta_pa
11426
12419
  | `f_meta_path` | `String` | Filesystem metadata — file path as seen on disk (displayed by `file_info`). |
11427
12420
  | `f_meta_type` | `Integer` | Filesystem metadata — file type. |
11428
12421
  | `f_meta_uid` | `Integer` | Filesystem metadata — user ID (Unix). |
11429
- | `f_meta_xattrs_cksum` | `String` | Filesystem metadata — checksum of extended attributes. |
11430
12422
  | `f_meta_xattrs` | `Integer` | Filesystem metadata — extended attributes (not used). |
12423
+ | `f_meta_xattrs_cksum` | `String` | Filesystem metadata — checksum of extended attributes. |
11431
12424
  | `message` | `String` | Error or status message associated with this entry. |
11432
12425
  | `meta_lastreq_no` | `Integer` | Sequence number of the last metadata request sent. |
11433
12426
  | `meta_lastresp_no` | `Integer` | Sequence number of the last metadata response received. |
@@ -11588,11 +12581,11 @@ To do so, set up the SMTP configuration with option `smtp`.
11588
12581
  The `smtp` option is a `Hash` ([Extended Value](#extended-value-syntax)) with the following fields:
11589
12582
 
11590
12583
  | Field | Type | Description |
11591
- |------------|---------|----------------------------------------------------------------------------------|
12584
+ | ---------- | ------- | -------------------------------------------------------------------------------- |
11592
12585
  | `domain` | `String` | Email domain of the user. Defaults to the domain part of `server`.<br/>Example: `gmail.com`. |
11593
12586
  | `from_email` | `String` | Sender address (used in `From:` header and as reply-to). Defaults to `username` when defined.<br/>Example: `johnny@example.com`. |
11594
12587
  | `from_name` | `String` | Display name of the sender. Defaults to the local-part of `from_email`.<br/>Example: `John Wayne`. |
11595
- | `password` | `String` | Password for the above `username`.<br/>Example: `my_password`. |
12588
+ | `password` | `String` | Password for the above `username`.<br/>Example: `<PASSWORD>`. |
11596
12589
  | `port` | `Integer` | Port for the SMTP service.<br/>Defaults: `587` (TLS), `465` (SSL), `25` (plain).<br/>Example: `587`. |
11597
12590
  | `server` | `String` | SMTP server address.<br/>Required.<br/>Example: `smtp.gmail.com`. |
11598
12591
  | `ssl` | `Bool` | Enable `TLS/SSL` (port 465).<br/>Default: `false`. |
@@ -11610,14 +12603,13 @@ ascli config preset set smtp_google password <PASSWORD>
11610
12603
  or
11611
12604
 
11612
12605
  ```shell
11613
- ascli config preset initialize smtp_google @json:'{"server":"smtp.google.com","username":"john@gmail.com","password":"<PASSWORD>"}'
12606
+ ascli config preset set smtp_google @json:'{"server":"smtp.google.com","username":"john@gmail.com","password":"<PASSWORD>"}'
11614
12607
  ```
11615
12608
 
11616
12609
  or
11617
12610
 
11618
-
11619
12611
  ```shell
11620
- ascli config preset update smtp_google --server=smtp.google.com --username=john@gmail.com --password=<PASSWORD>
12612
+ ascli config preset set smtp_google @: server=smtp.google.com username=john@gmail.com password=<PASSWORD>
11621
12613
  ```
11622
12614
 
11623
12615
  Set this configuration as global default, for instance:
@@ -11821,28 +12813,26 @@ This also requires Ruby header files.
11821
12813
  If Ruby was installed as a Linux package, then also install the Ruby development package:
11822
12814
  `ruby-dev` or `ruby-devel`, depending on distribution.
11823
12815
 
11824
- ### Private key type: `ed25519` not supported by default
11825
-
11826
- There are a few aspects concerning ED25519 keys.
12816
+ ### Private key type: `ed25519`
11827
12817
 
11828
- By default, the `aspera-cli` gem does not depend on the `ed25519` gem because it requires compilation of native code which can cause problems and prevent the installation of `ascli`, especially when using JRuby.
11829
- See [net-ssh issue 565](https://github.com/net-ssh/net-ssh/issues/565).
11830
- If you want to use `ed25519` keys, then install the required gems:
12818
+ Keys of type `ed25519` and keys in the OpenSSH format are supported by `net-ssh` using the Ruby `openssl` gem (>= 3.2.0): the `ed25519` gem is not needed.
12819
+ Only OpenSSH private keys protected by a passphrase require the `bcrypt_pbkdf` gem, which requires compilation of native code:
11831
12820
 
11832
12821
  ```shell
11833
- gem install ed25519 bcrypt_pbkdf
12822
+ gem install bcrypt_pbkdf
11834
12823
  ```
11835
12824
 
11836
- In addition, if those two gems are not installed, and if you are using Private Keys encoded using the OpenSSH format, the following message is displayed:
12825
+ If the gem is missing, then loading such a key fails with an error mentioning `bcrypt_pbkdf`.
12826
+
12827
+ If the OpenSSL backend does not support Ed25519, then the following message is displayed:
11837
12828
 
11838
12829
  ```text
11839
12830
  OpenSSH keys only supported if ED25519 is available (NotImplementedError)
11840
- net-ssh requires the following gems for ed25519 support:
11841
- * ed25519 (>= 1.2, < 2.0)
11842
- * bcrypt_pbkdf (>= 1.0, < 2.0)
11843
- See https://github.com/net-ssh/net-ssh/issues/565 for more information
12831
+ net-ssh requires openssl >= 3.2.0 and a crypto backend with Ed25519 enabled for ed25519 support.
11844
12832
  ```
11845
12833
 
12834
+ To ignore the `ed25519` keys of the default identities (`~/.ssh/id_ed25519`), set env var `ASCLI_ENABLE_ED25519` to `false`.
12835
+
11846
12836
  In addition, if **JRuby** is used, host keys of type: `ecdsa-sha2` and `ecdh-sha2` are also deactivated by default.
11847
12837
  To activate, set env var `ASCLI_ENABLE_ECDSHA2` to `true`.
11848
12838
 
@@ -11878,7 +12868,7 @@ This happens on Linux x86 if you try to install `transferd` on a Linux version t
11878
12868
  Workaround: Install an older version of `transferd`:
11879
12869
 
11880
12870
  ```shell
11881
- ascli config transferd install 1.1.2
12871
+ ascli transferd install 1.1.2
11882
12872
  ```
11883
12873
 
11884
12874
  See [Single file executable](#single-file-executable).
@@ -11919,11 +12909,45 @@ Another possibility is to add this option: `--transfer=@json:'{"ascp_args":["--p
11919
12909
  > If one relies on `--lock-port` when using containers to avoid parallel transfers in a cron job, this may be the cause, as `lock_port` does not lock across containers.
11920
12910
  > Use `flock` instead.
11921
12911
 
12912
+ ## Security and Trust
12913
+
12914
+ This section is for security and compliance reviewers who evaluate `ascli` before its use in an organization.
12915
+ It summarizes how `ascli` protects credentials, communications and the system that runs it, and how the project is developed and released.
12916
+ The detailed reasoning is in the [Security Assurance Case](ASSURANCE_CASE.md).
12917
+
12918
+ ### Protection by area
12919
+
12920
+ | Area | How `ascli` protects it | Details |
12921
+ | ---- | ------------------------ | ------- |
12922
+ | Credentials | Secret values are hidden in logs, results and error messages. Secrets can be kept in a vault instead of the configuration file: encrypted file, HashiCorp Vault, Keeper, 1Password, macOS keychain, Linux Secret Service. The configuration folder is readable only by the current user. | [Secret Vault](#secret-vault) |
12923
+ | Communications | API calls use HTTPS, and the certificate of the server is verified by default (disabled only with `--insecure=yes`). | [SSL CA certificate bundle](#configuring-the-ssl-ca-certificate-bundle) |
12924
+ | File transfers | Transfers use the IBM Aspera transfer engine (`ascp`), with the encryption in transit and at rest defined by the server and the transfer specification. | [Transfer Specification](#transfer-specification) |
12925
+ | Execution by a client that is not fully trusted (AI assistant, program that builds commands) | A security level restricts what commands can do: reading local files, executing code, writing files. The MCP server uses level `high` by default, and the client cannot change it. | [Security Level](#security-level) |
12926
+ | AI assistants (MCP server) | The AI client cannot execute code, cannot write files outside the folders that the user allows, and never sees secrets. Over HTTP, a token is mandatory when the server is not on the loopback address, and OAuth 2.0 with PKCE is supported. | [MCP server security](#security) |
12927
+ | Local web servers (login, MCP over HTTP) | They listen on the loopback address by default, with authentication and protection against cross-site requests. | [Web service](#web-service) |
12928
+ | Usage data | `ascli` sends no usage data (no telemetry). It connects to the servers given in commands and presets, and to public IBM and GitHub locations only for the commands that download from them (for example `transferd install`, development guides). Every 7 days by default, it checks RubyGems for a new version (option `version_check_days`, `0` to disable). | [Configuration](#plugin-config-configuration) |
12929
+
12930
+ ### Supply chain
12931
+
12932
+ - The gem is signed: its signature can be verified at installation, see [Verifying gem installation signature](#verifying-gem-installation-signature).
12933
+ - Publishing the gem on RubyGems requires multi-factor authentication.
12934
+ - Release packages (gem, single executable, portable packages, container image) are built by GitHub Actions from the repository.
12935
+ - Dependencies are gems, updated with Renovate.
12936
+ - The source code is analyzed by CodeQL and RuboCop in continuous integration, and tested by unit and integration tests, including tests of the security levels (coverage is shown in the README badge).
12937
+
12938
+ ### Project practices
12939
+
12940
+ - Open source, Apache 2.0 license, developed in the [IBM GitHub organization](https://github.com/IBM/aspera-cli).
12941
+ - [OpenSSF Best Practices](https://www.bestpractices.dev/projects/5861): silver badge.
12942
+ - Vulnerabilities are reported and handled as described in [SECURITY.md](../SECURITY.md).
12943
+ - Roles, decisions and continuity of the project: [GOVERNANCE.md](../GOVERNANCE.md).
12944
+ - Structure of the code: [ARCHITECTURE.md](ARCHITECTURE.md).
12945
+
11922
12946
  ## About
11923
12947
 
11924
12948
  ### Hootput, the mascot
11925
12949
 
11926
- ![Hootput the Owl](mascot.svg)
12950
+ ![Hootput the Owl](art/mascot.svg)
11927
12951
 
11928
12952
  Hootput lives in the terminal, watching over every command with wide, unblinking eyes.
11929
12953
  Known for concise output and sharp insight, this owl thrives where others get lost in the dark.