aspera-cli 4.27.5 → 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 (249) hide show
  1. checksums.yaml +4 -4
  2. checksums.yaml.gz.sig +0 -0
  3. data/BUGS.md +5 -10
  4. data/CHANGELOG.md +301 -4
  5. data/CODE_OF_CONDUCT.md +18 -0
  6. data/CONTRIBUTING.md +139 -58
  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 +10 -7
  13. data/docs/README.md +2551 -772
  14. data/docs/test-mcp-with-ai.md +13 -11
  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 +34 -22
  19. data/lib/aspera/agent/factory.rb +8 -4
  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 +8 -5
  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 +23 -19
  30. data/lib/aspera/ascmd.rb +8 -5
  31. data/lib/aspera/ascp/installation.rb +84 -42
  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 +102 -48
  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 +16 -37
  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 -34
  48. data/lib/aspera/cli/command_line.rb +24 -6
  49. data/lib/aspera/cli/command_registry.rb +49 -4
  50. data/lib/aspera/cli/command_spec.rb +34 -4
  51. data/lib/aspera/cli/completion/ascli.bash +53 -5
  52. data/lib/aspera/cli/completion/ascli.fish +27 -8
  53. data/lib/aspera/cli/completion/ascli.ps1 +63 -0
  54. data/lib/aspera/cli/completion/ascli.zsh +36 -4
  55. data/lib/aspera/cli/completion_actions.rb +594 -0
  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 +45 -0
  59. data/lib/aspera/cli/extended_value.rb +83 -24
  60. data/lib/aspera/cli/formatter.rb +142 -73
  61. data/lib/aspera/cli/gem_checker.rb +9 -6
  62. data/lib/aspera/cli/hints.rb +22 -11
  63. data/lib/aspera/cli/http.rb +17 -13
  64. data/lib/aspera/cli/info.rb +17 -6
  65. data/lib/aspera/cli/mailer.rb +7 -4
  66. data/lib/aspera/cli/mcp/http_servlet.rb +155 -0
  67. data/lib/aspera/cli/mcp/secrets.rb +146 -0
  68. data/lib/aspera/cli/mcp/tool.rb +232 -0
  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 +72 -11
  73. data/lib/aspera/cli/options.schema.yaml +856 -81
  74. data/lib/aspera/cli/parser.rb +64 -31
  75. data/lib/aspera/cli/plugins/alee.rb +7 -4
  76. data/lib/aspera/cli/plugins/aoc.rb +250 -44
  77. data/lib/aspera/cli/plugins/ats.rb +9 -8
  78. data/lib/aspera/cli/plugins/base.rb +51 -25
  79. data/lib/aspera/cli/plugins/basic_auth.rb +5 -2
  80. data/lib/aspera/cli/plugins/config.rb +207 -141
  81. data/lib/aspera/cli/plugins/console.rb +9 -4
  82. data/lib/aspera/cli/plugins/cos.rb +8 -4
  83. data/lib/aspera/cli/plugins/factory.rb +22 -8
  84. data/lib/aspera/cli/plugins/faspex5.rb +37 -44
  85. data/lib/aspera/cli/plugins/faspio.rb +41 -8
  86. data/lib/aspera/cli/plugins/httpgw.rb +8 -4
  87. data/lib/aspera/cli/plugins/mcp.rb +186 -121
  88. data/lib/aspera/cli/plugins/node.rb +41 -34
  89. data/lib/aspera/cli/plugins/oauth.rb +5 -1
  90. data/lib/aspera/cli/plugins/orchestrator.rb +572 -59
  91. data/lib/aspera/cli/plugins/preview.rb +69 -44
  92. data/lib/aspera/cli/plugins/server.rb +66 -12
  93. data/lib/aspera/cli/plugins/shares.rb +288 -48
  94. data/lib/aspera/cli/plugins/transferd.rb +223 -0
  95. data/lib/aspera/cli/preset_actions.rb +155 -33
  96. data/lib/aspera/cli/preset_manager.rb +72 -16
  97. data/lib/aspera/cli/prompt.rb +7 -2
  98. data/lib/aspera/cli/result.rb +28 -11
  99. data/lib/aspera/cli/runner.rb +193 -80
  100. data/lib/aspera/cli/secret_finder.rb +4 -1
  101. data/lib/aspera/cli/security.rb +204 -0
  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 +119 -0
  105. data/lib/aspera/cli/terminal_formatter.rb +32 -40
  106. data/lib/aspera/cli/transfer_actions.rb +11 -8
  107. data/lib/aspera/cli/transfer_agent.rb +31 -19
  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 +197 -50
  111. data/lib/aspera/cli/version.rb +4 -1
  112. data/lib/aspera/cli/web_secret.html.erb +61 -0
  113. data/lib/aspera/cli/web_secret.rb +222 -0
  114. data/lib/aspera/cli/wizard.rb +58 -45
  115. data/lib/aspera/command_line_builder.rb +35 -5
  116. data/lib/aspera/command_line_converter.rb +4 -1
  117. data/lib/aspera/coverage.rb +103 -33
  118. data/lib/aspera/data_repository.rb +42 -25
  119. data/lib/aspera/dot_container.rb +4 -1
  120. data/lib/aspera/duration.rb +45 -0
  121. data/lib/aspera/environment.rb +106 -33
  122. data/lib/aspera/exec_spec.rb +9 -5
  123. data/lib/aspera/faspex_gw.rb +105 -35
  124. data/lib/aspera/faspex_postproc.rb +193 -47
  125. data/lib/aspera/formatter_interface.rb +4 -2
  126. data/lib/aspera/graphql.rb +5 -1
  127. data/lib/aspera/hash_ext.rb +3 -0
  128. data/lib/aspera/id_generator.rb +6 -3
  129. data/lib/aspera/json_rpc/client.rb +55 -35
  130. data/lib/aspera/json_rpc/version.rb +4 -0
  131. data/lib/aspera/line_logger.rb +4 -1
  132. data/lib/aspera/link_header.rb +4 -1
  133. data/lib/aspera/log.rb +20 -10
  134. data/lib/aspera/markdown.rb +155 -115
  135. data/lib/aspera/mime.rb +9 -0
  136. data/lib/aspera/nagios.rb +9 -5
  137. data/lib/aspera/node_emulator.rb +111 -112
  138. data/lib/aspera/oauth/client/base.rb +163 -0
  139. data/lib/aspera/oauth/{boot.rb → client/boot.rb} +8 -4
  140. data/lib/aspera/oauth/{factory.rb → client/factory.rb} +13 -3
  141. data/lib/aspera/oauth/{generic.rb → client/generic.rb} +5 -1
  142. data/lib/aspera/oauth/{json_credentials.rb → client/json_credentials.rb} +4 -1
  143. data/lib/aspera/oauth/{jwt.rb → client/jwt.rb} +6 -3
  144. data/lib/aspera/oauth/client/shares_web.rb +85 -0
  145. data/lib/aspera/oauth/{url_json.rb → client/url_json.rb} +4 -1
  146. data/lib/aspera/oauth/client/web.rb +84 -0
  147. data/lib/aspera/oauth/server/authorize.html.erb +34 -0
  148. data/lib/aspera/oauth/server/pkce.rb +427 -0
  149. data/lib/aspera/orchestrator_workflow_checker.rb +679 -0
  150. data/lib/aspera/persistency_action_once.rb +5 -3
  151. data/lib/aspera/persistency_folder.rb +6 -3
  152. data/lib/aspera/preview/file_types.rb +6 -3
  153. data/lib/aspera/preview/generator.rb +9 -5
  154. data/lib/aspera/preview/options.schema.yaml +3 -3
  155. data/lib/aspera/preview/terminal.rb +11 -6
  156. data/lib/aspera/preview/utils.rb +6 -4
  157. data/lib/aspera/products/connect.rb +5 -2
  158. data/lib/aspera/products/desktop.rb +4 -1
  159. data/lib/aspera/products/other.rb +4 -2
  160. data/lib/aspera/products/transferd.rb +6 -2
  161. data/lib/aspera/products/transferd_service.rb +610 -0
  162. data/lib/aspera/proxy_auto_config.js +2 -2
  163. data/lib/aspera/proxy_auto_config.rb +5 -2
  164. data/lib/aspera/rainbow.rb +30 -1
  165. data/lib/aspera/rest/aspera_errors.rb +55 -60
  166. data/lib/aspera/rest/call_error.rb +3 -0
  167. data/lib/aspera/rest/client.rb +42 -42
  168. data/lib/aspera/rest/error_analyzer.rb +14 -2
  169. data/lib/aspera/rest/list.rb +14 -10
  170. data/lib/aspera/rest/parameters.rb +3 -0
  171. data/lib/aspera/rest/util.rb +13 -4
  172. data/lib/aspera/rest.rb +9 -7
  173. data/lib/aspera/schema/IBM Aspera Faspex API-5.0-enhanced.yaml +9 -11
  174. data/lib/aspera/schema/IBM Aspera Orchestrator API-v1-enhanced.yaml +4089 -0
  175. data/lib/aspera/schema/IBM Aspera faspio Gateway API-1.0.0-enhanced.yaml +1097 -0
  176. data/lib/aspera/schema/IBM Aspera on Cloud API-0.2.6-enhanced.yaml +11 -11
  177. data/lib/aspera/schema/IBM Aspera on Cloud Automation API-1.0.5-enhanced.yaml +2437 -1437
  178. data/lib/aspera/schema/IBM_Aspera_Shares.yaml +819 -7
  179. data/lib/aspera/schema/async_tables.yaml +11 -10
  180. data/lib/aspera/schema/documentation.rb +56 -78
  181. data/lib/aspera/schema/reader.rb +46 -11
  182. data/lib/aspera/schema/registry.rb +45 -24
  183. data/lib/aspera/schema/transferd-config.schema.json +333 -0
  184. data/lib/aspera/schema/validator.rb +4 -1
  185. data/lib/aspera/sealed_hash.rb +166 -0
  186. data/lib/aspera/secret/hider.rb +201 -0
  187. data/lib/aspera/secret/reference.rb +150 -0
  188. data/lib/aspera/secret/resolver.rb +212 -0
  189. data/lib/aspera/secret/store/base.rb +153 -0
  190. data/lib/aspera/secret/store/encrypted_hash.rb +329 -0
  191. data/lib/aspera/secret/store/factory.rb +103 -0
  192. data/lib/aspera/secret/store/hashicorp_vault.rb +390 -0
  193. data/lib/aspera/secret/store/keeper.rb +141 -0
  194. data/lib/aspera/secret/store/macos_security.rb +284 -0
  195. data/lib/aspera/secret/store/one_password_api.rb +99 -0
  196. data/lib/aspera/secret/store/one_password_base.rb +42 -0
  197. data/lib/aspera/secret/store/one_password_cli.rb +110 -0
  198. data/lib/aspera/secret/store/secret_service.rb +125 -0
  199. data/lib/aspera/secret/strength.rb +119 -0
  200. data/lib/aspera/servlet_helpers.rb +114 -0
  201. data/lib/aspera/ssh.rb +10 -7
  202. data/lib/aspera/ssl.rb +5 -2
  203. data/lib/aspera/string_ext.rb +3 -0
  204. data/lib/aspera/sync/args.schema.yaml +6 -1
  205. data/lib/aspera/sync/conf.schema.yaml +25 -10
  206. data/lib/aspera/sync/database.rb +3 -0
  207. data/lib/aspera/sync/operations.rb +34 -12
  208. data/lib/aspera/temp_file_manager.rb +85 -22
  209. data/lib/aspera/timer_limiter.rb +3 -0
  210. data/lib/aspera/transfer/error.rb +4 -1
  211. data/lib/aspera/transfer/faux_file.rb +4 -1
  212. data/lib/aspera/transfer/parameters.rb +22 -14
  213. data/lib/aspera/transfer/result.rb +3 -0
  214. data/lib/aspera/transfer/resumer.rb +6 -4
  215. data/lib/aspera/transfer/spec.rb +45 -18
  216. data/lib/aspera/transfer/spec.schema.yaml +8 -5
  217. data/lib/aspera/transfer/units.rb +75 -0
  218. data/lib/aspera/uri_reader.rb +57 -7
  219. data/lib/aspera/web_auth/index.html.erb +20 -0
  220. data/lib/aspera/web_auth/paste.rb +109 -0
  221. data/lib/aspera/web_auth/receiver.rb +50 -0
  222. data/lib/aspera/web_auth/relay.rb +76 -0
  223. data/lib/aspera/web_auth/reply.html.erb +150 -0
  224. data/lib/aspera/web_auth/server.rb +59 -14
  225. data/lib/aspera/web_page.html.erb +262 -0
  226. data/lib/aspera/web_page.rb +66 -0
  227. data/lib/aspera/web_server_simple.rb +82 -13
  228. data/lib/aspera/yaml.rb +5 -1
  229. data/llms.txt +81 -0
  230. data/skills/ascli/SKILL.md +88 -0
  231. data.tar.gz.sig +0 -0
  232. metadata +116 -48
  233. metadata.gz.sig +0 -0
  234. data/lib/aspera/cli/mcp_tool.rb +0 -189
  235. data/lib/aspera/keychain/base.rb +0 -25
  236. data/lib/aspera/keychain/encrypted_hash.rb +0 -188
  237. data/lib/aspera/keychain/factory.rb +0 -59
  238. data/lib/aspera/keychain/hashicorp_vault.rb +0 -74
  239. data/lib/aspera/keychain/macos_security.rb +0 -171
  240. data/lib/aspera/keychain/one_password_api.rb +0 -86
  241. data/lib/aspera/keychain/one_password_base.rb +0 -34
  242. data/lib/aspera/keychain/one_password_cli.rb +0 -98
  243. data/lib/aspera/oauth/base.rb +0 -141
  244. data/lib/aspera/oauth/web.rb +0 -57
  245. data/lib/aspera/oauth.rb +0 -9
  246. data/lib/aspera/schema/IBM Aspera Orchestrator API-v1.yaml +0 -1784
  247. data/lib/aspera/schema/IBM Aspera faspio Gateway API-1.0.0.yaml +0 -249
  248. data/lib/aspera/secret_hider.rb +0 -117
  249. data/lib/aspera/web_auth/index.html +0 -147
@@ -1,8 +1,11 @@
1
- openapi: 3.0.0
1
+ openapi: 3.1.0
2
2
  info:
3
3
  title: Aspera CLI Options Schema
4
4
  version: 1.0.0
5
5
  description: Schema definitions for Aspera CLI options
6
+ license:
7
+ name: Apache-2.0
8
+ identifier: Apache-2.0
6
9
  paths: {}
7
10
  components:
8
11
  schemas:
@@ -29,6 +32,133 @@ components:
29
32
  type: boolean
30
33
  description: Show passwords and secrets in logs.
31
34
  default: false
35
+ UiOptions:
36
+ type: object
37
+ description: >-
38
+ User interface: how URLs to open, secrets and files are presented to the user.
39
+ A plain value, e.g. `--ui=terminal`, is the `mode`.
40
+ additionalProperties: false
41
+ properties:
42
+ mode:
43
+ type: string
44
+ description: >-
45
+ - `auto`: `browser` on Windows and macOS, or if env var `DISPLAY` is set, else `terminal`.
46
+
47
+ - `terminal`: URLs to open are displayed on terminal, and secrets are entered on terminal.
48
+
49
+ - `browser`: a browser opens URLs, and secrets are entered on a web page.
50
+
51
+ `text` is an alias for `terminal`, and `graphical` is an alias for `browser`.
52
+
53
+ Files to edit are always opened with a text editor, whatever the `mode`.
54
+ enum:
55
+ - auto
56
+ - terminal
57
+ - browser
58
+ - text
59
+ - graphical
60
+ default: auto
61
+ web_auth:
62
+ type: string
63
+ description: >-
64
+ How the result of a web login (`--auth=web`, SSO) is received.
65
+
66
+ - `port`: `ascli` listens on the loopback port of `redirect_uri`, the browser is redirected to it.
67
+
68
+ - `paste`: no port is opened. After login, the browser shows a connection error on `redirect_uri`:
69
+ copy the full URL from the address bar of the browser and paste it in the terminal.
70
+ Use it when the browser cannot reach the host that runs `ascli` and a SSH tunnel is not possible.
71
+ For `shares`, Shares displays a code (a long text of letters, digits, `-` and `_`) instead: paste it in the terminal.
72
+ enum:
73
+ - port
74
+ - paste
75
+ default: port
76
+ command:
77
+ type: array
78
+ x-security: low
79
+ description: >-
80
+ Command that opens a URL, instead of the system default.
81
+ 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.
82
+ When set, it is used to open URLs, whatever the `mode`.
83
+ items:
84
+ type: string
85
+ SecurityOptions:
86
+ type: object
87
+ description: >-
88
+ Restrictions of the features that access local resources or execute code.
89
+ On the command line, the default level is `low`.
90
+ In MCP server mode, the default level is `high`, and commands of the client cannot change the security options.
91
+ additionalProperties: false
92
+ properties:
93
+ level:
94
+ type: string
95
+ description: >-
96
+ - `low`: no restriction.
97
+
98
+ - `medium`: `@file:` reads only files in `allowed_paths`, `@ruby:`, `@uri:` and `@env:` are refused, files are written only in `writable_paths`.
99
+
100
+ - `high`: `@ruby:`, `@file:`, `@uri:` and `@env:` are refused, files are written only in `writable_paths`.
101
+
102
+ Features that execute code, load plugins, or write a file chosen by the client (e.g. `--out.file`) are available only at level `low`.
103
+ enum:
104
+ - low
105
+ - medium
106
+ - high
107
+ allowed_paths:
108
+ type: array
109
+ description: >-
110
+ With level `medium`: files and folders that `@file:` can read.
111
+ A symbolic link leading outside of them is refused.
112
+ items:
113
+ type: string
114
+ writable_paths:
115
+ type: array
116
+ description: >-
117
+ With levels `medium` and `high`: folders where files can be written (downloaded files, results of `config download`), none by default.
118
+ A symbolic link leading outside of them is refused.
119
+ items:
120
+ type: string
121
+ TempOptions:
122
+ type: object
123
+ description: >-
124
+ Temporary files.
125
+ A plain value, e.g. `--temp=/tmp`, is the `folder`.
126
+ additionalProperties: false
127
+ properties:
128
+ folder:
129
+ type: string
130
+ x-cli-complete: folder
131
+ description: >-
132
+ Folder for temporary files, e.g. certificate for WSS transfers, logs of `transferd`.
133
+
134
+ - `@sys`: temporary folder of the system for the current user (Ruby `Etc.systmpdir`).
135
+
136
+ - `@env`: from environment variables, e.g. `TMPDIR` (Ruby `Dir.tmpdir`).
137
+ default: '@sys'
138
+ clean:
139
+ type: boolean
140
+ description: >-
141
+ Delete temporary files created by the command when it ends.
142
+ `false` keeps them, e.g. for debugging.
143
+ Files left by previous commands are still deleted according to `expiry`.
144
+ default: true
145
+ expiry:
146
+ oneOf:
147
+ - type: string
148
+ - type: number
149
+ minimum: 0
150
+ - type: boolean
151
+ enum:
152
+ - false
153
+ description: >-
154
+ Age after which file lists of `ascp` left by previous commands (e.g. interrupted) are deleted, when a command starts.
155
+ They are in folder `filelists` of the main folder (option `home`).
156
+ A duration, e.g. `5d`, `12h`, `1w`, `1h 30m`, `1d 02:00:00`, a plain number is seconds.
157
+ `false` or `null` (`@none:`): never delete them.
158
+ `0`: delete all of them, including file lists of transfers in progress in other executions of ascli.
159
+ Such a transfer fails if `ascp` reads its file list again: next session of a multi-session transfer, or resume after an error.
160
+ Use `0` only when no other transfer is in progress, not in a permanent configuration.
161
+ default: 5d
32
162
  McpServerOptions:
33
163
  type: object
34
164
  description: MCP server configuration for the `mcp server` command.
@@ -51,14 +181,60 @@ components:
51
181
  type: integer
52
182
  description: Maximum JSON frame size for stdio transport.
53
183
  default: 4194304
184
+ url:
185
+ type: string
186
+ description: >-
187
+ Address and port the HTTP transport listens on, without path.
188
+ Use `https://` for TLS, with `cert` and `key`.
189
+ default: http://127.0.0.1:3000
190
+ cert:
191
+ $ref: "#/components/schemas/WebServerOptions/properties/cert"
192
+ key:
193
+ $ref: "#/components/schemas/WebServerOptions/properties/key"
194
+ chain:
195
+ $ref: "#/components/schemas/WebServerOptions/properties/chain"
54
196
  port:
55
197
  type: integer
56
- description: TCP port for HTTP transport.
57
- default: 3000
198
+ description: "Deprecated: use `url`. TCP port for HTTP transport."
58
199
  bind:
59
200
  type: string
60
- description: Bind address for HTTP transport.
61
- default: 127.0.0.1
201
+ description: "Deprecated: use `url`. Bind address for HTTP transport."
202
+ public_url:
203
+ type: string
204
+ description: >-
205
+ URL of the server for clients, used in OAuth metadata and in the URL of secret pages (`@secret:`), for example `http://myhost:3000`.
206
+
207
+ Default: built from `url`. Mandatory with `oauth` when `url` has host `0.0.0.0` or `::`.
208
+ auth_token:
209
+ type: string
210
+ description: >-
211
+ Bearer token required in the `Authorization` header of HTTP requests.
212
+ It is also the access code asked on the secret pages (`@secret:`), and on the consent page with `oauth`.
213
+
214
+ If not set, HTTP requests are not authenticated.
215
+ Mandatory when the host of `url` or `public_url` is not loopback.
216
+ Generate it with `openssl rand -hex 32`: a weak token is refused (see `auth_token_min_bits`).
217
+ auth_token_min_bits:
218
+ type: integer
219
+ minimum: 0
220
+ default: 80
221
+ description: >-
222
+ Minimum estimated strength of `auth_token`, in bits (log2 of the number of guesses to find it).
223
+ The strength is estimated with gem `zxcvbn` if installed, else with a built-in estimate
224
+ that detects repeats, sequences, keyboard rows, words and years.
225
+ `0` disables the check.
226
+ oauth:
227
+ type: boolean
228
+ description: Enable OAuth 2.0 PKCE flow with dynamic client registration.
229
+ default: false
230
+ oauth_access_token_ttl:
231
+ type: integer
232
+ description: OAuth access token lifetime in seconds.
233
+ default: 3600
234
+ oauth_refresh_token_ttl:
235
+ type: integer
236
+ description: OAuth refresh token lifetime in seconds.
237
+ default: 2592000
62
238
  stateless:
63
239
  type: boolean
64
240
  description: Run HTTP transport in stateless mode.
@@ -135,12 +311,10 @@ components:
135
311
  default: []
136
312
  spawn_timeout_sec:
137
313
  type: number
138
- format: float
139
314
  description: Multi session - Maximum time (in seconds) to verify that `ascp` is running.
140
315
  default: 2
141
316
  spawn_delay_sec:
142
317
  type: number
143
- format: float
144
318
  description: Multi session - Delay (in seconds) between starting each `ascp` session.
145
319
  default: 2
146
320
  multi_incr_udp:
@@ -252,6 +426,16 @@ components:
252
426
  type: boolean
253
427
  description: Stop the daemon when `ascli` exits.
254
428
  default: true
429
+ api_key:
430
+ type: string
431
+ description: >-
432
+ API key of an existing daemon (`start` is `false`) that has `authentication` enabled in its configuration.
433
+ It is sent in the metadata `api_key` of each call.
434
+ ca_file:
435
+ type: string
436
+ description: >-
437
+ Path to the certificate authority file (PEM) that signed the certificate of an existing daemon (`start` is `false`)
438
+ that has `tls` enabled in its configuration. A self-signed certificate is its own authority.
255
439
  TransferAgentOptions:
256
440
  description: >-
257
441
  Transfer agent selector and agent-specific parameters.
@@ -282,7 +466,8 @@ components:
282
466
  server:
283
467
  type: string
284
468
  description: SMTP server address.
285
- example: smtp.gmail.com
469
+ examples:
470
+ - smtp.gmail.com
286
471
  tls:
287
472
  type: boolean
288
473
  description: Enable `STARTTLS` (port 587).
@@ -297,29 +482,102 @@ components:
297
482
  Port for the SMTP service.
298
483
 
299
484
  Defaults: `587` (TLS), `465` (SSL), `25` (plain).
300
- example: 587
485
+ examples:
486
+ - 587
301
487
  domain:
302
488
  type: string
303
489
  description: Email domain of the user. Defaults to the domain part of `server`.
304
- example: gmail.com
490
+ examples:
491
+ - gmail.com
305
492
  username:
306
493
  type: string
307
494
  description: >-
308
495
  User to authenticate on the SMTP server.
309
496
  Leave empty for open (unauthenticated) relay.
310
- example: john@example.com
497
+ examples:
498
+ - john@example.com
311
499
  password:
312
500
  type: string
313
501
  description: Password for the above `username`.
314
- example: my_password
502
+ examples:
503
+ - "<PASSWORD>"
315
504
  from_email:
316
505
  type: string
317
506
  description: Sender address (used in `From:` header and as reply-to). Defaults to `username` when defined.
318
- example: johnny@example.com
507
+ examples:
508
+ - johnny@example.com
319
509
  from_name:
320
510
  type: string
321
511
  description: Display name of the sender. Defaults to the local-part of `from_email`.
322
- example: John Wayne
512
+ examples:
513
+ - John Wayne
514
+ ServiceOptions:
515
+ type: object
516
+ description: >-
517
+ Installation parameters of the transfer daemon (`transferd`) as a system service.
518
+ The content of the daemon configuration file is described by its own schema.
519
+ additionalProperties: false
520
+ properties:
521
+ name:
522
+ type: string
523
+ description: >-
524
+ Name of the service.
525
+ The unit file is `<name>.service`.
526
+ default: aspera-transferd
527
+ minLength: 1
528
+ user:
529
+ type: string
530
+ description: >-
531
+ Account that runs the daemon.
532
+ It must exist, it is not created.
533
+ default: asperadaemon
534
+ minLength: 1
535
+ group:
536
+ type: string
537
+ description: Group that runs the daemon. Defaults to the primary group of `user`.
538
+ minLength: 1
539
+ unit_dir:
540
+ type: string
541
+ description: Folder where the unit file is created.
542
+ default: /etc/systemd/system
543
+ minLength: 1
544
+ after:
545
+ type: array
546
+ description: Units that shall be started before the daemon (`After=` in the unit).
547
+ items:
548
+ type: string
549
+ default:
550
+ - network.target
551
+ environment:
552
+ type: object
553
+ description: >-
554
+ Environment variables set in the unit.
555
+ None is set unless given here.
556
+ `TRANSFERD_ADDRESS`, `TRANSFERD_PORT`, `TRANSFERD_MGMT_PORT` and `TRANSFERD_MGMT_ADDRESS` override the configuration file.
557
+ additionalProperties:
558
+ type: string
559
+ version:
560
+ type: string
561
+ description: >-
562
+ Version of the SDK to install, used by `install` when the SDK folder is named `current` (versions side by side).
563
+ Defaults to the SDK version of this tool.
564
+ pattern: '^\d+(\.\d+)*$'
565
+ purge:
566
+ type: boolean
567
+ description: Used by `uninstall`. Also remove the configuration file and the log folder.
568
+ default: false
569
+ TransferdServiceConfig:
570
+ type: object
571
+ description: >-
572
+ Configuration of the transfer daemon (`transferd`) as a system service.
573
+ additionalProperties: false
574
+ properties:
575
+ service:
576
+ $ref: "#/components/schemas/ServiceOptions"
577
+ config:
578
+ type: object
579
+ description: >-
580
+ Content of `transferd.json`, validated against the transfer daemon configuration schema.
323
581
  HttpOptions:
324
582
  type: object
325
583
  description: >-
@@ -390,7 +648,11 @@ components:
390
648
  default: 120
391
649
  VaultHashicorpOptions:
392
650
  type: object
393
- description: IBM HashiCorp Vault secret store.
651
+ description: >-
652
+ IBM HashiCorp Vault secret store.
653
+ Labels of `config vault` and `@vault:<label>.<field>` are in mount `secret` (KV v2).
654
+ Reference `@vault://<store>/<mount>/<path>#<field>` (field required) in any KV v2 mount, options `version=<n>`, `mount=<mount>` (when the mount contains `/`).
655
+ additionalProperties: false
394
656
  required:
395
657
  - type
396
658
  - url
@@ -402,14 +664,49 @@ components:
402
664
  url:
403
665
  type: string
404
666
  description: URL of the HashiCorp Vault server.
405
- example: "http://127.0.0.1:8200"
667
+ examples:
668
+ - "http://127.0.0.1:8200"
406
669
  token:
407
670
  type: string
408
- description: Authentication token. Defaults to the value of `vault_password`.
409
- example: dev-only-token
671
+ description: >-
672
+ The authentication token. Its value, or `@file:<path>` (e.g. written and renewed by Vault Agent), read again when modified.
673
+ One of `token` or `approle` is required.
674
+ For the default store, defaults to the value of `vault_password`, unless `approle` is set.
675
+ examples:
676
+ - "<TOKEN>"
677
+ approle:
678
+ type: object
679
+ description: >-
680
+ AppRole authentication: the token is obtained by login, renewed, and obtained again when refused.
681
+ properties:
682
+ role_id:
683
+ type: string
684
+ description: Role ID.
685
+ secret_id:
686
+ type: string
687
+ description: "Secret ID (if the role requires one): the value, or `@file:<path>`."
688
+ mount:
689
+ type: string
690
+ description: Mount path of the AppRole auth method.
691
+ default: approle
692
+ required:
693
+ - role_id
694
+ namespace:
695
+ type: string
696
+ description: Namespace (Vault Enterprise).
697
+ ca_file:
698
+ type: string
699
+ x-cli-complete: file
700
+ description: File with the CA certificates that verify the certificate of the server (HTTPS).
701
+ allowed_prefixes:
702
+ type: array
703
+ description: "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."
704
+ items:
705
+ type: string
410
706
  VaultSystemOptions:
411
707
  type: object
412
708
  description: macOS system keychain secret store.
709
+ additionalProperties: false
413
710
  required:
414
711
  - type
415
712
  properties:
@@ -419,10 +716,27 @@ components:
419
716
  enum: [system]
420
717
  name:
421
718
  type: string
422
- description: Name of the keychain to use.
719
+ description: Name of the keychain to use (file `<name>.keychain-db` in the keychain search list).
720
+ default: ascli
721
+ VaultSecretServiceOptions:
722
+ type: object
723
+ description: Linux Secret Service secret store (GNOME Keyring, KWallet, KeePassXC...), using `secret-tool`.
724
+ additionalProperties: false
725
+ required:
726
+ - type
727
+ properties:
728
+ type:
729
+ type: string
730
+ description: Vault type selector.
731
+ enum: [secret_service]
732
+ name:
733
+ type: string
734
+ description: Name of the group of secrets (attribute `service` of the items).
735
+ default: ascli
423
736
  VaultOnePasswordOptions:
424
737
  type: object
425
738
  description: 1Password secret store (Connect REST API or CLI).
739
+ additionalProperties: false
426
740
  required:
427
741
  - type
428
742
  - source
@@ -439,22 +753,46 @@ components:
439
753
  url:
440
754
  type: string
441
755
  description: Base URL of the 1Password Connect server (required when `source` is `api`).
442
- example: "http://localhost:8080"
756
+ examples:
757
+ - "http://localhost:8080"
443
758
  vault_id:
444
759
  type: string
445
760
  description: ID of the 1Password vault to use (required when `source` is `api`).
446
761
  token:
447
762
  type: string
448
- description: Bearer token for the Connect API (required when `source` is `api`). Defaults to the value of `vault_password`.
763
+ description: Bearer token for the Connect API (required when `source` is `api`). For the default store, defaults to the value of `vault_password`.
449
764
  vault:
450
765
  type: string
451
766
  description: Name or ID of the 1Password vault to use with the CLI (used when `source` is `cli`). Uses the default vault if omitted.
452
767
  account:
453
768
  type: string
454
769
  description: Account shorthand for `op` (used when `source` is `cli`). Uses the default account if omitted.
770
+ VaultKeeperOptions:
771
+ type: object
772
+ description: >-
773
+ Keeper Secrets Manager secret store (Keeper Vault), using gem `keeper_secrets_manager`.
774
+ A secret is a record shared with the application: its label is its title or its UID.
775
+ Reference `@vault://<store>/<title or uid>[#<field>]`, field `password` by default: standard field by type (`login`, `password`, `url`...), custom field by label, or `notes`.
776
+ additionalProperties: false
777
+ required:
778
+ - type
779
+ properties:
780
+ type:
781
+ type: string
782
+ description: Vault type selector.
783
+ enum: [keeper]
784
+ config:
785
+ type: string
786
+ description: >-
787
+ Configuration of the client device (base64 or JSON, e.g. from `ksm profile export`): the value, or `@file:<path>`.
788
+ For the default store, defaults to the value of `vault_password`.
789
+ folder_uid:
790
+ type: string
791
+ description: UID of the shared folder where `config vault create` adds records (not needed to read).
455
792
  VaultFileOptions:
456
793
  type: object
457
- description: Encrypted file secret store.
794
+ description: Encrypted file secret store. Reference `@vault://<store>/<label>[#<field>]`, field `password` by default.
795
+ additionalProperties: false
458
796
  required:
459
797
  - type
460
798
  properties:
@@ -462,12 +800,23 @@ components:
462
800
  type: string
463
801
  description: Vault type selector.
464
802
  enum: [file]
465
- name:
803
+ file:
466
804
  type: string
805
+ x-cli-complete: file
467
806
  description: >-
468
- Path to the encrypted vault file.
807
+ Path to the encrypted vault file, created when the first secret is added.
469
808
  Relative paths are resolved from the configuration folder.
809
+ Read when used, and again when modified.
470
810
  default: vault.bin
811
+ name:
812
+ type: string
813
+ x-cli-complete: file
814
+ description: Same as `file` (compatibility).
815
+ password:
816
+ type: string
817
+ description: >-
818
+ Password of the vault file: the value, or `@file:<path>`, read again when modified.
819
+ For the default store, defaults to the value of `vault_password`.
471
820
  VaultSecret:
472
821
  type: object
473
822
  description: Secret entry in the vault
@@ -489,21 +838,58 @@ components:
489
838
  description:
490
839
  type: string
491
840
  description: Human-readable description of this secret
492
- VaultOptions:
493
- title: Secret vault configuration
494
- description: Secret vault configuration. Set `type` to select the vault backend.
841
+ VaultStore:
842
+ type: object
843
+ title: Secret store
844
+ description: Parameters of a secret store. Set `type` to select the store type.
495
845
  oneOf:
496
846
  - $ref: "#/components/schemas/VaultHashicorpOptions"
497
847
  - $ref: "#/components/schemas/VaultSystemOptions"
848
+ - $ref: "#/components/schemas/VaultSecretServiceOptions"
498
849
  - $ref: "#/components/schemas/VaultFileOptions"
499
850
  - $ref: "#/components/schemas/VaultOnePasswordOptions"
851
+ - $ref: "#/components/schemas/VaultKeeperOptions"
500
852
  discriminator:
501
853
  propertyName: type
502
854
  mapping:
503
855
  vault: "#/components/schemas/VaultHashicorpOptions"
504
856
  system: "#/components/schemas/VaultSystemOptions"
857
+ secret_service: "#/components/schemas/VaultSecretServiceOptions"
505
858
  file: "#/components/schemas/VaultFileOptions"
506
- 1password: "#/components/schemas/VaultOnePasswordOptions"
859
+ 1password: "#/components/schemas/VaultOnePasswordOptions" # HashiCorpIgnore
860
+ keeper: "#/components/schemas/VaultKeeperOptions"
861
+ VaultStores:
862
+ type: object
863
+ title: Secret stores
864
+ description: Named secret stores, and the default store.
865
+ additionalProperties: false
866
+ required:
867
+ - stores
868
+ properties:
869
+ default:
870
+ type: string
871
+ description: >-
872
+ Name of the default store, in `stores`: read by `@vault:<label>.<field>`, managed by `config vault`, unlocked with option `vault_password`.
873
+ No default store if not set.
874
+ cache_ttl:
875
+ type: number
876
+ minimum: 0
877
+ description: Time in seconds a value read by reference is kept in memory, `0` for no cache.
878
+ default: 60
879
+ stores:
880
+ type: object
881
+ description: >-
882
+ Name of store (letters, digits, `_`, `.`, `-`) → parameters of store, with `type`.
883
+ Secrets are read by reference with `@vault://<store>/<path>[?<options>][#<field>]` from any store.
884
+ additionalProperties:
885
+ $ref: "#/components/schemas/VaultStore"
886
+ VaultOptions:
887
+ type: object
888
+ title: Secret vault configuration
889
+ description: Named secret stores (`stores`), or (deprecated) the parameters of one store, which is the default store, named after its type.
890
+ oneOf:
891
+ - $ref: "#/components/schemas/VaultStores"
892
+ - $ref: "#/components/schemas/VaultStore"
507
893
  ImageOptions:
508
894
  type: object
509
895
  description: Options for displaying images and thumbnails in the terminal.
@@ -518,13 +904,101 @@ components:
518
904
  default: false
519
905
  double:
520
906
  type: boolean
521
- description: Use double vertical resolution via half-block characters.
522
- default: true
907
+ description: >-
908
+ Use double vertical resolution via half-block characters (Unicode).
909
+ Default is `true` if the terminal supports Unicode (see `utf8`).
523
910
  font_ratio:
524
911
  type: number
525
- format: float
526
912
  description: Terminal font aspect ratio (height divided by width).
527
913
  default: 2.3
914
+ AscpLogsOptions:
915
+ type: object
916
+ description: Analysis of `ascp` log files (`config ascp logs`).
917
+ additionalProperties: false
918
+ properties:
919
+ period:
920
+ type: integer
921
+ description: Snapshot period, in minutes.
922
+ default: 1
923
+ zero_bytes:
924
+ type: boolean
925
+ description: Include sessions without transferred bytes.
926
+ default: false
927
+ mtu:
928
+ type: integer
929
+ description: MTU, when not found in logs.
930
+ resolve:
931
+ type: boolean
932
+ description: Resolve peer addresses to host names.
933
+ default: false
934
+ timezone:
935
+ type: string
936
+ description: Time zone of the log lines (`UTC` or `+HH:MM`), to read a log from another time zone. Default is the local time zone.
937
+ health_minutes:
938
+ type: integer
939
+ description: Window in minutes to report transfer errors and low efficiency.
940
+ default: 60
941
+ remote_max_size:
942
+ type: integer
943
+ description: Maximum total size in bytes of the log files read from a server (`server logs`).
944
+ default: 536870912
945
+ thresholds:
946
+ type: object
947
+ description: Diagnostic thresholds.
948
+ additionalProperties: false
949
+ properties:
950
+ efficiency:
951
+ type: number
952
+ description: Minimum efficiency percentage below which a warning is emitted.
953
+ default: 90.0
954
+ control_loss_percent:
955
+ type: number
956
+ description: Minimum percentage of lost control messages to trigger a warning.
957
+ default: 5.0
958
+ control_loss_sent:
959
+ type: integer
960
+ description: Minimum number of control messages sent before checking control loss.
961
+ default: 10
962
+ retry_window:
963
+ type: integer
964
+ description: Maximum interval in seconds between sessions to link a retry.
965
+ default: 3600
966
+ last_error_window:
967
+ type: integer
968
+ description: Window in seconds before exit to attribute the last logged error.
969
+ default: 60
970
+ rate_decline_ratio:
971
+ type: number
972
+ description: Ratio of second half rate to first half rate below which rate decline is diagnosed.
973
+ default: 0.7
974
+ rate_decline_min_samples:
975
+ type: integer
976
+ description: Minimum number of samples to evaluate rate decline.
977
+ default: 10
978
+ rate_decline_delay:
979
+ type: integer
980
+ description: Delay in seconds after session start before evaluating rate decline samples.
981
+ default: 20
982
+ rate_decline_end_fraction:
983
+ type: number
984
+ description: Fraction of samples to discard from the end of a session when evaluating rate decline.
985
+ default: 0.1
986
+ license_expiry_days:
987
+ type: integer
988
+ description: Number of days before the expiry of the license of ascp (or less, if already expired) at which a warning is emitted.
989
+ default: 30
990
+ small_files_min_count:
991
+ type: integer
992
+ description: Minimum number of transferred files to check for the small-files diagnostic.
993
+ default: 100
994
+ small_files_max_mean:
995
+ type: integer
996
+ description: Maximum mean file size in bytes below which the small-files diagnostic is emitted.
997
+ default: 1000000
998
+ small_mtu_max:
999
+ type: integer
1000
+ description: Path MTU in bytes below which the small-MTU diagnostic is emitted (ascp measures 1492, 1006, 508 or 296).
1001
+ default: 1400
528
1002
  PackageFolderOptions:
529
1003
  type: object
530
1004
  title: Package download folder organization
@@ -540,7 +1014,9 @@ components:
540
1014
  items:
541
1015
  type: string
542
1016
  maxItems: 2
543
- example: ["name", "id"]
1017
+ examples:
1018
+ - - name
1019
+ - id
544
1020
  seq:
545
1021
  type: boolean
546
1022
  description: >-
@@ -571,7 +1047,8 @@ components:
571
1047
  user_id:
572
1048
  type: string
573
1049
  description: Identifier of the user for whom the token is generated.
574
- example: jdoe
1050
+ examples:
1051
+ - jdoe # cspell:disable-line
575
1052
  _validity:
576
1053
  type: integer
577
1054
  description: Token lifetime in seconds (convenience key, removed before signing).
@@ -597,7 +1074,8 @@ components:
597
1074
  description: >-
598
1075
  Token expiry timestamp in ISO 8601 format (`YYYY-MM-DDTHH:MM:SSZ`).
599
1076
  Computed automatically from `_validity` when absent.
600
- example: "2030-01-01T00:00:00Z"
1077
+ examples:
1078
+ - "2030-01-01T00:00:00Z"
601
1079
  NodeEmulatorOptions:
602
1080
  type: object
603
1081
  description: >-
@@ -616,26 +1094,34 @@ components:
616
1094
  default: http://localhost:8080
617
1095
  cert:
618
1096
  type: string
1097
+ x-cli-complete: file
619
1098
  description: >-
620
1099
  Path to the TLS certificate file.
621
1100
  Accepted formats: PEM (`.pem`) or PKCS12 (`.p12` / `.pfx`).
622
- example: /path/to/cert.pem
1101
+ examples:
1102
+ - /path/to/cert.pem
623
1103
  key:
624
1104
  type: string
1105
+ x-cli-complete: file
625
1106
  description: >-
626
1107
  Path to the PEM private key file, or the PKCS12 passphrase when `cert` is a `.p12`/`.pfx` file.
627
- example: /path/to/key.pem
1108
+ examples:
1109
+ - /path/to/key.pem
628
1110
  chain:
629
1111
  type: string
1112
+ x-cli-complete: file
630
1113
  description: Path to the PEM certificate chain file (appended as extra chain certificates).
631
- example: /path/to/chain.pem
1114
+ examples:
1115
+ - /path/to/chain.pem
632
1116
  docroot:
633
1117
  type: string
1118
+ x-cli-complete: folder
634
1119
  description: >-
635
1120
  Local folder of the node files.
636
1121
  Paths of `/files/browse` and local paths of transfers (sources of `send`, destination of `receive`) are relative to it, and confined in it.
637
1122
  Defaults to the current working directory.
638
- example: /data/aspera
1123
+ examples:
1124
+ - /data/aspera
639
1125
  retention_sec:
640
1126
  type: integer
641
1127
  minimum: 1
@@ -647,11 +1133,26 @@ components:
647
1133
  Username expected from clients in HTTP Basic authentication.
648
1134
  Set together with `password`.
649
1135
  When not set, requests are accepted without authentication.
650
- example: node_user
1136
+ Mandatory when `url` is not a loopback address (`localhost`, `127.0.0.0/8`, `::1`).
1137
+ examples:
1138
+ - node_user
651
1139
  password:
652
1140
  type: string
653
- description: Password expected from clients in HTTP Basic authentication, for the above `username`.
654
- example: my_password
1141
+ description: >-
1142
+ Password expected from clients in HTTP Basic authentication, for the above `username`.
1143
+ Generate it with `openssl rand -hex 32`: a weak password is refused (see `password_min_bits`).
1144
+ examples:
1145
+ - "<PASSWORD>"
1146
+ password_min_bits:
1147
+ type: integer
1148
+ minimum: 0
1149
+ default: 80
1150
+ description: >-
1151
+ Minimum estimated strength of `password`, in bits (log2 of the number of guesses to find it).
1152
+ The strength is estimated with gem `zxcvbn` if installed, else with a built-in estimate
1153
+ that detects repeats, sequences, keyboard rows, words and years.
1154
+ `0` disables the check.
1155
+ A random password of 32 bytes (`openssl rand -hex 32`) is far above the default.
655
1156
  NodeTelemetryOptions:
656
1157
  type: object
657
1158
  description: >-
@@ -665,14 +1166,15 @@ components:
665
1166
  url:
666
1167
  type: string
667
1168
  description: Base URL of the Instana backend (without `/v1`).
668
- example: https://my-instana.example.com
1169
+ examples:
1170
+ - https://my-instana.example.com
669
1171
  key:
670
1172
  type: string
671
1173
  description: Instana API key sent in the `x-instana-key` header.
672
- example: my-instana-api-key
1174
+ examples:
1175
+ - my-instana-api-key
673
1176
  interval:
674
1177
  type: number
675
- format: float
676
1178
  description: >-
677
1179
  Polling interval in seconds. Use `0` for a single-shot run (no loop).
678
1180
  default: 10
@@ -681,7 +1183,8 @@ components:
681
1183
  description: >-
682
1184
  Value sent in the `x-instana-host` header.
683
1185
  Defaults to the local machine's hostname.
684
- example: hsts-prod-01
1186
+ examples:
1187
+ - hsts-prod-01
685
1188
  OrchestratorWorkflowStart:
686
1189
  type: object
687
1190
  description: >-
@@ -699,13 +1202,15 @@ components:
699
1202
  description: >-
700
1203
  Name of the work step providing the result.
701
1204
  Requires `variable`, and implies `synchronous`.
702
- example: ResultStep
1205
+ examples:
1206
+ - ResultStep
703
1207
  variable:
704
1208
  type: string
705
1209
  description: >-
706
1210
  Name of the output variable of `step` returned as result.
707
1211
  Requires `step`, and implies `synchronous`.
708
- example: Complete_status_message
1212
+ examples:
1213
+ - Complete_status_message
709
1214
  OrchestratorInitiateParameters:
710
1215
  type: object
711
1216
  description: >-
@@ -713,40 +1218,90 @@ components:
713
1218
  Valid keys are defined by the workflow's input specification.
714
1219
  Use `orchestrator workflows inputs WORKFLOW_ID` to discover required parameters.
715
1220
  additionalProperties: true
716
- OrchestratorImportWorkflow:
1221
+ OrchestratorWorkflowExport:
717
1222
  type: object
718
- description: Workflow definition to import into Orchestrator.
719
- required:
720
- - name
1223
+ description: Options of `orchestrator workflows export`.
1224
+ additionalProperties: false
721
1225
  properties:
722
- name:
723
- type: string
724
- description: Workflow name.
725
- example: My Workflow
726
- description:
727
- type: string
728
- description: Workflow description.
729
- example: This is a sample workflow
730
- workflow_data:
731
- type: object
732
- description: Complete workflow definition.
1226
+ dependencies:
1227
+ type: boolean
1228
+ description: >-
1229
+ Export the sub-workflows and remote nodes used by the workflow in a package (`.wkf`),
1230
+ saved in the folder given by option `to_folder` (default: current folder), instead of displaying the workflow.
1231
+ default: false
1232
+ OrchestratorWorkflowImport:
1233
+ type: object
1234
+ description: Options of `orchestrator workflows import`.
1235
+ additionalProperties: false
1236
+ properties:
1237
+ folder_id:
1238
+ type: integer
1239
+ description: >-
1240
+ Folder of the new workflow (default: the default folder).
1241
+ The `folder_id` of existing workflows is in `orchestrator workflows list`.
1242
+ publish:
1243
+ type: boolean
1244
+ description: >-
1245
+ Publish the workflow after import.
1246
+ If not set, the server option `publish_api_imported_workflow` decides.
1247
+ link_to_subworkflows:
1248
+ type: boolean
1249
+ description: Link to existing sub-workflows instead of importing those of the package (`.wkf`).
1250
+ default: false
733
1251
  OrchestratorImportWithConstraints:
734
1252
  type: object
735
- description: Workflow definition to import with constraint resolution mappings.
1253
+ description: >-
1254
+ Import of a workflow file present on the Orchestrator host, as a new workflow or as a new revision of an existing workflow.
1255
+ `orchestrator workflows import` stores each uploaded file in `<run_dir>/workflows/import/`.
1256
+ Conflicts with existing global templates, sub-workflows and remote nodes are resolved by name.
1257
+ Use `orchestrator workflows find_constraints` to list the conflicts, and `orchestrator workflows check_import` to check the file beforehand.
1258
+ additionalProperties: false
736
1259
  required:
737
- - workflow_data
738
- - constraints
1260
+ - filename
739
1261
  properties:
740
- workflow_data:
1262
+ filename:
1263
+ type: string
1264
+ description: Path of the workflow file (`.yml` or `.wkf`) on the Orchestrator host.
1265
+ examples:
1266
+ - /opt/aspera/orchestrator/var/run/orchestrator/workflows/import/my_workflow.yml
1267
+ add_as_revision:
1268
+ type: integer
1269
+ description: >-
1270
+ ID of an existing workflow: the file is imported as a new revision of this workflow (to be published).
1271
+ If not set, a new workflow is created.
1272
+ examples:
1273
+ - 123
1274
+ subwf_constraints:
1275
+ type: object
1276
+ description: 'Resolution for each sub-workflow, by name: `Map to the Existing Sub-Workflow`, `Create a new Sub-Workflow with a unique name`, or `Add a new revision to the existing Sub-Workflow`.'
1277
+ additionalProperties:
1278
+ type: string
1279
+ enum:
1280
+ - Map to the Existing Sub-Workflow
1281
+ - Create a new Sub-Workflow with a unique name
1282
+ - Add a new revision to the existing Sub-Workflow
1283
+ action_template_constraints:
741
1284
  type: object
742
- description: Complete workflow definition to import.
743
- constraints:
1285
+ description: 'Resolution for each global action template, by name: `Map to the existing Global Template`, `Create a new Global Template with a different name`, or `Override the existing Global Template with this new template`.'
1286
+ additionalProperties:
1287
+ type: string
1288
+ enum:
1289
+ - Map to the existing Global Template
1290
+ - Create a new Global Template with a different name
1291
+ - Override the existing Global Template with this new template
1292
+ remote_node_constraints:
744
1293
  type: object
745
- description: Constraint resolution mappings for conflicting resources.
746
- example:
747
- resource_pools: {}
748
- queues: {}
749
- monitors: {}
1294
+ description: 'Resolution for each remote node, by name: `Map to the existing Remote Node`, `Create a new Remote Node with a different name`, or `Override the Existing Remote Node with this importing node`.'
1295
+ additionalProperties:
1296
+ type: string
1297
+ enum:
1298
+ - Map to the existing Remote Node
1299
+ - Create a new Remote Node with a different name
1300
+ - Override the Existing Remote Node with this importing node
1301
+ auto_enable_missing_plugins:
1302
+ type: boolean
1303
+ description: Enable the plugins used by the workflow that are not enabled.
1304
+ default: false
750
1305
  OrchestratorReloadPluginSet:
751
1306
  type: object
752
1307
  description: Set of plugins to reload.
@@ -758,9 +1313,66 @@ components:
758
1313
  description: List of plugin names to reload.
759
1314
  items:
760
1315
  type: string
761
- example:
762
- - soap_requests
763
- - frameio_operations
1316
+ examples:
1317
+ - - soap_requests
1318
+ - frameio_operations # cspell:disable-line
1319
+ DetectOptions:
1320
+ type: object
1321
+ description: Application to detect (`config detect`).
1322
+ additionalProperties: false
1323
+ properties:
1324
+ url:
1325
+ type: string
1326
+ description: URL of the application. Asked interactively if not provided.
1327
+ examples:
1328
+ - https://app.example.com/aspera/app
1329
+ plugin:
1330
+ type: string
1331
+ description: 'Check only this plugin (default: all plugins).'
1332
+ examples:
1333
+ - aoc
1334
+ PresetLookupCriteria:
1335
+ type: object
1336
+ description: Criteria to find a preset (`config preset lookup`).
1337
+ additionalProperties: false
1338
+ required:
1339
+ - url
1340
+ - username
1341
+ properties:
1342
+ url:
1343
+ type: string
1344
+ description: URL of the application, compared with option `url` of presets.
1345
+ examples:
1346
+ - https://app.example.com/aspera/app
1347
+ username:
1348
+ type: string
1349
+ description: User name (or access key), compared with option `username` of presets.
1350
+ WizardOptions:
1351
+ type: object
1352
+ description: Application to configure with the wizard (`config wizard`). Options of the plugin (e.g. `--username`, `--password`, `--client-id`, `--private-key`) are given on the command line.
1353
+ additionalProperties: false
1354
+ properties:
1355
+ url:
1356
+ type: string
1357
+ description: URL of the application. Asked interactively if not provided.
1358
+ examples:
1359
+ - https://app.example.com/aspera/app
1360
+ plugin:
1361
+ type: string
1362
+ description: 'Check only this plugin (default: all plugins).'
1363
+ examples:
1364
+ - aoc
1365
+ preset:
1366
+ type: string
1367
+ description: 'Name of the preset to create (default: generated from the product, URL and user).'
1368
+ examples:
1369
+ - my_preset
1370
+ override:
1371
+ type: boolean
1372
+ description: 'Override the existing default preset of the plugin, if it exists (default: no).'
1373
+ default:
1374
+ type: boolean
1375
+ description: 'Set the preset as default configuration for the plugin (default: yes).'
764
1376
  TableOptions:
765
1377
  type: object
766
1378
  description: Terminal table rendering options.
@@ -785,6 +1397,8 @@ components:
785
1397
  default: data
786
1398
  file:
787
1399
  type: string
1400
+ x-cli-complete: file
1401
+ x-security: low
788
1402
  description: Destination file for results (use `-` for stdout).
789
1403
  fields:
790
1404
  description: >-
@@ -792,8 +1406,13 @@ components:
792
1406
  `ALL` for all fields, `DEF` for default fields.
793
1407
  Prefix a field name with `-` to exclude it.
794
1408
  select:
795
- type: object
796
- description: Select only matching items from a list (field/value filter or lambda).
1409
+ description: >-
1410
+ Select only matching items from a list:
1411
+ `Hash` of field/value, or Ruby lambda (`@ruby:`) returning `true` for items to keep.
1412
+ query:
1413
+ description: >-
1414
+ Filter and reshape an object or list result, before `select` and `fields`:
1415
+ JMESPath expression (https://jmespath.org), or Ruby lambda (`@ruby:`) called with the data and returning the new data.
797
1416
  table:
798
1417
  $ref: "#/components/schemas/TableOptions"
799
1418
  flat:
@@ -808,11 +1427,167 @@ components:
808
1427
  type: boolean
809
1428
  description: >-
810
1429
  Use ANSI colors and styles in terminal output and logs.
811
- Default is auto-detected: enabled if both stdout and stderr are terminals and `TERM` is not `dumb`, or if `CLICOLOR_FORCE=1`.
1430
+ Default is auto-detected: disabled if `NO_COLOR` is set or results are written to a file,
1431
+ else enabled if `CLICOLOR_FORCE` is set and not `0`,
1432
+ else enabled if both stdout and stderr are terminals, `TERM` is not `dumb` and `CLICOLOR` is not `0`.
812
1433
  utf8:
813
1434
  type: boolean
814
1435
  description: >-
815
- Use Unicode characters in terminal output (e.g. table borders, check marks).
816
- Default is auto-detected: enabled if stdout is a terminal and the locale is UTF-8.
1436
+ Use Unicode characters in terminal output (e.g. table borders, check marks, hidden secrets), else ASCII replacements.
1437
+ Default is auto-detected: enabled if stdout is a terminal and the locale is UTF-8, or on Windows, the terminal renders Unicode (e.g. Windows Terminal, VS Code).
817
1438
  img:
818
1439
  $ref: "#/components/schemas/ImageOptions"
1440
+ WebServerOptions:
1441
+ type: object
1442
+ description: >-
1443
+ Address and TLS configuration for a local web server (`WebServerSimple`).
1444
+ Used by commands that start an embedded HTTP(S) listener (`faspex5 gateway`,
1445
+ `faspex5 postprocessing`, `aoc gateway`, `node emulator`, …).
1446
+ properties:
1447
+ url:
1448
+ type: string
1449
+ description: >-
1450
+ Address and port the server listens on.
1451
+ Use `https://` with `cert`/`key` for TLS.
1452
+ default: http://localhost:8080
1453
+ cert:
1454
+ type: string
1455
+ x-cli-complete: file
1456
+ description: >-
1457
+ Path to the TLS certificate file.
1458
+ Accepted formats: PEM (`.pem`) or PKCS12 (`.p12` / `.pfx`).
1459
+ examples:
1460
+ - /path/to/cert.pem
1461
+ key:
1462
+ type: string
1463
+ x-cli-complete: file
1464
+ description: >-
1465
+ Path to the PEM private key file, or the PKCS12 passphrase when `cert` is a `.p12`/`.pfx` file.
1466
+ examples:
1467
+ - /path/to/key.pem
1468
+ chain:
1469
+ type: string
1470
+ x-cli-complete: file
1471
+ description: Path to the PEM certificate chain file (appended as extra chain certificates).
1472
+ examples:
1473
+ - /path/to/chain.pem
1474
+ Faspex4GatewayOptions:
1475
+ description: >-
1476
+ Configuration for the Faspex 4 gateway emulator (`faspex5 gateway`, `aoc gateway`).
1477
+ The command starts a local HTTP server that accepts Faspex 4 API calls and translates them
1478
+ to Faspex 5 / AoC API calls.
1479
+ Clients authenticate with HTTP Basic, as on Faspex 4, when `username` and `password` are set.
1480
+ By default the server binds to loopback; use a routable address only when clients must reach
1481
+ the host from outside: then `username` and `password` are required.
1482
+ allOf:
1483
+ - $ref: "#/components/schemas/WebServerOptions"
1484
+ - type: object
1485
+ # List properties solely to allow them under additionalProperties: false.
1486
+ # Types and descriptions are already defined in WebServerOptions above.
1487
+ additionalProperties: false
1488
+ properties:
1489
+ url: {}
1490
+ cert: {}
1491
+ key: {}
1492
+ chain: {}
1493
+ username:
1494
+ type: string
1495
+ description: >-
1496
+ Username expected from clients in HTTP Basic authentication.
1497
+ Set together with `password`.
1498
+ When not set, requests are accepted without authentication.
1499
+ Mandatory when `url` is not a loopback address (`localhost`, `127.0.0.0/8`, `::1`).
1500
+ examples:
1501
+ - fx4_user
1502
+ password:
1503
+ type: string
1504
+ description: >-
1505
+ Password expected from clients in HTTP Basic authentication, for the above `username`.
1506
+ Generate it with `openssl rand -hex 32`: a weak password is refused (see `password_min_bits`).
1507
+ examples:
1508
+ - "<PASSWORD>"
1509
+ password_min_bits:
1510
+ type: integer
1511
+ minimum: 0
1512
+ default: 80
1513
+ description: >-
1514
+ Minimum estimated strength of `password`, in bits (log2 of the number of guesses to find it).
1515
+ The strength is estimated with gem `zxcvbn` if installed, else with a built-in estimate
1516
+ that detects repeats, sequences, keyboard rows, words and years.
1517
+ `0` disables the check.
1518
+ A random password of 32 bytes (`openssl rand -hex 32`) is far above the default.
1519
+ Faspex4PostProcOptions:
1520
+ description: >-
1521
+ Configuration for the Faspex 4-style post-processing webhook receiver (`faspex5 postprocessing`).
1522
+ The command starts a local HTTP(S) server that Faspex 5 calls after each package upload.
1523
+ It maps the URL path to a script under `script_folder` and executes it with the values of the
1524
+ webhook JSON body whose key starts with `faspex_` as environment variables.
1525
+ By default the server binds to loopback; use a routable address only when Faspex containers
1526
+ must reach the host: then `secret_token` or `allowed_ips` is required.
1527
+ allOf:
1528
+ - $ref: "#/components/schemas/WebServerOptions"
1529
+ - type: object
1530
+ additionalProperties: false
1531
+ properties:
1532
+ # Listed solely to allow them under additionalProperties: false (defined in WebServerOptions).
1533
+ url: {}
1534
+ cert: {}
1535
+ key: {}
1536
+ chain: {}
1537
+ script_folder:
1538
+ type: string
1539
+ x-cli-complete: folder
1540
+ description: >-
1541
+ Folder containing the post-processing scripts.
1542
+ The URL path (after the base path) is appended to this folder to locate the script to execute.
1543
+ default: "."
1544
+ examples:
1545
+ - /opt/faspex/scripts
1546
+ fail_on_error:
1547
+ type: boolean
1548
+ description: >-
1549
+ When `true`, return HTTP 500 if the script exits with a non-zero status code.
1550
+ When `false` (default), the exit code is reported in the response body but HTTP 200 is returned.
1551
+ default: false
1552
+ timeout_seconds:
1553
+ type: integer
1554
+ minimum: 1
1555
+ description: >-
1556
+ Maximum time in seconds to wait for the script to complete before killing it.
1557
+ default: 60
1558
+ secret_token:
1559
+ type: string
1560
+ minLength: 1
1561
+ description: >-
1562
+ Shared secret for webhook authentication.
1563
+ When set, every incoming request must include `?token=<value>` in the URL;
1564
+ requests without the correct token are rejected with HTTP 401.
1565
+ Configure the Faspex webhook URL as `http://host:port/path/script.sh?token=<value>`.
1566
+ This parameter or `allowed_ips` is required when `url` is not a local address.
1567
+ Generate it with `openssl rand -hex 32`: a weak token is refused (see `secret_token_min_bits`).
1568
+ secret_token_min_bits:
1569
+ type: integer
1570
+ minimum: 0
1571
+ default: 80
1572
+ description: >-
1573
+ Minimum estimated strength of `secret_token`, in bits (log2 of the number of guesses to find it).
1574
+ The strength is estimated with gem `zxcvbn` if installed, else with a built-in estimate
1575
+ that detects repeats, sequences, keyboard rows, words and years.
1576
+ `0` disables the check.
1577
+ A random token of 32 bytes (`openssl rand -hex 32`) is far above the default.
1578
+ allowed_ips:
1579
+ description: >-
1580
+ IP address or network (CIDR, e.g. `10.89.0.0/24`), or list of them, allowed to call the listener.
1581
+ Requests from any other source IP are rejected with HTTP 403.
1582
+ When not set, no IP restriction is applied.
1583
+ This parameter or `secret_token` is required when `url` is not a local address.
1584
+ oneOf:
1585
+ - type: string
1586
+ examples:
1587
+ - "192.168.1.10"
1588
+ - type: array
1589
+ items:
1590
+ type: string
1591
+ examples:
1592
+ - - "192.168.1.10"
1593
+ - "10.89.0.0/24"