aspera-cli 4.28.0 → 4.29.1
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.
- checksums.yaml +4 -4
- checksums.yaml.gz.sig +0 -0
- data/BUGS.md +5 -10
- data/CHANGELOG.md +217 -2
- data/CODE_OF_CONDUCT.md +18 -0
- data/CONTRIBUTING.md +135 -56
- data/GOVERNANCE.md +30 -0
- data/LICENSE +201 -0
- data/README.md +122 -26
- data/SECURITY.md +84 -0
- data/bin/ascli +8 -5
- data/bin/asession +9 -6
- data/docs/README.md +1895 -632
- data/docs/test-mcp-with-ai.md +8 -8
- data/lib/aspera/agent/base.rb +23 -2
- data/lib/aspera/agent/connect.rb +16 -12
- data/lib/aspera/agent/desktop.rb +10 -7
- data/lib/aspera/agent/direct.rb +20 -19
- data/lib/aspera/agent/factory.rb +6 -3
- data/lib/aspera/agent/httpgw.rb +7 -5
- data/lib/aspera/agent/node.rb +15 -7
- data/lib/aspera/agent/transferd.rb +167 -43
- data/lib/aspera/api/alee.rb +4 -1
- data/lib/aspera/api/aoc.rb +14 -11
- data/lib/aspera/api/ats.rb +4 -2
- data/lib/aspera/api/cos_node.rb +7 -4
- data/lib/aspera/api/faspex.rb +16 -9
- data/lib/aspera/api/httpgw.rb +9 -6
- data/lib/aspera/api/node.rb +29 -22
- data/lib/aspera/ascmd.rb +8 -5
- data/lib/aspera/ascp/installation.rb +95 -67
- data/lib/aspera/ascp/log.schema.yaml +1084 -0
- data/lib/aspera/ascp/log_analyzer/advice.rb +97 -0
- data/lib/aspera/ascp/log_analyzer/diagnostics.rb +344 -0
- data/lib/aspera/ascp/log_analyzer/lines.rb +75 -0
- data/lib/aspera/ascp/log_analyzer/log_file.rb +593 -0
- data/lib/aspera/ascp/log_analyzer/records.rb +379 -0
- data/lib/aspera/ascp/log_analyzer/rules.rb +172 -0
- data/lib/aspera/ascp/log_analyzer/session.rb +782 -0
- data/lib/aspera/ascp/log_analyzer.rb +370 -0
- data/lib/aspera/ascp/log_locations.rb +163 -0
- data/lib/aspera/ascp/management.rb +16 -8
- data/lib/aspera/ascp/session_errors.rb +217 -0
- data/lib/aspera/assert.rb +4 -0
- data/lib/aspera/cli/ascp_actions.rb +12 -19
- data/lib/aspera/cli/ascp_logs_actions.rb +188 -0
- data/lib/aspera/cli/async_transfer_store.rb +7 -4
- data/lib/aspera/cli/bootstrapper.rb +38 -33
- data/lib/aspera/cli/command_line.rb +63 -8
- data/lib/aspera/cli/command_registry.rb +9 -1
- data/lib/aspera/cli/command_spec.rb +47 -7
- data/lib/aspera/cli/completion/ascli.bash +19 -5
- data/lib/aspera/cli/completion/ascli.fish +13 -2
- data/lib/aspera/cli/completion/ascli.ps1 +31 -9
- data/lib/aspera/cli/completion/ascli.zsh +22 -6
- data/lib/aspera/cli/completion_actions.rb +303 -69
- data/lib/aspera/cli/context.rb +9 -4
- data/lib/aspera/cli/deprecation.rb +5 -2
- data/lib/aspera/cli/error.rb +6 -0
- data/lib/aspera/cli/extended_value.rb +66 -31
- data/lib/aspera/cli/formatter.rb +43 -30
- data/lib/aspera/cli/gem_checker.rb +9 -6
- data/lib/aspera/cli/hints.rb +22 -10
- data/lib/aspera/cli/http.rb +38 -10
- data/lib/aspera/cli/info.rb +12 -7
- data/lib/aspera/cli/mailer.rb +6 -3
- data/lib/aspera/cli/mcp/http_servlet.rb +7 -8
- data/lib/aspera/cli/mcp/secrets.rb +8 -5
- data/lib/aspera/cli/mcp/tool.rb +20 -17
- data/lib/aspera/cli/option_declarator.rb +10 -4
- data/lib/aspera/cli/option_registry.rb +6 -3
- data/lib/aspera/cli/option_types.rb +17 -2
- data/lib/aspera/cli/option_value.rb +77 -18
- data/lib/aspera/cli/options.schema.yaml +641 -80
- data/lib/aspera/cli/parser.rb +71 -35
- data/lib/aspera/cli/plugins/alee.rb +7 -4
- data/lib/aspera/cli/plugins/aoc.rb +248 -37
- data/lib/aspera/cli/plugins/ats.rb +10 -9
- data/lib/aspera/cli/plugins/base.rb +50 -18
- data/lib/aspera/cli/plugins/basic_auth.rb +5 -2
- data/lib/aspera/cli/plugins/config.rb +210 -104
- data/lib/aspera/cli/plugins/console.rb +6 -3
- data/lib/aspera/cli/plugins/cos.rb +8 -4
- data/lib/aspera/cli/plugins/factory.rb +21 -7
- data/lib/aspera/cli/plugins/faspex5.rb +31 -26
- data/lib/aspera/cli/plugins/faspio.rb +7 -5
- data/lib/aspera/cli/plugins/httpgw.rb +7 -4
- data/lib/aspera/cli/plugins/mcp.rb +42 -22
- data/lib/aspera/cli/plugins/node.rb +39 -38
- data/lib/aspera/cli/plugins/oauth.rb +23 -6
- data/lib/aspera/cli/plugins/orchestrator.rb +287 -83
- data/lib/aspera/cli/plugins/preview.rb +72 -45
- data/lib/aspera/cli/plugins/server.rb +66 -14
- data/lib/aspera/cli/plugins/shares.rb +87 -18
- data/lib/aspera/cli/plugins/transferd.rb +228 -0
- data/lib/aspera/cli/poll.rb +236 -0
- data/lib/aspera/cli/preset_actions.rb +144 -30
- data/lib/aspera/cli/preset_manager.rb +113 -35
- data/lib/aspera/cli/prompt.rb +157 -9
- data/lib/aspera/cli/result.rb +12 -8
- data/lib/aspera/cli/runner.rb +89 -48
- data/lib/aspera/cli/secret_finder.rb +4 -1
- data/lib/aspera/cli/security.rb +89 -9
- data/lib/aspera/cli/special_values.rb +4 -1
- data/lib/aspera/cli/sync_actions.rb +15 -10
- data/lib/aspera/cli/table_fitter.rb +3 -0
- data/lib/aspera/cli/terminal_formatter.rb +9 -6
- data/lib/aspera/cli/transfer_actions.rb +11 -8
- data/lib/aspera/cli/transfer_agent.rb +43 -20
- data/lib/aspera/cli/transfer_progress.rb +14 -45
- data/lib/aspera/cli/vault_actions.rb +45 -0
- data/lib/aspera/cli/vault_manager.rb +188 -42
- data/lib/aspera/cli/version.rb +4 -1
- data/lib/aspera/cli/web_secret.rb +12 -10
- data/lib/aspera/cli/wizard.rb +42 -39
- data/lib/aspera/command_line_builder.rb +9 -5
- data/lib/aspera/command_line_converter.rb +4 -1
- data/lib/aspera/coverage.rb +103 -33
- data/lib/aspera/data_repository.rb +4 -1
- data/lib/aspera/dot_container.rb +4 -1
- data/lib/aspera/environment.rb +23 -12
- data/lib/aspera/exec_spec.rb +3 -0
- data/lib/aspera/faspex_gw.rb +13 -9
- data/lib/aspera/faspex_postproc.rb +15 -12
- data/lib/aspera/formatter_interface.rb +4 -1
- data/lib/aspera/graphql.rb +5 -1
- data/lib/aspera/hash_ext.rb +3 -0
- data/lib/aspera/id_generator.rb +20 -5
- data/lib/aspera/inflate.rb +43 -0
- data/lib/aspera/json_rpc/client.rb +6 -5
- data/lib/aspera/json_rpc/version.rb +3 -0
- data/lib/aspera/line_logger.rb +4 -1
- data/lib/aspera/link_header.rb +4 -1
- data/lib/aspera/log.rb +18 -5
- data/lib/aspera/markdown.rb +5 -2
- data/lib/aspera/mime.rb +3 -0
- data/lib/aspera/nagios.rb +6 -4
- data/lib/aspera/node_emulator.rb +15 -13
- data/lib/aspera/oauth/client/base.rb +124 -73
- data/lib/aspera/oauth/client/boot.rb +7 -4
- data/lib/aspera/oauth/client/factory.rb +41 -18
- data/lib/aspera/oauth/client/generic.rb +5 -1
- data/lib/aspera/oauth/client/json_credentials.rb +7 -3
- data/lib/aspera/oauth/client/jwt.rb +6 -3
- data/lib/aspera/oauth/client/shares_web.rb +94 -0
- data/lib/aspera/oauth/client/url_json.rb +7 -3
- data/lib/aspera/oauth/client/web.rb +40 -13
- data/lib/aspera/oauth/server/pkce.rb +6 -5
- data/lib/aspera/orchestrator_workflow_checker.rb +129 -2
- data/lib/aspera/persistency_action_once.rb +5 -3
- data/lib/aspera/persistency_folder.rb +6 -3
- data/lib/aspera/preview/file_types.rb +6 -3
- data/lib/aspera/preview/generator.rb +9 -5
- data/lib/aspera/preview/options.schema.yaml +3 -3
- data/lib/aspera/preview/terminal.rb +16 -6
- data/lib/aspera/preview/utils.rb +6 -4
- data/lib/aspera/products/connect.rb +5 -2
- data/lib/aspera/products/desktop.rb +17 -2
- data/lib/aspera/products/other.rb +4 -2
- data/lib/aspera/products/transferd.rb +6 -2
- data/lib/aspera/products/transferd_service.rb +610 -0
- data/lib/aspera/proxy_auto_config.js +2 -2
- data/lib/aspera/proxy_auto_config.rb +5 -2
- data/lib/aspera/rainbow.rb +3 -0
- data/lib/aspera/rest/aspera_errors.rb +4 -1
- data/lib/aspera/rest/call_error.rb +3 -0
- data/lib/aspera/rest/client.rb +45 -34
- data/lib/aspera/rest/error_analyzer.rb +5 -2
- data/lib/aspera/rest/list.rb +8 -4
- data/lib/aspera/rest/parameters.rb +3 -0
- data/lib/aspera/rest/util.rb +8 -5
- data/lib/aspera/rest.rb +9 -6
- data/lib/aspera/schema/IBM Aspera Faspex API-5.0-enhanced.yaml +9 -9
- data/lib/aspera/schema/IBM Aspera Orchestrator API-v1-enhanced.yaml +118 -30
- data/lib/aspera/schema/IBM Aspera on Cloud API-0.2.6-enhanced.yaml +11 -11
- data/lib/aspera/schema/IBM Aspera on Cloud Automation API-1.0.5-enhanced.yaml +2437 -1437
- data/lib/aspera/schema/async_tables.yaml +11 -10
- data/lib/aspera/schema/documentation.rb +8 -2
- data/lib/aspera/schema/reader.rb +7 -0
- data/lib/aspera/schema/registry.rb +44 -28
- data/lib/aspera/schema/transferd-config.schema.json +333 -0
- data/lib/aspera/schema/validator.rb +4 -1
- data/lib/aspera/sealed_hash.rb +150 -0
- data/lib/aspera/secret/hider.rb +213 -0
- data/lib/aspera/secret/reference.rb +150 -0
- data/lib/aspera/secret/resolver.rb +212 -0
- data/lib/aspera/secret/store/base.rb +153 -0
- data/lib/aspera/secret/store/encrypted_hash.rb +329 -0
- data/lib/aspera/secret/store/factory.rb +103 -0
- data/lib/aspera/secret/store/hashicorp_vault.rb +390 -0
- data/lib/aspera/secret/store/keeper.rb +141 -0
- data/lib/aspera/secret/store/macos_security.rb +284 -0
- data/lib/aspera/secret/store/one_password_api.rb +99 -0
- data/lib/aspera/secret/store/one_password_base.rb +42 -0
- data/lib/aspera/secret/store/one_password_cli.rb +112 -0
- data/lib/aspera/secret/store/secret_service.rb +125 -0
- data/lib/aspera/secret/strength.rb +119 -0
- data/lib/aspera/servlet_helpers.rb +5 -2
- data/lib/aspera/ssh.rb +10 -7
- data/lib/aspera/ssl.rb +5 -2
- data/lib/aspera/string_ext.rb +3 -0
- data/lib/aspera/sync/args.schema.yaml +3 -0
- data/lib/aspera/sync/conf.schema.yaml +9 -4
- data/lib/aspera/sync/database.rb +3 -0
- data/lib/aspera/sync/operations.rb +17 -15
- data/lib/aspera/temp_file_manager.rb +8 -4
- data/lib/aspera/timer_limiter.rb +3 -0
- data/lib/aspera/transfer/error.rb +4 -1
- data/lib/aspera/transfer/faux_file.rb +4 -1
- data/lib/aspera/transfer/parameters.rb +17 -14
- data/lib/aspera/transfer/result.rb +23 -0
- data/lib/aspera/transfer/resumer.rb +6 -4
- data/lib/aspera/transfer/spec.rb +9 -22
- data/lib/aspera/units/decimal.rb +67 -0
- data/lib/aspera/units/duration.rb +109 -0
- data/lib/aspera/uri_reader.rb +64 -9
- data/lib/aspera/web_auth/index.html.erb +6 -2
- data/lib/aspera/web_auth/paste.rb +109 -0
- data/lib/aspera/web_auth/receiver.rb +50 -0
- data/lib/aspera/web_auth/relay.rb +76 -0
- data/lib/aspera/web_auth/reply.html.erb +150 -0
- data/lib/aspera/web_auth/server.rb +47 -10
- data/lib/aspera/web_page.rb +7 -2
- data/lib/aspera/web_server_simple.rb +6 -3
- data/lib/aspera/yaml.rb +5 -1
- data/llms-install.md +88 -0
- data/llms.txt +87 -0
- data/skills/ascli/SKILL.md +94 -0
- data.tar.gz.sig +0 -0
- metadata +77 -20
- metadata.gz.sig +0 -0
- data/lib/aspera/duration.rb +0 -42
- data/lib/aspera/keychain/base.rb +0 -30
- data/lib/aspera/keychain/encrypted_hash.rb +0 -192
- data/lib/aspera/keychain/factory.rb +0 -58
- data/lib/aspera/keychain/hashicorp_vault.rb +0 -77
- data/lib/aspera/keychain/macos_security.rb +0 -277
- data/lib/aspera/keychain/one_password_api.rb +0 -91
- data/lib/aspera/keychain/one_password_base.rb +0 -39
- data/lib/aspera/keychain/one_password_cli.rb +0 -100
- data/lib/aspera/secret_hider.rb +0 -196
- 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.1"
|
|
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
|
+

|
|
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.
|
|
198
|
+
tar -C $HOME/bin -zxvf ascli-4.29.1-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.
|
|
212
|
+
4.29.1
|
|
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
|
|
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
|
|
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,36 @@ 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
|
|
271
|
-
|
|
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
|
+
The same content is displayed by `ascli config skill`: an AI that can execute `ascli` can read it with no file to find.
|
|
306
|
+
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.
|
|
307
|
+
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:
|
|
308
|
+
|
|
309
|
+
```shell
|
|
310
|
+
cp -R "$(gem contents aspera-cli | grep 'skills/ascli/SKILL.md$' | xargs dirname)" ~/.claude/skills/
|
|
311
|
+
```
|
|
312
|
+
|
|
313
|
+
With Claude Code, install it as a plugin from the GitHub repository, which is also a plugin marketplace: it is updated with the repository.
|
|
314
|
+
|
|
315
|
+
```text
|
|
316
|
+
/plugin marketplace add IBM/aspera-cli
|
|
317
|
+
/plugin install ascli@aspera-cli
|
|
318
|
+
```
|
|
319
|
+
|
|
320
|
+
- **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.
|
|
321
|
+
The AI discovers commands and their arguments by itself, and executes them.
|
|
322
|
+
By default, the server restricts what the AI can do (see [Security](#security)), and the AI never sees secrets.
|
|
323
|
+
|
|
324
|
+
- **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.
|
|
325
|
+
|
|
326
|
+
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
327
|
|
|
273
|
-
Recommended Workflow:
|
|
328
|
+
Recommended Workflow for a chat assistant:
|
|
274
329
|
|
|
275
330
|
- **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
331
|
|
|
@@ -321,7 +376,7 @@ There are several ways to install `ascli`:
|
|
|
321
376
|
- On Windows, as a [portable package](#windows-portable-package)
|
|
322
377
|
|
|
323
378
|
This method is the simplest on Windows: extract and run. It includes Ruby, gems and `ascp`.
|
|
324
|
-
- On Windows, with the [Chocolatey package](#windows-chocolatey-package)
|
|
379
|
+
- On Windows, with the [Chocolatey package](#windows-chocolatey-package): it installs the portable package and adds `ascli` to the `PATH`.
|
|
325
380
|
- As a [container](#container) (`docker`, `podman`, `singularity`).
|
|
326
381
|
|
|
327
382
|
The following sections describe the various installation methods.
|
|
@@ -347,7 +402,7 @@ This executable includes the Ruby runtime and gems, but not the transfer SDK.
|
|
|
347
402
|
|
|
348
403
|
```shell
|
|
349
404
|
tar zxvf aspera-cli-<VERSION>-<PLATFORM>.tgz
|
|
350
|
-
./ascli
|
|
405
|
+
./ascli transferd install
|
|
351
406
|
```
|
|
352
407
|
|
|
353
408
|
#### Linux: Checking the GLIBC version
|
|
@@ -406,7 +461,7 @@ The GLIBC of the system must be at least the version in the archive name, see [C
|
|
|
406
461
|
|
|
407
462
|
> [!NOTE]
|
|
408
463
|
> The launcher `ascli` uses the `ascp` located in folder `sdk` of the package, unless environment variable `ASCLI_SDK_FOLDER` is set.
|
|
409
|
-
> So, `ascli
|
|
464
|
+
> So, `ascli transferd install` is not needed.
|
|
410
465
|
|
|
411
466
|
The configuration is stored in the [main folder](#main-configuration-and-persistency-folder), like for other installation methods.
|
|
412
467
|
To upgrade, extract the new version, and update the symbolic link.
|
|
@@ -443,7 +498,7 @@ Apart from the prerequisite below, no installation step, no administrator rights
|
|
|
443
498
|
|
|
444
499
|
> [!NOTE]
|
|
445
500
|
> 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
|
|
501
|
+
> So, `ascli transferd install` is not needed.
|
|
447
502
|
|
|
448
503
|
The configuration is stored in the [main folder](#main-configuration-and-persistency-folder), like for other installation methods.
|
|
449
504
|
To upgrade, extract the new version, and update the `PATH` if the folder name changed.
|
|
@@ -451,7 +506,8 @@ To uninstall, delete the folder, and remove it from the `PATH` if it was added.
|
|
|
451
506
|
|
|
452
507
|
### Windows: Chocolatey package
|
|
453
508
|
|
|
454
|
-
If you use [Chocolatey](https://chocolatey.org/), `ascli` can be installed with the `aspera-cli` package
|
|
509
|
+
If you use [Chocolatey](https://chocolatey.org/), `ascli` can be installed with the `aspera-cli` package.
|
|
510
|
+
It installs the [portable package](#windows-portable-package) (Ruby, gems and `ascp` included, checked with its SHA-256) and adds only the command `ascli` to the `PATH`: no Ruby installation is needed.
|
|
455
511
|
|
|
456
512
|
In a PowerShell as Administrator:
|
|
457
513
|
|
|
@@ -459,16 +515,16 @@ In a PowerShell as Administrator:
|
|
|
459
515
|
choco install aspera-cli -y
|
|
460
516
|
```
|
|
461
517
|
|
|
462
|
-
|
|
518
|
+
Upgrade with `choco upgrade aspera-cli`, uninstall with `choco uninstall aspera-cli` (the configuration is kept).
|
|
463
519
|
|
|
464
520
|
### Ruby
|
|
465
521
|
|
|
466
522
|
A Ruby interpreter is required to run `ascli`.
|
|
467
523
|
|
|
468
|
-
Required Ruby version is version: >= 3.
|
|
524
|
+
Required Ruby version is version: >= 3.3.
|
|
469
525
|
|
|
470
526
|
> [!WARNING]
|
|
471
|
-
> The minimum Ruby version will be 3.
|
|
527
|
+
> The minimum Ruby version will be 3.4 in a future version.
|
|
472
528
|
|
|
473
529
|
**Ruby can be installed using any of the following methods**: `rpm`, `yum`, `dnf`, `rvm`, `rbenv`, `brew`, Windows installer, ...
|
|
474
530
|
|
|
@@ -479,10 +535,21 @@ Required Ruby version is version: >= 3.2.
|
|
|
479
535
|
|
|
480
536
|
For convenience, you may refer to the following sections for a proposed method for specific operating systems.
|
|
481
537
|
|
|
482
|
-
`ascli` supports a Ruby version until
|
|
538
|
+
`ascli` supports a Ruby version until 6 months after its [end of official support](https://www.ruby-lang.org/en/downloads/branches/).
|
|
483
539
|
The minimum version is increased accordingly, and announced in advance.
|
|
484
540
|
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
541
|
|
|
542
|
+
The following table summarizes Ruby version life cycles and `ascli` support status:
|
|
543
|
+
|
|
544
|
+
| Ruby Version | Official EOL Date | ascli Support End (EOL + 6 mo) | ascli Status |
|
|
545
|
+
| ------------ | ----------------- | ------------------------------ | --------------------------------- |
|
|
546
|
+
| 4.0 | 2029-03-31 | 2029-09-30 | **Supported (Tested & Packaged)** |
|
|
547
|
+
| 3.4 | 2028-03-31 | 2028-09-30 | **Supported (Future minimum)** |
|
|
548
|
+
| 3.3 | 2027-03-31 | 2027-09-30 | **Supported (Current minimum)** |
|
|
549
|
+
| 3.2 | 2026-03-31 | 2026-09-30 | End of Support |
|
|
550
|
+
| 3.1 | 2025-03-26 | 2025-09-26 | End of Support |
|
|
551
|
+
| 3.0 | 2024-04-23 | 2024-10-23 | End of Support |
|
|
552
|
+
|
|
486
553
|
#### Windows: Installer
|
|
487
554
|
|
|
488
555
|
Manual installation:
|
|
@@ -545,6 +612,24 @@ Add it to your shell configuration file:
|
|
|
545
612
|
|
|
546
613
|
#### Linux: Package
|
|
547
614
|
|
|
615
|
+
`ascli` supports Linux distributions that are officially maintained by their vendor (Red Hat for RHEL / UBI, Canonical for Ubuntu LTS).
|
|
616
|
+
|
|
617
|
+
- **GLIBC Requirement:** The Transfer SDK executables (`ascp`, `transferd`) and the Linux portable package require **`glibc >= 2.28`**.
|
|
618
|
+
- **Installation Compatibility:**
|
|
619
|
+
- 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`.
|
|
620
|
+
- 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`).
|
|
621
|
+
|
|
622
|
+
The following table summarizes supported Linux distributions, vendor end of support dates, GLIBC versions, available Ruby streams, and recommended `ascli` installation modes:
|
|
623
|
+
|
|
624
|
+
| Linux Distribution | OS Support End (EOL) | GLIBC (>= 2.28) | OS Ruby Version(s) | ascli Support / Mode |
|
|
625
|
+
| -------------------- | -------------------- | ------------------ | ------------------------------------ | ----------------------------------------------------- |
|
|
626
|
+
| **RHEL / UBI 10** | 2035-05-31 | 2.39+ (Compatible) | >= 3.3 (default) | Gem, Portable, Container |
|
|
627
|
+
| **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 |
|
|
628
|
+
| **RHEL / UBI 8** | 2029-05-31 | 2.28 (Compatible) | 3.1, 3.3 (DNF module) | Gem (`dnf module enable ruby:3.3`), Portable, Container |
|
|
629
|
+
| **Ubuntu 26.04 LTS** | 2031-05-29 | 2.43+ (Compatible) | >= 3.3 (APT package) | Gem, Portable, Container |
|
|
630
|
+
| **Ubuntu 24.04 LTS** | 2029-05-31 | 2.39 (Compatible) | 3.2 (APT package) | Gem (`apt install ruby-full`), Portable, Container |
|
|
631
|
+
| **Ubuntu 22.04 LTS** | 2027-06-01 | 2.35 (Compatible) | 3.0 (APT package) | Portable, Container, rbenv (OS Ruby < 3.2) |
|
|
632
|
+
|
|
548
633
|
If your Linux distribution provides a standard Ruby package, you can use it provided that the version is supported.
|
|
549
634
|
|
|
550
635
|
**Example:** RHEL 8+, Rocky Linux 8+: with extensions to compile native gems:
|
|
@@ -754,30 +839,30 @@ Those are not installed as part of dependencies because they involve compilation
|
|
|
754
839
|
See [Gemfile](../Gemfile):
|
|
755
840
|
|
|
756
841
|
| name | version | comment |
|
|
757
|
-
|
|
842
|
+
| ---------------------- | --------- | -------------------------------------------------------------------------------- |
|
|
758
843
|
| rake | ~> 13.0 | |
|
|
759
844
|
| debug | ~> 1.11 | (no jruby) |
|
|
760
845
|
| grpc-tools | ~> 1.67 | |
|
|
761
|
-
| reek | ~> 6.
|
|
846
|
+
| reek | ~> 6.6.0 | |
|
|
762
847
|
| rspec | ~> 3.0 | |
|
|
763
848
|
| rubocop | ~> 1.75 | |
|
|
764
849
|
| rubocop-ast | ~> 1.4 | |
|
|
765
850
|
| rubocop-performance | ~> 1.10 | (no jruby) |
|
|
766
|
-
| rubocop-shopify | ~>
|
|
767
|
-
| simplecov | ~>
|
|
851
|
+
| rubocop-shopify | ~> 3.1 | |
|
|
852
|
+
| simplecov | ~> 1.3 | |
|
|
768
853
|
| solargraph | ~> 0.48 | (no jruby) |
|
|
769
|
-
| ferrum | ~> 0.
|
|
854
|
+
| ferrum | ~> 0.20.1 | (no jruby) |
|
|
770
855
|
| mcp | ~> 1.2 | for ascli mcp server (MCP protocol support) |
|
|
771
856
|
| rack | ~> 3.0 | for ascli mcp server HTTP transport (required by mcp StreamableHTTPTransport) |
|
|
772
857
|
| grpc | ~> 1.71 | (no jruby) for Aspera Transfer Daemon |
|
|
773
858
|
| sqlite3 | ~> 2.7 | (no jruby) for async DB |
|
|
774
859
|
| jdbc-sqlite3 | ~> 3.46 | (jruby) for async DB |
|
|
775
860
|
| sequel | ~> 5.96 | (jruby) for async DB |
|
|
776
|
-
|
|
|
777
|
-
| bcrypt_pbkdf | ~> 1.1 | (no jruby) for ed25519 and OpenSSH file format |
|
|
861
|
+
| bcrypt_pbkdf | ~> 1.1 | (no jruby) for passphrase-protected OpenSSH private keys (ed25519 is native in net-ssh 8) |
|
|
778
862
|
| syslog | ~> 0.3 | (no jruby) for logger=syslog |
|
|
779
863
|
| zxcvbn | ~> 1.0 | for better estimate of secret strength (faspex5 postprocessing secret_token) |
|
|
780
|
-
|
|
|
864
|
+
| keeper_secrets_manager | ~> 17.2 | for vault of type keeper (Keeper Secrets Manager) |
|
|
865
|
+
| rmagick | ~> 7.2 | (no jruby) for terminal view |
|
|
781
866
|
|
|
782
867
|
Install like this:
|
|
783
868
|
|
|
@@ -785,26 +870,26 @@ Install like this:
|
|
|
785
870
|
gem install rake -v '~> 13.0'
|
|
786
871
|
gem install debug -v '~> 1.11'
|
|
787
872
|
gem install grpc-tools -v '~> 1.67'
|
|
788
|
-
gem install reek -v '~> 6.
|
|
873
|
+
gem install reek -v '~> 6.6.0'
|
|
789
874
|
gem install rspec -v '~> 3.0'
|
|
790
875
|
gem install rubocop -v '~> 1.75'
|
|
791
876
|
gem install rubocop-ast -v '~> 1.4'
|
|
792
877
|
gem install rubocop-performance -v '~> 1.10'
|
|
793
|
-
gem install rubocop-shopify -v '~>
|
|
794
|
-
gem install simplecov -v '~>
|
|
878
|
+
gem install rubocop-shopify -v '~> 3.1'
|
|
879
|
+
gem install simplecov -v '~> 1.3'
|
|
795
880
|
gem install solargraph -v '~> 0.48'
|
|
796
|
-
gem install ferrum -v '~> 0.
|
|
881
|
+
gem install ferrum -v '~> 0.20.1'
|
|
797
882
|
gem install mcp -v '~> 1.2'
|
|
798
883
|
gem install rack -v '~> 3.0'
|
|
799
884
|
gem install grpc -v '~> 1.71'
|
|
800
885
|
gem install sqlite3 -v '~> 2.7'
|
|
801
886
|
gem install jdbc-sqlite3 -v '~> 3.46'
|
|
802
887
|
gem install sequel -v '~> 5.96'
|
|
803
|
-
gem install ed25519 -v '~> 1.4'
|
|
804
888
|
gem install bcrypt_pbkdf -v '~> 1.1'
|
|
805
889
|
gem install syslog -v '~> 0.3'
|
|
806
890
|
gem install zxcvbn -v '~> 1.0'
|
|
807
|
-
gem install
|
|
891
|
+
gem install keeper_secrets_manager -v '~> 17.2'
|
|
892
|
+
gem install rmagick -v '~> 7.2'
|
|
808
893
|
```
|
|
809
894
|
|
|
810
895
|
### Ruby gem: `aspera-cli`
|
|
@@ -880,7 +965,7 @@ The easiest option to install `ascp` is through the use of the IBM Aspera Transf
|
|
|
880
965
|
Install it using `ascli` (for the current platform) with:
|
|
881
966
|
|
|
882
967
|
```shell
|
|
883
|
-
ascli
|
|
968
|
+
ascli transferd install
|
|
884
969
|
```
|
|
885
970
|
|
|
886
971
|
The installation of the transfer binaries follows those steps:
|
|
@@ -893,6 +978,8 @@ The installation of the transfer binaries follows those steps:
|
|
|
893
978
|
- This YAML file lists supported architectures (OS, CPU) and Aspera Transfer Daemon versions with their associated package URLs.
|
|
894
979
|
- The SDK version is selected as follows: if an additional **positional parameter** is provided it specifies the version; if the special value `LATEST` is given the latest available version is used; otherwise the version tested with this release of `ascli` is used.
|
|
895
980
|
- The package URL matching the current system architecture is then used.
|
|
981
|
+
- The request for the YAML file includes the version of `ascli` in the HTTP header `Referer`.
|
|
982
|
+
- The YAML file is not read if the requested version is already installed, or if option `sdk_url` gives the archive.
|
|
896
983
|
- **Extract the archive**
|
|
897
984
|
- By default, the archive is extracted to `$HOME/.aspera/sdk`.
|
|
898
985
|
- The destination folder can be changed by setting the `sdk_folder` option.
|
|
@@ -903,30 +990,33 @@ The installation of the transfer binaries follows those steps:
|
|
|
903
990
|
| `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
991
|
| `sdk_folder` | Folder where the SDK archive is extracted.<br/>Default: `$HOME/.aspera/sdk` |
|
|
905
992
|
|
|
906
|
-
|
|
993
|
+
> [!NOTE]
|
|
994
|
+
> Commands `config transferd ...` and `config ascp install` are deprecated aliases of `transferd ...` and `transferd install`.
|
|
995
|
+
|
|
996
|
+
Transfer Daemon versions available from `locations_url` can be listed with: `ascli transferd list`
|
|
907
997
|
|
|
908
998
|
To install a specific version, for example, 1.1.3:
|
|
909
999
|
|
|
910
1000
|
```shell
|
|
911
|
-
ascli
|
|
1001
|
+
ascli transferd install 1.1.3
|
|
912
1002
|
```
|
|
913
1003
|
|
|
914
1004
|
To get the download URL for a specific platform and version:
|
|
915
1005
|
|
|
916
1006
|
```shell
|
|
917
|
-
ascli
|
|
1007
|
+
ascli transferd list --select.platform=osx-arm64 --select.version=1.1.3 --fields=url
|
|
918
1008
|
```
|
|
919
1009
|
|
|
920
1010
|
To download it, pipe to `config download`:
|
|
921
1011
|
|
|
922
1012
|
```shell
|
|
923
|
-
ascli
|
|
1013
|
+
ascli transferd list --select.platform=osx-arm64 --select.version=1.1.3 --fields=url | ascli config download @stdin:
|
|
924
1014
|
```
|
|
925
1015
|
|
|
926
1016
|
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
1017
|
|
|
928
1018
|
```shell
|
|
929
|
-
ascli
|
|
1019
|
+
ascli transferd install --sdk-url=file:///macos-arm64-1.1.3-c6c7a2a.zip
|
|
930
1020
|
```
|
|
931
1021
|
|
|
932
1022
|
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 +1032,7 @@ Supported platforms are listed in the [Release Notes](https://developer.ibm.com/
|
|
|
942
1032
|
|
|
943
1033
|
If the embedded method is not used, the following packages are also suitable:
|
|
944
1034
|
|
|
945
|
-
- IBM Aspera Connect Client (Free)
|
|
1035
|
+
- IBM Aspera Connect Client (Free, to be deprecated in 2027, use IBM Aspera for Desktop)
|
|
946
1036
|
- IBM Aspera Desktop Client (Free)
|
|
947
1037
|
- IBM Aspera for Desktop (Free)
|
|
948
1038
|
- IBM Aspera High Speed Transfer Server (Licensed)
|
|
@@ -980,13 +1070,13 @@ For an air-gapped installation, two alternatives are available:
|
|
|
980
1070
|
On a system with internet access, retrieve the SDK archive for the target platform and version:
|
|
981
1071
|
|
|
982
1072
|
```shell
|
|
983
|
-
ascli
|
|
1073
|
+
ascli transferd list --select.platform=<PLATFORM> --select.version=<VERSION> --fields=url | ascli config download @stdin:
|
|
984
1074
|
```
|
|
985
1075
|
|
|
986
1076
|
On the air-gapped system, install from the downloaded file using option `--sdk-url`:
|
|
987
1077
|
|
|
988
1078
|
```shell
|
|
989
|
-
ascli
|
|
1079
|
+
ascli transferd install --sdk-url=file:///<SDK_ARCHIVE_PATH>
|
|
990
1080
|
```
|
|
991
1081
|
|
|
992
1082
|
2. Retrieve the [single file executable](#single-file-executable) from the release, if available, and the SDK (not included) as described above.
|
|
@@ -999,11 +1089,11 @@ Alternatively, the necessary gems can be packaged into a `tar.gz` archive as fol
|
|
|
999
1089
|
|
|
1000
1090
|
```shell
|
|
1001
1091
|
mkdir temp_folder
|
|
1002
|
-
gem install aspera-cli:4.
|
|
1092
|
+
gem install aspera-cli:4.29.1 --no-document --install-dir temp_folder
|
|
1003
1093
|
find temp_folder
|
|
1004
|
-
mv temp_folder/cache aspera-cli-4.
|
|
1094
|
+
mv temp_folder/cache aspera-cli-4.29.1-gems
|
|
1005
1095
|
rm -fr temp_folder
|
|
1006
|
-
tar zcvf aspera-cli-4.
|
|
1096
|
+
tar zcvf aspera-cli-4.29.1-gems.tgz aspera-cli-4.29.1-gems
|
|
1007
1097
|
```
|
|
1008
1098
|
|
|
1009
1099
|
#### Unix-like: Alternative installation using `rvm`
|
|
@@ -1028,7 +1118,7 @@ The following procedure applies when using RVM for the Ruby installation:
|
|
|
1028
1118
|
cd $HOME
|
|
1029
1119
|
tar zxvf rvm-ascli.tgz
|
|
1030
1120
|
source ~/.rvm/scripts/rvm
|
|
1031
|
-
ascli
|
|
1121
|
+
ascli transferd install --sdk-url=file:///<SDK_ARCHIVE_PATH>
|
|
1032
1122
|
```
|
|
1033
1123
|
|
|
1034
1124
|
6. Add the following line to the shell environment file (`.profile`):
|
|
@@ -1076,7 +1166,7 @@ On the target system:
|
|
|
1076
1166
|
4. Install the Aspera Transfer Daemon SDK:
|
|
1077
1167
|
|
|
1078
1168
|
```shell
|
|
1079
|
-
ascli
|
|
1169
|
+
ascli transferd install --sdk-url=file:///<SDK_ARCHIVE_PATH>
|
|
1080
1170
|
```
|
|
1081
1171
|
|
|
1082
1172
|
### Container
|
|
@@ -1139,7 +1229,7 @@ ascli -v
|
|
|
1139
1229
|
```
|
|
1140
1230
|
|
|
1141
1231
|
```text
|
|
1142
|
-
4.
|
|
1232
|
+
4.29.1
|
|
1143
1233
|
```
|
|
1144
1234
|
|
|
1145
1235
|
To persist the configuration on the host, specify your user's configuration folder as a volume for the container.
|
|
@@ -1464,7 +1554,6 @@ Command line arguments that are not options are referred to as **Positional Argu
|
|
|
1464
1554
|
|
|
1465
1555
|
For example:
|
|
1466
1556
|
|
|
1467
|
-
|
|
1468
1557
|
```shell
|
|
1469
1558
|
ascli plugin command verb --option-name=VAL1 VAL2
|
|
1470
1559
|
```
|
|
@@ -1474,6 +1563,7 @@ ascli plugin command verb --option-name=VAL1 VAL2
|
|
|
1474
1563
|
|
|
1475
1564
|
Enumeration values (positional arguments and option names/values) support prefix matching.
|
|
1476
1565
|
See [Enumerations](#enumerations) for details.
|
|
1566
|
+
|
|
1477
1567
|
For example `ascli config pre ov --for=c` is the same as `ascli config preset overview --format=csv`.
|
|
1478
1568
|
|
|
1479
1569
|
The value of **Options** and **Command Parameters** is evaluated with the [Extended Value](#extended-value-syntax) syntax.
|
|
@@ -1580,7 +1670,6 @@ The following are enumerations:
|
|
|
1580
1670
|
|
|
1581
1671
|
Examples:
|
|
1582
1672
|
|
|
1583
|
-
|
|
1584
1673
|
- Positional: `ascli config pre ov --for=c` is the same as `ascli config preset overview --format=csv`
|
|
1585
1674
|
- Option name: `--log-l=debug` is the same as `--log-level=debug`
|
|
1586
1675
|
- Option value: `--format=c` is the same as `--format=csv`
|
|
@@ -1602,7 +1691,7 @@ Understanding this concept once makes it immediately usable everywhere it appear
|
|
|
1602
1691
|
| [Option](#options) names | `--opt.key.sub=value` | Input | write |
|
|
1603
1692
|
| [Positional arguments](#positional-arguments) | `@: key.sub=value ... [END]` | Input | write |
|
|
1604
1693
|
| [Extended value](#extended-value-syntax) `@preset:` | `@preset:key.sub` | Input | read |
|
|
1605
|
-
| [Output field names](#
|
|
1694
|
+
| [Output field names](#filtering-results) | `--out.fields=key.sub` | Output | read |
|
|
1606
1695
|
|
|
1607
1696
|
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
1697
|
|
|
@@ -1666,6 +1755,8 @@ The general syntax for this argument is:
|
|
|
1666
1755
|
The optional text after `:` sets the end marker. If it is empty, the marker is `END`.
|
|
1667
1756
|
|
|
1668
1757
|
- `<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.
|
|
1758
|
+
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`.
|
|
1759
|
+
Options placed among the assignments are not collected: they are processed as usual, for example `@: a=1 --format=json b=2`.
|
|
1669
1760
|
|
|
1670
1761
|
- `<MARKER>` (`END` by default): An optional argument that ends the collection.
|
|
1671
1762
|
|
|
@@ -1788,6 +1879,44 @@ The behavior can be controlled with:
|
|
|
1788
1879
|
- `--ask-options=<yes|no>` (default=no)
|
|
1789
1880
|
- `yes`: Optional parameters/arguments are asked to the user.
|
|
1790
1881
|
|
|
1882
|
+
#### Hidden Input
|
|
1883
|
+
|
|
1884
|
+
Secrets (passwords, `@secret:`, code or URL pasted after a web login) are read without displaying them.
|
|
1885
|
+
On a terminal, a mark shows the state of the input, without revealing its length:
|
|
1886
|
+
|
|
1887
|
+
| Mark | ASCII | State |
|
|
1888
|
+
|------|-------|-------|
|
|
1889
|
+
| `🔑` | `***` | Waiting for input: nothing typed or pasted yet. |
|
|
1890
|
+
| `…` | `...` | Something was typed or pasted. |
|
|
1891
|
+
| `✓` (green) | `valid` | Checked input: it is valid. |
|
|
1892
|
+
| `✗` (red) | `invalid` | Checked input: it is not valid (yet), e.g. incomplete, mistyped or expired. |
|
|
1893
|
+
|
|
1894
|
+
The ASCII form is used when the locale does not support Unicode.
|
|
1895
|
+
|
|
1896
|
+
Some inputs are checked while they are typed or pasted, e.g. the code displayed by Shares after login (see [Authentication of SAML users](#authentication-of-saml-users)): `✓` or `✗` replaces `…`.
|
|
1897
|
+
If `Enter` is pressed on an input that is not valid, the error is displayed and the input is asked again (`Ctrl-C` to stop).
|
|
1898
|
+
If the standard input is not a terminal, an input that is not valid is an error.
|
|
1899
|
+
|
|
1900
|
+
Keys:
|
|
1901
|
+
|
|
1902
|
+
| Key | Action |
|
|
1903
|
+
|-----|--------|
|
|
1904
|
+
| `Enter` | End the input. |
|
|
1905
|
+
| `Backspace` | Erase the last character. |
|
|
1906
|
+
| `Ctrl-W` | Erase the last word. |
|
|
1907
|
+
| `Ctrl-U` | Erase all (for example, to paste again). |
|
|
1908
|
+
| `Ctrl-D` (Unix), `Ctrl-Z` (Windows) | End the input; if empty: error (end of input). |
|
|
1909
|
+
| `Ctrl-C` | Stop `ascli`. |
|
|
1910
|
+
|
|
1911
|
+
If the standard input is not a terminal (for example, a pipe), the line is read as is, without mark.
|
|
1912
|
+
It is the same if the terminal does not support reading characters one by one (raw mode).
|
|
1913
|
+
|
|
1914
|
+
To read secrets without any mark (no feedback, as `getpass`), set option `ui.hidden_silent` to `yes`:
|
|
1915
|
+
|
|
1916
|
+
```shell
|
|
1917
|
+
ascli config preset set GLOBAL ui.hidden_silent yes
|
|
1918
|
+
```
|
|
1919
|
+
|
|
1791
1920
|
### Output
|
|
1792
1921
|
|
|
1793
1922
|
Command execution will result in output (terminal, stdout/stderr).
|
|
@@ -1838,9 +1967,212 @@ ascli config echo @json:'{"ni":null,"es":"","ea":[],"eh":{}}'
|
|
|
1838
1967
|
╰───────┴────────────────╯
|
|
1839
1968
|
```
|
|
1840
1969
|
|
|
1841
|
-
####
|
|
1970
|
+
#### Filtering results
|
|
1971
|
+
|
|
1972
|
+
The result of a command can be filtered on the server side, by the API, and then on the client side, by `ascli`.
|
|
1973
|
+
Filtering on the server side reduces the data transferred, while filtering on the client side accepts any condition.
|
|
1974
|
+
|
|
1975
|
+
Options are evaluated in this order:
|
|
1976
|
+
|
|
1977
|
+

|
|
1978
|
+
|
|
1979
|
+
1. `--query`: parameters sent to the API.
|
|
1980
|
+
2. `--out.secrets`: secrets are hidden first, so that an expression cannot reveal them.
|
|
1981
|
+
3. `--out.query`: JMESPath expression or Ruby lambda, applied to the data as returned by the API.
|
|
1982
|
+
4. `--out.select`: selection of items (rows).
|
|
1983
|
+
5. `--out.fields`: selection of fields (columns).
|
|
1984
|
+
6. Display in the format set by `--out.format`.
|
|
1985
|
+
|
|
1986
|
+
| To | Use |
|
|
1987
|
+
|------------------------------------------|------------------------------------------|
|
|
1988
|
+
| Limit what the API returns | `--query`, with parameters `max` and `pmax` |
|
|
1989
|
+
| Filter on any condition, reshape, count | `--out.query` |
|
|
1990
|
+
| Select items by the value of fields | `--out.select` |
|
|
1991
|
+
| Choose the fields displayed | `--out.fields` |
|
|
1992
|
+
|
|
1993
|
+
##### Option: `--query`: Parameters of the API
|
|
1994
|
+
|
|
1995
|
+
The `query` option can generally be used to add URL parameters to commands that list resources.
|
|
1996
|
+
It takes a `Hash`, corresponding to key/value pairs that appear in the query part of the request.
|
|
1997
|
+
|
|
1998
|
+
For example: `--query=@json:'{"p1":"v1","p2":"v2"}'` leads to query: `?p1=v1&p2=v2`.
|
|
1999
|
+
|
|
2000
|
+
If the same parameter needs to be provided several times, then it is also possible to provide an `Array`.
|
|
2001
|
+
|
|
2002
|
+
For example: `--query=@json:'{"p":["v1","v2"]}'` leads to query: `?p=v1&p=v2`.
|
|
2003
|
+
|
|
2004
|
+
If PHP-style arrays are expected in the API, add `[]` to the name of the parameter.
|
|
2005
|
+
|
|
2006
|
+
For example: `--query=@json:'{"p[]":["v1","v2"]}'` leads to query: `?p[]=v1&p[]=v2`.
|
|
2007
|
+
|
|
2008
|
+
Commands that read a list by pages (for example, `aoc admin user list`) also accept parameters `max` and `pmax`.
|
|
2009
|
+
They are processed by `ascli`, not sent to the API: they limit the number of items (`max`) and of pages (`pmax`) requested.
|
|
2010
|
+
|
|
2011
|
+
For example: `--query.max=10` reads the first 10 items.
|
|
2012
|
+
|
|
2013
|
+
> [!TIP]
|
|
2014
|
+
> Use `--query=help` on any `list` command to display the available query parameters and their types, as documented in the API.
|
|
2015
|
+
> For example: `ascli faspex5 admin accounts list --query=help`
|
|
2016
|
+
|
|
2017
|
+
##### Option: `--out.query`: JMESPath expression
|
|
2018
|
+
|
|
2019
|
+
Option `--out.query` applies a [JMESPath](https://jmespath.org) expression to the result of a command, when it is an object or a list.
|
|
2020
|
+
JMESPath is a standard query language for JSON, also used by option `--query` of the AWS and Azure CLIs.
|
|
2021
|
+
|
|
2022
|
+
The expression is applied to the data as returned by the API (secrets hidden), before options `--out.select` and `--out.fields`.
|
|
2023
|
+
Its syntax is checked before the command is executed.
|
|
2024
|
+
Results of other types (status, no result) are not changed.
|
|
2025
|
+
|
|
2026
|
+
Examples:
|
|
2027
|
+
|
|
2028
|
+
```shell
|
|
2029
|
+
# Name and email of ATS administrators
|
|
2030
|
+
ascli aoc admin user list --out.query='[?ats_admin].{name: name, email: email}'
|
|
2031
|
+
# Number of users
|
|
2032
|
+
ascli aoc admin user list --out.query='length(@)'
|
|
2033
|
+
# Email of users, one per line, for use in a shell loop
|
|
2034
|
+
ascli aoc admin user list --out.query='[].email' --format=text
|
|
2035
|
+
```
|
|
2036
|
+
|
|
2037
|
+
> [!TIP]
|
|
2038
|
+
> Enclose the expression in single quotes for the shell.
|
|
2039
|
+
> In JMESPath, literal values are enclosed in backticks, for example: ``[?size > `1000`]``.
|
|
2040
|
+
> An expression with string literals in single quotes (`'...'`) is enclosed in double quotes, for example: `"[?name=='Ann']"`.
|
|
2041
|
+
|
|
2042
|
+
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).
|
|
2043
|
+
It is refused at [Security Level](#security-level) `medium` and `high`.
|
|
1842
2044
|
|
|
1843
|
-
|
|
2045
|
+
```shell
|
|
2046
|
+
# Number of users per email domain
|
|
2047
|
+
ascli aoc admin user list --out.query=@ruby:'->(users){users.group_by{|u|u["email"].split("@").last}.transform_values(&:count)}'
|
|
2048
|
+
```
|
|
2049
|
+
|
|
2050
|
+
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.
|
|
2051
|
+
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}`.
|
|
2052
|
+
|
|
2053
|
+
> [!NOTE]
|
|
2054
|
+
> Option `--query` gives filtering parameters to the API, while option `--out.query` filters and reshapes the result received.
|
|
2055
|
+
> Option `--out.query` is the equivalent of option `--query` of the AWS and Azure CLIs.
|
|
2056
|
+
|
|
2057
|
+
##### Option: `--out.select`: Selection of items
|
|
2058
|
+
|
|
2059
|
+
A list of objects (`object_list`) can be filtered with option `--out.select` (or `--select`).
|
|
2060
|
+
Its value is either a `Hash` or a `Proc`:
|
|
2061
|
+
|
|
2062
|
+
- `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`).
|
|
2063
|
+
- `Proc`: a Ruby lambda called with each item (`Hash`), that returns `true` to select it, or `false` to remove it.
|
|
2064
|
+
|
|
2065
|
+
Example:
|
|
2066
|
+
|
|
2067
|
+
```shell
|
|
2068
|
+
ascli aoc admin user list --out.fields=name,email,ats_admin --query=@json:'{"sort":"name"}' --out.select=@json:'{"ats_admin":true}'
|
|
2069
|
+
```
|
|
2070
|
+
|
|
2071
|
+
```text
|
|
2072
|
+
╭────────────────┬─────────────────────┬───────────╮
|
|
2073
|
+
│ name │ email │ ats_admin │
|
|
2074
|
+
╞════════════════╪═════════════════════╪═══════════╡
|
|
2075
|
+
│ John Curtis │ john@example.com │ true │
|
|
2076
|
+
│ Laurent Martin │ laurent@example.com │ true │
|
|
2077
|
+
╰────────────────┴─────────────────────┴───────────╯
|
|
2078
|
+
```
|
|
2079
|
+
|
|
2080
|
+
In the above example, the same result is obtained with option:
|
|
2081
|
+
|
|
2082
|
+
```shell
|
|
2083
|
+
--out.select=@ruby:'->(i){i["ats_admin"]}'
|
|
2084
|
+
```
|
|
2085
|
+
|
|
2086
|
+
A key can be a [dot-path](#dot-path-notation), for example, `directory_user.type`, with all formats.
|
|
2087
|
+
|
|
2088
|
+
##### Option: `--out.fields`: Selection of fields
|
|
2089
|
+
|
|
2090
|
+
Depending on the command, results may include by default all fields, or only some selected fields.
|
|
2091
|
+
It is possible to define specific columns to be displayed, by setting option `--out.fields` (or `--fields`).
|
|
2092
|
+
|
|
2093
|
+
The `--out.fields` option is a list that can be either a comma-separated list or an [Extended Value](#extended-value-syntax) `Array`.
|
|
2094
|
+
|
|
2095
|
+
Individual elements of the list can be:
|
|
2096
|
+
|
|
2097
|
+
- **property**: add property to the current list
|
|
2098
|
+
- `-`**property**: remove property from the current list
|
|
2099
|
+
- `DEF`: default list of fields (that is the default, when not set)
|
|
2100
|
+
- `ALL`: all fields
|
|
2101
|
+
- A Ruby `RegEx`: using `@ruby:'/.../'`, or `@re:...` add those matching to the list
|
|
2102
|
+
|
|
2103
|
+
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`).
|
|
2104
|
+
With other formats, use a JMESPath multi-select hash with option `--out.query`, for example: `--out.query='[].{name: name, type: directory_user.type}'`.
|
|
2105
|
+
|
|
2106
|
+
Examples:
|
|
2107
|
+
|
|
2108
|
+
- `a,b,c`: the list of attributes specified as a comma-separated list (overrides the default)
|
|
2109
|
+
- `@list:,a,b,c`: `Array` [Extended Value](#extended-value-syntax): same as above
|
|
2110
|
+
- `@json:'["a","b","c"]'`: `Array` [Extended Value](#extended-value-syntax): same as above
|
|
2111
|
+
- `b,DEF,-a`: default property list, remove `a` and add `b` in first position
|
|
2112
|
+
- `@ruby:'/^server/'`: Display all fields whose name begins with `server`
|
|
2113
|
+
|
|
2114
|
+
##### `--out.select` or `--out.query`
|
|
2115
|
+
|
|
2116
|
+
Option `--out.select` is shorter for a test of equality, while option `--out.query` accepts any condition.
|
|
2117
|
+
|
|
2118
|
+
| Condition | `--out.select` | `--out.query` |
|
|
2119
|
+
|--------------------------|----------------------------------------------------|--------------------------------------------------|
|
|
2120
|
+
| Equal to a `Boolean` | `@json:'{"ats_admin":true}'` | `'[?ats_admin]'` |
|
|
2121
|
+
| Equal to a `String` | `@json:'{"name":"Ann"}'` | `"[?name=='Ann']"` |
|
|
2122
|
+
| Field of a nested object | `@json:'{"directory_user.type":"active_directory"}'` | `"[?directory_user.type=='active_directory']"` |
|
|
2123
|
+
| Several conditions (and) | `@json:'{"ats_admin":true,"name":"Ann"}'` | `"[?ats_admin && name=='Ann']"` |
|
|
2124
|
+
| Negation, or | Ruby lambda (`@ruby:`) | `'[?!ats_admin]'`, or: see [Recipes](#recipes) |
|
|
2125
|
+
| Number comparison | Ruby lambda (`@ruby:`) | ``'[?size > `1000000`]'`` |
|
|
2126
|
+
| Substring | Ruby lambda (`@ruby:`) | ``'[?contains(email, `@example`)]'`` |
|
|
2127
|
+
| Choice of fields | With option `--out.fields` | `'[].{name: name, email: email}'` |
|
|
2128
|
+
| Count | Not possible | `'length(@)'` |
|
|
2129
|
+
|
|
2130
|
+
> [!WARNING]
|
|
2131
|
+
>
|
|
2132
|
+
> - 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.
|
|
2133
|
+
> - 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`.
|
|
2134
|
+
> - Secrets are hidden before `--out.query` is applied, so that the expression cannot reveal them.
|
|
2135
|
+
|
|
2136
|
+
##### Recipes
|
|
2137
|
+
|
|
2138
|
+
```shell
|
|
2139
|
+
# Users of Active Directory, with user name and email
|
|
2140
|
+
ascli shares admin user all list --out.query="[?directory_user.type=='active_directory'].{username: username, email: email}"
|
|
2141
|
+
# Users without directory (field missing or null)
|
|
2142
|
+
ascli shares admin user all list --out.query='[?directory_user == null].username'
|
|
2143
|
+
# Number of ATS administrators
|
|
2144
|
+
ascli aoc admin user list --out.query='length([?ats_admin])'
|
|
2145
|
+
# Users who are ATS administrators, or have no email
|
|
2146
|
+
ascli aoc admin user list --out.query='[?ats_admin || !email].name'
|
|
2147
|
+
# Emails of a domain, one per line
|
|
2148
|
+
ascli aoc admin user list --out.query='[?ends_with(email, `@example.com`)].email' --format=text
|
|
2149
|
+
# Largest file of a folder
|
|
2150
|
+
ascli node browse / --out.query='max_by([?type==`file`], &size).path'
|
|
2151
|
+
# Files larger than 1 MB
|
|
2152
|
+
ascli node browse / --out.query='[?size > `1000000`].{path: path, size: size}'
|
|
2153
|
+
# Files modified since a date
|
|
2154
|
+
ascli node browse / --out.query='[?mtime >= `"2025-06-01"`].path'
|
|
2155
|
+
```
|
|
2156
|
+
|
|
2157
|
+
> [!NOTE]
|
|
2158
|
+
> The JMESPath implementation of `ascli` (gem `jmespath`) also compares strings with `<`, `<=`, `>` and `>=`, which the JMESPath specification defines only for numbers.
|
|
2159
|
+
> Dates in ISO 8601 format, in the same time zone, are compared in chronological order.
|
|
2160
|
+
|
|
2161
|
+
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"))'`.
|
|
2162
|
+
|
|
2163
|
+
##### Other filters
|
|
2164
|
+
|
|
2165
|
+
Some commands provide their own filters:
|
|
2166
|
+
|
|
2167
|
+
- [Percent selector](#percent-selector) `%<field>:<value>`: selects a single resource by the value of one of its fields.
|
|
2168
|
+
- `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)).
|
|
2169
|
+
- `faspex5 packages list`: a Ruby lambda as last argument (see [Faspex 5: List packages](#faspex-5-list-packages)).
|
|
2170
|
+
- `console transfer`: query parameter `filter` (see [Transfer filter](#transfer-filter)).
|
|
2171
|
+
- `preview`: options `--filter` and `--skip-folders` (see [Candidate detection](#candidate-detection-for-creation-or-update-or-deletion)).
|
|
2172
|
+
|
|
2173
|
+
#### Option: `--out.format`
|
|
2174
|
+
|
|
2175
|
+
The style of output can be set using option `--out.format` (or `--format`):
|
|
1844
2176
|
|
|
1845
2177
|
| `format` | Output formatting |
|
|
1846
2178
|
| -------- | -------- |
|
|
@@ -1894,7 +2226,7 @@ ascli config echo @json:'[{"name":"foo","id":1},{"name":"bar","id":8}]' --format
|
|
|
1894
2226
|
|
|
1895
2227
|
This option controls how object fields are displayed for complex objects.
|
|
1896
2228
|
|
|
1897
|
-
Effective only when `format` is `table` to display `single_object` or `object_list`.
|
|
2229
|
+
Effective only when `format` is `table` or `csv` to display `single_object` or `object_list`.
|
|
1898
2230
|
|
|
1899
2231
|
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
2232
|
|
|
@@ -2076,110 +2408,59 @@ ascli config preset overview --out.colors=no --out.utf8=no
|
|
|
2076
2408
|
> [!NOTE]
|
|
2077
2409
|
> Logs issued before the option is processed (e.g. at startup) use the detected value.
|
|
2078
2410
|
|
|
2079
|
-
|
|
2411
|
+
### Polling: Option `poll`
|
|
2080
2412
|
|
|
2081
|
-
|
|
2082
|
-
It
|
|
2083
|
-
|
|
2084
|
-
The `fields` option is a list that can be either a comma-separated list or an [Extended Value](#extended-value-syntax) `Array`.
|
|
2413
|
+
Option `--poll` executes a read-only command several times, and displays its results, for example to wait for a state: a work order complete, a task waiting for a user, a package received.
|
|
2414
|
+
It replaces a shell loop with `sleep`: arguments are read once (identifiers looked up once), the command runs again in the same process.
|
|
2085
2415
|
|
|
2086
|
-
|
|
2416
|
+
Its value is a `Hash` (also with dot-notation, e.g. `--poll.interval=10`):
|
|
2087
2417
|
|
|
2088
|
-
|
|
2089
|
-
|
|
2090
|
-
|
|
2091
|
-
|
|
2092
|
-
|
|
2093
|
-
|
|
2094
|
-
|
|
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`]``.
|
|
2418
|
+
| Field | Type | Description |
|
|
2419
|
+
| -------- | -------------- | -------------------------------------------------------------------------------- |
|
|
2420
|
+
| `errors` | `Enum[String]` | What an error of a run does (e.g. an API error, an entity not found yet).<br/>- `fail`: the command ends with this error.<br/>- `retry`: the error is shown on the status line, and the command runs again, as for a result where `until` is false. If the last run fails, the command ends with its error.<br/>Allowed values: `fail`, `retry`.<br/>Default: `fail`. |
|
|
2421
|
+
| `interval` | `Number, String` | Time to wait after a run, before the next one. A duration: a number of seconds, or a `String`, e.g. `30s`, `2m`, `1h 30m`, `1d 02:00:00` (rounded down to seconds).<br/>Default: `5`. |
|
|
2422
|
+
| `max` | `Integer` | Maximum number of runs. No limit by default. |
|
|
2423
|
+
| `show` | `Enum[String]` | Which results are displayed.<br/>- `change`: the first result, then each result whose display differs from the previous one.<br/>- `each`: every result.<br/>- `last`: only the last result, when polling stops (including when the condition is not met).<br/>Allowed values: `change`, `each`, `last`.<br/>Default: `change`. |
|
|
2424
|
+
| `timeout` | `Number, String` | Maximum time since the start of the first run. A duration, as `interval`, e.g. `600`, `10m`, `1h`. A last run occurs at this time. No limit by default. With `max`, polling stops at the first limit reached. |
|
|
2425
|
+
| `until` | `String` | JMESPath expression (https://jmespath.org) evaluated on the JSON view of the result data: after `--select` (for a list of objects), before `--fields` and `--out.query`. Polling stops at the first run where it is true: as in JMESPath, `false`, `null`, empty string, empty list and empty object are false, other values are true. So `@` (the data itself) waits for a non-empty result, e.g. a list with at least one item. The syntax is checked before the first run. If the condition is not met after the last run (`max` or `timeout`), the command fails (exit code 1). |
|
|
2161
2426
|
|
|
2162
|
-
|
|
2163
|
-
It is refused at [Security Level](#security-level) `medium` and `high`.
|
|
2427
|
+
`interval` and `timeout` are durations: a number of seconds, or a `String` with units `w`, `d`, `h`, `m`, `s`, e.g. `30s`, `2m`, `1h 30m`, `1d 02:00:00`, as for the [HTTP socket parameters](#http-socket-parameters).
|
|
2164
2428
|
|
|
2165
2429
|
```shell
|
|
2166
|
-
#
|
|
2167
|
-
ascli
|
|
2430
|
+
# Wait for a work order to complete, check every 10 seconds, at most 30 times
|
|
2431
|
+
ascli orchestrator workorders status <WORKORDER_ID> --poll=@json:'{"interval":10,"max":30,"until":"status == `Complete`"}'
|
|
2432
|
+
# Same, with dot-notation, and a timeout of 10 minutes
|
|
2433
|
+
ascli orchestrator workorders status <WORKORDER_ID> --poll.interval=10s --poll.timeout=10m --poll.until='status == `Complete`'
|
|
2434
|
+
# Wait for a task waiting for a user (a non-empty list), display only the last result
|
|
2435
|
+
ascli orchestrator tasks list --poll=@json:'{"interval":5,"max":60,"until":"@","show":"last"}' --format=json
|
|
2436
|
+
# Display the status of the resources of a pool, each time it changes, until interrupted (Ctrl-C)
|
|
2437
|
+
ascli orchestrator pools status <POOL_NAME> --poll.interval=5
|
|
2168
2438
|
```
|
|
2169
2439
|
|
|
2170
|
-
|
|
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}`.
|
|
2440
|
+
Behavior:
|
|
2172
2441
|
|
|
2173
|
-
|
|
2174
|
-
|
|
2175
|
-
|
|
2442
|
+
- Polling stops at the first run where `until` is true, or after `max` runs, or at `timeout`.
|
|
2443
|
+
- Without `until`, the command runs `max` times (or until `timeout`, or until interrupted), and the exit status is success.
|
|
2444
|
+
- If `until` is not true after the last run, the command fails with `condition not met after <N> runs` (exit status `1`).
|
|
2445
|
+
- `until` is evaluated on the data of the result (as seen by `--out.query`: JSON values), after `--out.select`, before `--out.fields` and `--out.query`.
|
|
2446
|
+
Expression `@` is true for a non-empty result: e.g. a list with at least one item.
|
|
2447
|
+
- Options `--format`, `--out.fields`, `--out.select` and `--out.query` apply to each result displayed.
|
|
2448
|
+
With `show=change` (default), a result is displayed when its display differs from the previous one.
|
|
2449
|
+
- Before each result displayed, a status line on `stderr` gives the run number and the time, e.g. `poll: run 3/30 2026-01-02 10:20:30`.
|
|
2450
|
+
Output is flushed after each result: it can be read line by line by another program, e.g. with `--format=json` (one line per result).
|
|
2451
|
+
- An error of a run (e.g. an API error) ends the command with this error, unless `errors` is `retry`: then the run counts as one where `until` is false.
|
|
2452
|
+
- `Ctrl-C` ends polling: with `show=last`, the last result is displayed, and the exit status is `130`.
|
|
2453
|
+
|
|
2454
|
+
For safety, option `poll` is refused, before anything is executed, on a command that is not marked read-only: a command that creates, modifies, deletes, sends, starts or cancels something, e.g. `faspex5 packages send`.
|
|
2455
|
+
Commands named `list`, `show`, `status`, `info`, `health`, `ls`, `browse` and `find` are read-only (except `preview show`, which generates a preview file), and some others, e.g. `orchestrator workflows workorders`, `server du`, `node ssync state`.
|
|
2456
|
+
It is also refused with options `once_only` (state saved at each run) and `notify_to` (email sent at each run), with format `nagios`, and in [MCP server](#plugin-mcp-model-context-protocol-server) mode (the client calls the tool again instead).
|
|
2176
2457
|
|
|
2177
2458
|
### Exit status
|
|
2178
2459
|
|
|
2179
2460
|
The exit code of `ascli` indicates the category of error, so that scripts can react to it:
|
|
2180
2461
|
|
|
2181
2462
|
| Code | Description |
|
|
2182
|
-
|
|
2463
|
+
| ---- | -------------------------------------------------------------------------- |
|
|
2183
2464
|
| `0` | Success |
|
|
2184
2465
|
| `1` | Other error |
|
|
2185
2466
|
| `2` | Command line error: unknown command or option, invalid or missing argument |
|
|
@@ -2256,10 +2537,10 @@ The following decoders are supported:
|
|
|
2256
2537
|
| `stdin` | `String` | `String` | Read from stdin in text mode. Argument: `<empty>`, `bin` or `chomp`. |
|
|
2257
2538
|
| `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
2539
|
| `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
|
|
2540
|
+
| `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
2541
|
| `yaml` | `String` | Any | Decode YAML. |
|
|
2261
2542
|
| `zlib` | `String` | `String` | Decompress data using zlib. |
|
|
2262
|
-
| `<empty>`|
|
|
2543
|
+
| `<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
2544
|
|
|
2264
2545
|
> [!NOTE]
|
|
2265
2546
|
> A few commands support a value of type `Proc` (lambda expression).
|
|
@@ -2270,7 +2551,21 @@ The following decoders are supported:
|
|
|
2270
2551
|
To display the result of an [Extended Value](#extended-value-syntax), use the `config echo` command.
|
|
2271
2552
|
|
|
2272
2553
|
The `extend` decoder is useful to evaluate embedded [Extended Value](#extended-value-syntax) syntax in a string.
|
|
2273
|
-
It expects a `@` to close the embedded [Extended Value](#extended-value-syntax) syntax.
|
|
2554
|
+
It expects a `@` to close the embedded [Extended Value](#extended-value-syntax) syntax: `@vault:my_label.password@`.
|
|
2555
|
+
A value inserted by `extend` is not evaluated again: `@extend:@file:<PATH>@` inserts the content of the file as is.
|
|
2556
|
+
If the text on the right of `@extend:` is a single [Extended Value](#extended-value-syntax) without closing `@` (for example `@extend:@file:<PATH>`), it is decoded first, and embedded values in the result are then evaluated.
|
|
2557
|
+
|
|
2558
|
+
Example: a JSON file whose values are read from the [vault](#secret-vault):
|
|
2559
|
+
|
|
2560
|
+
```json
|
|
2561
|
+
{"title":"Report","recipients":["@vault:my_label.username@"]}
|
|
2562
|
+
```
|
|
2563
|
+
|
|
2564
|
+
```shell
|
|
2565
|
+
ascli config echo @json:@extend:@file:<PATH>
|
|
2566
|
+
```
|
|
2567
|
+
|
|
2568
|
+
In the file, an embedded value without closing `@` (`"@vault:my_label.username"`) is not evaluated: it stays a string, and `@json:@file:<PATH>` does not evaluate values inside the JSON.
|
|
2274
2569
|
|
|
2275
2570
|
Option `parser` allows definition of a default parser when the positional parameter or option expects a `Hash` or `Array`.
|
|
2276
2571
|
For example, with `--parser=json`, the parameter `{}` will be parsed as an empty JSON Hash, even without prefix `@json:`.
|
|
@@ -2550,7 +2845,6 @@ Adding `--show-config` to any command line performs a dry run and displays the r
|
|
|
2550
2845
|
To display a specific option, add `--fields=<option_name>`.
|
|
2551
2846
|
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
2847
|
|
|
2553
|
-
|
|
2554
2848
|
```shell
|
|
2555
2849
|
ascli --opt=@json:'{"a":1,"b":"two"}' some_plugin --show-config --fields=opt --out.flat=no
|
|
2556
2850
|
ascli --opt.a=1 --opt.b=two some_plugin --show-config --fields=opt --out.flat=no
|
|
@@ -2588,18 +2882,51 @@ It is a `Hash` with the following keys:
|
|
|
2588
2882
|
|-----|-----|-----|-----|
|
|
2589
2883
|
| `level` | `string` | `low` | `low`, `medium`, or `high` |
|
|
2590
2884
|
| `allowed_paths` | `Array<string>` | - | With level `medium`: files and folders that `@file:` can read |
|
|
2885
|
+
| `writable_paths` | `Array<string>` | - | With levels `medium` and `high`: folders where files can be written |
|
|
2591
2886
|
|
|
2592
|
-
| Level | `@file:` | `@ruby:`, `@uri:`, and `@
|
|
2593
|
-
|
|
2594
|
-
| `low` | Allowed | Allowed | Allowed |
|
|
2595
|
-
| `medium` | Only files in `allowed_paths` | Refused | Refused |
|
|
2596
|
-
| `high` | Refused | Refused | Refused |
|
|
2887
|
+
| Level | `@file:` | `@ruby:`, `@uri:`, `@env:`, and `@zlib:` | Secret processed by another extended value | Write files | Features that execute code |
|
|
2888
|
+
|---|---|---|---|---|---|
|
|
2889
|
+
| `low` | Allowed | Allowed | Allowed | Allowed | Allowed |
|
|
2890
|
+
| `medium` | Only files in `allowed_paths` | Refused | Refused | Only in `writable_paths` | Refused |
|
|
2891
|
+
| `high` | Refused | Refused | Refused | Only in `writable_paths` | Refused |
|
|
2597
2892
|
|
|
2598
2893
|
With level `medium`, the real path of the file is checked: a symbolic link leading outside of `allowed_paths` is refused.
|
|
2599
2894
|
|
|
2895
|
+
`@zlib:` is refused with levels `medium` and `high`: a small value can decompress to gigabytes and exhaust the memory of the system.
|
|
2896
|
+
|
|
2897
|
+
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.
|
|
2898
|
+
The real path of the folder is checked: neither `..` nor a symbolic link leading outside of `writable_paths` is accepted.
|
|
2899
|
+
|
|
2900
|
+
> [!NOTE]
|
|
2901
|
+
> Reading files is not restricted for transfers: a command that sends files (for example `server upload`, or `orchestrator workflows import`) reads the files that it is given, whatever the level.
|
|
2902
|
+
> The security level restricts extended values, not the paths of transfers.
|
|
2903
|
+
> A command that reads a local file to display something about its content (for example `orchestrator workflows check_import`) reads it as `@file:`.
|
|
2904
|
+
|
|
2905
|
+
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.
|
|
2906
|
+
|
|
2600
2907
|
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
2908
|
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
2909
|
|
|
2910
|
+
Features that execute code (own, or downloaded), load code, or write a file chosen by the client, are available only at level `low`:
|
|
2911
|
+
|
|
2912
|
+
| Feature | Why |
|
|
2913
|
+
|---|---|
|
|
2914
|
+
| Option `notify_template` | ERB template: Ruby code |
|
|
2915
|
+
| Option `fpac` | Proxy auto configuration: JavaScript code |
|
|
2916
|
+
| Option `ui`, key `command` | Command executed to open a URL |
|
|
2917
|
+
| Options `sdk_url` and `locations_url` | The SDK, including `ascp`, is downloaded from this location, then executed |
|
|
2918
|
+
| Option `out`, key `file` (and `output`), option `pid_file` | Write (or truncate, or delete) a file chosen by the client |
|
|
2919
|
+
| Option `home` | Configuration folder: its presets, and its folder `plugins` (Ruby code) are used |
|
|
2920
|
+
| Option `plugin_folder` | Plugins are Ruby code |
|
|
2921
|
+
| 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 |
|
|
2922
|
+
| Command `config plugins create` | Creates Ruby code, loaded as a plugin |
|
|
2923
|
+
| Command `faspex5 postprocessing` | Executes scripts, or Ruby code |
|
|
2924
|
+
|
|
2925
|
+
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`.
|
|
2926
|
+
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.
|
|
2927
|
+
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`.
|
|
2928
|
+
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:...`).
|
|
2929
|
+
|
|
2603
2930
|
Options are evaluated in the order of the command line: place `--security` before options that use extended values.
|
|
2604
2931
|
|
|
2605
2932
|
```shell
|
|
@@ -2607,7 +2934,7 @@ ascli config echo @file:/etc/hosts --security.level=high
|
|
|
2607
2934
|
```
|
|
2608
2935
|
|
|
2609
2936
|
```text
|
|
2610
|
-
ERRR Argument: Evaluation of file for argument: value: @file: extended value is disabled by security level high
|
|
2937
|
+
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
2938
|
```
|
|
2612
2939
|
|
|
2613
2940
|
### Main, configuration and Persistency Folder
|
|
@@ -2740,61 +3067,56 @@ An [Option Preset](#option-preset) is a collection of options and their associat
|
|
|
2740
3067
|
A named [Option Preset](#option-preset) can be modified directly using `ascli`, which will update the configuration file:
|
|
2741
3068
|
|
|
2742
3069
|
```text
|
|
2743
|
-
ascli config preset <show|delete|get|
|
|
3070
|
+
ascli config preset <show|delete|get|set|ask> <PRESET_NAME> ...
|
|
2744
3071
|
```
|
|
2745
3072
|
|
|
2746
3073
|
The syntax of all `config preset` commands, including `list` and `overview`, is displayed with `ascli config commands config preset`.
|
|
2747
3074
|
|
|
2748
|
-
The command `
|
|
3075
|
+
The command `set` merges values into the configuration, at one of three levels, depending on its arguments:
|
|
2749
3076
|
|
|
2750
|
-
|
|
2751
|
-
|
|
2752
|
-
|
|
2753
|
-
|
|
2754
|
-
One
|
|
2755
|
-
|
|
2756
|
-
```shell
|
|
2757
|
-
ascli config preset initialize demo_server @: url=ssh://demo.asperasoft.com:33001 username=asperaweb password=<PASSWORD> ts.precalculate_job_size=true
|
|
2758
|
-
```
|
|
3077
|
+
| Arguments | Merged into | Example |
|
|
3078
|
+
| --------- | ----------- | ------- |
|
|
3079
|
+
| `<Hash>` | Presets, by name | `ascli config preset set @: demo_server.url=ssh://demo.asperasoft.com:33001 default.server=demo_server` |
|
|
3080
|
+
| `<preset_name> <Hash>` | Parameters of a preset | `ascli config preset set demo_server @: url=ssh://demo.asperasoft.com:33001 username=asperaweb` |
|
|
3081
|
+
| `<preset_name> <parameter_name> <value>` | One parameter of a preset | `ascli config preset set demo_server password <PASSWORD>` |
|
|
2759
3082
|
|
|
2760
|
-
The
|
|
3083
|
+
The `Hash` is usually given with [dot-path](#positional-arguments-with-dot-path) (`@:`), or with `@json:`.
|
|
3084
|
+
Parameters have the names of options, without `--`, for example:
|
|
2761
3085
|
|
|
2762
3086
|
```shell
|
|
2763
|
-
ascli config preset
|
|
3087
|
+
ascli config preset set demo_server @: url=ssh://demo.asperasoft.com:33001 username=asperaweb password=<PASSWORD> ts.precalculate_job_size=true
|
|
3088
|
+
ascli config preset set demo_server @json:'{"url":"ssh://demo.asperasoft.com:33001","username":"asperaweb","password":"<PASSWORD>","ts":{"precalculate_job_size":true}}'
|
|
2764
3089
|
```
|
|
2765
3090
|
|
|
2766
|
-
|
|
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
|
-
```
|
|
3091
|
+
A preset is created if needed.
|
|
3092
|
+
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`.
|
|
2776
3093
|
|
|
2777
|
-
|
|
3094
|
+
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
3095
|
|
|
2779
3096
|
```shell
|
|
2780
|
-
ascli config preset set
|
|
3097
|
+
ascli config preset set GLOBAL out.table.pivot @none:
|
|
3098
|
+
ascli config preset set demo_server @: username=@none: ts.precalculate_job_size=@none:
|
|
3099
|
+
ascli config preset set @: demo_server=@none:
|
|
2781
3100
|
```
|
|
2782
3101
|
|
|
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).
|
|
3102
|
+
The parameter name of the third form supports **dot-notation** to set nested hash options:
|
|
2785
3103
|
|
|
2786
3104
|
```shell
|
|
2787
3105
|
ascli config preset set GLOBAL out.table.pivot single
|
|
2788
3106
|
ascli config preset set GLOBAL out.level data
|
|
2789
3107
|
```
|
|
2790
3108
|
|
|
2791
|
-
|
|
3109
|
+
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
3110
|
|
|
2793
|
-
|
|
3111
|
+
Options of the command line are not saved in the preset: they apply to the command `set` itself (for example `--log-level`).
|
|
3112
|
+
The section `config` of the configuration file cannot be changed.
|
|
2794
3113
|
|
|
2795
|
-
|
|
2796
|
-
|
|
2797
|
-
|
|
3114
|
+
> [!NOTE]
|
|
3115
|
+
> Commands `update`, `initialize` and `unset` are deprecated, and show the command to use instead:
|
|
3116
|
+
>
|
|
3117
|
+
> - `update <preset_name> --url=...` is replaced by `set <preset_name> @: url=...`. It takes only the options placed after `update`.
|
|
3118
|
+
> - `initialize <preset_name> <Hash>`, which replaces a preset, is replaced by `delete <preset_name>`, then `set <preset_name> <Hash>`.
|
|
3119
|
+
> - `unset <preset_name> <parameter_name>` is replaced by `set <preset_name> <parameter_name> @none:`.
|
|
2798
3120
|
|
|
2799
3121
|
A full terminal based overview of the configuration can be displayed using:
|
|
2800
3122
|
|
|
@@ -2822,6 +3144,10 @@ demo_server:
|
|
|
2822
3144
|
> [!NOTE]
|
|
2823
3145
|
> Comment keys are preserved and visible in `config preset overview` for inspection, but are never injected as CLI options.
|
|
2824
3146
|
|
|
3147
|
+
By convention, `_comment` holds a short description of the preset.
|
|
3148
|
+
The [shell completion](#shell-completion) of preset names (e.g. `-P <tab>`) shows it next to each name.
|
|
3149
|
+
The wizard sets it for the presets it creates: `_comment: "wizard: <application>"`.
|
|
3150
|
+
|
|
2825
3151
|
A good practice is to not manually edit the configuration file and use modification commands instead.
|
|
2826
3152
|
If necessary, the configuration file can be opened in a text editor with:
|
|
2827
3153
|
|
|
@@ -2894,10 +3220,10 @@ Some temporary files may be needed during runtime, for example the file list of
|
|
|
2894
3220
|
The composite option `temp` (use `--temp=help` to display this schema) controls them:
|
|
2895
3221
|
|
|
2896
3222
|
| Field | Type | Description |
|
|
2897
|
-
|
|
3223
|
+
| ------ | -------------------- | -------------------------------------------------------------------------------- |
|
|
2898
3224
|
| `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
3225
|
| `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
|
|
3226
|
+
| `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
3227
|
|
|
2902
3228
|
A plain value is the `folder`, for example: `--temp=/data/tmp`.
|
|
2903
3229
|
|
|
@@ -2918,7 +3244,7 @@ Plugin `config` provides general commands for `ascli`:
|
|
|
2918
3244
|
- `wizard`
|
|
2919
3245
|
- `vault`
|
|
2920
3246
|
- `ascp`
|
|
2921
|
-
- `transferd`
|
|
3247
|
+
- `transferd` (deprecated, use plugin [`transferd`](#plugin-transferd-transfer-daemon))
|
|
2922
3248
|
|
|
2923
3249
|
The default preset for `config` is read for any plugin invocation: this allows setting global options, such as `--log-level` or `--interactive`.
|
|
2924
3250
|
When `ascli` starts, it looks for the `default` Option Preset and checks the value for `config`.
|
|
@@ -2960,6 +3286,9 @@ ascli config preset set GLOBAL version_check_days 0
|
|
|
2960
3286
|
> Add `ascli config` in front of the following commands:
|
|
2961
3287
|
|
|
2962
3288
|
```shell
|
|
3289
|
+
agents jobs cleanup
|
|
3290
|
+
agents jobs list
|
|
3291
|
+
agents jobs status <CONF_ASYNC_NODE_UPLOAD>
|
|
2963
3292
|
agents list
|
|
2964
3293
|
agents parameters connect
|
|
2965
3294
|
agents parameters direct
|
|
@@ -2968,9 +3297,6 @@ agents show connect
|
|
|
2968
3297
|
agents show direct
|
|
2969
3298
|
ascp errors
|
|
2970
3299
|
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
3300
|
ascp products list
|
|
2975
3301
|
ascp schema --format=jsonpp
|
|
2976
3302
|
ascp show
|
|
@@ -2985,15 +3311,15 @@ commands
|
|
|
2985
3311
|
commands aoc --expand-mounts=yes
|
|
2986
3312
|
commands aoc files
|
|
2987
3313
|
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://
|
|
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
|
|
3314
|
+
detect @: url=app.example.com
|
|
3315
|
+
detect @: url=https://f5.example.com/path
|
|
3316
|
+
detect @: url=https://f5.example.com/path plugin=faspex5
|
|
3317
|
+
detect @: url=https://node.example.com/path
|
|
3318
|
+
detect @: url=https://server1.example.com/path
|
|
3319
|
+
detect @: url=https://shares.example.com/path plugin=shares
|
|
3320
|
+
detect @: url=https://tst.example.com/path plugin=faspio
|
|
3321
|
+
detect @: url=https://tst.example.com/path plugin=httpgw
|
|
3322
|
+
detect @: url=my_org plugin=aoc
|
|
2997
3323
|
doc
|
|
2998
3324
|
doc github transfer-parameters
|
|
2999
3325
|
doc local quick-start --ui=text
|
|
@@ -3041,49 +3367,50 @@ options server --select=@json:'{"option":"--display"}' --fields=replacement
|
|
|
3041
3367
|
plugins create my_command .
|
|
3042
3368
|
plugins list
|
|
3043
3369
|
preset delete conf_name
|
|
3044
|
-
preset initialize conf_name @json:'{"p1":"v1","p2":"v2"}'
|
|
3045
3370
|
preset list
|
|
3046
3371
|
preset overview
|
|
3372
|
+
preset set @: conf_name.p4=v4 conf_name_other.p1=v1
|
|
3373
|
+
preset set @: conf_name_other=@none:
|
|
3047
3374
|
preset set GLOBAL sdk_folder 'product:IBM Aspera Connect'
|
|
3048
|
-
preset set GLOBAL vault @: type=file
|
|
3375
|
+
preset set GLOBAL vault @: default=local stores.local.type=file stores.local.file=/secure/vault_file
|
|
3049
3376
|
preset set GLOBAL vault_password <PASSWORD>
|
|
3050
3377
|
preset set GLOBAL version_check_days 0
|
|
3378
|
+
preset set conf_name @: p1=@none: p2.sub=v2 p3=v3
|
|
3379
|
+
preset set conf_name param @none:
|
|
3051
3380
|
preset set conf_name param value
|
|
3052
3381
|
preset set default shares conf_name
|
|
3053
3382
|
preset show conf_name
|
|
3054
|
-
preset unset conf_name param
|
|
3055
|
-
preset update conf_name --p1=v1 --p2=v2
|
|
3056
3383
|
proxy_check --fpac=@file:proxy.pac https://eudemo.asperademo.com --proxy-credentials=@list:,user,pass
|
|
3057
3384
|
pubkey @file:my_key
|
|
3058
3385
|
remote_certificate chain https://node.example.com/path
|
|
3059
3386
|
remote_certificate name https://node.example.com/path
|
|
3060
3387
|
remote_certificate only https://node.example.com/path
|
|
3388
|
+
skill
|
|
3061
3389
|
smtp_settings
|
|
3062
3390
|
sync spec
|
|
3063
3391
|
tokens flush
|
|
3064
3392
|
tokens list
|
|
3065
|
-
|
|
3066
|
-
transfer list
|
|
3067
|
-
transfer status <conf_async_node_upload>
|
|
3068
|
-
transferd install
|
|
3069
|
-
transferd list
|
|
3393
|
+
vault check @vault://local/my_label
|
|
3070
3394
|
vault create @: label=my_label password=<PASSWORD> 'description=my secret'
|
|
3071
3395
|
vault delete foo --vault.type=system
|
|
3072
3396
|
vault delete my_label
|
|
3397
|
+
vault field my_label
|
|
3073
3398
|
vault ids
|
|
3074
3399
|
vault info
|
|
3075
3400
|
vault list
|
|
3401
|
+
vault overview
|
|
3076
3402
|
vault show my_label
|
|
3077
|
-
wizard https://console.example.com/path console
|
|
3078
|
-
wizard https://f5.example.com/path faspex5 --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://
|
|
3082
|
-
wizard https://shares.example.com/path shares --username=test --password=<PASSWORD>
|
|
3083
|
-
wizard https://tst.example.com/path faspio
|
|
3084
|
-
wizard https://tst.example.com/path httpgw
|
|
3085
|
-
wizard my_org aoc
|
|
3086
|
-
wizard my_org aoc
|
|
3403
|
+
wizard @: url=https://console.example.com/path plugin=console override=yes --username=my_username --password=<PASSWORD>
|
|
3404
|
+
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>
|
|
3405
|
+
wizard @: url=https://node.example.com/path plugin=node override=yes --username=test --password=<PASSWORD>
|
|
3406
|
+
wizard @: url=https://orch.example.com/path plugin=orchestrator override=yes --username=test --password=<PASSWORD>
|
|
3407
|
+
wizard @: url=https://server1.example.com/path plugin=server override=yes --username=my_username --password=<PASSWORD>
|
|
3408
|
+
wizard @: url=https://shares.example.com/path plugin=shares override=yes --username=test --password=<PASSWORD>
|
|
3409
|
+
wizard @: url=https://tst.example.com/path plugin=faspio override=yes --username=my_username --password=<PASSWORD>
|
|
3410
|
+
wizard @: url=https://tst.example.com/path plugin=httpgw override=yes
|
|
3411
|
+
wizard @: url=my_org plugin=aoc override=yes --username=my_user_email --private-key=@file:<PRIVATE_KEY_FILE> --use-generic-client=no --interactive=yes
|
|
3412
|
+
wizard @: url=my_org plugin=aoc override=yes --username=my_user_email --private-key=@file:<PRIVATE_KEY_FILE> --use-generic-client=yes
|
|
3413
|
+
wizard @: url=my_org plugin=aoc preset=my_aoc_preset override=yes --username=my_user_email --private-key=@file:<PRIVATE_KEY_FILE>
|
|
3087
3414
|
```
|
|
3088
3415
|
|
|
3089
3416
|
#### Evaluation order of options
|
|
@@ -3117,10 +3444,10 @@ ascli config preset set cli_default interactive no
|
|
|
3117
3444
|
ascli config preset set default config cli_default
|
|
3118
3445
|
```
|
|
3119
3446
|
|
|
3120
|
-
An [Option Preset](#option-preset) value can be removed with
|
|
3447
|
+
An [Option Preset](#option-preset) value can be removed with `@none:`:
|
|
3121
3448
|
|
|
3122
3449
|
```shell
|
|
3123
|
-
ascli config preset
|
|
3450
|
+
ascli config preset set cli_default interactive @none:
|
|
3124
3451
|
```
|
|
3125
3452
|
|
|
3126
3453
|
Example: Define options using command line:
|
|
@@ -3140,6 +3467,9 @@ ascli -N --preset=@json:'{"url":"<URL>","password":"<PASSWORD>","username":"<USE
|
|
|
3140
3467
|
`ascli` supports shell tab-completion for **Bash**, **Zsh**, **Fish**, and **PowerShell** (Windows PowerShell 5.1 and PowerShell 7, on any OS).
|
|
3141
3468
|
The command `ascli config completion <shell>` displays the completion script for the given shell.
|
|
3142
3469
|
|
|
3470
|
+
The default shell is Zsh on macOS, Bash on most Linux distributions, and PowerShell on Windows (its prompt starts with `PS`).
|
|
3471
|
+
In Bash and Zsh, `echo $0` displays the name of the running shell.
|
|
3472
|
+
|
|
3143
3473
|
To activate completion, add the line for your shell to its startup file:
|
|
3144
3474
|
|
|
3145
3475
|
```bash
|
|
@@ -3185,26 +3515,40 @@ In PowerShell, the words proposed are kept for the session, so only the first `T
|
|
|
3185
3515
|
|
|
3186
3516
|
Once active, press `Tab` to complete:
|
|
3187
3517
|
|
|
3188
|
-
|
|
3189
3518
|
```bash
|
|
3190
3519
|
ascli <Tab> # plugins and global options: aoc, server, node, ..., --format, ...
|
|
3191
3520
|
ascli server <Tab> # sub-commands and options of plugin: upload, download, ls, ..., --url, ...
|
|
3192
3521
|
ascli aoc admin <Tab> # sub-commands at any depth: user, node, ...
|
|
3193
3522
|
ascli server ls --u<Tab> # options, after any command: --url, --username, ...
|
|
3194
3523
|
ascli --format=<Tab> # values of option: --format=json, --format=table, ...
|
|
3195
|
-
ascli --ts.<Tab> # keys of option, from its schema: --ts.direction
|
|
3524
|
+
ascli --ts.<Tab> # keys of option, from its schema: --ts.direction=, --ts.target_rate_kbps=, ...
|
|
3525
|
+
ascli --out.t<Tab> # a sub-structure is followed by a dot: --out.table.
|
|
3196
3526
|
ascli --ts.direction=<Tab> # values of key: --ts.direction=send, --ts.direction=receive
|
|
3527
|
+
ascli --transfer=<Tab> # plain value of option, key agent: --transfer=direct, --transfer=node, ...
|
|
3528
|
+
ascli faspex5 admin accounts list --query.<Tab> # keys of --query, from the command: --query.limit=, ...
|
|
3197
3529
|
ascli server upload <Tab> # local files
|
|
3198
|
-
ascli
|
|
3530
|
+
ascli server download --to-folder <Tab> # local folders
|
|
3531
|
+
ascli config genkey <Tab> # local files, where a local path is expected
|
|
3532
|
+
ascli --temp.folder=<Tab> # local folders, for a key of option
|
|
3533
|
+
ascli --ts=@<Tab> # extended value modifiers: @json:, @file:, @preset:, @:, ...
|
|
3534
|
+
ascli --private-key=@file:<Tab> # local files, after @file: or @path:
|
|
3535
|
+
ascli -P <Tab> # presets: also for config preset show, @preset:
|
|
3536
|
+
ascli config preset get myconf <Tab> # parameters of preset: url, username, ...
|
|
3537
|
+
ascli config agents jobs status <Tab> # asynchronous transfer jobs
|
|
3538
|
+
ascli node access_keys do <Tab> # type of expected value, not inserted: <identifier>
|
|
3199
3539
|
ascli aoc packages send <Tab> # type, and keys of structure (required ones with *): <Hash> name*, workspace_id*, ...
|
|
3200
|
-
ascli aoc packages send @:
|
|
3540
|
+
ascli aoc packages send @: <Tab> # keys of structure built with @:, from its schema: name=, workspace_id=, recipients.0., ...
|
|
3541
|
+
ascli aoc packages send @: archived=<Tab> # values of key: archived=true, archived=false
|
|
3542
|
+
ascli aoc packages send @: name=x <Tab> # end marker of structure built with @: END, and the other keys
|
|
3201
3543
|
```
|
|
3202
3544
|
|
|
3203
|
-
|
|
3545
|
+
No space is inserted after a word that continues: `key=`, `key.`, `@file:`, or a folder (Bash 4 and later).
|
|
3546
|
+
Zsh, Fish and PowerShell also display the description of commands, options, keys and extended value modifiers.
|
|
3547
|
+
In PowerShell, a word starting with `@` is inserted with quotes (e.g. `'@file:README.md'`), as required by PowerShell.
|
|
3204
3548
|
Zsh lists options once `-` is typed (zsh style `prefix-needed`).
|
|
3205
3549
|
The type of an expected value is displayed by Bash and Zsh, and by PowerShell in the list of `MenuComplete` (`Ctrl+Space`).
|
|
3206
3550
|
|
|
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.
|
|
3551
|
+
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
3552
|
The words are not evaluated (e.g. `@env:` is not replaced).
|
|
3209
3553
|
The command `ascli config completion words [<word>...]` lists the words that can follow the given ones.
|
|
3210
3554
|
It can be used directly to inspect available commands:
|
|
@@ -3217,32 +3561,36 @@ ascli config completion words aoc admin
|
|
|
3217
3561
|
|
|
3218
3562
|
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
3563
|
|
|
3220
|
-
It takes
|
|
3564
|
+
It takes one optional argument: a `Hash`, usually given with [`@:`](#positional-arguments-with-dot-path) as `key=value` items, in any order:
|
|
3221
3565
|
|
|
3222
|
-
|
|
3223
|
-
|
|
3224
|
-
|
|
|
3225
|
-
|
|
|
3226
|
-
|
|
|
3566
|
+
| Key | Description | If not provided, `ascli` |
|
|
3567
|
+
|------------|---------------------------------------------------------------------------------|--------------------------------------------|
|
|
3568
|
+
| `url` | **URL** or hostname of the application | asks for it. |
|
|
3569
|
+
| `plugin` | The **plugin name** to limit search to | tries to detect known plugins from the URL |
|
|
3570
|
+
| `preset` | The **preset name** to save in config file | generates a unique preset name |
|
|
3571
|
+
| `default` | Set the preset as default configuration for the plugin (`yes`/`no`) | `yes` |
|
|
3572
|
+
| `override` | Override the existing default preset of the plugin, if it exists (`yes`/`no`) | `no` |
|
|
3227
3573
|
|
|
3228
|
-
Options
|
|
3574
|
+
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.
|
|
3575
|
+
Options that the wizard needs, but that are not provided, are asked.
|
|
3576
|
+
An unknown key in the `Hash` is refused.
|
|
3229
3577
|
|
|
3230
|
-
|
|
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. |
|
|
3578
|
+
For example:
|
|
3235
3579
|
|
|
3236
|
-
|
|
3237
|
-
|
|
3580
|
+
```shell
|
|
3581
|
+
ascli config wizard @: url=<URL> plugin=<PLUGIN> preset=<PRESET>
|
|
3582
|
+
```
|
|
3583
|
+
|
|
3584
|
+
The command `config detect` takes the same argument, with keys `url` and `plugin`, and shows the detected applications, without creating a preset.
|
|
3585
|
+
Use `ascli config wizard help` to show the schema of the argument.
|
|
3238
3586
|
|
|
3239
|
-
The simplest invocation is:
|
|
3587
|
+
The simplest invocation (without argument: the URL is asked) is:
|
|
3240
3588
|
|
|
3241
3589
|
```shell
|
|
3242
3590
|
ascli config wizard
|
|
3243
3591
|
```
|
|
3244
3592
|
|
|
3245
|
-
If the application requires a private key, the user can provide the path
|
|
3593
|
+
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
3594
|
The user is told where to place the associated public key PEM in the application.
|
|
3247
3595
|
|
|
3248
3596
|
#### Example of configuration for a plugin
|
|
@@ -3268,13 +3616,13 @@ ascli config preset set shares06 password <PASSWORD>
|
|
|
3268
3616
|
This can also be done with one single command:
|
|
3269
3617
|
|
|
3270
3618
|
```shell
|
|
3271
|
-
ascli config preset
|
|
3619
|
+
ascli config preset set shares06 @json:'{"url":"https://10.25.0.6","username":"john","password":"<PASSWORD>"}'
|
|
3272
3620
|
```
|
|
3273
3621
|
|
|
3274
3622
|
Or:
|
|
3275
3623
|
|
|
3276
3624
|
```shell
|
|
3277
|
-
ascli config preset
|
|
3625
|
+
ascli config preset set shares06 @: url=https://10.25.0.6 username=john password=<PASSWORD>
|
|
3278
3626
|
```
|
|
3279
3627
|
|
|
3280
3628
|
- Define this [Option Preset](#option-preset) as the default [Option Preset](#option-preset) for the specified plugin (`shares`)
|
|
@@ -3326,7 +3674,71 @@ export ASCLI_PASSWORD
|
|
|
3326
3674
|
|
|
3327
3675
|
Another possibility is to retrieve values from a secret vault.
|
|
3328
3676
|
|
|
3329
|
-
|
|
3677
|
+
Option `vault` declares named secret stores (`stores`), and the name of the default store (`default`):
|
|
3678
|
+
|
|
3679
|
+
- `@vault:<label>.<field>` reads field `<field>` of secret `<label>` of the default store, managed with command `config vault` (see [Vault: Operations](#vault-operations)).
|
|
3680
|
+
- `@vault://<store>/<path>[?<options>][#<field>]` reads a secret of any store (see [Vault: Secret references](#vault-secret-references)).
|
|
3681
|
+
|
|
3682
|
+
| Field | Type | Description |
|
|
3683
|
+
| --------- | ------ | -------------------------------------------------------------------------------- |
|
|
3684
|
+
| `cache_ttl` | `Number` | Time in seconds a value read by reference is kept in memory, `0` for no cache.<br/>Default: `60`. |
|
|
3685
|
+
| `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. |
|
|
3686
|
+
| `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. |
|
|
3687
|
+
|
|
3688
|
+
For example, to use as default store an encrypted file `vault.bin` in the configuration folder (see [Vault: Encrypted file](#vault-encrypted-file)):
|
|
3689
|
+
|
|
3690
|
+
```shell
|
|
3691
|
+
ascli config preset set GLOBAL vault @json:'{"default":"local","stores":{"local":{"type":"file","file":"vault.bin"}}}'
|
|
3692
|
+
```
|
|
3693
|
+
|
|
3694
|
+
Parameters of a store, with `type` (see sections below):
|
|
3695
|
+
|
|
3696
|
+
| Field | Type | Description |
|
|
3697
|
+
| ----------------- | ------------- | -------------------------------------------------------------------------------- |
|
|
3698
|
+
| **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 `/`). |
|
|
3699
|
+
| `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. |
|
|
3700
|
+
| `approle` | `Hash` | AppRole authentication: the token is obtained by login, renewed, and obtained again when refused. |
|
|
3701
|
+
| `approle.mount` | `String` | Mount path of the AppRole auth method.<br/>Default: `approle`. |
|
|
3702
|
+
| `approle.role_id` | `String` | Role ID.<br/>Required. |
|
|
3703
|
+
| `approle.secret_id` | `String` | Secret ID (if the role requires one): the value, or `@file:<path>`. |
|
|
3704
|
+
| `ca_file` | `String` | File with the CA certificates that verify the certificate of the server (HTTPS). |
|
|
3705
|
+
| `namespace` | `String` | Namespace (Vault Enterprise). |
|
|
3706
|
+
| `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>`. |
|
|
3707
|
+
| `type` | `Enum[String]` | Vault type selector.<br/>Required.<br/>Allowed values: `vault`. |
|
|
3708
|
+
| `url` | `String` | URL of the HashiCorp Vault server.<br/>Required.<br/>Example: `http://127.0.0.1:8200`. |
|
|
3709
|
+
| **type** | `String` | `system`: macOS system keychain secret store. |
|
|
3710
|
+
| `name` | `String` | Name of the keychain to use (file `<name>.keychain-db` in the keychain search list).<br/>Default: `ascli`. |
|
|
3711
|
+
| `type` | `Enum[String]` | Vault type selector.<br/>Required.<br/>Allowed values: `system`. |
|
|
3712
|
+
| **type** | `String` | `secret_service`: Linux Secret Service secret store (GNOME Keyring, KWallet, KeePassXC...), using `secret-tool`. |
|
|
3713
|
+
| `name` | `String` | Name of the group of secrets (attribute `service` of the items).<br/>Default: `ascli`. |
|
|
3714
|
+
| `type` | `Enum[String]` | Vault type selector.<br/>Required.<br/>Allowed values: `secret_service`. |
|
|
3715
|
+
| **type** | `String` | `file`: Encrypted file secret store. Reference `@vault://<store>/<label>[#<field>]`, field `password` by default. |
|
|
3716
|
+
| `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`. |
|
|
3717
|
+
| `name` | `String` | Same as `file` (compatibility). |
|
|
3718
|
+
| `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`. |
|
|
3719
|
+
| `type` | `Enum[String]` | Vault type selector.<br/>Required.<br/>Allowed values: `file`. |
|
|
3720
|
+
| **type** | `String` | `1password`: 1Password secret store (Connect REST API or CLI). |
|
|
3721
|
+
| `account` | `String` | Account shorthand for `op` (used when `source` is `cli`). Uses the default account if omitted. |
|
|
3722
|
+
| `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`. |
|
|
3723
|
+
| `token` | `String` | Bearer token for the Connect API (required when `source` is `api`). For the default store, defaults to the value of `vault_password`. |
|
|
3724
|
+
| `type` | `Enum[String]` | Vault type selector.<br/>Required.<br/>Allowed values: `1password`. |
|
|
3725
|
+
| `url` | `String` | Base URL of the 1Password Connect server (required when `source` is `api`).<br/>Example: `http://localhost:8080`. |
|
|
3726
|
+
| `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. |
|
|
3727
|
+
| `vault_id` | `String` | ID of the 1Password vault to use (required when `source` is `api`). |
|
|
3728
|
+
| **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`. |
|
|
3729
|
+
| `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`. |
|
|
3730
|
+
| `folder_uid` | `String` | UID of the shared folder where `config vault create` adds records (not needed to read). |
|
|
3731
|
+
| `type` | `Enum[String]` | Vault type selector.<br/>Required.<br/>Allowed values: `keeper`. |
|
|
3732
|
+
|
|
3733
|
+
> [!NOTE]
|
|
3734
|
+
> 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.
|
|
3735
|
+
> Set the store in `stores`, and its name in `default` instead: `{"default":"local","stores":{"local":{"type":"file","file":"vault.bin"}}}`.
|
|
3736
|
+
|
|
3737
|
+
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.
|
|
3738
|
+
As for extended value `@file:`, reading the file is restricted by option `security` (see [Security Level](#security-level)).
|
|
3739
|
+
In a YAML file, quote the value: `@` cannot start a plain scalar.
|
|
3740
|
+
|
|
3741
|
+
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
3742
|
To avoid exposing the vault password in the shell history, provide it via an environment variable:
|
|
3331
3743
|
|
|
3332
3744
|
```shell
|
|
@@ -3352,29 +3764,20 @@ brew install hashicorp/tap/vault
|
|
|
3352
3764
|
vault server -dev -dev-root-token-id=<TOKEN>
|
|
3353
3765
|
```
|
|
3354
3766
|
|
|
3355
|
-
|
|
3356
|
-
|
|
3357
|
-
|
|
3358
|
-
|
|
3359
|
-
|
|
3360
|
-
|
|
3361
|
-
|
|
3362
|
-
|
|
3363
|
-
|
|
3364
|
-
|
|
3365
|
-
|
|
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. |
|
|
3767
|
+
```shell
|
|
3768
|
+
--vault=@json:'{"default":"corp","stores":{"corp":{"type":"vault","url":"http://127.0.0.1:8200"}}}' --vault-password=<TOKEN>
|
|
3769
|
+
```
|
|
3770
|
+
|
|
3771
|
+
With a token in a file (for example, written and renewed by Vault Agent), read again when the file is modified:
|
|
3772
|
+
|
|
3773
|
+
```shell
|
|
3774
|
+
--vault=@json:'{"default":"corp","stores":{"corp":{"type":"vault","url":"https://vault.example.com:8200","token":"@file:/run/vault/token"}}}'
|
|
3775
|
+
```
|
|
3776
|
+
|
|
3777
|
+
With AppRole authentication, the token is obtained by login, and renewed:
|
|
3375
3778
|
|
|
3376
3779
|
```shell
|
|
3377
|
-
--vault=@json:'{"type":"vault","url":"
|
|
3780
|
+
--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
3781
|
```
|
|
3379
3782
|
|
|
3380
3783
|
#### Vault: System keychain
|
|
@@ -3386,28 +3789,42 @@ It is possible to manage secrets in macOS keychain.
|
|
|
3386
3789
|
Commands `list`, `ids` and `delete` are not supported: use the **Keychain Access** app.
|
|
3387
3790
|
|
|
3388
3791
|
```shell
|
|
3389
|
-
--vault=@json:'{"type":"system","name":"ascli"}'
|
|
3792
|
+
--vault=@json:'{"default":"keychain","stores":{"keychain":{"type":"system","name":"ascli"}}}'
|
|
3793
|
+
```
|
|
3794
|
+
|
|
3795
|
+
#### Vault: Linux Secret Service
|
|
3796
|
+
|
|
3797
|
+
> [!WARNING]
|
|
3798
|
+
> **Linux only**
|
|
3799
|
+
|
|
3800
|
+
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).
|
|
3801
|
+
A session with an unlocked keyring is required.
|
|
3802
|
+
Secrets are grouped with attribute `service`, which is parameter `name` (default: `ascli`).
|
|
3803
|
+
|
|
3804
|
+
```shell
|
|
3805
|
+
--vault=@json:'{"default":"keyring","stores":{"keyring":{"type":"secret_service","name":"ascli"}}}'
|
|
3390
3806
|
```
|
|
3391
3807
|
|
|
3392
3808
|
#### Vault: Encrypted file
|
|
3393
3809
|
|
|
3394
|
-
It is possible to store and use secrets encrypted in a file
|
|
3810
|
+
It is possible to store and use secrets encrypted in a file, with a store of type `file`:
|
|
3395
3811
|
|
|
3396
3812
|
```json
|
|
3397
|
-
{"type":"file","
|
|
3813
|
+
{"default":"local","stores":{"local":{"type":"file","file":"vault.bin"}}}
|
|
3398
3814
|
```
|
|
3399
3815
|
|
|
3400
|
-
To configure the encrypted file vault as the default, set the `vault` option in the global preset:
|
|
3816
|
+
To configure the encrypted file vault as the default store, set the `vault` option in the global preset:
|
|
3401
3817
|
|
|
3402
3818
|
```shell
|
|
3403
|
-
ascli config preset set GLOBAL vault
|
|
3819
|
+
ascli config preset set GLOBAL vault @json:'{"default":"local","stores":{"local":{"type":"file","file":"vault.bin"}}}'
|
|
3404
3820
|
```
|
|
3405
3821
|
|
|
3406
|
-
The vault file is created automatically
|
|
3822
|
+
The vault file is created automatically when the first secret is added - no explicit initialization is needed.
|
|
3823
|
+
It is read when used, and again when it is modified.
|
|
3407
3824
|
|
|
3408
3825
|
> [!WARNING]
|
|
3409
3826
|
> 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.
|
|
3827
|
+
> Use an environment variable as described above, or parameter `password` with `@file:<path>` (for example, a credential of `systemd`).
|
|
3411
3828
|
|
|
3412
3829
|
#### Vault: 1Password
|
|
3413
3830
|
|
|
@@ -3428,7 +3845,7 @@ docker run -d --name op-connect \
|
|
|
3428
3845
|
```
|
|
3429
3846
|
|
|
3430
3847
|
```shell
|
|
3431
|
-
--vault=@json:'{"type":"1password","source":"api","url":"http://localhost:8080","vault_id":"<VAULT_ID>"}' \
|
|
3848
|
+
--vault=@json:'{"default":"op","stores":{"op":{"type":"1password","source":"api","url":"http://localhost:8080","vault_id":"<VAULT_ID>"}}}' \
|
|
3432
3849
|
--vault-password=<CONNECT_TOKEN>
|
|
3433
3850
|
```
|
|
3434
3851
|
|
|
@@ -3448,9 +3865,9 @@ Requires the `op` CLI to be installed and signed in.
|
|
|
3448
3865
|
No server to deploy: authentication is handled by the 1Password desktop app (biometric unlock) or by `op signin`.
|
|
3449
3866
|
|
|
3450
3867
|
```shell
|
|
3451
|
-
--vault=@json:'{"type":"1password","source":"cli"}'
|
|
3868
|
+
--vault=@json:'{"default":"op","stores":{"op":{"type":"1password","source":"cli"}}}'
|
|
3452
3869
|
# or, to target a specific vault and account:
|
|
3453
|
-
--vault=@json:'{"type":"1password","source":"cli","vault":"<VAULT_NAME>","account":"<ACCOUNT_SHORTHAND>"}'
|
|
3870
|
+
--vault=@json:'{"default":"op","stores":{"op":{"type":"1password","source":"cli","vault":"<VAULT_NAME>","account":"<ACCOUNT_SHORTHAND>"}}}'
|
|
3454
3871
|
```
|
|
3455
3872
|
|
|
3456
3873
|
> [!TIP]
|
|
@@ -3469,18 +3886,57 @@ An item can be referenced by its title (label) or by its 1Password ID, in `@vaul
|
|
|
3469
3886
|
> [!NOTE]
|
|
3470
3887
|
> If several items share the same title, use the item ID (or the `vault` parameter to restrict the search).
|
|
3471
3888
|
|
|
3889
|
+
#### Vault: Keeper
|
|
3890
|
+
|
|
3891
|
+
<https://docs.keeper.io/keeperpam/secrets-manager/overview>
|
|
3892
|
+
|
|
3893
|
+
Keeper Secrets Manager (KSM) gives an application access to the records of shared folders of a Keeper vault, without the credentials of a user.
|
|
3894
|
+
It requires the optional gem `keeper_secrets_manager`:
|
|
3895
|
+
|
|
3896
|
+
```shell
|
|
3897
|
+
gem install keeper_secrets_manager
|
|
3898
|
+
```
|
|
3899
|
+
|
|
3900
|
+
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`).
|
|
3901
|
+
Parameter `config` is the value, or `@file:<path>`:
|
|
3902
|
+
|
|
3903
|
+
```shell
|
|
3904
|
+
--vault=@json:'{"default":"keeper","stores":{"keeper":{"type":"keeper","config":"@file:<KSM_CONFIG_FILE>"}}}'
|
|
3905
|
+
```
|
|
3906
|
+
|
|
3907
|
+
If `config` is not set in the default store, it is the value of option `vault_password`.
|
|
3908
|
+
|
|
3909
|
+
A secret is a record of the vault: its label is its title, or its UID.
|
|
3910
|
+
The field of a reference is `password` by default: standard field of the record (`login`, `password`, `url`...), custom field by its label, or `notes`.
|
|
3911
|
+
Field `username` is an alias of `login`.
|
|
3912
|
+
|
|
3913
|
+
```shell
|
|
3914
|
+
--password=@vault:<RECORD_TITLE>.password
|
|
3915
|
+
--password=@vault://keeper/<RECORD_TITLE>#<FIELD>
|
|
3916
|
+
```
|
|
3917
|
+
|
|
3918
|
+
To create records with `config vault create` (type `login`), set parameter `folder_uid`: UID of the shared folder where records are added.
|
|
3919
|
+
Reading does not need it.
|
|
3920
|
+
|
|
3921
|
+
> [!NOTE]
|
|
3922
|
+
> If several records share the same title, use the UID.
|
|
3923
|
+
> Deleting a record with `config vault delete` requires that the application has edit permission.
|
|
3924
|
+
|
|
3472
3925
|
#### Vault: Operations
|
|
3473
3926
|
|
|
3474
|
-
Secrets can be manipulated using the `config vault` command:
|
|
3927
|
+
Secrets of the default store can be manipulated using the `config vault` command:
|
|
3475
3928
|
|
|
3476
3929
|
- `info` : Show vault information
|
|
3477
3930
|
- `ids` : List secret labels in the vault
|
|
3478
3931
|
- `list` : List all secrets with full details
|
|
3932
|
+
- `overview` : List labels of all secrets with their field names, without values
|
|
3933
|
+
- `field` : List field names of a secret by label, without values
|
|
3479
3934
|
- `show` : Show a secret by label (or id)
|
|
3480
3935
|
- `create` : Add a new secret to the vault
|
|
3481
3936
|
- `delete` : Delete a secret by label (or id)
|
|
3482
3937
|
- `password` : Set a new password for the vault
|
|
3483
3938
|
- `import` : Import secrets from a JSON array (supports `--bulk`)
|
|
3939
|
+
- `check` : Check that a [Secret Reference](#vault-secret-references) can be read, without its value
|
|
3484
3940
|
|
|
3485
3941
|
To add a new password entry in the vault for label `<NAME>`:
|
|
3486
3942
|
|
|
@@ -3497,10 +3953,10 @@ To migrate all secrets from one vault backend to another (for example, from the
|
|
|
3497
3953
|
|
|
3498
3954
|
```shell
|
|
3499
3955
|
ascli config vault list --format=json --out.level=data --out.secrets=yes \
|
|
3500
|
-
--vault=@json:'{"type":"file","
|
|
3956
|
+
--vault=@json:'{"default":"local","stores":{"local":{"type":"file","file":"<SOURCE_VAULT_FILE>"}}}' \
|
|
3501
3957
|
--vault-password=<SOURCE_PASSWORD> | \
|
|
3502
3958
|
ascli config vault import @json:@stdin: --bulk=yes \
|
|
3503
|
-
--vault=@json:'{"type":"1password","url":"<CONNECT_URL>","vault_id":"<VAULT_ID>"}' \
|
|
3959
|
+
--vault=@json:'{"default":"op","stores":{"op":{"type":"1password","url":"<CONNECT_URL>","vault_id":"<VAULT_ID>"}}}' \
|
|
3504
3960
|
--vault-password=<CONNECT_TOKEN>
|
|
3505
3961
|
```
|
|
3506
3962
|
|
|
@@ -3512,6 +3968,44 @@ The `import` command accepts a JSON array where each element is a vault secret o
|
|
|
3512
3968
|
On error (for example a duplicate label), the default behavior is to stop (`--bfail=yes`).
|
|
3513
3969
|
Pass `--bfail=no` to skip failures and continue with the remaining entries.
|
|
3514
3970
|
|
|
3971
|
+
#### Vault: Secret references
|
|
3972
|
+
|
|
3973
|
+
Secrets can also be read by reference, from any store of option `vault`:
|
|
3974
|
+
|
|
3975
|
+
```text
|
|
3976
|
+
@vault://<store>/<path>[?<options>][#<field>]
|
|
3977
|
+
```
|
|
3978
|
+
|
|
3979
|
+
- `<store>`: name of a store in `stores` of option `vault`.
|
|
3980
|
+
- `<path>`: path of the secret in the store, and `<field>`: field of the secret. Both are percent-decoded (for example, `%20` for a space).
|
|
3981
|
+
For most types, the path is the label, and the field is `password` by default.
|
|
3982
|
+
For type `vault`, the path is `<mount>/<path>` in a KV v2 secrets engine, and the field is required.
|
|
3983
|
+
- `<options>`: options of the store, as a URL query (for example, `version=2`).
|
|
3984
|
+
|
|
3985
|
+
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.
|
|
3986
|
+
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`).
|
|
3987
|
+
Values read by reference are kept in memory for `cache_ttl` seconds.
|
|
3988
|
+
The configuration of stores is the same as in applications that use the library with references `secret://<store>/<path>` (for example, IBM Aspera Orchestrator).
|
|
3989
|
+
|
|
3990
|
+
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`:
|
|
3991
|
+
|
|
3992
|
+
```shell
|
|
3993
|
+
--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"}}}'
|
|
3994
|
+
```
|
|
3995
|
+
|
|
3996
|
+
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:
|
|
3997
|
+
|
|
3998
|
+
```shell
|
|
3999
|
+
ascli config preset set <PRESET_NAME> @: url=... username=... password=@val:@vault://corp/kv/aspera/faspex#password
|
|
4000
|
+
ascli config preset set <PRESET_NAME> @: url=... username=... password=@val:@vault://local/<VAULT_LABEL>
|
|
4001
|
+
```
|
|
4002
|
+
|
|
4003
|
+
To check that a reference can be read, without its value (store, version, time of update):
|
|
4004
|
+
|
|
4005
|
+
```shell
|
|
4006
|
+
ascli config vault check @vault://corp/kv/aspera/faspex#password
|
|
4007
|
+
```
|
|
4008
|
+
|
|
3515
4009
|
#### Configuration Finder
|
|
3516
4010
|
|
|
3517
4011
|
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 +4018,13 @@ A password can be saved in clear in an [Option Preset](#option-preset) together
|
|
|
3524
4018
|
Example:
|
|
3525
4019
|
|
|
3526
4020
|
```shell
|
|
3527
|
-
ascli config preset
|
|
4021
|
+
ascli config preset set <PRESET_NAME> @: url=... username=... password=...
|
|
3528
4022
|
```
|
|
3529
4023
|
|
|
3530
4024
|
For more secure storage, first create a vault entry (see [Vault: Operations](#vault-operations)), then refer to it in the preset:
|
|
3531
4025
|
|
|
3532
4026
|
```shell
|
|
3533
|
-
ascli config preset
|
|
4027
|
+
ascli config preset set <PRESET_NAME> @: url=... username=... password=@val:@vault:<VAULT_LABEL>.password
|
|
3534
4028
|
```
|
|
3535
4029
|
|
|
3536
4030
|
> [!NOTE]
|
|
@@ -3549,7 +4043,7 @@ This scans all presets (or a single one if a name is provided) and, for every op
|
|
|
3549
4043
|
ascli config preset secure <PRESET_NAME>
|
|
3550
4044
|
```
|
|
3551
4045
|
|
|
3552
|
-
When a vault is configured, the `
|
|
4046
|
+
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
4047
|
To disable this behavior for a single command, pass `--vault=@none:`.
|
|
3554
4048
|
|
|
3555
4049
|
### Private Key
|
|
@@ -3565,13 +4059,12 @@ The file containing the private key (key pair) can optionally be protected by a
|
|
|
3565
4059
|
If the key is protected by a passphrase, then the passphrase is prompted when the key is used.
|
|
3566
4060
|
Some plugins support option `passphrase`.
|
|
3567
4061
|
|
|
3568
|
-
|
|
3569
|
-
See section: [Private key type ed25519](#private-key-type-ed25519
|
|
3570
|
-
|
|
3571
|
-
To support `ed25519` and OpenSSH format (default on modern Linux), install those gems:
|
|
4062
|
+
Keys of type `ed25519` and OpenSSH encoded keys (default on modern Linux) are supported.
|
|
4063
|
+
See section: [Private key type ed25519](#private-key-type-ed25519).
|
|
4064
|
+
For OpenSSH encoded keys protected by a passphrase, install gem `bcrypt_pbkdf` (not available for JRuby):
|
|
3572
4065
|
|
|
3573
4066
|
```shell
|
|
3574
|
-
gem install
|
|
4067
|
+
gem install bcrypt_pbkdf
|
|
3575
4068
|
```
|
|
3576
4069
|
|
|
3577
4070
|
The following sample commands use the shell variable `KEY_PAIR_PATH`.
|
|
@@ -3650,9 +4143,35 @@ For example: <https://cryptotools.net/rsagen>
|
|
|
3650
4143
|
|
|
3651
4144
|
### Web service
|
|
3652
4145
|
|
|
3653
|
-
|
|
3654
|
-
|
|
4146
|
+
`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.
|
|
4147
|
+
It is not intended to be a public-facing web server.
|
|
4148
|
+
When commands come from another program, for example an MCP client, see [Security Level](#security-level).
|
|
4149
|
+
|
|
4150
|
+
Some commands start a web server, for a specific client:
|
|
4151
|
+
|
|
4152
|
+
| Command | Client | Protection required when `url` is not loopback |
|
|
4153
|
+
|---|---|---|
|
|
4154
|
+
| `mcp server`, `http` transport | MCP client | `auth_token`, see [MCP Security](#security) |
|
|
4155
|
+
| `faspex5 postprocessing` | Faspex 5 web hooks | `secret_token` or `allowed_ips`, see [Faspex 4-style post-processing](#faspex-5-faspex-4-style-post-processing) |
|
|
4156
|
+
| `faspex5 gateway`, `aoc gateway` | Faspex 4 client applications | `username` and `password`, see [Faspex 4 Gateway](#faspex-5-faspex-4-gateway) |
|
|
4157
|
+
| `node emulator` | Node API clients, for tests | `username` and `password`, see [Node emulator](#node-emulator) |
|
|
3655
4158
|
|
|
4159
|
+
By default, the server listens on a loopback address: `localhost`, an address of `127.0.0.0/8`, or `::1`.
|
|
4160
|
+
It can be reached only from the same host.
|
|
4161
|
+
|
|
4162
|
+
> [!WARNING]
|
|
4163
|
+
> Loopback restricts the host, not the user: on a host shared with other users, they can also reach the server.
|
|
4164
|
+
> On such a host, also set the protection of the command.
|
|
4165
|
+
|
|
4166
|
+
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.
|
|
4167
|
+
On a network, use HTTPS (`https://` in `url`) or a reverse proxy with TLS: with HTTP, passwords and tokens are sent in clear.
|
|
4168
|
+
|
|
4169
|
+
Other features listen on a loopback address only, to receive input from the browser of the user:
|
|
4170
|
+
|
|
4171
|
+
- [Web login flow](#web-login-flow): the result of the login, on `redirect_uri`.
|
|
4172
|
+
- `@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.
|
|
4173
|
+
|
|
4174
|
+
The server serves HTTP, or HTTPS with a certificate.
|
|
3656
4175
|
The following parameters are supported:
|
|
3657
4176
|
|
|
3658
4177
|
| Parameter | Type | Default | Description |
|
|
@@ -3692,7 +4211,7 @@ This feature can be used:
|
|
|
3692
4211
|
The following options can be specified in option `--out.img`:
|
|
3693
4212
|
|
|
3694
4213
|
| Field | Type | Description |
|
|
3695
|
-
|
|
4214
|
+
| ---------- | ------- | -------------------------------------------------------------------------------- |
|
|
3696
4215
|
| `double` | `Bool` | Use double vertical resolution via half-block characters (Unicode). Default is `true` if the terminal supports Unicode (see `utf8`). |
|
|
3697
4216
|
| `font_ratio` | `Number` | Terminal font aspect ratio (height divided by width).<br/>Default: `2.3`. |
|
|
3698
4217
|
| `reserve` | `Integer` | Number of terminal lines reserved for non-image output.<br/>Default: `3`. |
|
|
@@ -3726,40 +4245,202 @@ Some actions may require the use of a graphical tool:
|
|
|
3726
4245
|
- A browser to enter a secret requested with `@secret:`
|
|
3727
4246
|
- A text editor for editing the configuration file
|
|
3728
4247
|
|
|
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:
|
|
4248
|
+
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.
|
|
4249
|
+
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
4250
|
|
|
3732
4251
|
| 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
|
-
| `
|
|
4252
|
+
| ------------- | ------------- | -------------------------------------------------------------------------------- |
|
|
4253
|
+
| `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`. |
|
|
4254
|
+
| `hidden_silent` | `Bool` | Secrets typed or pasted on a terminal are read without any feedback (no echo, no mark), as `getpass`. By default, a mark shows whether something was typed or pasted, without revealing the length.<br/>Default: `false`. |
|
|
4255
|
+
| `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`. |
|
|
4256
|
+
| `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`. |
|
|
3736
4257
|
|
|
3737
4258
|
A plain value is the `mode`:
|
|
3738
4259
|
|
|
3739
|
-
- `--ui=browser` (or `graphical`) forces a graphical environment: a browser is opened for URLs or secrets
|
|
3740
|
-
- `--ui=terminal` (or `text`) forces a text environment
|
|
4260
|
+
- `--ui=browser` (or `graphical`) forces a graphical environment: a browser is opened for URLs or secrets.
|
|
4261
|
+
- `--ui=terminal` (or `text`) forces a text environment: the URL to open is displayed on terminal, and secrets are entered on terminal.
|
|
3741
4262
|
- `--ui=auto` selects the mode from the environment (default).
|
|
3742
4263
|
|
|
3743
4264
|
The browser is opened, by priority, with: `--ui.command`, or the system default.
|
|
4265
|
+
The system default is opened with the following command:
|
|
4266
|
+
|
|
4267
|
+
| OS | Command |
|
|
4268
|
+
|---------|------------------------|
|
|
4269
|
+
| macOS | `open <url>` |
|
|
4270
|
+
| Windows | `start explorer "<url>"` |
|
|
4271
|
+
| Linux | `xdg-open <url>` |
|
|
4272
|
+
|
|
4273
|
+
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).
|
|
4274
|
+
|
|
3744
4275
|
When a command is defined, it is used to open URLs whatever the `mode`.
|
|
3745
4276
|
The command is an array: the URL is appended as last argument.
|
|
4277
|
+
The executable is either a full path, or the name of an executable found in the `PATH`.
|
|
3746
4278
|
For example, to use Firefox:
|
|
3747
4279
|
|
|
3748
4280
|
```bash
|
|
3749
4281
|
ascli config echo @secret: --ui=browser --ui.command=@json:'["firefox","--private-window"]'
|
|
3750
4282
|
```
|
|
3751
4283
|
|
|
4284
|
+
### Web login flow
|
|
4285
|
+
|
|
4286
|
+
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.
|
|
4287
|
+
|
|
4288
|
+

|
|
4289
|
+
|
|
4290
|
+
1. `ascli` generates a random `state` and starts a local HTTP server on the loopback address of `redirect_uri` (default: `http://localhost:12345`).
|
|
4291
|
+
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`.
|
|
4292
|
+
If no graphical environment is available, the URL is displayed, to be opened on any browser of the same host.
|
|
4293
|
+
3. The user logs in on the server, possibly redirected to an identity provider.
|
|
4294
|
+
4. The server redirects the browser to `redirect_uri`, with the OAuth code (`web`), or, for Shares, the tokens, and the `state`.
|
|
4295
|
+
5. The browser sends this request to `ascli`, which checks that `state` is the one it generated, and stops listening.
|
|
4296
|
+
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.
|
|
4297
|
+
For Faspex 5, the code is protected with PKCE: `ascli` sends a challenge with the login URL, and the matching verifier with the code.
|
|
4298
|
+
Next calls use the cached token, renewed if needed without a browser.
|
|
4299
|
+
|
|
4300
|
+
The code or tokens never go to another host than the local one: the host of `redirect_uri` shall be loopback.
|
|
4301
|
+
|
|
4302
|
+
#### Option `ui.web_auth`
|
|
4303
|
+
|
|
4304
|
+
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:
|
|
4305
|
+
|
|
4306
|
+
| Value | Local port | Use when |
|
|
4307
|
+
|------------------|------------|----------|
|
|
4308
|
+
| `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. |
|
|
4309
|
+
| `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. |
|
|
4310
|
+
|
|
4311
|
+
With `paste`, after login the user gives the result to `ascli` through the terminal (it is hidden, as it contains a code or tokens: see [Hidden Input](#hidden-input)):
|
|
4312
|
+
|
|
4313
|
+
- the code displayed by Shares (a long text of letters, digits, `-` and `_`), or the code shown by `ascli config web_login` on the workstation,
|
|
4314
|
+
- 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.
|
|
4315
|
+
|
|
4316
|
+
In all cases the `state` is checked.
|
|
4317
|
+
Details are in the following sections.
|
|
4318
|
+
|
|
4319
|
+
Example:
|
|
4320
|
+
|
|
4321
|
+
```shell
|
|
4322
|
+
ascli <PLUGIN> <COMMAND> --ui=terminal --ui.web_auth=paste
|
|
4323
|
+
```
|
|
4324
|
+
|
|
4325
|
+
#### Web login when the browser is on another system
|
|
4326
|
+
|
|
4327
|
+
The browser sends the result of the login to `redirect_uri`, on the loopback address of the system where the browser runs.
|
|
4328
|
+
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`.
|
|
4329
|
+
|
|
4330
|
+
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:
|
|
4331
|
+
|
|
4332
|
+
1. On the workstation, open the SSH session with a tunnel (same port on both sides, default `12345`):
|
|
4333
|
+
|
|
4334
|
+
```shell
|
|
4335
|
+
ssh -L 127.0.0.1:12345:127.0.0.1:12345 <SERVER_USER>@<SERVER_HOST>
|
|
4336
|
+
```
|
|
4337
|
+
|
|
4338
|
+
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):
|
|
4339
|
+
|
|
4340
|
+
```shell
|
|
4341
|
+
ascli <PLUGIN> <COMMAND> --ui=terminal
|
|
4342
|
+
```
|
|
4343
|
+
|
|
4344
|
+
3. Copy the displayed URL in the browser of the workstation, and log in.
|
|
4345
|
+
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.
|
|
4346
|
+
|
|
4347
|
+
The tunnel only exists as long as the SSH session is open.
|
|
4348
|
+
|
|
4349
|
+
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.
|
|
4350
|
+
There are two ways, depending on whether `ascli` is also installed on the workstation.
|
|
4351
|
+
|
|
4352
|
+
With `--ui.web_auth=port` (default), in an SSH session with `--ui=terminal`, a warning reminds this option.
|
|
4353
|
+
|
|
4354
|
+
##### With `ascli` on the workstation
|
|
4355
|
+
|
|
4356
|
+
`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.
|
|
4357
|
+
Nothing else is needed on the workstation: no configuration, no preset, no access to the server of the application.
|
|
4358
|
+
The exchange of the code for a token is done by `ascli` on the server: the secret of the client does not leave it.
|
|
4359
|
+
|
|
4360
|
+
1. In the SSH session, run the command with `--ui=terminal --ui.web_auth=paste`:
|
|
4361
|
+
|
|
4362
|
+
```shell
|
|
4363
|
+
ascli <PLUGIN> <COMMAND> --ui=terminal --ui.web_auth=paste
|
|
4364
|
+
```
|
|
4365
|
+
|
|
4366
|
+
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:
|
|
4367
|
+
|
|
4368
|
+
```text
|
|
4369
|
+
USER ACTION: To continue, choose one of these two ways:
|
|
4370
|
+
1. With any browser (ascli is not needed on the workstation):
|
|
4371
|
+
- Open this URL in a browser and log in:
|
|
4372
|
+
https://...
|
|
4373
|
+
- The browser shows a connection error on http://localhost:12345: this is expected.
|
|
4374
|
+
- Copy the full URL from the address bar of the browser, and paste it in the prompt below.
|
|
4375
|
+
2. If ascli is installed on the workstation that has the browser:
|
|
4376
|
+
- Run there:
|
|
4377
|
+
ascli config web_login <CODE>
|
|
4378
|
+
- Log in in the page that opens.
|
|
4379
|
+
- Copy the code shown by the browser, and paste it in the prompt below.
|
|
4380
|
+
```
|
|
4381
|
+
|
|
4382
|
+
The command is displayed only if `ascli` does not start the browser itself (`--ui=terminal` without `--ui.command`).
|
|
4383
|
+
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.
|
|
4384
|
+
|
|
4385
|
+
3. On the workstation, run this command.
|
|
4386
|
+
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.
|
|
4387
|
+
Trusted hosts are saved; without a terminal, an unknown host is refused.
|
|
4388
|
+
`ascli` then opens the browser on the login page and listens on `redirect_uri`.
|
|
4389
|
+
4. Log in. The browser shows a page "Login Complete" with the code to paste, hidden by default:
|
|
4390
|
+
- The button **Copy** puts the code in the clipboard.
|
|
4391
|
+
- The **eye** button shows or hides the code, to select it manually.
|
|
4392
|
+
5. Paste the code in the terminal of the server ([hidden](#hidden-input): `🔑` becomes `…`). `ascli` on the server checks the `state`, and the flow continues as described above, from step 6.
|
|
4393
|
+
|
|
4394
|
+
The command on the workstation:
|
|
4395
|
+
|
|
4396
|
+
- 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;
|
|
4397
|
+
- is available only at security level `low`;
|
|
4398
|
+
- 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);
|
|
4399
|
+
- gives to the server only the parameters it needs (the `code` and the `state`).
|
|
4400
|
+
|
|
4401
|
+
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.
|
|
4402
|
+
The codes are authenticated: a code that is incomplete, mistyped or modified is detected.
|
|
4403
|
+
Spaces and line breaks are ignored (letter case matters): a code displayed on several lines can be pasted.
|
|
4404
|
+
|
|
4405
|
+
##### Without `ascli` on the workstation
|
|
4406
|
+
|
|
4407
|
+
If `ascli` is not installed on the workstation, the URL of the error page is used:
|
|
4408
|
+
|
|
4409
|
+
1. In the SSH session, run the command with `--ui=terminal --ui.web_auth=paste`.
|
|
4410
|
+
2. Copy the displayed login URL in the browser of the workstation, and log in.
|
|
4411
|
+
3. The browser is redirected to `redirect_uri` (for example `http://localhost:12345/?code=...&state=...`) and shows a connection error: this is expected.
|
|
4412
|
+
4. Copy the full URL from the address bar of the browser, and paste it in the terminal ([hidden](#hidden-input), as it contains a code or tokens).
|
|
4413
|
+
The query alone (`code=...&state=...`) is also accepted.
|
|
4414
|
+
The `state` is mandatory: it is checked like in the standard flow, then the flow continues from step 6.
|
|
4415
|
+
|
|
4416
|
+
Both ways accept, at the prompt, the code, the URL or the query.
|
|
4417
|
+
If standard input is not a terminal, the line is read from it.
|
|
4418
|
+
The size of a pasted line may be limited by the terminal: the code of the reply contains only what is needed.
|
|
4419
|
+
|
|
4420
|
+
Notes:
|
|
4421
|
+
|
|
4422
|
+
- 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)).
|
|
4423
|
+
- The port must be free on the workstation.
|
|
4424
|
+
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`.
|
|
4425
|
+
For Aspera on Cloud, this `redirect_uri` shall also be declared in the API client (see [API Client Registration](#api-client-registration)).
|
|
4426
|
+
- The tunnel listens on `127.0.0.1`: if the browser resolves `localhost` to `::1`, use `--redirect-uri=http://127.0.0.1:12345`.
|
|
4427
|
+
- On Windows, `ssh` is the OpenSSH client provided with the system; with PuTTY, add a local port forwarding (Connection → SSH → Tunnels) from `127.0.0.1:12345` to `127.0.0.1:12345`.
|
|
4428
|
+
- Another solution is X11 forwarding: run an X server on the workstation (for example `VcXsrv` or X410 on Windows) and connect with `ssh -X`.
|
|
4429
|
+
The browser then runs on the server and is displayed on the workstation, so no tunnel is needed.
|
|
4430
|
+
It is heavier (X server to install, slower display), and the browser is the one of the server.
|
|
4431
|
+
- Without interaction (automation), prefer a method that needs no browser, such as `--auth=jwt` for Aspera on Cloud.
|
|
4432
|
+
|
|
3752
4433
|
### Logging, Debugging
|
|
3753
4434
|
|
|
3754
4435
|
The gem is equipped with traces, mainly for debugging and learning APIs.
|
|
3755
4436
|
The composite option `log` groups all logging parameters (use `--log=help` to display this schema):
|
|
3756
4437
|
|
|
3757
4438
|
| 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`. |
|
|
4439
|
+
| ------- | ------------ | ------------------------------------------------------------------------- |
|
|
4440
|
+
| `format` | `Enum[String]` | Log line formatter. Use `@ruby:` for a custom lambda.<br/>Allowed values: `default`, `caller`, `standard`.<br/>Default: `default`. |
|
|
4441
|
+
| `level` | `Enum[String]` | Minimum log level displayed.<br/>Allowed values: `trace2`, `trace1`, `debug`, `info`, `warn`, `error`, `fatal`, `unknown`.<br/>Default: `warn`. |
|
|
3761
4442
|
| `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`. |
|
|
4443
|
+
| `type` | `Enum[String]` | Log output destination.<br/>Allowed values: `stderr`, `stdout`, `syslog`.<br/>Default: `stderr`. |
|
|
3763
4444
|
|
|
3764
4445
|
> [!TIP]
|
|
3765
4446
|
> 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,23 +4521,26 @@ To disable this warning, set the option `warn_insecure` to `no`.
|
|
|
3840
4521
|
HTTP connection parameters (not `ascp` WSS) can be adjusted using option `http_options`:
|
|
3841
4522
|
|
|
3842
4523
|
| Field | Type | Description |
|
|
3843
|
-
|
|
4524
|
+
| ----------------------- | -------------- | -------------------------------------------------------------------------------- |
|
|
3844
4525
|
| `download_partial_suffix` | `String` | File suffix appended to the target filename while a download is in progress. (Rest)<br/>Default: `.http_partial`. |
|
|
3845
|
-
| `
|
|
3846
|
-
| `
|
|
3847
|
-
| `
|
|
4526
|
+
| `jwt_accepted_offset_sec` | `String, Number` | Tolerance of clock difference with the server: a generated JWT is valid since this duration in the past (`nbf`). (OAuth) A duration, e.g. `30s`, `12h`, `1d`, `1h 30m`, a plain number is seconds.<br/>Default: `300`. |
|
|
4527
|
+
| `jwt_expiry_offset_sec` | `String, Number` | Validity of a generated JWT, used to request a token. (OAuth) A duration, e.g. `30s`, `12h`, `1d`, `1h 30m`, a plain number is seconds.<br/>Default: `3600`. |
|
|
4528
|
+
| `keep_alive_timeout` | `String, Number` | Maximum time in seconds to keep an idle persistent connection open. (Net::HTTP) A duration, e.g. `30s`, `12h`, `1d`, `1h 30m`, a plain number is seconds.<br/>Default: `2`. |
|
|
4529
|
+
| `open_timeout` | `String, Number` | Maximum time in seconds to wait for a connection to be established. (Net::HTTP) A duration, e.g. `30s`, `12h`, `1d`, `1h 30m`, a plain number is seconds.<br/>Default: `60`. |
|
|
4530
|
+
| `read_timeout` | `String, Number` | Maximum time in seconds to wait for data to be read from the server. (Net::HTTP) A duration, e.g. `30s`, `12h`, `1d`, `1h 30m`, a plain number is seconds.<br/>Default: `60`. |
|
|
3848
4531
|
| `retry_max` | `Integer` | Maximum number of retry attempts. (Rest)<br/>Default: `1`. |
|
|
3849
4532
|
| `retry_on_error` | `Bool` | Retry the request on any HTTP error response. (Rest)<br/>Default: `false`. |
|
|
3850
4533
|
| `retry_on_timeout` | `Bool` | Retry the request on connection timeout. (Rest)<br/>Default: `true`. |
|
|
3851
4534
|
| `retry_on_unavailable` | `Bool` | Retry the request on HTTP 503 Service Unavailable. (Rest)<br/>Default: `true`. |
|
|
3852
|
-
| `retry_sleep` | `
|
|
4535
|
+
| `retry_sleep` | `String, Number` | Delay in seconds between retry attempts. (Rest) A duration, e.g. `30s`, `12h`, `1d`, `1h 30m`, a plain number is seconds.<br/>Default: `4`. |
|
|
3853
4536
|
| `ssl_options` | `Array[String]` | List of OpenSSL option flags to set on the HTTP session (e.g. `IGNORE_UNEXPECTED_EOF`). (SSL) |
|
|
3854
|
-
| `token_cache_max_age` | `
|
|
3855
|
-
| `
|
|
4537
|
+
| `token_cache_max_age` | `String, Number` | Maximum age in seconds of a cached OAuth token before it is discarded. (OAuth) A duration, e.g. `30s`, `12h`, `1d`, `1h 30m`, a plain number is seconds.<br/>Default: `1800`. |
|
|
4538
|
+
| `token_refresh_max_age` | `String, Number` | Age in seconds (since it was obtained) above which the token is proactively refreshed, `0` for no limit. E.g. keeps a session alive when the refresh token expires at the same time as the token (Shares). (OAuth) A duration, e.g. `30s`, `12h`, `1d`, `1h 30m`, a plain number is seconds.<br/>Default: `0`. |
|
|
4539
|
+
| `token_refresh_threshold` | `String, Number` | Remaining token lifetime in seconds below which the token is proactively refreshed. (OAuth) A duration, e.g. `30s`, `12h`, `1d`, `1h 30m`, a plain number is seconds.<br/>Default: `120`. |
|
|
3856
4540
|
| `user_agent` | `String` | Value sent in the `User-Agent` HTTP request header. (Rest) |
|
|
3857
|
-
| `write_timeout` | `Number` | Maximum time in seconds to wait for data to be written to the server. (Net::HTTP)
|
|
4541
|
+
| `write_timeout` | `String, Number` | Maximum time in seconds to wait for data to be written to the server. (Net::HTTP) A duration, e.g. `30s`, `12h`, `1d`, `1h 30m`, a plain number is seconds.<br/>Default: `60`. |
|
|
3858
4542
|
|
|
3859
|
-
Time values are
|
|
4543
|
+
Time values are durations: a number of **seconds** (`Integer` or `Float`), or a `String`, e.g. `30s`, `12h`, `1d`, `1h 30m`, `1d 02:00:00`.
|
|
3860
4544
|
Any additional key is forwarded as a setter to the `Net::HTTP` session.
|
|
3861
4545
|
For a full list, refer to the Ruby library: [`Net::HTTP`](https://github.com/ruby/net-http/blob/master/lib/net/http.rb).
|
|
3862
4546
|
|
|
@@ -3868,6 +4552,13 @@ Example:
|
|
|
3868
4552
|
ascli aoc admin package list --http-options=@json:'{"read_timeout":10.0}'
|
|
3869
4553
|
```
|
|
3870
4554
|
|
|
4555
|
+
With a server whose token and refresh token expire at the same time (e.g. Shares: 24 hours), `token_refresh_max_age` refreshes the token before its refresh token expires.
|
|
4556
|
+
A command run more often than this duration (e.g. scheduled every 12 hours) keeps the session alive without a new login, provided the token stays in cache (`token_cache_max_age`):
|
|
4557
|
+
|
|
4558
|
+
```shell
|
|
4559
|
+
ascli shares files browse / --http-options=@json:'{"token_cache_max_age":"1d","token_refresh_max_age":"12h"}'
|
|
4560
|
+
```
|
|
4561
|
+
|
|
3871
4562
|
The option `ssl_options` corresponds to a list of options as listed in `man SSL_CTX_set_options`.
|
|
3872
4563
|
The default initial value is the default of Ruby as specified in `openssl/ssl.rb`.
|
|
3873
4564
|
Each option can be specified as a `String` with the same name as in the OpenSSL library by removing the prefix: `SSL_OP_`, or an `Integer` (for example, `0` resets to no option).
|
|
@@ -3993,7 +4684,7 @@ Or, alternatively, (prefer transfer spec like above, generally):
|
|
|
3993
4684
|
|
|
3994
4685
|
By default, it uses the `direct` agent, which is a local `ascp`.
|
|
3995
4686
|
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
|
|
4687
|
+
This is the reason why it is advised to install the Aspera Transfer Daemon during installation (`ascli transferd install`).
|
|
3997
4688
|
|
|
3998
4689
|
By default, `ascli` uses the `ascp` binary found in **well known locations**, that is, typical Aspera product installation paths.
|
|
3999
4690
|
|
|
@@ -4002,7 +4693,7 @@ It provides the following commands for `ascp` sub-command:
|
|
|
4002
4693
|
|
|
4003
4694
|
- `show` : Show the path of `ascp` used
|
|
4004
4695
|
- `info` : Show information on `ascp` and its environment
|
|
4005
|
-
- `install` : Install the Transfer SDK (same as `
|
|
4696
|
+
- `install` : Install the Transfer SDK (deprecated, same as `transferd install`)
|
|
4006
4697
|
- `spec` : List transfer spec parameters supported by `ascp`
|
|
4007
4698
|
- `schema` : Show the JSON schema of the transfer spec
|
|
4008
4699
|
- `errors` : List known `ascp` errors and whether they are retry-able
|
|
@@ -4011,7 +4702,7 @@ It provides the following commands for `ascp` sub-command:
|
|
|
4011
4702
|
#### Selection of `ascp` location for [`direct`](#agent-direct) agent
|
|
4012
4703
|
|
|
4013
4704
|
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 `
|
|
4705
|
+
By default, `ascli` uses `ascp` from the Transfer SDK installed in its configuration folder (see `transferd install`).
|
|
4015
4706
|
|
|
4016
4707
|
To override and use an alternate `ascp` path, use option `sdk_folder` (`--sdk-folder=`).
|
|
4017
4708
|
|
|
@@ -4099,7 +4790,7 @@ The following agents are supported and selected with option `transfer`:
|
|
|
4099
4790
|
|----------|----------|-------------------------------|
|
|
4100
4791
|
| [`direct`](#agent-direct) | local | direct execution of `ascp` |
|
|
4101
4792
|
| [`transferd`](#agent-transfer-daemon) | local | Aspera Transfer Daemon |
|
|
4102
|
-
| [`connect`](#agent-connect-client) | local | Aspera Connect Client
|
|
4793
|
+
| [`connect`](#agent-connect-client) | local | Aspera Connect Client (to be deprecated in 2027, use `desktop`) |
|
|
4103
4794
|
| [`desktop`](#agent-desktop-client) | local | Aspera for Desktop |
|
|
4104
4795
|
| [`node`](#agent-node-api) | remote | Aspera Transfer Node |
|
|
4105
4796
|
| [`httpgw`](#agent-http-gateway) | remote | Aspera HTTP Gateway |
|
|
@@ -4141,6 +4832,17 @@ Parameters in transfer-spec can be modified with option `ts`.
|
|
|
4141
4832
|
> [!NOTE]
|
|
4142
4833
|
> Parameters in `transfer` are specific for each agent type and are described in the agents respective sections.
|
|
4143
4834
|
|
|
4835
|
+
#### Dry run of a transfer
|
|
4836
|
+
|
|
4837
|
+
With option `dry_run` (`--dry-run=yes`), a transfer command does not start the transfer: its result is the final transfer spec, as it would be given to the agent (with option `ts` and file list applied), with secrets hidden (unless `--out.secrets=yes`).
|
|
4838
|
+
Nothing is transferred.
|
|
4839
|
+
|
|
4840
|
+
```shell
|
|
4841
|
+
ascli server download /aspera-test-dir-large/100MB --dry-run=yes
|
|
4842
|
+
```
|
|
4843
|
+
|
|
4844
|
+
Commands that change something before the transfer are refused with option `dry_run`, before any change: `aoc packages send` and `faspex5 packages send` (the package is created first), `sync` commands, and preview generation of `preview`.
|
|
4845
|
+
|
|
4144
4846
|
#### Asynchronous Transfer Mode
|
|
4145
4847
|
|
|
4146
4848
|
Adding `asynchronous: true` to the `transfer` option makes `ascli` return immediately after
|
|
@@ -4154,15 +4856,18 @@ ascli server download /remote/big-file.bin --to-folder=/tmp \
|
|
|
4154
4856
|
'--transfer=@json:{"agent":"desktop","asynchronous":true}'
|
|
4155
4857
|
|
|
4156
4858
|
# Poll status later
|
|
4157
|
-
ascli config
|
|
4859
|
+
ascli config agents jobs status <job_id>
|
|
4158
4860
|
|
|
4159
4861
|
# List all pending/completed async transfers
|
|
4160
|
-
ascli config
|
|
4862
|
+
ascli config agents jobs list
|
|
4161
4863
|
|
|
4162
4864
|
# Remove completed/failed entries
|
|
4163
|
-
ascli config
|
|
4865
|
+
ascli config agents jobs cleanup
|
|
4164
4866
|
```
|
|
4165
4867
|
|
|
4868
|
+
> [!NOTE]
|
|
4869
|
+
> `config transfer` (`list`, `status`, `cleanup`) is deprecated after 4.28.0: use `config agents jobs`. It still works, with a warning.
|
|
4870
|
+
|
|
4166
4871
|
All transfer agents support asynchronous mode:
|
|
4167
4872
|
|
|
4168
4873
|
| Agent | Status source | Persisted across restart |
|
|
@@ -4176,16 +4881,16 @@ All transfer agents support asynchronous mode:
|
|
|
4176
4881
|
|
|
4177
4882
|
For `direct` and `httpgw`, the transfer runs as a Ruby thread inside the `ascli` process.
|
|
4178
4883
|
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
|
|
4884
|
+
If the process is restarted, `config agents jobs status` returns `unknown` for those jobs.
|
|
4180
4885
|
|
|
4181
|
-
Parameters of the agent are persisted, except secrets (e.g. `password` of agent `node`): `config
|
|
4886
|
+
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
4887
|
|
|
4183
4888
|
> [!NOTE]
|
|
4184
4889
|
> **`asynchronous` and MCP** - When `ascli` is used as an MCP server, an AI assistant calling
|
|
4185
4890
|
> a transfer command may time out or cancel the request and retry, causing duplicate transfers.
|
|
4186
4891
|
> Using `asynchronous: true` eliminates this risk: the transfer is submitted immediately,
|
|
4187
4892
|
> the `job_id` is returned, and the AI can poll
|
|
4188
|
-
> `config
|
|
4893
|
+
> `config agents jobs status <job_id>` to track progress without any risk of duplication.
|
|
4189
4894
|
> This works with all agents, including `direct` and `httpgw`.
|
|
4190
4895
|
|
|
4191
4896
|
#### Agent: Direct
|
|
@@ -4200,75 +4905,210 @@ See [FASP](#fasp-configuration).
|
|
|
4200
4905
|
The `transfer` option accepts the following optional parameters to control multi-session, Web Socket Session, Resume policy and add any argument to `ascp`:
|
|
4201
4906
|
|
|
4202
4907
|
| Field | Type | Description |
|
|
4203
|
-
|
|
4908
|
+
| -------------------- | ------------- | -------------------------------------------------------------------------------- |
|
|
4204
4909
|
| `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`. |
|
|
4910
|
+
| `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
4911
|
| `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
4912
|
| `monitor` | `Bool` | Enable use of the `ascp` management port for transfer monitoring.<br/>Default: `true`. |
|
|
4208
4913
|
| `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
4914
|
| `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`. |
|
|
4915
|
+
| `resume` | `Hash` | Configuration for automatic transfer resume on interruption. |
|
|
4210
4916
|
| `resume.iter_max` | `Integer` | Maximum number of retry attempts on error.<br/>Default: `7`. |
|
|
4211
4917
|
| `resume.sleep_factor` | `Integer` | Multiplier applied to sleep duration between consecutive retry attempts.<br/>Default: `2`. |
|
|
4212
4918
|
| `resume.sleep_initial` | `Integer` | Initial sleep duration (in seconds) before first retry.<br/>Default: `2`. |
|
|
4213
4919
|
| `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
4920
|
| `spawn_delay_sec` | `Number` | Multi session - Delay (in seconds) between starting each `ascp` session.<br/>Default: `2`. |
|
|
4216
4921
|
| `spawn_timeout_sec` | `Number` | Multi session - Maximum time (in seconds) to verify that `ascp` is running.<br/>Default: `2`. |
|
|
4217
4922
|
| `trusted_certs` | `Array[String]` | List of trusted certificate repositories. |
|
|
4218
4923
|
| `wss` | `Bool` | Enable Web Socket Session when available.<br/>Default: `true`. |
|
|
4219
4924
|
|
|
4220
|
-
In case of transfer interruption, the agent will **resume** a transfer up to `iter_max` times.
|
|
4221
|
-
Sleep between iterations is given by the following formula where `iter_index` is the current iteration index, starting at 0:
|
|
4925
|
+
In case of transfer interruption, the agent will **resume** a transfer up to `iter_max` times.
|
|
4926
|
+
Sleep between iterations is given by the following formula where `iter_index` is the current iteration index, starting at 0:
|
|
4927
|
+
|
|
4928
|
+
```text
|
|
4929
|
+
min( sleep_max, sleep_initial * sleep_factor ^ iter_index )
|
|
4930
|
+
```
|
|
4931
|
+
|
|
4932
|
+
By default, the progress bar of `ascli` is displayed (see [Transfer progress bar](#transfer-progress-bar)): it aggregates all sessions of a multi-session transfer.
|
|
4933
|
+
|
|
4934
|
+
To display the native progress bar of `ascp` instead, set parameter `quiet` to `false`:
|
|
4935
|
+
|
|
4936
|
+
```shell
|
|
4937
|
+
--transfer.quiet=false
|
|
4938
|
+
```
|
|
4939
|
+
|
|
4940
|
+
In that case, the progress bar of `ascli` is not displayed, unless option `progress_bar` is set.
|
|
4941
|
+
For multi-session transfers, each `ascp` process displays its own progress bar.
|
|
4942
|
+
|
|
4943
|
+
To skip usage of management port (which disables the progress bar of `ascli`), set option `monitor` to `false`.
|
|
4944
|
+
|
|
4945
|
+
By default, Ruby's root CA store is used to validate any HTTPS endpoint used by `ascp` (for example, WSS).
|
|
4946
|
+
To use a custom certificate store, use the `trusted_certs` option of direct agent's option `transfer`.
|
|
4947
|
+
To use `ascp`'s default, use option:
|
|
4948
|
+
|
|
4949
|
+
```shell
|
|
4950
|
+
--transfer.trusted_certs=@none:
|
|
4951
|
+
```
|
|
4952
|
+
|
|
4953
|
+
Some transfer errors are considered **retry-able** (for example, timeout) and others are not (for example, wrong password).
|
|
4954
|
+
The list of known protocol errors and retry level can be listed:
|
|
4955
|
+
|
|
4956
|
+
```shell
|
|
4957
|
+
ascli config ascp errors
|
|
4958
|
+
```
|
|
4959
|
+
|
|
4960
|
+
Error codes of sessions (`errcode` in `ascp` logs) are a different numbering, listed with their category and the corresponding error above:
|
|
4961
|
+
|
|
4962
|
+
```shell
|
|
4963
|
+
ascli config ascp errors session
|
|
4964
|
+
```
|
|
4965
|
+
|
|
4966
|
+
Examples:
|
|
4967
|
+
|
|
4968
|
+
```shell
|
|
4969
|
+
ascli ... --transfer.wss=true --transfer.resume.iter_max=20
|
|
4970
|
+
ascli ... --transfer.spawn_delay_sec=2.5 --transfer.multi_incr_udp=false
|
|
4971
|
+
```
|
|
4972
|
+
|
|
4973
|
+
Parameter `ascp_args` can also be used to activate logging using option `-L` of `ascp`.
|
|
4974
|
+
For example, to activate debug level 2 for `ascp` (`DD`), and display those logs on the terminal (`-`):
|
|
4975
|
+
|
|
4976
|
+
```shell
|
|
4977
|
+
--transfer=@json:'{"ascp_args":["-DDL-"]}'
|
|
4978
|
+
```
|
|
4979
|
+
|
|
4980
|
+
This is useful to debug if a transfer fails.
|
|
4981
|
+
|
|
4982
|
+
To store `ascp` logs in file `aspera-scp-transfer.log` in a folder, use `--transfer=@json:'{"ascp_args":["-L","/path/to/folder"]}'`.
|
|
4983
|
+
|
|
4984
|
+
To analyze `ascp` log files (`ascp` 4.0 and later), give log files, or folders with log files, to `config ascp logs`:
|
|
4985
|
+
|
|
4986
|
+
```shell
|
|
4987
|
+
ascli config ascp logs summary /path/to/folder
|
|
4988
|
+
ascli config ascp logs sessions /path/to/folder/aspera-scp-transfer.log
|
|
4989
|
+
```
|
|
4990
|
+
|
|
4991
|
+
| Command | Result |
|
|
4992
|
+
|---------------------|-----------------------------------------------------------------|
|
|
4993
|
+
| `summary` | Statistics of sessions, errors by category, maximum throughput, findings. |
|
|
4994
|
+
| `health` | Health check for monitoring in Nagios format (failed sessions and low efficiency over last N minutes). |
|
|
4995
|
+
| `sessions` | One row per session, with diagnostics. |
|
|
4996
|
+
| `diagnostics` | One row per diagnostic of a session: `id`, `severity` (`error`, `warning`, `info`), `message` and `recommendation` (action to take, when the diagnostic has one). |
|
|
4997
|
+
| `multi_sessions` | Multi-session transfers: sessions grouped by transfer, with aggregate rate. |
|
|
4998
|
+
| `snapshots` | Aggregate rates per period. |
|
|
4999
|
+
| `snapshot_sessions` | Rates of each session per period. |
|
|
5000
|
+
| `peers` | Sessions and errors by peer address. |
|
|
5001
|
+
| `transfers` | Transferred files. |
|
|
5002
|
+
| `licenses` | Licenses of local and peer systems. |
|
|
5003
|
+
| `overdrives` | Sessions with loss due to overdriving of network or storage. |
|
|
5004
|
+
| `records` | Log lines parsed into records: `samples`, `sessions` or `transfers` (see below). |
|
|
5005
|
+
| `fields` | Description of the fields of records: `samples`, `sessions` or `transfers`. |
|
|
5006
|
+
| `find` | `ascp` log files of this system (no argument): `path`, `size`, `modified`, `source`, most recent first. |
|
|
5007
|
+
|
|
5008
|
+
Command `find` lists the local files that contain `ascp` log lines, in the log folders of the installed products (including `<logging><directory>` of their `aspera.conf`), of `ascp` found in `PATH`, of IBM Aspera for Desktop, and in the default locations of `ascp` (below). Give the paths it lists to the other commands:
|
|
5009
|
+
|
|
5010
|
+
```shell
|
|
5011
|
+
ascli config ascp logs find --fields=path
|
|
5012
|
+
ascli config ascp logs sessions ~/Library/Logs/Aspera
|
|
5013
|
+
```
|
|
5014
|
+
|
|
5015
|
+
`ascp` writes its log in the folder of option `-L`, else in `<logging><directory>` of `aspera.conf`, else in a location that depends on the OS:
|
|
5016
|
+
|
|
5017
|
+
| OS | Default location of the `ascp` log |
|
|
5018
|
+
|---------------|------------------------------------|
|
|
5019
|
+
| Linux, Unix | syslog, facility `local2`: `/var/log/messages` or `/var/log/syslog` by default, `/var/log/aspera.log` if syslog is configured to separate the Aspera logs. |
|
|
5020
|
+
| macOS | `~/Library/Logs/Aspera` (`/Library/Logs/Aspera` for `root`). |
|
|
5021
|
+
| Windows | `var\log` of the product if this folder exists, else the folder of `ascp`. |
|
|
5022
|
+
|
|
5023
|
+
For the `ascp` used by `ascli`, `ascli config ascp info --fields=log` gives this location (a folder, or `syslog`).
|
|
5024
|
+
|
|
5025
|
+
In a folder, the file is `aspera-scp-transfer.<n>.log` (rotated, `n` from `0` to `log_count` of `aspera.conf`), and `aspera-scp-transfer.log` is a hard link to the current one. `ascp` 4 (`ascp4`) writes `ascp4.<n>.log`.
|
|
4222
5026
|
|
|
4223
|
-
|
|
4224
|
-
|
|
4225
|
-
|
|
5027
|
+
| Application | Location of the `ascp` log |
|
|
5028
|
+
|------------------------|----------------------------|
|
|
5029
|
+
| `ascli`, agent `direct` or `transferd` | No `-L`: default location above (e.g. on Linux in syslog). With agent `direct`, `-L` can be set with `ascp_args` (see above). |
|
|
5030
|
+
| IBM Aspera Connect | `-L` set to its log folder (e.g. `~/Library/Logs/Aspera_Connect`). |
|
|
5031
|
+
| IBM Aspera for Desktop | Log folder of the application, also used for its own logs and those of `transferd`: `~/Library/Logs/com.ibm.software.aspera.desktop` on macOS, `%APPDATA%\com.ibm.software.aspera.desktop\logs` on Windows, `~/.config/com.ibm.software.aspera.desktop/logs` on Linux. |
|
|
5032
|
+
| IBM Aspera Transfer Daemon | `-L` set to `fasp_runtime.log.dir` of its configuration (or `localLog` of the transfer), else the default location above. |
|
|
5033
|
+
| Server side of a transfer | On the server, configured by its `aspera.conf`, or by option `-R` of the client: see [`server logs`](#analyze-ascp-logs-of-the-server). |
|
|
4226
5034
|
|
|
4227
|
-
|
|
5035
|
+
On Linux, the syslog files are often readable only by `root`, and a container may have no syslog daemon (the log of `ascp` is then lost): use `-L`, or read the system journal, e.g. `journalctl -t ascp | ascli config ascp logs summary -`.
|
|
5036
|
+
For the other logs of Aspera products, see the IBM support page [Where are IBM Aspera logs located](https://www.ibm.com/support/pages/where-are-ibm-aspera-desktop-client-or-ibm-aspera-server-logs-located).
|
|
4228
5037
|
|
|
4229
|
-
|
|
5038
|
+
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:
|
|
4230
5039
|
|
|
4231
5040
|
```shell
|
|
4232
|
-
|
|
5041
|
+
ascli config ascp logs summary /var/log/aspera.log-20261101.gz
|
|
5042
|
+
zcat /var/log/aspera.log-2026*.gz | ascli config ascp logs summary -
|
|
4233
5043
|
```
|
|
4234
5044
|
|
|
4235
|
-
|
|
4236
|
-
For multi-session transfers, each `ascp` process displays its own progress bar.
|
|
5045
|
+
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).
|
|
4237
5046
|
|
|
4238
|
-
|
|
5047
|
+
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.
|
|
4239
5048
|
|
|
4240
|
-
|
|
4241
|
-
|
|
4242
|
-
|
|
5049
|
+
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`).
|
|
5050
|
+
|
|
5051
|
+
For example, to list only errors:
|
|
4243
5052
|
|
|
4244
5053
|
```shell
|
|
4245
|
-
--
|
|
5054
|
+
ascli config ascp logs diagnostics /path/to/folder --select=@json:'{"severity":"error"}'
|
|
4246
5055
|
```
|
|
4247
5056
|
|
|
4248
|
-
|
|
4249
|
-
The list of known protocol errors and retry level can be listed:
|
|
5057
|
+
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:
|
|
4250
5058
|
|
|
4251
|
-
|
|
4252
|
-
|
|
4253
|
-
|
|
5059
|
+
| Column | Value |
|
|
5060
|
+
|------------------|--------------------------------------------------------------------------------------------------------------------|
|
|
5061
|
+
| `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`. |
|
|
5062
|
+
| `transport` | `ssh` if `Session Start` has `tcp_port`, `wss` if it has `wss_port`. |
|
|
5063
|
+
| `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. |
|
|
5064
|
+
| `proxy` | Address of the proxy (`proxy_ip` of `Session Params`), absent if there is none. |
|
|
5065
|
+
| `fips` | `true` or `false` (`fips_enabled` of `Session Params`). |
|
|
4254
5066
|
|
|
4255
|
-
|
|
5067
|
+
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`).
|
|
4256
5068
|
|
|
4257
|
-
|
|
4258
|
-
ascli ... --transfer.wss=true --transfer.resume.iter_max=20
|
|
4259
|
-
ascli ... --transfer.spawn_delay_sec=2.5 --transfer.multi_incr_udp=false
|
|
4260
|
-
```
|
|
5069
|
+
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`.
|
|
4261
5070
|
|
|
4262
|
-
|
|
4263
|
-
|
|
5071
|
+
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`.
|
|
5072
|
+
|
|
5073
|
+
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`).
|
|
5074
|
+
|
|
5075
|
+
Command `records` gives the log lines parsed into records, with the field names of the log lines, to filter them with `--out.query` (JMESPath):
|
|
5076
|
+
|
|
5077
|
+
| Record | Log lines |
|
|
5078
|
+
|-------------|-------------------------------------------------------------------------------------------------|
|
|
5079
|
+
| `samples` | `Receiver bl` or `Sender bl` line, with the `DS Qs` line that follows it in field `DS`. |
|
|
5080
|
+
| `sessions` | `Session Start`, `Session Params`, `Session Stop` and `Session Statistics` lines of a session, and lines of the process about it (see below). |
|
|
5081
|
+
| `transfers` | `Transfer Start` and `Transfer Stop` lines of a file. |
|
|
5082
|
+
|
|
5083
|
+
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.
|
|
5084
|
+
Values are numbers when the log value is a number: rates in bps, durations in ms, s or µs, and percentages without `%`.
|
|
5085
|
+
`Session Stop` and `Transfer Stop` have the fields of `Session Start` and `Transfer Start`, with their final values.
|
|
5086
|
+
When several log files are read, field `log_file` gives the log file of each record.
|
|
5087
|
+
Field `cookie` of `Session Params` is never output.
|
|
5088
|
+
|
|
5089
|
+
A session record also has the fields of these lines of the process (`ascp`), when the log has them:
|
|
5090
|
+
|
|
5091
|
+
| Field | Log line |
|
|
5092
|
+
|----------------------------------------------------------------|-------------------------------------------------------------------------------------------------------|
|
|
5093
|
+
| `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. |
|
|
5094
|
+
| `pMTU`, `start_brtt` | `Measured pMTU: <N> Bytes, start_brtt: <N> ms`. |
|
|
5095
|
+
| `datagram_size`, `block_size`, `path_mtu` | `datagram size <N>B, block size <N>B, path MTU <N>B` (no `path_mtu` in old versions). |
|
|
5096
|
+
| `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. |
|
|
5097
|
+
|
|
5098
|
+
For example, samples where the calculated rate is lower than the target rate, and sessions with loss of control messages from the receiver:
|
|
4264
5099
|
|
|
4265
5100
|
```shell
|
|
4266
|
-
--
|
|
5101
|
+
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}'
|
|
5102
|
+
ascli config ascp logs records sessions /path/to/folder --out.query='[?rcvr_ctl.lost_pct > `1`]'
|
|
4267
5103
|
```
|
|
4268
5104
|
|
|
4269
|
-
|
|
5105
|
+
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`):
|
|
4270
5106
|
|
|
4271
|
-
|
|
5107
|
+
```shell
|
|
5108
|
+
ascli config ascp logs fields samples
|
|
5109
|
+
ascli config ascp logs fields sessions
|
|
5110
|
+
ascli config ascp logs fields transfers
|
|
5111
|
+
```
|
|
4272
5112
|
|
|
4273
5113
|
> [!NOTE]
|
|
4274
5114
|
> 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`.
|
|
@@ -4451,6 +5291,10 @@ So, for example:
|
|
|
4451
5291
|
|
|
4452
5292
|
#### Agent: Connect Client
|
|
4453
5293
|
|
|
5294
|
+
> **Note:** IBM Aspera Connect will be deprecated in 2027.
|
|
5295
|
+
> Use [IBM Aspera for Desktop](#agent-desktop-client) instead: `--transfer=desktop`.
|
|
5296
|
+
> `ascli` displays a warning when the `connect` agent is used.
|
|
5297
|
+
|
|
4454
5298
|
By specifying option: `--transfer=connect`, `ascli` will start transfers using the locally installed **IBM Aspera Connect Client**.
|
|
4455
5299
|
There are no specific parameters for option `transfer`.
|
|
4456
5300
|
|
|
@@ -4467,7 +5311,7 @@ This is especially useful for direct node-to-node transfers.
|
|
|
4467
5311
|
Parameters provided in option `transfer` are:
|
|
4468
5312
|
|
|
4469
5313
|
| Field | Type | Description |
|
|
4470
|
-
|
|
5314
|
+
| -------- | ------ | ------------------------------------------------------------- |
|
|
4471
5315
|
| `password` | `String` | Password, secret, or bearer token.<br/>Required. |
|
|
4472
5316
|
| `root_id` | `String` | Root file ID. Mandatory only when `password` is a bearer token. |
|
|
4473
5317
|
| `url` | `String` | URL of the Node API.<br/>Required. |
|
|
@@ -4499,8 +5343,8 @@ By specifying option: `--transfer=httpgw`, `ascli` will start transfers using th
|
|
|
4499
5343
|
Parameters provided in option `transfer` are:
|
|
4500
5344
|
|
|
4501
5345
|
| Field | Type | Description |
|
|
4502
|
-
|
|
4503
|
-
| `api_version` | `String` | Force use of a specific API version.<br/>Allowed values: `v1`, `v2`.<br/>Default: `v2`. |
|
|
5346
|
+
| ----------------- | ------------ | ------------------------------------------- |
|
|
5347
|
+
| `api_version` | `Enum[String]` | Force use of a specific API version.<br/>Allowed values: `v1`, `v2`.<br/>Default: `v2`. |
|
|
4504
5348
|
| `synchronous` | `Bool` | Wait for acknowledgment after each message.<br/>Default: `false`. |
|
|
4505
5349
|
| `upload_chunk_size` | `Integer` | Size in bytes of each upload chunk.<br/>Default: `64000`. |
|
|
4506
5350
|
| `url` | `String` | URL of the HTTP Gateway.<br/>Required. |
|
|
@@ -4524,7 +5368,9 @@ Set option `transfer` to `transferd`.
|
|
|
4524
5368
|
Options for `transfer` are:
|
|
4525
5369
|
|
|
4526
5370
|
| Field | Type | Description |
|
|
4527
|
-
|
|
5371
|
+
| ------- | ------ | -------------------------------------------------------------------------------- |
|
|
5372
|
+
| `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. |
|
|
5373
|
+
| `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
5374
|
| `start` | `Bool` | Start a new daemon instance.<br/>Default: `true`. |
|
|
4529
5375
|
| `stop` | `Bool` | Stop the daemon when `ascli` exits.<br/>Default: `true`. |
|
|
4530
5376
|
| `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 +5414,165 @@ On Windows the compilation may fail for various reasons (3.1.1):
|
|
|
4568
5414
|
|
|
4569
5415
|
<!-- spellchecker: enable -->
|
|
4570
5416
|
|
|
5417
|
+
#### Transfer Daemon as a system service
|
|
5418
|
+
|
|
5419
|
+
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`).
|
|
5420
|
+
`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.
|
|
5421
|
+
|
|
5422
|
+
Commands are in `transferd service` (plugin [`transferd`](#plugin-transferd-transfer-daemon)):
|
|
5423
|
+
|
|
5424
|
+
| Command | Action |
|
|
5425
|
+
|-------------|--------|
|
|
5426
|
+
| `spec` | Show the schema of the configuration file of the daemon (`transferd.json`). Works on any system. |
|
|
5427
|
+
| `install` | Install the SDK if it is missing, then do `configure`. |
|
|
5428
|
+
| `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. |
|
|
5429
|
+
| `status` | Show the version, the state of the service, the endpoint and whether it listens. The API key is never shown. |
|
|
5430
|
+
| `uninstall` | Stop and remove the service. With `purge` set to `true` in `service`, also remove the configuration file and the log folder. |
|
|
5431
|
+
| `use` | Switch to an installed version of the SDK and restart the service (see below). |
|
|
5432
|
+
| `versions` | List the installed versions of the SDK (see below). |
|
|
5433
|
+
|
|
5434
|
+
Except `spec` and `versions`, commands take the optional **last** positional argument `CONFIG`: a `Hash` ([Extended Value](#extended-value-syntax)) with two optional sections:
|
|
5435
|
+
|
|
5436
|
+
- `service`: how the service is installed.
|
|
5437
|
+
- `config`: content of `transferd.json`.
|
|
5438
|
+
|
|
5439
|
+
```json
|
|
5440
|
+
{
|
|
5441
|
+
"service": {
|
|
5442
|
+
"user": "asperadaemon"
|
|
5443
|
+
},
|
|
5444
|
+
"config": {
|
|
5445
|
+
"address": "127.0.0.1",
|
|
5446
|
+
"port": 55002,
|
|
5447
|
+
"log_directory": "/var/log/aspera-transferd",
|
|
5448
|
+
"workers": {"max_concurrent": 10},
|
|
5449
|
+
"authentication": {"enabled": true}
|
|
5450
|
+
}
|
|
5451
|
+
}
|
|
5452
|
+
```
|
|
5453
|
+
|
|
5454
|
+
Parameters of section `service`:
|
|
5455
|
+
|
|
5456
|
+
| Field | Type | Description |
|
|
5457
|
+
| ----------- | ------------- | -------------------------------------------------------------------------------- |
|
|
5458
|
+
| `after` | `Array[String]` | Units that shall be started before the daemon (`After=` in the unit).<br/>Default: `["network.target"]`. |
|
|
5459
|
+
| `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. |
|
|
5460
|
+
| `group` | `String` | Group that runs the daemon. Defaults to the primary group of `user`. |
|
|
5461
|
+
| `name` | `String` | Name of the service. The unit file is `<name>.service`.<br/>Default: `aspera-transferd`. |
|
|
5462
|
+
| `purge` | `Bool` | Used by `uninstall`. Also remove the configuration file and the log folder.<br/>Default: `false`. |
|
|
5463
|
+
| `unit_dir` | `String` | Folder where the unit file is created.<br/>Default: `/etc/systemd/system`. |
|
|
5464
|
+
| `user` | `String` | Account that runs the daemon. It must exist, it is not created.<br/>Default: `asperadaemon`. |
|
|
5465
|
+
| `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. |
|
|
5466
|
+
|
|
5467
|
+
Section `config` follows the JSON schema of the daemon, displayed with:
|
|
5468
|
+
|
|
5469
|
+
```shell
|
|
5470
|
+
ascli transferd service spec
|
|
5471
|
+
```
|
|
5472
|
+
|
|
5473
|
+
| Field | Type | Description |
|
|
5474
|
+
| ---------------------------------------- | ------------- | -------------------------------------------------------------------------------- |
|
|
5475
|
+
| `$schema` | `String` | Optional URI or path of this schema, used by editors for completion and validation. Ignored by transferd. |
|
|
5476
|
+
| `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`. |
|
|
5477
|
+
| `api_time_settings` | `Hash` | Keepalive and connection lifetime settings of the gRPC API server, in seconds. |
|
|
5478
|
+
| `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`. |
|
|
5479
|
+
| `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`. |
|
|
5480
|
+
| `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`. |
|
|
5481
|
+
| `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`. |
|
|
5482
|
+
| `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`. |
|
|
5483
|
+
| `authentication` | `Hash` | API key authentication of clients of the gRPC API. |
|
|
5484
|
+
| `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`. |
|
|
5485
|
+
| `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`. |
|
|
5486
|
+
| `fasp_management` | `Hash` | Management port on which the ascp processes started by transferd report transfer progress. |
|
|
5487
|
+
| `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`. |
|
|
5488
|
+
| `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`. |
|
|
5489
|
+
| `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`. |
|
|
5490
|
+
| `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. |
|
|
5491
|
+
| `fasp_runtime.extra_config` | `Array[Hash]` | Extra command line options added to the executables started for transfers. Does not apply to async. |
|
|
5492
|
+
| `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`. |
|
|
5493
|
+
| `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"]`. |
|
|
5494
|
+
| `fasp_runtime.force_version` | `String` | Accepted for backward compatibility. Has no effect. |
|
|
5495
|
+
| `fasp_runtime.log` | `Hash` | Default logging of ascp, for transfers whose request configuration does not set localLog or logLevel. Does not apply to async. |
|
|
5496
|
+
| `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`. |
|
|
5497
|
+
| `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`. |
|
|
5498
|
+
| `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`. |
|
|
5499
|
+
| `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. |
|
|
5500
|
+
| `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`. |
|
|
5501
|
+
| `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`. |
|
|
5502
|
+
| `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`. |
|
|
5503
|
+
| `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`. |
|
|
5504
|
+
| `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`. |
|
|
5505
|
+
| `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`. |
|
|
5506
|
+
| `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`. |
|
|
5507
|
+
| `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`. |
|
|
5508
|
+
| `tls` | `Hash` | TLS for the gRPC API. When enabled, clients must connect using TLS. |
|
|
5509
|
+
| `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`. |
|
|
5510
|
+
| `tls.enabled` | `Bool` | Enables TLS. certificate and key are then required.<br/>Default: `false`. |
|
|
5511
|
+
| `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`. |
|
|
5512
|
+
| `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`. |
|
|
5513
|
+
| `workers` | `Hash` | Transfer execution and retention. |
|
|
5514
|
+
| `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`. |
|
|
5515
|
+
| `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`. |
|
|
5516
|
+
| `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`. |
|
|
5517
|
+
|
|
5518
|
+
The configuration is checked before anything is written:
|
|
5519
|
+
|
|
5520
|
+
- Keys not given keep their value in the existing `transferd.json` (deep merge), and a key set to `null` is removed.
|
|
5521
|
+
- 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.
|
|
5522
|
+
The daemon itself ignores unknown keys silently.
|
|
5523
|
+
- The section `fasp_runtime` is computed from the SDK folder, and can be overridden.
|
|
5524
|
+
- 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.
|
|
5525
|
+
The file is written in clear text with mode `0640`, owner `user:group`.
|
|
5526
|
+
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:'...'`.
|
|
5527
|
+
|
|
5528
|
+
Requirements:
|
|
5529
|
+
|
|
5530
|
+
- `systemd` on Linux only.
|
|
5531
|
+
On other systems, or without `systemctl`, commands fail with a message (only `spec` and `--dry-run` work everywhere).
|
|
5532
|
+
- 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`.
|
|
5533
|
+
- The account (`asperadaemon` by default) is **not** created by `ascli`.
|
|
5534
|
+
If it does not exist, the command fails and shows the command to create it:
|
|
5535
|
+
`useradd --system --no-create-home --shell /usr/sbin/nologin asperadaemon`.
|
|
5536
|
+
This is the account used by other Aspera products on the same host, so that files have the same owner.
|
|
5537
|
+
- 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).
|
|
5538
|
+
|
|
5539
|
+
Example:
|
|
5540
|
+
|
|
5541
|
+
```shell
|
|
5542
|
+
sudo ascli transferd service install --sdk-folder=/opt/aspera/transferd/current @json:'{"config":{"port":55002,"authentication":{"enabled":true}}}'
|
|
5543
|
+
```
|
|
5544
|
+
|
|
5545
|
+
```shell
|
|
5546
|
+
ascli transferd service configure --dry-run=yes @json:'{"config":{"log_level":"debug"}}'
|
|
5547
|
+
```
|
|
5548
|
+
|
|
5549
|
+
```shell
|
|
5550
|
+
sudo ascli transferd service status
|
|
5551
|
+
```
|
|
5552
|
+
|
|
5553
|
+
```shell
|
|
5554
|
+
sudo ascli transferd service uninstall @json:'{"service":{"purge":true}}'
|
|
5555
|
+
```
|
|
5556
|
+
|
|
5557
|
+
##### Versions side by side and rollback
|
|
5558
|
+
|
|
5559
|
+
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:
|
|
5560
|
+
|
|
5561
|
+
```text
|
|
5562
|
+
/opt/aspera/transferd/1.1.9
|
|
5563
|
+
/opt/aspera/transferd/1.1.10
|
|
5564
|
+
/opt/aspera/transferd/current -> 1.1.10
|
|
5565
|
+
```
|
|
5566
|
+
|
|
5567
|
+
- `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`.
|
|
5568
|
+
If the installation fails, then the link is set back to the previous version.
|
|
5569
|
+
- The unit and `transferd.json` refer to `current`: switching the link and restarting the service is enough to change the version.
|
|
5570
|
+
- `service versions` lists the installed versions and the one in use.
|
|
5571
|
+
- `service use <VERSION>` switches the link and restarts the service.
|
|
5572
|
+
If the service does not start, then the link is set back to the previous version and the service is restarted.
|
|
5573
|
+
|
|
5574
|
+
Any other folder name is used as is, with no link.
|
|
5575
|
+
|
|
4571
5576
|
### Transfer Specification
|
|
4572
5577
|
|
|
4573
5578
|
Some commands lead to file transfer (upload/download).
|
|
@@ -4656,7 +5661,7 @@ The description gives the supported agents, if not all, and the corresponding `a
|
|
|
4656
5661
|
#### Transfer Specification Reference
|
|
4657
5662
|
|
|
4658
5663
|
| ID | Name |
|
|
4659
|
-
|
|
5664
|
+
| -- | --------- |
|
|
4660
5665
|
| A | Direct |
|
|
4661
5666
|
| C | Connect |
|
|
4662
5667
|
| D | Desktop |
|
|
@@ -4665,61 +5670,61 @@ The description gives the supported agents, if not all, and the corresponding `a
|
|
|
4665
5670
|
| T | Transferd |
|
|
4666
5671
|
|
|
4667
5672
|
| Field | Type | Description |
|
|
4668
|
-
|
|
5673
|
+
| ------------------------------ | --------------- | -------------------------------------------------------------------------------- |
|
|
4669
5674
|
| `apply_local_docroot` | `Bool` | Apply local docroot to source paths.<br/>(A, T)<br/>(`--apply-local-docroot`) |
|
|
4670
5675
|
| `authentication` | `String` | Set to `token` for SSH bypass keys, else password asked if not provided.<br/>(C) |
|
|
4671
|
-
| `
|
|
4672
|
-
| `
|
|
5676
|
+
| `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}`) |
|
|
5677
|
+
| `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) |
|
|
5678
|
+
| `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
5679
|
| `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
5680
|
| `cookie` | `String` | Metadata for transfer specified by application.<br/>(env:`ASPERA_SCP_COOKIE`) |
|
|
4676
5681
|
| `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
5682
|
| `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
5683
|
| `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
5684
|
| `destination_root` | `String` | Destination root directory.<br/>Required. |
|
|
5685
|
+
| `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
5686
|
| `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}`) |
|
|
5687
|
+
| `direction` | `Enum[String]` | Direction of transfer (on client side).<br/>Required.<br/>Allowed values: `send`, `receive`.<br/>(`--mode=(conversion){enum}`) |
|
|
4683
5688
|
| `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
5689
|
| `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
5690
|
| `fail_bad_filepass` | `Bool` | Fail on bad file decryption passphrase.<br/>(A, T)<br/>(`--fail-bad-filepass`) |
|
|
4686
5691
|
| `fasp_port` | `Integer` | Specifies fasp (UDP) port.<br/>Default: `33001`.<br/>(`-O {integer}`) |
|
|
4687
5692
|
| `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}`) |
|
|
5693
|
+
| `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
5694
|
| `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}`) |
|
|
5695
|
+
| `http_fallback_port` | `Integer` | Specifies HTTP port when no cipher is used.<br/>(`-t {integer}`) |
|
|
4691
5696
|
| `https_fallback_port` | `Integer` | Specifies HTTPS port when cipher is used.<br/>(`-t {integer}`) |
|
|
4692
5697
|
| `icos` | `Hash` | Configuration parameters for IBM Cloud Object Storage (ICOS).<br/>(T) |
|
|
4693
5698
|
| `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
5699
|
| `lock_min_rate` | `Bool` | n/a<br/>(C) |
|
|
5700
|
+
| `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
5701
|
| `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
5702
|
| `lock_target_rate` | `Bool` | n/a<br/>(C) |
|
|
5703
|
+
| `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
5704
|
| `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
5705
|
| `min_rate_kbps` | `Integer` | Set the minimum transfer rate in kilobits per second.<br/>Default: `0`.<br/>(`-m {integer}`) |
|
|
4701
5706
|
| `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
5707
|
| `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}`) |
|
|
5708
|
+
| `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
5709
|
| `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}`) |
|
|
5710
|
+
| `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
5711
|
| `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
5712
|
| `paths` | `Array` | Array of path to the source (required) and a path to the destination (optional).<br/>Required. |
|
|
4708
5713
|
| `precalculate_job_size` | `Bool` | Specifies whether to precalculate the job size.<br/>(`--precalculate-job-size / --precalculate-disable`) |
|
|
4709
5714
|
| `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}`) |
|
|
5715
|
+
| `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
5716
|
| `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}`) |
|
|
5717
|
+
| `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
5718
|
| `preserve_file_owner_gid` | `Bool` | Preserve the group ID for a file owner.<br/>(A, T)<br/>(`--preserve-file-owner-gid`) |
|
|
4714
5719
|
| `preserve_file_owner_uid` | `Bool` | Preserve the user ID for a file owner.<br/>(A, T)<br/>(`--preserve-file-owner-uid`) |
|
|
4715
5720
|
| `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}`) |
|
|
5721
|
+
| `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}`) |
|
|
5722
|
+
| `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
5723
|
| `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
5724
|
| `preserve_times` | `Bool` | Preserve file timestamps.<br/>(A, N, T)<br/>(`-p`) |
|
|
4720
5725
|
| `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
|
-
| `
|
|
4722
|
-
| `
|
|
5726
|
+
| `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}`) |
|
|
5727
|
+
| `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
5728
|
| `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
5729
|
| `remote_host` | `String` | IP or fully qualified domain name (FQDN) of the remote server.<br/>Required.<br/>(`--host={string}`) |
|
|
4725
5730
|
| `remote_password` | `String` | SSH session password.<br/>(env:`ASPERA_SCP_PASS`) |
|
|
@@ -4729,27 +5734,27 @@ The description gives the supported agents, if not all, and the corresponding `a
|
|
|
4729
5734
|
| `remove_empty_source_dir` | `Bool` | Remove empty source subdirectories and remove the source directory itself, if empty.<br/>(T) |
|
|
4730
5735
|
| `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
5736
|
| `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}`) |
|
|
5737
|
+
| `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
5738
|
| `retry_duration` | `Integer, String` | Specifies how long to wait before retrying transfer (e.g. `5min`).<br/>(T) |
|
|
4734
5739
|
| `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
5740
|
| `skip_duplicate_check` | `Bool` | Don't check for duplicate files at the destination.<br/>(A, T)<br/>(`--skip-dir-traversal-dupes`) |
|
|
4736
5741
|
| `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
5742
|
| `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
|
-
| `
|
|
5743
|
+
| `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
5744
|
| `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}`) |
|
|
5745
|
+
| `src_base64` | `String` | The folder name below which the directory structure is preserved (base64 encoded).<br/>(A, T)<br/>(`--src-base64={string}`) |
|
|
4741
5746
|
| `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
5747
|
| `ssh_port` | `Integer` | Specifies SSH (TCP) port.<br/>Default: `direct:22, other:33001`.<br/>(`-P {integer}`) |
|
|
5748
|
+
| `ssh_private_key` | `String` | Private key used for SSH authentication.<br/>Shall look like: -----BEGIN RSA PRIV4TE KEY-----\nMII...<br/>Note the JSON encoding: \n for newlines.<br/>(A, T)<br/>(env:`ASPERA_SCP_KEY`) |
|
|
4743
5749
|
| `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
5750
|
| `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-----\nMII...<br/>Note the JSON encoding: \n for newlines.<br/>(A, T)<br/>(env:`ASPERA_SCP_KEY`) |
|
|
4746
5751
|
| `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}`) |
|
|
5752
|
+
| `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
5753
|
| `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}`) |
|
|
5754
|
+
| `tags64` | `String` | Base64 string for `tags`.<br/>(A, T)<br/>(`--tags64={string}`) |
|
|
5755
|
+
| `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
5756
|
| `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
5757
|
| `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
5758
|
| `title` | `String` | Title of the transfer.<br/>(C, N, T) |
|
|
4754
5759
|
| `token` | `String` | Authorization token. Type is Bearer, Basic or ATM.<br/>(env:`ASPERA_SCP_TOKEN`) |
|
|
4755
5760
|
| `use_ascp4` | `Bool` | Specify version of protocol. `ascp4` will be deprecated.<br/>Default: `false`.<br/>(A, N, T) |
|
|
@@ -5563,7 +6568,7 @@ If the transfer user has no docroot and the transfer does not use a token, you c
|
|
|
5563
6568
|
```text
|
|
5564
6569
|
ascli -h
|
|
5565
6570
|
NAME
|
|
5566
|
-
ascli -- a command line tool for Aspera Applications (v4.
|
|
6571
|
+
ascli -- a command line tool for Aspera Applications (v4.29.1)
|
|
5567
6572
|
|
|
5568
6573
|
SYNOPSIS
|
|
5569
6574
|
ascli [GLOBAL_OPTIONS] <command> [OPTIONS] [ARGS]
|
|
@@ -5574,6 +6579,7 @@ DESCRIPTION
|
|
|
5574
6579
|
execute: ascli conf doc
|
|
5575
6580
|
or visit: https://ibm.biz/ascli-doc
|
|
5576
6581
|
source repo: https://github.com/IBM/aspera-cli
|
|
6582
|
+
AI assistants: ascli config commands, https://ibm.github.io/aspera-cli/llms.txt
|
|
5577
6583
|
|
|
5578
6584
|
ENVIRONMENT VARIABLES
|
|
5579
6585
|
Any option can be set as an environment variable, refer to the manual
|
|
@@ -5619,7 +6625,7 @@ OPTIONS: global
|
|
|
5619
6625
|
-h, --help Show this message
|
|
5620
6626
|
--show-config Display parameters used for the provided action
|
|
5621
6627
|
-v, --version Display version
|
|
5622
|
-
--ui=HASH User interface (dot-notation: mode, command)
|
|
6628
|
+
--ui=HASH User interface (dot-notation: mode, web_auth, hidden_silent, command)
|
|
5623
6629
|
--invalid-characters=VALUE Replacement character and invalid filename characters
|
|
5624
6630
|
--log-level=ENUM Log level
|
|
5625
6631
|
--log-format=VALUE Log formatter
|
|
@@ -5628,6 +6634,7 @@ OPTIONS: global
|
|
|
5628
6634
|
--security=HASH Security restrictions (dot-notation: level, allowed_paths)
|
|
5629
6635
|
--lock-port=INT Prevent dual execution of a command, e.g. in cron
|
|
5630
6636
|
--once-only=yes|no Process only new items (some commands)
|
|
6637
|
+
--dry-run=yes|no Do not perform changes, only show what would be done
|
|
5631
6638
|
--log-secrets=yes|no Show passwords in logs
|
|
5632
6639
|
--temp=HASH Temporary files (dot-notation: folder, clean, expiry)
|
|
5633
6640
|
--clean-temp=yes|no Cleanup temporary files on exit (deprecated after 4.27.5: use --temp.clean)
|
|
@@ -5643,6 +6650,7 @@ OPTIONS: global
|
|
|
5643
6650
|
--fpac=VALUE Proxy auto configuration script
|
|
5644
6651
|
--proxy-credentials=LIST HTTP proxy credentials for fpac: user, password
|
|
5645
6652
|
--sql=VALUE SQL suffix appended to sqlite3 queries for admin subcommands (e.g. WHERE clause)
|
|
6653
|
+
--ascp-logs=HASH Ascp: log analysis (dot-notation: period, zero_bytes, mtu, resolve, thresholds, timezone, health_minutes, remote_max_size)
|
|
5646
6654
|
-P, --preset=VALUE Load the named option preset from current config file
|
|
5647
6655
|
--version-check-days=INT Period in days to check new version (zero to disable)
|
|
5648
6656
|
--plugin-folder=VALUE Folder where to find additional plugins
|
|
@@ -5655,9 +6663,6 @@ OPTIONS: global
|
|
|
5655
6663
|
--cache-tokens=yes|no Save and reuse OAuth tokens
|
|
5656
6664
|
--expand-mounts=yes|no Commands: list commands of sub-trees provided by another plugin
|
|
5657
6665
|
-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
6666
|
--insecure=yes|no HTTP/S: Do not validate any certificate
|
|
5662
6667
|
--ignore-certificate=LIST HTTP/S: Do not validate certificate for these URLs
|
|
5663
6668
|
--warn-insecure=yes|no HTTP/S: Issue a warning if certificate is ignored
|
|
@@ -5667,6 +6672,7 @@ OPTIONS: global
|
|
|
5667
6672
|
--query=HASH Additional filter for for some commands (list/delete)
|
|
5668
6673
|
--bulk=yes|no Bulk operation (only some)
|
|
5669
6674
|
--bfail=yes|no Bulk operation error handling
|
|
6675
|
+
--poll=HASH Repeat a read-only command (dot-notation: interval, max, timeout, until, show, errors)
|
|
5670
6676
|
--ts=HASH Override transfer spec values
|
|
5671
6677
|
--to-folder=VALUE Destination folder for transferred files
|
|
5672
6678
|
--sources=VALUE How list of transferred files is provided (@args,@ts,Array)
|
|
@@ -5689,6 +6695,7 @@ PLUGINS
|
|
|
5689
6695
|
preview Preview
|
|
5690
6696
|
server HSTS Fasp/SSH
|
|
5691
6697
|
shares Shares
|
|
6698
|
+
transferd Transfer Daemon
|
|
5692
6699
|
|
|
5693
6700
|
|
|
5694
6701
|
```
|
|
@@ -5699,25 +6706,6 @@ Bulk creation and deletion of resources are possible using option `bulk` (`yes`,
|
|
|
5699
6706
|
In that case, the operation expects an `Array` of `Hash` instead of a simple `Hash` using the [Extended Value](#extended-value-syntax) syntax.
|
|
5700
6707
|
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
6708
|
|
|
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
6709
|
### Plugins
|
|
5722
6710
|
|
|
5723
6711
|
`ascli` uses a plugin mechanism.
|
|
@@ -5761,11 +6749,82 @@ ascli config plugins create foo .
|
|
|
5761
6749
|
Created ./foo.rb
|
|
5762
6750
|
```
|
|
5763
6751
|
|
|
5764
|
-
|
|
5765
6752
|
```shell
|
|
5766
6753
|
ascli --plugin-folder=. foo
|
|
5767
6754
|
```
|
|
5768
6755
|
|
|
6756
|
+
#### Writing a plugin
|
|
6757
|
+
|
|
6758
|
+
A plugin is a Ruby file in a plugin folder (option `plugin_folder`, or folder `plugins` of the configuration folder).
|
|
6759
|
+
|
|
6760
|
+
- **Name**: the file name is the plugin name, which is the first command, e.g. file `my_app.rb` for command `my_app`.
|
|
6761
|
+
The file defines class `Aspera::Cli::Plugins::<Class>`, the name in CamelCase (`MyApp`), subclass of:
|
|
6762
|
+
- `Base`: no common option.
|
|
6763
|
+
- `BasicAuth` (`aspera/cli/plugins/basic_auth`): options `url`, `username`, `password`, method `basic_auth_api` returns a REST client with HTTP Basic authentication.
|
|
6764
|
+
- `Oauth` (`aspera/cli/plugins/oauth`): options of `BasicAuth`, and `auth` (default `jwt`), `client_id`, `client_secret`, `redirect_uri`, `private_key`, `passphrase`.
|
|
6765
|
+
- **Requires**: the plugin requires the files of the gem that it uses, e.g. `require 'aspera/cli/plugins/base'` (the `lib` folder of the gem is in the Ruby load path).
|
|
6766
|
+
Built-in plugins load only what they use: a class of the gem (for example `Plugins::Oauth`, `Rest::Client`) may not be loaded yet when the plugin is read (`NameError: uninitialized constant`).
|
|
6767
|
+
- **Options**: `option :<name>, description: '...'` (optional: `default:`, `allowed:` a type or a list of values), value read with `options.get_option(:<name>)` (`mandatory: true` to require it).
|
|
6768
|
+
`use_options <Module>` adds the options of a module, e.g. `use_options OauthWebOptions` (`client_id`, `client_secret`, `redirect_uri`) for the OAuth web flow only, without the other options of `Oauth`.
|
|
6769
|
+
- **Commands**: `command :<name>, description: '...'`, inside `commands_under :<name> do ... end` for sub-commands.
|
|
6770
|
+
Positional arguments: `arguments: [{name: :<name>, description: '...'}]` (optional: `mandatory: false`, `default:`, `type: Hash`, `multiple: true`).
|
|
6771
|
+
`read_only: true` for a command that changes nothing (allowed with option `poll`).
|
|
6772
|
+
- **Actions**: the method `action_<command path>`, e.g. `action_item_show` for `item show`, receives the arguments as keyword arguments (and `**` for others).
|
|
6773
|
+
It returns a result, displayed according to option `format`: `Result::SingleObject.new(<Hash>)`, `Result::ObjectList.new(<Array of Hash>)`, `Result::Status.new('<text>')`, `Result::Nothing.new`.
|
|
6774
|
+
- **REST**: `Rest::Client.new(base_url:, auth:)` (`aspera/rest`), methods `read`, `create`, `update`, `delete` (JSON), and `call` for other cases:
|
|
6775
|
+
- `auth`: `{type: :basic, username:, password:}`, or `{type: :oauth2, grant_method: :web, client_id:, ...}` (see `lib/aspera/oauth/client`).
|
|
6776
|
+
Parameters `path_authorize` and `path_token` are paths from `base_url`, or absolute URLs, when the token is created on another host than the authorization page.
|
|
6777
|
+
Parameter `token_field` is the field of the token in the answer (default `access_token`), or a dot-separated path of a nested field, e.g. `authed_user.access_token` for a Slack user token.
|
|
6778
|
+
- Raw body, e.g. binary, sent as is: `call(operation: 'PUT', body: <String or IO>, headers: {'Content-Type' => '<MIME_TYPE>'})`.
|
|
6779
|
+
An `IO` (e.g. `File.open(path, 'rb')`) is streamed from its current position, without loading the file in memory.
|
|
6780
|
+
- **Errors**: raise `Cli::BadArgument` (wrong argument or option) or `Cli::Error`.
|
|
6781
|
+
For any other error, the location in the plugin (file and line) is logged at level `info`.
|
|
6782
|
+
- **Security**: a plugin is code: plugins from other folders than the gem are loaded at [Security Level](#security-level) `low` only.
|
|
6783
|
+
|
|
6784
|
+
Example: plugin `my_app` for a REST API with Basic authentication: `my_app info`, `my_app item list`, `my_app item show <ID>`.
|
|
6785
|
+
|
|
6786
|
+
```ruby
|
|
6787
|
+
# Plugin `my_app`, file `my_app.rb` in a plugin folder, class `MyApp`
|
|
6788
|
+
# Files of the gem used by the plugin (its `lib` folder is in the load path)
|
|
6789
|
+
require 'aspera/cli/plugins/basic_auth'
|
|
6790
|
+
|
|
6791
|
+
module Aspera
|
|
6792
|
+
module Cli
|
|
6793
|
+
module Plugins
|
|
6794
|
+
# Options `url`, `username` and `password` of `BasicAuth`
|
|
6795
|
+
class MyApp < BasicAuth
|
|
6796
|
+
application_name 'My Application'
|
|
6797
|
+
option :page_size, description: 'Number of items per page', allowed: Integer, default: 100
|
|
6798
|
+
|
|
6799
|
+
command :info, description: 'Show application information', read_only: true
|
|
6800
|
+
commands_under :item, description: 'Manage items' do
|
|
6801
|
+
command :list, description: 'List items', read_only: true
|
|
6802
|
+
command :show, description: 'Show an item', arguments: [{name: :id, description: 'Item identifier'}], read_only: true
|
|
6803
|
+
end
|
|
6804
|
+
|
|
6805
|
+
# Command `info`
|
|
6806
|
+
def action_info(**) = Result::SingleObject.new(api.read('info'))
|
|
6807
|
+
|
|
6808
|
+
# Command `item list`
|
|
6809
|
+
def action_item_list(**) = Result::ObjectList.new(api.read('items', {limit: options.get_option(:page_size)}))
|
|
6810
|
+
|
|
6811
|
+
# Command `item show <ID>`, with arguments as keyword arguments
|
|
6812
|
+
def action_item_show(id:, **) = Result::SingleObject.new(api.read("items/#{id}"))
|
|
6813
|
+
|
|
6814
|
+
private
|
|
6815
|
+
|
|
6816
|
+
# REST client of the application, with Basic authentication
|
|
6817
|
+
def api = @api ||= basic_auth_api
|
|
6818
|
+
end
|
|
6819
|
+
end
|
|
6820
|
+
end
|
|
6821
|
+
end
|
|
6822
|
+
```
|
|
6823
|
+
|
|
6824
|
+
```shell
|
|
6825
|
+
ascli --plugin-folder=<FOLDER> my_app item list --url=https://app.example.com/api --username=<USERNAME> --password=<PASSWORD> --page-size=10
|
|
6826
|
+
```
|
|
6827
|
+
|
|
5769
6828
|
### Plugins vs Transfer Agents
|
|
5770
6829
|
|
|
5771
6830
|
Plugins typically represent a specific remote application on which `ascli` can operate, while transfer agents are the underlying components that handle the actual data transfer.
|
|
@@ -5834,7 +6893,7 @@ It's up to the program to split arguments:
|
|
|
5834
6893
|
|
|
5835
6894
|
`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
6895
|
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)):
|
|
6896
|
+
(See `w32_cmdvector` in Ruby source [`win32.c`](https://github.com/ruby/ruby/blob/master/win32/win32.c#L1766)):
|
|
5838
6897
|
|
|
5839
6898
|
- Space characters: split arguments (space, tab, newline)
|
|
5840
6899
|
- Backslash: `\` escapes a single special character
|
|
@@ -6144,11 +7203,13 @@ To complete the setup, you must have:
|
|
|
6144
7203
|
|
|
6145
7204
|
#### Wizard Invocation
|
|
6146
7205
|
|
|
6147
|
-
The wizard accepts
|
|
7206
|
+
The wizard accepts an optional argument, a `Hash` with keys:
|
|
7207
|
+
|
|
7208
|
+
- `url`: The organization name or the full FQDN.
|
|
6148
7209
|
|
|
6149
|
-
-
|
|
7210
|
+
- `plugin`: Specify `aoc` to bypass automatic application detection.
|
|
6150
7211
|
|
|
6151
|
-
-
|
|
7212
|
+
- `preset`: Name of the preset to create.
|
|
6152
7213
|
|
|
6153
7214
|
If the URL is omitted, the wizard will prompt for it interactively.
|
|
6154
7215
|
|
|
@@ -6165,8 +7226,8 @@ Once saved in the UI, return to the terminal and press Enter.
|
|
|
6165
7226
|
```console
|
|
6166
7227
|
$ ascli config wizard
|
|
6167
7228
|
Using: Aspera on Cloud at https://<ORG_NAME>.ibmaspera.com
|
|
6168
|
-
|
|
6169
|
-
option:
|
|
7229
|
+
Private RSA key, e.g. @file:<path> (leave empty to generate):
|
|
7230
|
+
option: private_key>
|
|
6170
7231
|
Using existing key:
|
|
6171
7232
|
/home/john/.aspera/ascli/<PKEY_NAME>.pem
|
|
6172
7233
|
Please Log in as user john@example.com at: https://<ORG_NAME>.ibmaspera.com
|
|
@@ -6191,12 +7252,12 @@ Saving config file.
|
|
|
6191
7252
|
|
|
6192
7253
|
- **Custom Client Identification**:
|
|
6193
7254
|
By default, `ascli` uses a pre-registered global client ID.
|
|
6194
|
-
To create and use an organization-specific integration,
|
|
7255
|
+
To create and use an organization-specific integration, give the option `--use-generic-client=no` of plugin `aoc` to the wizard command.
|
|
6195
7256
|
|
|
6196
7257
|
- **Direct Plugin Targeting**: To limit detection to the `aoc` plugin and skip discovery, provide both the URL and plugin name:
|
|
6197
7258
|
|
|
6198
7259
|
```shell
|
|
6199
|
-
ascli config wizard
|
|
7260
|
+
ascli config wizard @: url=<ORG_NAME> plugin=aoc
|
|
6200
7261
|
```
|
|
6201
7262
|
|
|
6202
7263
|
#### Verifying the Configuration
|
|
@@ -6262,6 +7323,7 @@ To register with web-based authentication (auth=web):
|
|
|
6262
7323
|
|
|
6263
7324
|
> [!NOTE]
|
|
6264
7325
|
> 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.
|
|
7326
|
+
> See [Web login flow](#web-login-flow).
|
|
6265
7327
|
> For `ascli`, HTTP is required, and `12345` is the default port.
|
|
6266
7328
|
> The host of `redirect_uri` shall be loopback: `localhost`, an address of `127.0.0.0/8`, or `[::1]`.
|
|
6267
7329
|
|
|
@@ -6284,7 +7346,7 @@ updated: <AOC_ORG>
|
|
|
6284
7346
|
> [!NOTE]
|
|
6285
7347
|
> In above example, replace `https://<ORG_NAME>.ibmaspera.com` with your actual AoC URL.
|
|
6286
7348
|
|
|
6287
|
-
(This can also be done in one line using the command `config preset
|
|
7349
|
+
(This can also be done in one line using the command `config preset set <AOC_ORG> @: url=...`)
|
|
6288
7350
|
|
|
6289
7351
|
Define this [Option Preset](#option-preset) as default configuration for the `aoc` plugin:
|
|
6290
7352
|
|
|
@@ -6398,7 +7460,7 @@ To activate default use of JWT authentication for `ascli` using the [Option Pres
|
|
|
6398
7460
|
Execute:
|
|
6399
7461
|
|
|
6400
7462
|
```shell
|
|
6401
|
-
ascli config preset
|
|
7463
|
+
ascli config preset set <AOC_ORG> @: auth=jwt private_key=@val:@file:~/.aspera/ascli/<PKEY_NAME> username=someuser@example.com
|
|
6402
7464
|
```
|
|
6403
7465
|
|
|
6404
7466
|
> [!NOTE]
|
|
@@ -6518,7 +7580,7 @@ The following parameters are supported:
|
|
|
6518
7580
|
| other | Native | Other specific parameters depending on resource type. |
|
|
6519
7581
|
|
|
6520
7582
|
> [!NOTE]
|
|
6521
|
-
> Both `max` and `pmax` are processed
|
|
7583
|
+
> Both `max` and `pmax` are processed by `ascli` (see [option `--query`](#option---query-parameters-of-the-api)).
|
|
6522
7584
|
> `ascli` will return all values using paging if not provided.
|
|
6523
7585
|
> `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
7586
|
> (AoC allows a maximum page size of 1000).
|
|
@@ -6529,7 +7591,7 @@ The following parameters are supported:
|
|
|
6529
7591
|
> For example: `ascli aoc admin user list --query=help`
|
|
6530
7592
|
|
|
6531
7593
|
> [!TIP]
|
|
6532
|
-
>
|
|
7594
|
+
> Options `--out.query` and `--out.select` can also be used to further refine selection, refer to [Filtering results](#filtering-results).
|
|
6533
7595
|
|
|
6534
7596
|
Examples:
|
|
6535
7597
|
|
|
@@ -6785,7 +7847,7 @@ ascli aoc user settings modify <ID> @json:'{"value":"..."}'
|
|
|
6785
7847
|
> - **Application identity**: derived from the `client_id` used during authentication.
|
|
6786
7848
|
>
|
|
6787
7849
|
> 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`).
|
|
7850
|
+
> By default, `ascli` uses the pre-registered global `client_id` (see option `--use-generic-client` of plugin `aoc`).
|
|
6789
7851
|
|
|
6790
7852
|
#### Example: Create a sub access key in a `node`
|
|
6791
7853
|
|
|
@@ -6954,7 +8016,7 @@ In this example, a user has access to a workspace where two shared folders are l
|
|
|
6954
8016
|
First, set up the environment (skip if already done), see [AoC configuration: Using Wizard](#aoc-configuration-using-wizard):
|
|
6955
8017
|
|
|
6956
8018
|
```shell
|
|
6957
|
-
ascli config wizard https://sedemo.ibmaspera.com aoc aoc_sedemo --username=someuser@example.com
|
|
8019
|
+
ascli config wizard @: url=https://sedemo.ibmaspera.com plugin=aoc preset=aoc_sedemo --username=someuser@example.com
|
|
6958
8020
|
```
|
|
6959
8021
|
|
|
6960
8022
|
This creates the option preset `aoc_sedemo` to allow seamless command line access and sets it as default for Aspera on Cloud.
|
|
@@ -7241,7 +8303,7 @@ The `package_folder` option (`Hash`) controls how downloaded packages are organi
|
|
|
7241
8303
|
**Supported Fields**:
|
|
7242
8304
|
|
|
7243
8305
|
| Field | Type | Description |
|
|
7244
|
-
|
|
8306
|
+
| ----- | ------------- | -------------------------------------------------------------------------------- |
|
|
7245
8307
|
| `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
8308
|
| `inf` | `Bool` | If `true`, creates a `<ID>.info.json` sidecar file inside the folder containing package metadata.<br/>Default: `false`. |
|
|
7247
8309
|
| `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 +8785,7 @@ For instructions, refer to section `find` for plugin `node`.
|
|
|
7723
8785
|
|
|
7724
8786
|
```shell
|
|
7725
8787
|
admin analytics application_events
|
|
7726
|
-
admin analytics files organization '' <
|
|
8788
|
+
admin analytics files organization '' <ID>
|
|
7727
8789
|
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
8790
|
admin analytics transfers users --once-only=yes
|
|
7729
8791
|
admin application instance list
|
|
@@ -7731,8 +8793,8 @@ admin application instance list --query.aspera_app_type=files
|
|
|
7731
8793
|
admin application instance list --query.organization_apps=true
|
|
7732
8794
|
admin application membership list
|
|
7733
8795
|
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":"
|
|
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
|
|
8796
|
+
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":"/"}}'
|
|
8797
|
+
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
8798
|
admin ats access_key delete ak1ibmcloud
|
|
7737
8799
|
admin ats access_key list --fields=name,id
|
|
7738
8800
|
admin ats access_key node ak1ibmcloud --secret=<SECRET> browse /
|
|
@@ -7745,10 +8807,10 @@ admin bearer_token --out.level=data --out.secrets=yes
|
|
|
7745
8807
|
admin client list
|
|
7746
8808
|
admin client_access_key list
|
|
7747
8809
|
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 <
|
|
8810
|
+
admin client_registration_token delete <ID>
|
|
7749
8811
|
admin client_registration_token list
|
|
7750
8812
|
admin configuration_policy list
|
|
7751
|
-
admin configuration_policy show <
|
|
8813
|
+
admin configuration_policy show <ID>
|
|
7752
8814
|
admin contact list
|
|
7753
8815
|
admin dropbox list
|
|
7754
8816
|
admin dropbox_membership list
|
|
@@ -7756,7 +8818,7 @@ admin group list
|
|
|
7756
8818
|
admin group_membership list --fields=ALL --query=@json:'{"page":1,"per_page":50,"embed":"member","inherited":false,"workspace_id":11363,"sort":"name"}'
|
|
7757
8819
|
admin kms_profile list
|
|
7758
8820
|
admin network_policy list
|
|
7759
|
-
admin network_policy show <
|
|
8821
|
+
admin network_policy show <ID>
|
|
7760
8822
|
admin node bearer_token %name:my_node_name user:all
|
|
7761
8823
|
admin node do %name:my_node_name --secret=<AK_SECRET> browse /
|
|
7762
8824
|
admin node do %name:my_node_name --secret=<AK_SECRET> browse /folder_sub --node-api.cache=false
|
|
@@ -7764,8 +8826,8 @@ admin node do %name:my_node_name --secret=<AK_SECRET> delete /folder1
|
|
|
7764
8826
|
admin node do %name:my_node_name --secret=<AK_SECRET> delete /folder_sub
|
|
7765
8827
|
admin node do %name:my_node_name --secret=<AK_SECRET> mkdir /folder1
|
|
7766
8828
|
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":"
|
|
7768
|
-
admin node do %name:my_node_name --secret=<AK_SECRET> v3 access_key delete
|
|
8829
|
+
admin node do %name:my_node_name --secret=<AK_SECRET> v3 access_key create @json:'{"id":"test-sub-1","storage":{"path":"/folder_sub"}}'
|
|
8830
|
+
admin node do %name:my_node_name --secret=<AK_SECRET> v3 access_key delete test-sub-1
|
|
7769
8831
|
admin node do %name:my_node_name --secret=<AK_SECRET> v3 events
|
|
7770
8832
|
admin node do %name:my_node_name delete test_shared_folder
|
|
7771
8833
|
admin node do %name:my_node_name mkdir test_shared_folder
|
|
@@ -7790,12 +8852,15 @@ admin user preferences %name:my_user_email show
|
|
|
7790
8852
|
admin workspace dropbox %name:my_other_workspace list
|
|
7791
8853
|
admin workspace list
|
|
7792
8854
|
admin workspace shared_folder %name:my_other_workspace list
|
|
7793
|
-
admin workspace shared_folder %name:my_other_workspace member <
|
|
8855
|
+
admin workspace shared_folder %name:my_other_workspace member <ID> list
|
|
8856
|
+
admin workspace shared_folder %name:my_other_workspace node <ID> browse /
|
|
7794
8857
|
admin workspace_membership list
|
|
7795
8858
|
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 <
|
|
8859
|
+
automation workflow action <ID> create @: name=toto
|
|
7797
8860
|
automation workflow create @: name=test_workflow
|
|
7798
|
-
automation workflow delete <
|
|
8861
|
+
automation workflow delete <ID>
|
|
8862
|
+
automation workflow details <ID>
|
|
8863
|
+
automation workflow export <ID>
|
|
7799
8864
|
automation workflow list
|
|
7800
8865
|
automation workflow list --query.show_org_workflows=@val:true
|
|
7801
8866
|
automation workflow list --select.name=test_workflow --fields=id
|
|
@@ -7803,65 +8868,66 @@ bearer_token --out.level=data --out.secrets=yes
|
|
|
7803
8868
|
files bearer /
|
|
7804
8869
|
files bearer_token_node / --cache-tokens=no
|
|
7805
8870
|
files browse /
|
|
7806
|
-
files browse / --url
|
|
7807
|
-
files browse / --url
|
|
7808
|
-
files browse / --url
|
|
8871
|
+
files browse / --url=<PRIVATE_LINK_SHARED_FOLDER>
|
|
8872
|
+
files browse / --url=<PUBLIC_LINK_FOLDER_NO_PASS>
|
|
8873
|
+
files browse / --url=<PUBLIC_LINK_FOLDER_WITH_PASS> --password=<PUBLIC_LINK_FOLDER_PASSWORD>
|
|
7809
8874
|
files browse my_remote_file
|
|
7810
8875
|
files browse my_remote_folder
|
|
7811
8876
|
files browse my_remote_folder/
|
|
7812
|
-
files cat
|
|
7813
|
-
files delete /
|
|
7814
|
-
files download --to-folder=.
|
|
7815
|
-
files download --transfer.agent=connect
|
|
7816
|
-
files download --transfer.agent=desktop
|
|
8877
|
+
files cat test-dst/test_file.bin
|
|
8878
|
+
files delete /test-src
|
|
8879
|
+
files download --to-folder=. test-dst/test_file.bin test-dst/test_file.bin
|
|
8880
|
+
files download --transfer.agent=connect test-dst/test_file.bin
|
|
8881
|
+
files download --transfer.agent=desktop test-dst/test_file.bin
|
|
7817
8882
|
files find /sample_video
|
|
7818
8883
|
files find /sample_video '\.partial$'
|
|
7819
8884
|
files find /sample_video @ruby:'->(f){f["type"].eql?("file")}'
|
|
7820
|
-
files mkdir /
|
|
8885
|
+
files mkdir /test-src
|
|
7821
8886
|
files modify /some_folder @: mount_point=false
|
|
7822
8887
|
files permission my_test_folder list
|
|
7823
|
-
files rename /some_folder
|
|
7824
|
-
files short_link /
|
|
7825
|
-
files short_link /
|
|
7826
|
-
files short_link /
|
|
7827
|
-
files short_link /
|
|
7828
|
-
files show %id:<
|
|
8888
|
+
files rename /some_folder test-dst
|
|
8889
|
+
files short_link /test-dst private create
|
|
8890
|
+
files short_link /test-dst private list
|
|
8891
|
+
files short_link /test-dst public create @: access_levels.0=mkdir access_levels.1=write --fields=id
|
|
8892
|
+
files short_link /test-dst public modify <AOC_SHORT_LINK_PUB_CREATE> @: access_levels=edit
|
|
8893
|
+
files show %id:<ID>
|
|
7829
8894
|
files show /
|
|
7830
|
-
files show
|
|
8895
|
+
files show test-dst/test_file.bin
|
|
7831
8896
|
files sync admin status /data/local_sync
|
|
7832
|
-
files sync pull /
|
|
8897
|
+
files sync pull /test-dst --to-folder=/data/local_sync @json:'{"reset":true,"transport":{"target_rate":my_bps}}'
|
|
7833
8898
|
files thumbnail my_test_folder/video_file.mpg
|
|
7834
8899
|
files thumbnail my_test_folder/video_file.mpg --query.text=true --query.double=true
|
|
7835
|
-
files transfer push /
|
|
7836
|
-
files upload --to-folder=/ test_file.bin --url
|
|
7837
|
-
files upload --to-folder=/
|
|
7838
|
-
files upload --to-folder=/
|
|
8900
|
+
files transfer push /test-src --to-folder=/test-dst test_file.bin
|
|
8901
|
+
files upload --to-folder=/ test_file.bin --url=<PUBLIC_LINK_FOLDER_NO_PASS>
|
|
8902
|
+
files upload --to-folder=/test-src test_file.bin
|
|
8903
|
+
files upload --to-folder=/test-src test_file.bin test_file.bin
|
|
7839
8904
|
files v3 info
|
|
7840
8905
|
gateway @: url=https://localhost:12347/aspera/faspex
|
|
7841
8906
|
organization
|
|
7842
8907
|
organization --format=image --fields=background_image_url --ui=text
|
|
7843
|
-
organization --url
|
|
7844
|
-
packages browse <
|
|
8908
|
+
organization --url=<PUBLIC_LINK_RECV_FROM_AOC_USER>
|
|
8909
|
+
packages browse <ID> /
|
|
7845
8910
|
packages list
|
|
7846
8911
|
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 <
|
|
7848
|
-
packages receive <
|
|
8912
|
+
packages receive <ID> --to-folder=.
|
|
8913
|
+
packages receive <ID> --to-folder=. /
|
|
7849
8914
|
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
8915
|
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}'
|
|
8916
|
+
packages receive ALL --url=<PUBLIC_LINK_RECV_FROM_AOC_USER> --to-folder=.
|
|
7851
8917
|
packages receive INIT --once-only=yes --query.dropbox_name=my_shared_inbox_name
|
|
7852
8918
|
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
8919
|
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
8920
|
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
|
|
7856
|
-
packages send @: 'name=package title' END test_file.bin --url
|
|
8921
|
+
packages send @: 'name=package title' END test_file.bin --url=<PUBLIC_LINK_SEND_AOC_USER> --password=<PUBLIC_LINK_SEND_USE_PASS>
|
|
8922
|
+
packages send @: 'name=package title' END test_file.bin --url=<PUBLIC_LINK_SEND_SHARED_INBOX>
|
|
7857
8923
|
packages send @: 'name=package title' recipients.0=my_username 'note=some notes' END test_file.bin
|
|
7858
8924
|
packages send @json:'{"name":"package title","recipients":["my_email_external"]}' --new-user-option.package_contact=true test_file.bin
|
|
7859
8925
|
packages shared_inboxes list
|
|
7860
8926
|
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 <
|
|
8927
|
+
packages shared_inboxes short_link public %name:my_shared_inbox_name delete <AOC_SHARED_INBOX_SHORT_LINK_CREATE>
|
|
7862
8928
|
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 <
|
|
7864
|
-
packages shared_inboxes short_link public %name:my_shared_inbox_name show <
|
|
8929
|
+
packages shared_inboxes short_link public %name:my_shared_inbox_name modify <AOC_SHARED_INBOX_SHORT_LINK_CREATE> @: password=<PUBLIC_LINK_FOLDER_PASSWORD>
|
|
8930
|
+
packages shared_inboxes short_link public %name:my_shared_inbox_name show <AOC_SHARED_INBOX_SHORT_LINK_CREATE>
|
|
7865
8931
|
packages shared_inboxes show %name:my_shared_inbox_name
|
|
7866
8932
|
packages show '%name:package title'
|
|
7867
8933
|
remind --username=my_user_email --url=https://aoc.example.com/path
|
|
@@ -7925,7 +8991,7 @@ Then, to register the key by default for the `ats` plugin, create a preset.
|
|
|
7925
8991
|
Execute:
|
|
7926
8992
|
|
|
7927
8993
|
```shell
|
|
7928
|
-
ascli config preset
|
|
8994
|
+
ascli config preset set <PRESET_NAME> @: ibm_api_key=<API_KEY>
|
|
7929
8995
|
```
|
|
7930
8996
|
|
|
7931
8997
|
```shell
|
|
@@ -7941,7 +9007,7 @@ aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee
|
|
|
7941
9007
|
```
|
|
7942
9008
|
|
|
7943
9009
|
```shell
|
|
7944
|
-
ascli config preset
|
|
9010
|
+
ascli config preset set <PRESET_NAME> @: instance=aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee
|
|
7945
9011
|
```
|
|
7946
9012
|
|
|
7947
9013
|
```shell
|
|
@@ -7958,7 +9024,7 @@ ascli ats api_key create --out.secrets=yes
|
|
|
7958
9024
|
```
|
|
7959
9025
|
|
|
7960
9026
|
```shell
|
|
7961
|
-
ascli config preset
|
|
9027
|
+
ascli config preset set <PRESET_NAME> @: ats_key=<ATS_KEY> ats_secret=<ATS_SECRET>
|
|
7962
9028
|
```
|
|
7963
9029
|
|
|
7964
9030
|
### ATS Access key creation parameters
|
|
@@ -8011,8 +9077,8 @@ The parameters provided to ATS for access key creation are the ones of [ATS API]
|
|
|
8011
9077
|
|
|
8012
9078
|
```shell
|
|
8013
9079
|
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":"
|
|
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":"
|
|
9080
|
+
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":"/"}}'
|
|
9081
|
+
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
9082
|
access_key delete ak2ibmcloud
|
|
8017
9083
|
access_key entitlement ak2ibmcloud
|
|
8018
9084
|
access_key list --fields=name,id
|
|
@@ -8059,7 +9125,7 @@ ascli server --url=ssh://hsts.example.com:33001 --username=john --ssh-keys=~/.ss
|
|
|
8059
9125
|
|
|
8060
9126
|
```shell
|
|
8061
9127
|
browse /
|
|
8062
|
-
browse / --password @none: --ssh-options.number_of_password_prompts=0 --ssh-keys=<
|
|
9128
|
+
browse / --password @none: --ssh-options.number_of_password_prompts=0 --ssh-keys=<SERV_KEY_PATH>
|
|
8063
9129
|
browse my_inside_folder/test_file.bin
|
|
8064
9130
|
browse my_upload_folder/target_hot
|
|
8065
9131
|
cp my_inside_folder/test_file.bin my_upload_folder/200KB.2
|
|
@@ -8084,6 +9150,7 @@ sync admin status /data/local_sync
|
|
|
8084
9150
|
sync pull my_inside_folder --to-folder=/data/local_sync @: name=serv_sync_pull_conf
|
|
8085
9151
|
sync pull my_inside_folder --to-folder=/data/local_sync @json:'{"name":"serv_sync_pull_conf","reset":true,"transport":{"target_rate":my_bps}}'
|
|
8086
9152
|
upload 'faux:///test.bin?1k' --to-folder=my_upload_folder
|
|
9153
|
+
upload 'faux:///test.bin?1m' --to-folder=my_upload_folder --ts.target_rate=500m
|
|
8087
9154
|
upload --sources=@ts --transfer.ascp_args=@list:,--file-list,file_list.txt --to-folder=my_inside_folder
|
|
8088
9155
|
upload --sources=@ts --transfer.ascp_args=@list:,--file-pair-list,file_pair_list.txt
|
|
8089
9156
|
upload --sources=@ts --ts=@json:'{"paths":[{"source":"test_file.bin","destination":"my_inside_folder/other_name_4"}]}' --transfer.agent=transferd
|
|
@@ -8169,6 +9236,23 @@ ascli server --ssh-options=@json:'{"use_agent": false}' ...
|
|
|
8169
9236
|
If one of the SSH private keys is passphrase-protected, then option `passphrase` can be used.
|
|
8170
9237
|
It is equivalent to setting both options `ssh_options.passphrase` and `ts.ssh_private_key_passphrase`.
|
|
8171
9238
|
|
|
9239
|
+
### Analyze `ascp` logs of the server
|
|
9240
|
+
|
|
9241
|
+
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`.
|
|
9242
|
+
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`).
|
|
9243
|
+
Files compressed with gzip (rotations) are supported. A folder is not read, give its files.
|
|
9244
|
+
|
|
9245
|
+
```shell
|
|
9246
|
+
ascli server --url=ssh://<SERVER_ADDRESS>:33001 --username=root --ssh-keys=~/.ssh/id_rsa logs summary /var/log/aspera.log
|
|
9247
|
+
ascli server ... logs sessions /var/log/aspera.log /var/log/aspera.log-20261101.gz --select=@json:'{"status":"failed"}'
|
|
9248
|
+
```
|
|
9249
|
+
|
|
9250
|
+
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`).
|
|
9251
|
+
The files are copied to a temporary folder, removed after the analysis.
|
|
9252
|
+
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`.
|
|
9253
|
+
The modification date of each file is kept, as the year of syslog lines is deduced from it.
|
|
9254
|
+
Not available with `--url=local:` and `https`.
|
|
9255
|
+
|
|
8172
9256
|
### Other session channels for `server`
|
|
8173
9257
|
|
|
8174
9258
|
URL schemes `local` and `https` are also supported (mainly for testing purposes).
|
|
@@ -8655,7 +9739,8 @@ ascli node -N --url=https://... --password="Bearer $(cat bearer.txt)" --root-id=
|
|
|
8655
9739
|
```shell
|
|
8656
9740
|
--url=http://localhost:12348 --username=sim --password=<PASSWORD> browse / --fields=path --format=csv --select=@json:'{"basename":"test_file.bin"}'
|
|
8657
9741
|
--url=http://localhost:12348 --username=sim --password=<PASSWORD> transfer list --fields=status
|
|
8658
|
-
--url=https://
|
|
9742
|
+
--url=https://node.example.com:9092 --username=user1 --password=<PASSWORD> --ui=text asperabrowser
|
|
9743
|
+
--url=https://tst.example.com/path --password 'Bearer <ND_BEARER_TOKEN>' --root-id=<ID> access_key do self browse /
|
|
8659
9744
|
access_key create @json:'{"id":"my_username","secret":"<PASSWORD>","storage":{"type":"local","path":"/"}}'
|
|
8660
9745
|
access_key delete my_username
|
|
8661
9746
|
access_key do my_ak_name browse / --secret=<AK_SECRET>
|
|
@@ -8673,15 +9758,14 @@ access_key do my_ak_name node_info / --secret=<AK_SECRET>
|
|
|
8673
9758
|
access_key do my_ak_name rename /tst_nd_ak test_nd_ak2 --secret=<AK_SECRET>
|
|
8674
9759
|
access_key do my_ak_name show %id:1 --secret=<AK_SECRET>
|
|
8675
9760
|
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:<
|
|
9761
|
+
access_key do self permission %id:<ID> create @json:'{"access_type":"user","access_id":"666"}'
|
|
8677
9762
|
access_key do self permission / delete 1
|
|
8678
9763
|
access_key do self permission / modify 1 @: 'access_levels=@list: read list'
|
|
8679
9764
|
access_key do self permission / show 1
|
|
8680
9765
|
access_key list
|
|
8681
|
-
access_key set_bearer_key self @file
|
|
9766
|
+
access_key set_bearer_key self @file:<PRIVATE_KEY_FILE>
|
|
8682
9767
|
access_key show %id:self
|
|
8683
9768
|
api_details
|
|
8684
|
-
asperabrowser
|
|
8685
9769
|
async bandwidth %name:my_sync_session_name
|
|
8686
9770
|
async counters %name:my_sync_session_name
|
|
8687
9771
|
async delete ALL
|
|
@@ -8730,12 +9814,12 @@ sync admin status /data/local_sync
|
|
|
8730
9814
|
sync pull /aspera-test-dir-tiny --to-folder=/data/local_sync @: reset=true
|
|
8731
9815
|
sync pull /aspera-test-dir-tiny --to-folder=/data/local_sync @json:'{"name":"my_sync_session_name","reset":true}'
|
|
8732
9816
|
transfer bandwidth_average
|
|
8733
|
-
transfer cancel <
|
|
9817
|
+
transfer cancel <ID>
|
|
8734
9818
|
transfer list --query.active_only=true
|
|
8735
9819
|
transfer list --query.reset=true --once-only=yes
|
|
8736
|
-
transfer modify <
|
|
9820
|
+
transfer modify <ID> @: target_rate_kbps=10000
|
|
8737
9821
|
transfer sessions
|
|
8738
|
-
transfer show <
|
|
9822
|
+
transfer show <ID>
|
|
8739
9823
|
transport
|
|
8740
9824
|
upload 'faux:///testfile1?1m' --to-folder=my_local_path
|
|
8741
9825
|
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 +9851,7 @@ Identify the region and the endpoint URL will be `https://otlp-[region]-saas.ins
|
|
|
8767
9851
|
For convenience, those parameters can be provided in a preset, for example, named `otel_default`.
|
|
8768
9852
|
|
|
8769
9853
|
```shell
|
|
8770
|
-
ascli config preset
|
|
9854
|
+
ascli config preset set otel_default @json:'{"url":"https://otlp-orange-saas.instana.io:4318","key":"<KEY>","interval":1.1}'
|
|
8771
9855
|
```
|
|
8772
9856
|
|
|
8773
9857
|
Then it is invoked like this (assuming a default node is configured):
|
|
@@ -8797,13 +9881,13 @@ The emulator starts its own `transferd`, and stops it on exit.
|
|
|
8797
9881
|
It takes an optional `Hash` argument with the following parameters:
|
|
8798
9882
|
|
|
8799
9883
|
| Field | Type | Description |
|
|
8800
|
-
|
|
9884
|
+
| ----------------- | ------- | -------------------------------------------------------------------------------- |
|
|
8801
9885
|
| `cert` | `String` | Path to the TLS certificate file. Accepted formats: PEM (`.pem`) or PKCS12 (`.p12` / `.pfx`).<br/>Example: `/path/to/cert.pem`. |
|
|
8802
9886
|
| `chain` | `String` | Path to the PEM certificate chain file (appended as extra chain certificates).<br/>Example: `/path/to/chain.pem`. |
|
|
8803
9887
|
| `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
9888
|
| `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`. |
|
|
9889
|
+
| `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
9890
|
| `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
9891
|
| `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
9892
|
| `url` | `String` | Address and port the emulator listens on. Use `https://` with `cert`/`key` for TLS.<br/>Default: `http://localhost:8080`. |
|
|
8809
9893
|
| `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 +9906,7 @@ ascli node emulator @json:'{"url":"http://localhost:12348","username":"sim","pas
|
|
|
8822
9906
|
|
|
8823
9907
|
Generate the password with `openssl rand -hex 32`.
|
|
8824
9908
|
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 (
|
|
9909
|
+
`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
9910
|
|
|
8827
9911
|
Then, in another terminal, use it as a node, for example, to list the files in `/data`:
|
|
8828
9912
|
|
|
@@ -8903,13 +9987,13 @@ Multiple applications detected:
|
|
|
8903
9987
|
product> faspex5
|
|
8904
9988
|
```
|
|
8905
9989
|
|
|
8906
|
-
When Faspex is detected, the wizard asks for
|
|
9990
|
+
When Faspex is detected, the wizard asks for a private key (a value like `@file:<path>`).
|
|
8907
9991
|
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
9992
|
|
|
8909
9993
|
```text
|
|
8910
9994
|
Using: Faspex at https://faspex5.example.com/aspera/faspex
|
|
8911
|
-
|
|
8912
|
-
option:
|
|
9995
|
+
Private RSA key, e.g. @file:<path> (leave empty to generate):
|
|
9996
|
+
option: private_key>
|
|
8913
9997
|
Using existing key:
|
|
8914
9998
|
/Users/someuser/.aspera/ascli/my_key
|
|
8915
9999
|
```
|
|
@@ -9004,7 +10088,7 @@ Typically, users create a preset so they don't have to enter these options each
|
|
|
9004
10088
|
Example:
|
|
9005
10089
|
|
|
9006
10090
|
```shell
|
|
9007
|
-
ascli config preset
|
|
10091
|
+
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
10092
|
|
|
9009
10093
|
ascli config preset set default faspex5 <F5_PRESET>
|
|
9010
10094
|
|
|
@@ -9019,9 +10103,9 @@ For web-based authentication, the administrator must create an **API client** in
|
|
|
9019
10103
|
- Do not Activate JWT
|
|
9020
10104
|
- Set **Redirect URI** to `https://127.0.0.1:8888`
|
|
9021
10105
|
- Click **Create**
|
|
9022
|
-
- Take note of the Client Id
|
|
10106
|
+
- Take note of the Client Id, and of the Client Secret if HTTP basic authentication is enabled on the API client
|
|
9023
10107
|
|
|
9024
|
-
The user will use the following options:
|
|
10108
|
+
The user will use the following options (`client_secret` only if HTTP basic authentication is enabled on the API client):
|
|
9025
10109
|
|
|
9026
10110
|
```text
|
|
9027
10111
|
--auth=web
|
|
@@ -9030,6 +10114,9 @@ The user will use the following options:
|
|
|
9030
10114
|
--redirect-uri=https://127.0.0.1:8888
|
|
9031
10115
|
```
|
|
9032
10116
|
|
|
10117
|
+
`ascli` uses PKCE (RFC 7636, method `S256`): the authorization code can be exchanged for a token only by the `ascli` process that requested it.
|
|
10118
|
+
Faspex checks it since version 5.0.16, earlier versions ignore it.
|
|
10119
|
+
|
|
9033
10120
|
### Faspex 5 public link authentication
|
|
9034
10121
|
|
|
9035
10122
|
If all you have is a public link received by email or other, you can still do authorized actions with it.
|
|
@@ -9052,7 +10139,7 @@ For `boot` method: (will be removed in future)
|
|
|
9052
10139
|
Use this token as password and use `--auth=boot`.
|
|
9053
10140
|
|
|
9054
10141
|
```shell
|
|
9055
|
-
ascli config preset
|
|
10142
|
+
ascli config preset set f5boot @: url=https://localhost/aspera/faspex auth=boot password=<TOKEN>
|
|
9056
10143
|
```
|
|
9057
10144
|
|
|
9058
10145
|
### Tested commands for `faspex5`
|
|
@@ -9102,33 +10189,36 @@ gateway @: url=https://localhost:12346/aspera/faspex
|
|
|
9102
10189
|
health --url=https://f5.example.com/path
|
|
9103
10190
|
invitation list
|
|
9104
10191
|
invitations create @: email_address=aspera.user1+u@gmail.com
|
|
9105
|
-
packages browse --url
|
|
9106
|
-
packages browse <
|
|
9107
|
-
packages delete <
|
|
10192
|
+
packages browse --url=<PUBLIC_LINK_RECV_FR_USER> /
|
|
10193
|
+
packages browse <ID> --query.recursive=true
|
|
10194
|
+
packages delete <ID>
|
|
9108
10195
|
packages list --box=ALL
|
|
9109
10196
|
packages list --box=my_shared_box_name
|
|
9110
10197
|
packages list --box=my_workgroup --group-type=workgroups
|
|
9111
10198
|
packages list --box=outbox --fields=DEF,sender.email,recipients.0.recipient_type
|
|
9112
10199
|
packages list --query=@json:'{"mailbox":"inbox","status":"completed"}'
|
|
9113
|
-
packages receive --box=my_shared_box_name <
|
|
9114
|
-
packages receive --box=my_workgroup --group-type=workgroups <
|
|
9115
|
-
packages receive --url
|
|
9116
|
-
packages receive --url
|
|
9117
|
-
packages receive <
|
|
9118
|
-
packages receive <
|
|
9119
|
-
packages receive ALL --once-only=yes --to-folder=.
|
|
10200
|
+
packages receive --box=my_shared_box_name <ID> --to-folder=.
|
|
10201
|
+
packages receive --box=my_workgroup --group-type=workgroups <ID> --to-folder=.
|
|
10202
|
+
packages receive --url=<PUBLIC_LINK_RECV_FR_USER> --to-folder=.
|
|
10203
|
+
packages receive --url=<PUBLIC_LINK_RECV_FR_USER> ALL --to-folder=.
|
|
10204
|
+
packages receive <ID> --to-folder=. --ts.content_protection_password=<PASSWORD>
|
|
10205
|
+
packages receive <ID> <F5_PACK_FIRST_FILE> --to-folder=. --ts.content_protection_password=<PASSWORD>
|
|
10206
|
+
packages receive ALL --once-only=yes --to-folder=.
|
|
10207
|
+
packages receive ALL --once-only=yes --to-folder=. --query.max=5 --ts.content_protection_password=<PASSWORD>
|
|
9120
10208
|
packages receive INIT --once-only=yes
|
|
9121
|
-
packages send --url
|
|
9122
|
-
packages send --url
|
|
10209
|
+
packages send --url=<PUBLIC_LINK_SEND_SHARED_BOX> @json:'{"title":"test title"}' test_file.bin
|
|
10210
|
+
packages send --url=<PUBLIC_LINK_SEND_TO_USER> @json:'{"title":"test title"}' test_file.bin
|
|
9123
10211
|
packages send @: 'title=for shared inbox' recipients.0=my_shared_box_name metadata.Options=Opt1 'metadata.TextInput=example text' END test_file.bin
|
|
10212
|
+
packages send @: 'title=test ear' recipients.0.name=my_username END test_file.bin --ts.content_protection=encrypt --ts.content_protection_password=<PASSWORD>
|
|
10213
|
+
packages send @: 'title=test recipient types' recipients.0=my_username recipient_types.0=user END test_file.bin
|
|
9124
10214
|
packages send @: 'title=test title' recipients.0.name=my_username END test_file.bin --ts.content_protection_password=<PASSWORD>
|
|
9125
10215
|
packages send @json:'{"title":"test title","recipients":["my_workgroup"]}' test_file.bin
|
|
9126
10216
|
packages send @json:'{"title":"test_webhook_ascli","recipients":["my_shared_box_name"]}' 'faux:///test1?1m'
|
|
9127
|
-
packages show --box=my_shared_box_name <
|
|
9128
|
-
packages show --box=my_workgroup --group-type=workgroups <
|
|
9129
|
-
packages show <
|
|
9130
|
-
packages status <
|
|
9131
|
-
packages status <
|
|
10217
|
+
packages show --box=my_shared_box_name <ID>
|
|
10218
|
+
packages show --box=my_workgroup --group-type=workgroups <ID>
|
|
10219
|
+
packages show <ID>
|
|
10220
|
+
packages status <F5_PACK_SEND_SHARED> @list:,failed,completed
|
|
10221
|
+
packages status <ID>
|
|
9132
10222
|
postprocessing @: url=https://localhost:8553/asclihook script_folder=/path/to/scripts cert=.../localhost.p12 key=<PASSWORD>
|
|
9133
10223
|
shared browse %name:my_shared_folder_name
|
|
9134
10224
|
shared list
|
|
@@ -9533,15 +10623,15 @@ ascli faspex5 postprocessing
|
|
|
9533
10623
|
An optional positional parameter can be provided as [Extended Value](#extended-value-syntax) `Hash`:
|
|
9534
10624
|
|
|
9535
10625
|
| Field | Type | Description |
|
|
9536
|
-
|
|
10626
|
+
| --------------------- | --------------------- | -------------------------------------------------------------------------------- |
|
|
9537
10627
|
| `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
10628
|
| `cert` | `String` | Path to the TLS certificate file. Accepted formats: PEM (`.pem`) or PKCS12 (`.p12` / `.pfx`).<br/>Example: `/path/to/cert.pem`. |
|
|
9539
10629
|
| `chain` | `String` | Path to the PEM certificate chain file (appended as extra chain certificates).<br/>Example: `/path/to/chain.pem`. |
|
|
9540
10630
|
| `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
10631
|
| `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
10632
|
| `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
10633
|
| `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`). |
|
|
10634
|
+
| `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
10635
|
| `timeout_seconds` | `Integer` | Maximum time in seconds to wait for the script to complete before killing it.<br/>Default: `60`. |
|
|
9546
10636
|
| `url` | `String` | Address and port the server listens on. Use `https://` with `cert`/`key` for TLS.<br/>Default: `http://localhost:8080`. |
|
|
9547
10637
|
|
|
@@ -9574,8 +10664,8 @@ Instead, one can specify the **IP address of the host** or `host.containers.inte
|
|
|
9574
10664
|
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
10665
|
|
|
9576
10666
|
> [!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
|
|
10667
|
+
> **Security**: by default the listener binds to loopback (`localhost`) and is not reachable from outside the host (see [Web service](#web-service)).
|
|
10668
|
+
> When `url` is not a loopback address, at least one of the following protections is required:
|
|
9579
10669
|
>
|
|
9580
10670
|
> - **`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
10671
|
> - **`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 +10698,17 @@ For legacy Faspex client applications that use the `send` API (only) of Faspex v
|
|
|
9608
10698
|
It takes an optional `Hash` argument:
|
|
9609
10699
|
|
|
9610
10700
|
| Field | Type | Description |
|
|
9611
|
-
|
|
10701
|
+
| ----------------- | ------- | -------------------------------------------------------------------------------- |
|
|
9612
10702
|
| `cert` | `String` | Path to the TLS certificate file. Accepted formats: PEM (`.pem`) or PKCS12 (`.p12` / `.pfx`).<br/>Example: `/path/to/cert.pem`. |
|
|
9613
10703
|
| `chain` | `String` | Path to the PEM certificate chain file (appended as extra chain certificates).<br/>Example: `/path/to/chain.pem`. |
|
|
9614
10704
|
| `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`. |
|
|
10705
|
+
| `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
10706
|
| `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
10707
|
| `url` | `String` | Address and port the server listens on. Use `https://` with `cert`/`key` for TLS.<br/>Default: `http://localhost:8080`. |
|
|
9618
10708
|
| `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
10709
|
|
|
10710
|
+
For details on `url` and HTTPS (`cert`, `key`, `chain`), see [Web service](#web-service).
|
|
10711
|
+
|
|
9620
10712
|
Example:
|
|
9621
10713
|
|
|
9622
10714
|
```shell
|
|
@@ -9626,7 +10718,7 @@ ascli faspex5 gateway @json:'{"url":"https://localhost:12345/aspera/faspex","use
|
|
|
9626
10718
|
Clients authenticate with HTTP Basic, as on Faspex 4, with the `username` and `password` of the gateway.
|
|
9627
10719
|
Generate the password with `openssl rand -hex 32`.
|
|
9628
10720
|
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 (
|
|
10721
|
+
`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
10722
|
When they are not set, requests are accepted without authentication.
|
|
9631
10723
|
|
|
9632
10724
|
There are many limitations:
|
|
@@ -9704,6 +10796,45 @@ ascli shares admin user all share_permissions %username:john@example.com list --
|
|
|
9704
10796
|
done
|
|
9705
10797
|
```
|
|
9706
10798
|
|
|
10799
|
+
### Authentication of SAML users
|
|
10800
|
+
|
|
10801
|
+
By default, `shares` authenticates with `username` and `password`.
|
|
10802
|
+
A user that has only a SAML identity (no local password) can authenticate with a web browser: `--auth=web`.
|
|
10803
|
+
|
|
10804
|
+
```shell
|
|
10805
|
+
ascli shares --url=https://shares.example.com --auth=web files browse /
|
|
10806
|
+
```
|
|
10807
|
+
|
|
10808
|
+
Option `ui.web_auth` selects how the result of the login is received (see [Web login flow](#web-login-flow)):
|
|
10809
|
+
|
|
10810
|
+
- `port` (default): automatic when the browser runs on the same system as `ascli`.
|
|
10811
|
+
`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.
|
|
10812
|
+
The host of `redirect_uri` shall be loopback: `localhost`, an address of `127.0.0.0/8`, or `[::1]`.
|
|
10813
|
+
- `paste`: the browser may run on another system than `ascli` (for example, `ascli` runs on a server accessed with SSH), without tunnel.
|
|
10814
|
+
No local port is opened and `--redirect-uri` is not used.
|
|
10815
|
+
`ascli` generates a random `state` and opens the SAML login page with `RelayState` `aspera://device-code?state=<state>`.
|
|
10816
|
+
After login, Shares displays a code (a long text of letters, digits, `-` and `_`), and tells how long the code and the session token are valid. The user copies the code and pastes it in the prompt of `ascli` ([hidden](#hidden-input), as the code contains a token).
|
|
10817
|
+
The mark of the prompt becomes `✓` if the code is valid, else `✗`. A code that is not valid is asked again.
|
|
10818
|
+
If standard input is not a terminal, the code is read from it.
|
|
10819
|
+
`ascli` checks that the `state` of the code is the one it generated.
|
|
10820
|
+
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).
|
|
10821
|
+
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.
|
|
10822
|
+
The code is also protected against typing errors and modification.
|
|
10823
|
+
|
|
10824
|
+
The token is saved, and renewed with its refresh token: the browser is opened again only if this fails.
|
|
10825
|
+
Shares gives a token and a refresh token that both expire after 24 hours: then a new login is needed, unless the token is refreshed before (see `token_refresh_max_age` in [HTTP socket parameters](#http-socket-parameters)).
|
|
10826
|
+
Option `username` is optional: with it, the token is saved for this user.
|
|
10827
|
+
|
|
10828
|
+
> [!IMPORTANT]
|
|
10829
|
+
> 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`).
|
|
10830
|
+
> The patch is the file [`docs/shares/zz_saml_cli_relay_state.rb`](shares/zz_saml_cli_relay_state.rb) of the GitHub repository.
|
|
10831
|
+
> It is temporary code, provided until an equivalent function is officially released in Shares.
|
|
10832
|
+
> 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.
|
|
10833
|
+
> With a Shares without the patch, `ascli` reports that no token was received.
|
|
10834
|
+
> 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.
|
|
10835
|
+
> 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`.
|
|
10836
|
+
> 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.
|
|
10837
|
+
|
|
9707
10838
|
### Tested commands for `shares`
|
|
9708
10839
|
|
|
9709
10840
|
> [!NOTE]
|
|
@@ -9737,7 +10868,7 @@ files download --to-folder=. my_share_folder/test_file.bin my_share_folder/test_
|
|
|
9737
10868
|
files mkdir my_share_folder/new_folder
|
|
9738
10869
|
files sync push /data/local_sync --to-folder=my_share_folder/synctst
|
|
9739
10870
|
files sync push /data/local_sync --to-folder=my_share_folder/synctst @: reset=true
|
|
9740
|
-
files upload 'faux:///
|
|
10871
|
+
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
10872
|
files upload --to-folder=my_share_folder test_file.bin
|
|
9742
10873
|
files upload --to-folder=my_share_folder test_file.bin --transfer.agent=httpgw --transfer.url=https://tst.example.com/path
|
|
9743
10874
|
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 +10898,41 @@ In addition, it is possible to place a single `query` parameter in the request t
|
|
|
9767
10898
|
endpoint list
|
|
9768
10899
|
health
|
|
9769
10900
|
ssh_key list
|
|
9770
|
-
transfer current files <
|
|
10901
|
+
transfer current files <ID>
|
|
9771
10902
|
transfer current list --query.filter='(transfer_name contain aoc)'
|
|
9772
10903
|
transfer current list --query=@json:'{"filter1":"transfer_name","comp1":"contain","val1":"aoc"}'
|
|
9773
|
-
transfer current show <
|
|
10904
|
+
transfer current show <ID>
|
|
9774
10905
|
transfer smart list
|
|
9775
|
-
transfer smart sub
|
|
10906
|
+
transfer smart sub <SMART_ID> @: source.paths.0=my_smart_file source_type=user_selected
|
|
9776
10907
|
```
|
|
9777
10908
|
|
|
9778
10909
|
## Plugin: `orchestrator`: IBM Aspera Orchestrator
|
|
9779
10910
|
|
|
9780
|
-
To write workflow files without the designer, refer to the [
|
|
10911
|
+
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
10912
|
|
|
9782
|
-
Command `workflows development`
|
|
9783
|
-
|
|
10913
|
+
Command `workflows development` gives access to the documentation for workflow development, read from GitHub.
|
|
10914
|
+
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`).
|
|
10915
|
+
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
10916
|
It does not require access to Orchestrator.
|
|
9785
10917
|
The [MCP server](#plugin-mcp-model-context-protocol-server) instructs AI assistants to read it before writing or modifying a workflow.
|
|
9786
10918
|
|
|
9787
10919
|
```shell
|
|
9788
|
-
ascli orchestrator workflows development
|
|
9789
|
-
ascli orchestrator workflows development templates customruby
|
|
10920
|
+
ascli orchestrator workflows development guide toc
|
|
10921
|
+
ascli orchestrator workflows development templates section customruby
|
|
9790
10922
|
```
|
|
9791
10923
|
|
|
9792
|
-
|
|
10924
|
+
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
10925
|
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/
|
|
9795
|
-
|
|
9796
|
-
|
|
10926
|
+
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.
|
|
10927
|
+
`toc` lists the plugins, with the anchor of their section in the Plugin Manual (`manual_anchor`, for `workflows development manual section`).
|
|
10928
|
+
`show` with a plugin name (class name, case insensitive) displays its specification, or one section: `attributes`, `inputs` or `outputs`.
|
|
9797
10929
|
It does not require access to Orchestrator.
|
|
9798
10930
|
Option `plugin_specs` gives another URL or path of the file, for example for another version of Orchestrator.
|
|
9799
10931
|
|
|
9800
10932
|
```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
|
|
10933
|
+
ascli orchestrator plugins spec toc --select=@json:'{"category":"Triggers"}'
|
|
10934
|
+
ascli orchestrator plugins spec show AmazonS3Operation --format=yaml
|
|
10935
|
+
ascli orchestrator plugins spec show ascpclient inputs
|
|
9804
10936
|
```
|
|
9805
10937
|
|
|
9806
10938
|
### Authentication
|
|
@@ -9811,9 +10943,9 @@ The Orchestrator plugin supports different credentials and authentication styles
|
|
|
9811
10943
|
- `--auth_style=token` (default): Exchanges credentials for a JWT Bearer token via `/api/login`.
|
|
9812
10944
|
- `--auth_style=basic`: Standard HTTP Basic Authentication.
|
|
9813
10945
|
- `--auth_style=query`: Passes credentials in URL query parameters (`?login=...&password=...`).
|
|
9814
|
-
- **API Key** (`--apikey`):
|
|
10946
|
+
- **Username / API Key** (`--username` and `--apikey`): the API key is the one of the user, so the user name is required.
|
|
9815
10947
|
- `--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
|
|
10948
|
+
- `--auth_style=query`: Passes the API key in URL query parameters (`?login=...&api_key=...`).
|
|
9817
10949
|
|
|
9818
10950
|
### Start a workflow
|
|
9819
10951
|
|
|
@@ -9888,6 +11020,7 @@ ascli orchestrator workflows check_import my_workflow.yml
|
|
|
9888
11020
|
```
|
|
9889
11021
|
|
|
9890
11022
|
It displays one line per issue, or `no problem found`.
|
|
11023
|
+
The file is read as `@file:`: at [Security Level](#security-level) `medium`, only in `allowed_paths`, and not at level `high`.
|
|
9891
11024
|
An issue has these fields:
|
|
9892
11025
|
|
|
9893
11026
|
| Field | Description |
|
|
@@ -9900,7 +11033,9 @@ An issue has these fields:
|
|
|
9900
11033
|
|
|
9901
11034
|
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
11035
|
|
|
9903
|
-
|
|
11036
|
+
A package (`.wkf`) whose files exceed 256 MiB once decompressed is not checked: it is reported as an issue (`package.too_large`).
|
|
11037
|
+
|
|
11038
|
+
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
11039
|
|
|
9905
11040
|
- plugin class name, attributes of the template, and their values (type, allowed values),
|
|
9906
11041
|
- required inputs not mapped (`step.input_missing`),
|
|
@@ -9946,39 +11081,45 @@ Orchestrator does not refuse an incomplete resolution: `workflows import_with_co
|
|
|
9946
11081
|
```shell
|
|
9947
11082
|
--auth_style=query workflow list
|
|
9948
11083
|
--auth_style=token workflow list
|
|
11084
|
+
alerts list
|
|
9949
11085
|
health
|
|
9950
11086
|
info
|
|
9951
11087
|
journal files journal --query=@json:'{"details":"false"}'
|
|
9952
11088
|
monitors list node
|
|
9953
11089
|
monitors snapshot
|
|
9954
11090
|
plugins list
|
|
9955
|
-
plugins spec --
|
|
9956
|
-
plugins spec
|
|
9957
|
-
plugins spec
|
|
11091
|
+
plugins spec show AmazonS3Operation --format=yaml
|
|
11092
|
+
plugins spec show ascpclient inputs
|
|
11093
|
+
plugins spec toc --select=@json:'{"category":"Triggers"}'
|
|
11094
|
+
portlets list
|
|
9958
11095
|
processes
|
|
9959
11096
|
queues list
|
|
11097
|
+
queues stats
|
|
11098
|
+
tasks list
|
|
9960
11099
|
workflow check_import orch_wf_check.yml
|
|
9961
|
-
workflow details
|
|
9962
|
-
workflow export
|
|
9963
|
-
workflow inputs
|
|
11100
|
+
workflow details <WORKFLOW_ID>
|
|
11101
|
+
workflow export <WORKFLOW_ID>
|
|
11102
|
+
workflow inputs <WORKFLOW_ID>
|
|
9964
11103
|
workflow list
|
|
9965
|
-
workflow outputs
|
|
9966
|
-
workflow start
|
|
9967
|
-
workflow start
|
|
9968
|
-
workflow start
|
|
11104
|
+
workflow outputs <WORKFLOW_ID>
|
|
11105
|
+
workflow start <SLEEP_WORKFLOW_ID> --fields=work_order.id
|
|
11106
|
+
workflow start <WORKFLOW_ID> @: 'Param=world !'
|
|
11107
|
+
workflow start <WORKFLOW_ID> @: 'Param=world !' END @: step=ResultStep variable=Complete_status_message
|
|
11108
|
+
workflow status <WORKFLOW_ID>
|
|
9969
11109
|
workflow status ALL
|
|
9970
|
-
workflow
|
|
9971
|
-
workflow workorders
|
|
9972
|
-
|
|
9973
|
-
workflows development
|
|
9974
|
-
|
|
9975
|
-
workorder
|
|
9976
|
-
workorder
|
|
9977
|
-
workorder
|
|
9978
|
-
|
|
9979
|
-
|
|
9980
|
-
|
|
9981
|
-
|
|
11110
|
+
workflow workorders <WORKFLOW_ID>
|
|
11111
|
+
workflow workorders <WORKFLOW_ID> --fields=id --query.max_results=1
|
|
11112
|
+
workflows development guide toc
|
|
11113
|
+
workflows development templates section customruby
|
|
11114
|
+
workorder cancel <ID>
|
|
11115
|
+
workorder output <ID>
|
|
11116
|
+
workorder reset <ID>
|
|
11117
|
+
workorder status <ID>
|
|
11118
|
+
workorders stats
|
|
11119
|
+
workorders worksteps <ORCH_WF_START_SLEEP> --select.status='In Progress' --fields=id
|
|
11120
|
+
worksteps cancel <ID>
|
|
11121
|
+
worksteps stats
|
|
11122
|
+
worksteps status <ID>
|
|
9982
11123
|
```
|
|
9983
11124
|
|
|
9984
11125
|
## Plugin: `cos`: IBM Cloud Object Storage
|
|
@@ -10010,7 +11151,7 @@ If you already have these parameters, provide the following options to `ascli`:
|
|
|
10010
11151
|
Example: Create a Default Configuration
|
|
10011
11152
|
|
|
10012
11153
|
```shell
|
|
10013
|
-
ascli config preset
|
|
11154
|
+
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
11155
|
ascli config preset set default cos <COS_PRESET_NAME>
|
|
10015
11156
|
```
|
|
10016
11157
|
|
|
@@ -10080,7 +11221,7 @@ The required options for this method are:
|
|
|
10080
11221
|
Example: Create a Default Configuration
|
|
10081
11222
|
|
|
10082
11223
|
```shell
|
|
10083
|
-
ascli config preset
|
|
11224
|
+
ascli config preset set <COS_PRESET_NAME> @: bucket=mybucket service_credentials=@val:@json:@file:~/service_creds.json region=us-south
|
|
10084
11225
|
ascli config preset set default cos <COS_PRESET_NAME>
|
|
10085
11226
|
```
|
|
10086
11227
|
|
|
@@ -10104,8 +11245,8 @@ ascli cos node upload 'faux:///sample1G?1g'
|
|
|
10104
11245
|
|
|
10105
11246
|
```shell
|
|
10106
11247
|
node download test_file.bin --to-folder=.
|
|
10107
|
-
node info --bucket=my_bucket --endpoint=my_endpoint --apikey
|
|
10108
|
-
node info --bucket=my_bucket --region=my_region --service-credentials=@json:@file
|
|
11248
|
+
node info --bucket=my_bucket --endpoint=my_endpoint --apikey=<API_KEY> --crn=<RESOURCE_INSTANCE_ID>
|
|
11249
|
+
node info --bucket=my_bucket --region=my_region --service-credentials=@json:@file:<COS_SVC_CRED_FILE>
|
|
10109
11250
|
node info --log-level=trace2
|
|
10110
11251
|
node upload test_file.bin
|
|
10111
11252
|
```
|
|
@@ -10122,6 +11263,47 @@ health
|
|
|
10122
11263
|
info
|
|
10123
11264
|
```
|
|
10124
11265
|
|
|
11266
|
+
## Plugin: `transferd`: Transfer Daemon
|
|
11267
|
+
|
|
11268
|
+
Plugin `transferd` installs the IBM Aspera Transfer Daemon (`transferd`, which includes `ascp`) and runs it as a system service.
|
|
11269
|
+
See [Installing `ascp` through `transferd`](#installing-ascp-through-transferd) and [Transfer Daemon as a system service](#transfer-daemon-as-a-system-service).
|
|
11270
|
+
|
|
11271
|
+
The plugin also has client commands for a running daemon (for example one installed with `transferd service install`):
|
|
11272
|
+
|
|
11273
|
+
| Command | Action |
|
|
11274
|
+
|---------------------------------|---------------------------------------------------------------------|
|
|
11275
|
+
| `info` | Version of the API and information on the instance of the daemon. |
|
|
11276
|
+
| `transfers show <transfer_id>` | Status of a transfer: the daemon keeps it for some time after its end. |
|
|
11277
|
+
| `transfers cancel <transfer_id>`| Stop a transfer. |
|
|
11278
|
+
|
|
11279
|
+
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`).
|
|
11280
|
+
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).
|
|
11281
|
+
The options of the plugin have priority.
|
|
11282
|
+
The daemon has no call to list the transfers.
|
|
11283
|
+
These commands require the gem `grpc`: it is loaded only when one of them runs, so that the other commands do not need it.
|
|
11284
|
+
If it is missing: `gem install grpc`.
|
|
11285
|
+
|
|
11286
|
+
```bash
|
|
11287
|
+
ascli transferd info --url=127.0.0.1:55002 --api-key=@vault:transferd.api_key
|
|
11288
|
+
```
|
|
11289
|
+
|
|
11290
|
+
> [!NOTE]
|
|
11291
|
+
> Commands `config transferd ...` and `config ascp install` are deprecated aliases of `transferd ...` and `transferd install`.
|
|
11292
|
+
|
|
11293
|
+
### Tested commands for `transferd`
|
|
11294
|
+
|
|
11295
|
+
> [!NOTE]
|
|
11296
|
+
> Add `ascli transferd` in front of the following commands:
|
|
11297
|
+
|
|
11298
|
+
```shell
|
|
11299
|
+
install
|
|
11300
|
+
install --sdk-folder=sdk_test_dir
|
|
11301
|
+
install 1.1.3
|
|
11302
|
+
list
|
|
11303
|
+
service configure --dry-run=yes @json:'{"service":{"user":"aspweb"},"config":{"port":55002}}'
|
|
11304
|
+
service spec
|
|
11305
|
+
```
|
|
11306
|
+
|
|
10125
11307
|
## Plugin: `faspio`: Faspio Gateway
|
|
10126
11308
|
|
|
10127
11309
|
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 +11317,7 @@ Using `ascli`, you can remotely create and manage bridges on faspio Gateway, sim
|
|
|
10135
11317
|
|
|
10136
11318
|
```shell
|
|
10137
11319
|
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:<
|
|
11320
|
+
bridges delete --bulk=yes @json:<FASPIO_BCLEAN_LIST>
|
|
10139
11321
|
bridges list
|
|
10140
11322
|
bridges show 1
|
|
10141
11323
|
health
|
|
@@ -10338,7 +11520,7 @@ For example:
|
|
|
10338
11520
|
```shell
|
|
10339
11521
|
su -s /bin/bash - xfer
|
|
10340
11522
|
|
|
10341
|
-
ascli config preset
|
|
11523
|
+
ascli config preset set <PREVIEW_PRESET_NAME> @: url=https://localhost:9092 username=<ACCESS_KEY> password=<SECRET> skip_types=office lock_port=12346
|
|
10342
11524
|
|
|
10343
11525
|
ascli config preset set default preview <PREVIEW_PRESET_NAME>
|
|
10344
11526
|
```
|
|
@@ -10359,7 +11541,7 @@ This shall list the contents of the storage root of the access key.
|
|
|
10359
11541
|
When generating preview files, the following options can be modified on command line (or in a preset):
|
|
10360
11542
|
|
|
10361
11543
|
| Field | Type | Description |
|
|
10362
|
-
|
|
11544
|
+
| ------------------- | ------------ | -------------------------------------------------------------------------------- |
|
|
10363
11545
|
| `blend_fps` | `Integer` | MP4 video preview (`blend`): frames per second.<br/>Default: `15`. |
|
|
10364
11546
|
| `blend_keyframes` | `Integer` | MP4 video preview (`blend`): number of key frames.<br/>Default: `30`. |
|
|
10365
11547
|
| `blend_pauseframes` | `Integer` | MP4 video preview (`blend`): number of pause frames (repetitions of each key frame).<br/>Default: `3`. |
|
|
@@ -10367,17 +11549,17 @@ When generating preview files, the following options can be modified on command
|
|
|
10367
11549
|
| `clips_count` | `Integer` | MP4 video preview (`clips`): number of clips.<br/>Default: `5`. |
|
|
10368
11550
|
| `clips_length` | `Integer` | Video: length (in seconds) of each clip of MP4 video preview (`clips`), and of `animated` PNG thumbnail.<br/>Default: `5`. |
|
|
10369
11551
|
| `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`. |
|
|
11552
|
+
| `office_conversion` | `Enum[String]` | PNG thumbnail of office document: conversion tool.<br/>Allowed values: `soffice`, `unoconv`.<br/>Default: `soffice`. |
|
|
11553
|
+
| `reencode_ffmpeg` | `Hash` | MP4 video preview (`reencode`): `ffmpeg` options replacing the default ones.<br/>Default: `{}`. |
|
|
10371
11554
|
| `reencode_ffmpeg.in` | `Array` | Input options. |
|
|
10372
11555
|
| `reencode_ffmpeg.out` | `Array` | Output options. |
|
|
10373
|
-
| `reencode_ffmpeg` | `Hash` | MP4 video preview (`reencode`): `ffmpeg` options replacing the default ones.<br/>Default: `{}`. |
|
|
10374
11556
|
| `thumb_img_size` | `Integer` | PNG thumbnail of image, PDF, office document or text: size (in pixels).<br/>Default: `800`. |
|
|
10375
11557
|
| `thumb_text_font` | `String` | PNG thumbnail of text: font name, as listed by `magick identify -list font`.<br/>Default: `Courier`. |
|
|
10376
11558
|
| `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
11559
|
| `thumb_vid_scale` | `String` | PNG thumbnail of video: frame size, as `ffmpeg` scale filter argument.<br/>Default: `-1:min(ih,100)`. |
|
|
10378
11560
|
| `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`. |
|
|
11561
|
+
| `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`. |
|
|
11562
|
+
| `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
11563
|
| `video_scale` | `String` | MP4 video preview: frame size, as `ffmpeg` scale filter argument.<br/>Default: `min(iw,360):-2`. |
|
|
10382
11564
|
| `video_start_sec` | `Integer` | Video: start offset (in seconds) of MP4 video preview and of `animated` PNG thumbnail.<br/>Default: `10`. |
|
|
10383
11565
|
|
|
@@ -10539,10 +11721,6 @@ trevents --once-only=yes --skip-types=office --log-level=info
|
|
|
10539
11721
|
|
|
10540
11722
|
## Plugin: `mcp`: Model Context Protocol server
|
|
10541
11723
|
|
|
10542
|
-
> [!WARNING]
|
|
10543
|
-
> This plugin is **experimental**.
|
|
10544
|
-
> The interface, options, and behavior may change in future releases without notice.
|
|
10545
|
-
|
|
10546
11724
|
The `mcp` plugin starts a [Model Context Protocol (MCP)](https://modelcontextprotocol.io/) server that exposes `ascli` to AI assistants and LLM-based tools.
|
|
10547
11725
|
The server registers a single tool, `execute_ascli_command`, which executes any `ascli` command in-process and returns the result as text.
|
|
10548
11726
|
|
|
@@ -10613,6 +11791,8 @@ Keys of a transport are refused with the other transport.
|
|
|
10613
11791
|
> [!NOTE]
|
|
10614
11792
|
> `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
11793
|
|
|
11794
|
+
For the addresses the server listens on, and HTTPS, see [Web service](#web-service).
|
|
11795
|
+
|
|
10616
11796
|
### Security
|
|
10617
11797
|
|
|
10618
11798
|
> [!WARNING]
|
|
@@ -10623,7 +11803,7 @@ With the `http` transport:
|
|
|
10623
11803
|
|
|
10624
11804
|
- With `oauth`, the consent page asks for `auth_token` as access code, else anyone reaching the server could approve its own client.
|
|
10625
11805
|
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
|
|
11806
|
+
- 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
11807
|
Without `auth_token`, the consent page only asks to click **Allow**.
|
|
10628
11808
|
- `auth_token` and `oauth` can coexist: a request is accepted if it carries a valid static token **or** a valid OAuth access token.
|
|
10629
11809
|
- A weak `auth_token` is refused at startup (see `auth_token_min_bits`): generate it with `openssl rand -hex 32`.
|
|
@@ -10636,9 +11816,12 @@ With both transports:
|
|
|
10636
11816
|
- Extended value `@stdin:` is refused.
|
|
10637
11817
|
- `@secret:` is entered by the user on a web page, see [Secrets entered in a web page](#secrets-entered-in-a-web-page).
|
|
10638
11818
|
- 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
|
|
11819
|
+
- The [Security Level](#security-level) is `high` by default: `@ruby:`, `@file:` (also in the parameters of stores of option `vault`), `@uri:`, `@env:`, and `@zlib:` are refused, and a secret must be the whole value: hidden in results, it cannot be processed by another extended value.
|
|
10640
11820
|
It applies to commands sent by the client, and to presets, because the client can modify presets.
|
|
10641
11821
|
Commands sent by the client cannot change option `security`.
|
|
11822
|
+
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).
|
|
11823
|
+
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.
|
|
11824
|
+
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
11825
|
|
|
10643
11826
|
To use another level, set option `security` when starting the server, for example:
|
|
10644
11827
|
|
|
@@ -10646,12 +11829,20 @@ To use another level, set option `security` when starting the server, for exampl
|
|
|
10646
11829
|
ascli mcp server --security.level=medium --security.allowed_paths.0=$HOME/.aspera/ascli/my_private_key
|
|
10647
11830
|
```
|
|
10648
11831
|
|
|
11832
|
+
To let the client download files in a folder, keep the level `high` and give the folder:
|
|
11833
|
+
|
|
11834
|
+
```shell
|
|
11835
|
+
ascli mcp server --security.writable_paths.0=$HOME/Downloads/ascli
|
|
11836
|
+
```
|
|
11837
|
+
|
|
10649
11838
|
> [!NOTE]
|
|
10650
11839
|
> 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
11840
|
> Without option `security`, the parameters of the `server` command are not restricted.
|
|
10652
11841
|
>
|
|
10653
11842
|
> A preset created by `aoc wizard` or `faspex5 wizard` reads the private key with `@file:`.
|
|
10654
11843
|
> 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`.
|
|
11844
|
+
>
|
|
11845
|
+
> 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
11846
|
|
|
10656
11847
|
### HTTP endpoints
|
|
10657
11848
|
|
|
@@ -10873,7 +12064,7 @@ For [**IBM Bob**](https://bob.ibm.com/docs/ide/configuration/mcp/mcp-in-bob), ad
|
|
|
10873
12064
|
}
|
|
10874
12065
|
```
|
|
10875
12066
|
|
|
10876
|
-
|
|
12067
|
+
Most other clients (Claude Desktop, Cursor, and so on) use the same `mcpServers` format, VS Code uses `servers` (see below).
|
|
10877
12068
|
|
|
10878
12069
|
##### Claude Desktop `stdio`
|
|
10879
12070
|
|
|
@@ -10893,6 +12084,47 @@ Place this section in `mcpServers`:
|
|
|
10893
12084
|
}
|
|
10894
12085
|
```
|
|
10895
12086
|
|
|
12087
|
+
##### Claude Code `stdio`
|
|
12088
|
+
|
|
12089
|
+
For [**Claude Code**](https://code.claude.com/docs/en/mcp), register the server with the command line (option `--scope user` for all projects):
|
|
12090
|
+
|
|
12091
|
+
```shell
|
|
12092
|
+
claude mcp add ascli -- ascli mcp server
|
|
12093
|
+
```
|
|
12094
|
+
|
|
12095
|
+
In a shell, Claude Code can also execute `ascli` directly: install the agent skill instead (see [Leveraging AI Assistance](#leveraging-ai-assistance)).
|
|
12096
|
+
|
|
12097
|
+
##### VS Code `stdio`
|
|
12098
|
+
|
|
12099
|
+
For **VS Code** (GitHub Copilot agent mode), add to `.vscode/mcp.json` in your workspace (or run command **MCP: Add Server**):
|
|
12100
|
+
|
|
12101
|
+
```json
|
|
12102
|
+
{
|
|
12103
|
+
"servers": {
|
|
12104
|
+
"ascli": {
|
|
12105
|
+
"type": "stdio",
|
|
12106
|
+
"command": "ascli",
|
|
12107
|
+
"args": ["mcp", "server"]
|
|
12108
|
+
}
|
|
12109
|
+
}
|
|
12110
|
+
}
|
|
12111
|
+
```
|
|
12112
|
+
|
|
12113
|
+
##### Cursor `stdio`
|
|
12114
|
+
|
|
12115
|
+
For **Cursor**, add to `.cursor/mcp.json` in your project (or `~/.cursor/mcp.json` for global configuration):
|
|
12116
|
+
|
|
12117
|
+
```json
|
|
12118
|
+
{
|
|
12119
|
+
"mcpServers": {
|
|
12120
|
+
"ascli": {
|
|
12121
|
+
"command": "ascli",
|
|
12122
|
+
"args": ["mcp", "server"]
|
|
12123
|
+
}
|
|
12124
|
+
}
|
|
12125
|
+
}
|
|
12126
|
+
```
|
|
12127
|
+
|
|
10896
12128
|
##### Development mode for `stdio`
|
|
10897
12129
|
|
|
10898
12130
|
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 +12363,10 @@ ascli config sync spec
|
|
|
11131
12363
|
> The options listed in the **Description** column correspond to the equivalent parameters used by the low-level `async` command.
|
|
11132
12364
|
|
|
11133
12365
|
| Field | Type | Description |
|
|
11134
|
-
|
|
12366
|
+
| ---------------------------------------- | ------------- | -------------------------------------------------------------------------------- |
|
|
11135
12367
|
| `ascp_dir` | `String` | Directory containing ascp executable to use. |
|
|
11136
12368
|
| `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) |
|
|
12369
|
+
| `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
12370
|
| `clean_excluded` | `Bool` | Removes any existing entries in the snapshot database for excluded paths<br/>Default: `false`.<br/>(`--clean-excluded`) |
|
|
11139
12371
|
| `cookie` | `String` | User-defined identification string.<br/>(`--cookie={string}`) |
|
|
11140
12372
|
| `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 +12375,20 @@ ascli config sync spec
|
|
|
11143
12375
|
| `db_cache_size` | `Integer` | Specify DB cache size.<br/>Default: `16000`. |
|
|
11144
12376
|
| `db_journal_off` | `Bool` | Turn off DB journal.<br/>Default: `false`. |
|
|
11145
12377
|
| `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}`) |
|
|
12378
|
+
| `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
12379
|
| `delete_before` | `Bool` | Schedule deletes before transfers.<br/>Default: `false`.<br/>(`--delete-before`) |
|
|
11148
12380
|
| `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) |
|
|
12381
|
+
| `direction` | `Enum[String]` | The direction of replication relative to the local.<br/>Allowed values: `bidi`, `pull`, `push`.<br/>Default: `push`.<br/>(`--direction={enum}`)(-K) |
|
|
12382
|
+
| `exclude_dirs_older_than` | `Hash` | Don't scan directories with a recursive modified time older than absolute or async start time - relative_seconds |
|
|
11150
12383
|
| `exclude_dirs_older_than.absolute` | `String` | UTC timestamp. Empty value for disabled. |
|
|
11151
12384
|
| `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
12385
|
| `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 |
|
|
12386
|
+
| `filters[].rule` | `Enum[String]` | The rule for the filter.<br/>Required.<br/>Allowed values: `include`, `exclude`, `include_from`, `exclude_from`. |
|
|
12387
|
+
| `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
12388
|
| `ignore_delete` | `Bool` | Do not copy removals to the peer.<br/>Default: `false`.<br/>(`--ignore-delete`) |
|
|
11157
12389
|
| `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
12390
|
| `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`. |
|
|
12391
|
+
| `local` | `Hash` | Required. |
|
|
11159
12392
|
| `local.pass` | `String` | Authenticate the local async with the specified password. |
|
|
11160
12393
|
| `local.path` | `String` | The directory to be synchronized on the local host.<br/>Required.<br/>(`--local-dir={string}`)(-d) |
|
|
11161
12394
|
| `local_apply_docroot` | `Bool` | Prepend the docroot to the directory on the local host.<br/>Default: `false`.<br/>(`--apply-local-docroot`) |
|
|
@@ -11167,26 +12400,25 @@ ascli config sync spec
|
|
|
11167
12400
|
| `local_keep_dir` | `String` | Move deleted files into the specified directory on the local host.<br/>(`--keep-dir-local={string}`) |
|
|
11168
12401
|
| `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
12402
|
| `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}`) |
|
|
12403
|
+
| `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}`) |
|
|
12404
|
+
| `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
12405
|
| `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
12406
|
| `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
12407
|
| `local_stat_cache_size` | `Integer` | Set stat cache size on the local host. 0 for disabled.<br/>Default: `0`. |
|
|
11175
|
-
| `
|
|
11176
|
-
| `log.level` | `String` | Use the specified log level.<br/>Allowed values: `log`, `dbg1`, `dbg2`.<br/>Default: `log`.<br/>(special:`-D`) |
|
|
12408
|
+
| `log` | `Hash` | |
|
|
12409
|
+
| `log.level` | `Enum[String]` | Use the specified log level.<br/>Allowed values: `log`, `dbg1`, `dbg2`.<br/>Default: `log`.<br/>(special:`-D`) |
|
|
11177
12410
|
| `log.local_dir` | `String` | Use the specified logging directory on the local host.<br/>(`--alt-logdir={string}`)(-L) |
|
|
11178
12411
|
| `log.remote_dir` | `String` | Use the specified logging directory on the remote host.<br/>(`--remote-logdir={string}`)(-R) |
|
|
11179
|
-
| `log` | `Hash` | |
|
|
11180
12412
|
| `manifest_path` | `String` | A directory path where ascp will create manifest TEXT files (passed to ascp as --file-manifest-path) |
|
|
11181
12413
|
| `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) |
|
|
12414
|
+
| `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
12415
|
| `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
12416
|
| `name` | `String` | Name of the synchronization pair.<br/>Required.<br/>(`--name={string}`)(-N) |
|
|
11185
12417
|
| `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
12418
|
| `no_preserve_root_attrs` | `Bool` | Disable the preservation of attributes on the Sync root.<br/>Default: `false`.<br/>(`--no-preserve-root-attrs`) |
|
|
11187
12419
|
| `no_scan` | `Bool` | Skip initial scanning.<br/>Default: `false`.<br/>(`--no-scan`) |
|
|
11188
12420
|
| `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) |
|
|
12421
|
+
| `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
12422
|
| `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
12423
|
| `preserve_access_time` | `Bool` | Preserve file access time from the source to the destination.<br/>Default: `false`.<br/>(`--preserve-access-time`) |
|
|
11192
12424
|
| `preserve_creation_time` | `Bool` | Preserve file creation time from the source to the destination.<br/>Default: `false`.<br/>(`--preserve-creation-time`) |
|
|
@@ -11197,21 +12429,22 @@ ascli config sync spec
|
|
|
11197
12429
|
| `preserve_object_metadata` | `Bool` | Preserve object metadata from the source to the destination.<br/>Default: `false`.<br/>(`--preserve-object-metadata`) |
|
|
11198
12430
|
| `preserve_uid` | `Bool` | Preserve the file owner's UID.<br/>Default: `false`.<br/>(`--preserve-uid`)(-u) |
|
|
11199
12431
|
| `quiet` | `Bool` | Disable progress display.<br/>Default: `true`.<br/>(`--quiet`)(-q) |
|
|
11200
|
-
| `remote
|
|
12432
|
+
| `remote` | `Hash` | Required. |
|
|
12433
|
+
| `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
12434
|
| `remote.fingerprint` | `String` | Check it against server SSH host key fingerprint. |
|
|
11202
12435
|
| `remote.host` | `String` | Use the specified host name or address of the remote host.<br/>Required.<br/>(`--host={string}`) |
|
|
11203
12436
|
| `remote.pass` | `String` | Authenticate the transfer with the specified password.<br/>(`--pass={string}`)(-w) |
|
|
11204
12437
|
| `remote.path` | `String` | Synchronize the specified directory on the remote host.<br/>Required.<br/>(`--remote-dir={string}`)(-r) |
|
|
11205
12438
|
| `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
12439
|
| `remote.private_key_paths` | `Array[String]` | Authenticate with the specified SSH private key file.<br/>(`--private-key-path={array}`)(-i) |
|
|
12440
|
+
| `remote.proxy` | `Hash` | Specify the address of the Aspera high-speed proxy server.<br/>(special:`--proxy={object}`) |
|
|
11207
12441
|
| `remote.proxy.host` | `String` | Use the specified host name or address of the proxy. |
|
|
11208
12442
|
| `remote.proxy.pass` | `String` | Authenticate to the proxy with the specified password. |
|
|
11209
12443
|
| `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`. |
|
|
12444
|
+
| `remote.proxy.protocol` | `Enum[String]` | The protocol to be used.<br/>Allowed values: `none`, `dnat`, `dnats`.<br/>Default: `none`. |
|
|
11211
12445
|
| `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
12446
|
| `remote.token` | `String` | Token string passed to server's authentication service. |
|
|
12447
|
+
| `remote.token_node_user` | `String` | Node API user identity associated with the token. Required for node user bearer tokens |
|
|
11215
12448
|
| `remote.user` | `String` | Authenticate the transfer with the specified username.<br/>Required.<br/>(`--user={string}`) |
|
|
11216
12449
|
| `remote.ws_port` | `Integer` | Use the specified port for Websocket. Used when connect_mode is `ws`.<br/>Default: `9093`. |
|
|
11217
12450
|
| `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 +12455,45 @@ ascli config sync spec
|
|
|
11222
12455
|
| `remote_keep_dir` | `String` | Move deleted files into the specified directory on the remote host.<br/>(`--keep-dir-remote={string}`) |
|
|
11223
12456
|
| `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
12457
|
| `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}`) |
|
|
12458
|
+
| `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}`) |
|
|
12459
|
+
| `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
12460
|
| `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
12461
|
| `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
12462
|
| `remote_stat_cache_size` | `Integer` | Set stat cache size on the remote host. 0 for disabled.<br/>Default: `0`. |
|
|
11230
|
-
| `remote` | `Hash` | Required. |
|
|
11231
12463
|
| `remove_after_transfer` | `Bool` | Remove source files after they are successfully synchronized.<br/>Default: `false`.<br/>(`--remove-after-transfer`) |
|
|
11232
12464
|
| `reset` | `Bool` | Clear the snapshot database and rescan the synchronized directories and files to create a fresh snapshot<br/>Default: `false`.<br/>(`--reset`)(-x) |
|
|
12465
|
+
| `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
12466
|
| `resume.enabled` | `Bool` | Enable the possibility of resuming individual file transfers between async sessions.<br/>Default: `false`. |
|
|
11234
12467
|
| `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
12468
|
| `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
12469
|
| `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
12470
|
| `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
12471
|
| `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) |
|
|
12472
|
+
| `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
12473
|
| `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
12474
|
| `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) |
|
|
12475
|
+
| `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
12476
|
| `tags` | `Hash` | User-defined metadata tags.<br/>(special:`--tags64={object}`) |
|
|
12477
|
+
| `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
12478
|
| `transfer_threads[].size` | `Integer` | Upper limit. `-1` for infinity.<br/>Default: `-1`. |
|
|
11246
12479
|
| `transfer_threads[].threads` | `Integer` | The number of threads.<br/>Required. |
|
|
11247
|
-
| `
|
|
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}`) |
|
|
12480
|
+
| `transport` | `Hash` | |
|
|
12481
|
+
| `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) |
|
|
12482
|
+
| `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
12483
|
| `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
12484
|
| `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) |
|
|
12485
|
+
| `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
12486
|
| `transport.raw_options` | `Array[String]` | Pass arbitrary arguments to `ascp`.<br/>(special:`--raw-options={array}`) |
|
|
11254
12487
|
| `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
12488
|
| `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
12489
|
| `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
12490
|
| `transport.udp_port` | `Integer` | Use the specified UDP port for FASP data transfer.<br/>Default: `33001`.<br/>(`--udp-port={integer}`)(-O) |
|
|
11258
12491
|
| `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
|
-
| `
|
|
11260
|
-
| `watchd.datastore` | `String` | Specify the type of datastore, `none` for disabled.<br/>Allowed values: `none`, `redis`, `scalekv`.<br/>Default: `none`. |
|
|
12492
|
+
| `watchd` | `Hash` | When connection is configured, `asperawatchd` is used to detect the changes on the source directory.<br/>(special:`--watchd={object}`) |
|
|
12493
|
+
| `watchd.datastore` | `Enum[String]` | Specify the type of datastore, `none` for disabled.<br/>Allowed values: `none`, `redis`, `scalekv`.<br/>Default: `none`. |
|
|
11261
12494
|
| `watchd.domain` | `String` | Specify the domain. Default is the current username. |
|
|
11262
12495
|
| `watchd.host` | `String` | Use the specified host name or address to connect to the datastore. |
|
|
11263
12496
|
| `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
12497
|
| `write_gid` | `String` | Try to write files as the specified group.<br/>(`--write-gid={string}`) |
|
|
11266
12498
|
| `write_uid` | `String` | Try to write files as the specified user.<br/>(`--write-uid={string}`) |
|
|
11267
12499
|
|
|
@@ -11338,16 +12570,16 @@ ascli ... sync admin file_info <FOLDER> --sql="WHERE state=20 ORDER BY f_meta_pa
|
|
|
11338
12570
|
**`sync_snapmeta_table`** - one row per session, written at start and updated at stop:
|
|
11339
12571
|
|
|
11340
12572
|
| Field | Type | Description |
|
|
11341
|
-
|
|
12573
|
+
| ----------------------- | ------------ | -------------------------------------------------------------------------------- |
|
|
11342
12574
|
| `ascp_sids` | `String` | Last known FASP (ascp) session IDs. |
|
|
11343
12575
|
| `byte_peerxfer` | `Integer` | Number of bytes transferred by the peer. |
|
|
11344
12576
|
| `byte_synced` | `Integer` | Number of bytes successfully synchronized. |
|
|
11345
12577
|
| `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`. |
|
|
12578
|
+
| `checksum` | `Enum[String]` | Checksum algorithm.<br/>Allowed values: `sha1`, `md5`, `sha1_sparse`, `md5_sparse`, `none`. |
|
|
11347
12579
|
| `cip_true_val` | `Integer` | Candidate-in-progress counter true value (internal). |
|
|
11348
|
-
| `condition` | `String` | Last known session condition.<br/>Allowed values: `running`, `stopped`. |
|
|
12580
|
+
| `condition` | `Enum[String]` | Last known session condition.<br/>Allowed values: `running`, `stopped`. |
|
|
11349
12581
|
| `dbversion` | `String` | Database schema version. |
|
|
11350
|
-
| `direction` | `String` | Sync direction.<br/>Allowed values: `push`, `pull`, `bidi`. |
|
|
12582
|
+
| `direction` | `Enum[String]` | Sync direction.<br/>Allowed values: `push`, `pull`, `bidi`. |
|
|
11351
12583
|
| `exclude_dirs_older_than` | `Integer` | Exclude directories with modification time older than this epoch value (0 = disabled). |
|
|
11352
12584
|
| `file_peerxfer` | `Integer` | Number of files transferred by the peer. |
|
|
11353
12585
|
| `file_synced` | `Integer` | Number of files successfully synchronized. |
|
|
@@ -11371,7 +12603,7 @@ ascli ... sync admin file_info <FOLDER> --sql="WHERE state=20 ORDER BY f_meta_pa
|
|
|
11371
12603
|
**`sync_snap_counters_table`** - one row, updated live during a session:
|
|
11372
12604
|
|
|
11373
12605
|
| Field | Type | Description |
|
|
11374
|
-
|
|
12606
|
+
| ------------------------ | ------- | ------------------------------------------------ |
|
|
11375
12607
|
| `conflict` | `Integer` | Number of paths in the `Conflict` state. |
|
|
11376
12608
|
| `error` | `Integer` | Number of paths in the `Error` state. |
|
|
11377
12609
|
| `files_conflict` | `Integer` | Number of files in the `Conflict` state. |
|
|
@@ -11387,7 +12619,7 @@ ascli ... sync admin file_info <FOLDER> --sql="WHERE state=20 ORDER BY f_meta_pa
|
|
|
11387
12619
|
**`sync_snapdb_table`** - one row per tracked file or directory:
|
|
11388
12620
|
|
|
11389
12621
|
| Field | Type | Description |
|
|
11390
|
-
|
|
12622
|
+
| ---------------------- | ------- | -------------------------------------------------------------------------------- |
|
|
11391
12623
|
| `c_cont_csum` | `String` | Current content — checksum. |
|
|
11392
12624
|
| `c_cont_mtime` | `Integer` | Current content — modification time (epoch). |
|
|
11393
12625
|
| `c_cont_size` | `Integer` | Current content — file size in bytes. |
|
|
@@ -11405,8 +12637,8 @@ ascli ... sync admin file_info <FOLDER> --sql="WHERE state=20 ORDER BY f_meta_pa
|
|
|
11405
12637
|
| `c_meta_path` | `String` | Current metadata — file path as known to the snapshot. |
|
|
11406
12638
|
| `c_meta_type` | `Integer` | Current metadata — file type (file, directory, …). |
|
|
11407
12639
|
| `c_meta_uid` | `Integer` | Current metadata — user ID (Unix). |
|
|
11408
|
-
| `c_meta_xattrs_cksum` | `String` | Current metadata — checksum of extended attributes. |
|
|
11409
12640
|
| `c_meta_xattrs` | `Integer` | Current metadata — extended attributes (not used). |
|
|
12641
|
+
| `c_meta_xattrs_cksum` | `String` | Current metadata — checksum of extended attributes. |
|
|
11410
12642
|
| `candidate_in_prog` | `Integer` | Set to 1 when this record is currently in the candidate transfer list. |
|
|
11411
12643
|
| `commit_version` | `Integer` | Local commit version for this entry. |
|
|
11412
12644
|
| `f_cont_csum` | `String` | Filesystem content — checksum. |
|
|
@@ -11426,8 +12658,8 @@ ascli ... sync admin file_info <FOLDER> --sql="WHERE state=20 ORDER BY f_meta_pa
|
|
|
11426
12658
|
| `f_meta_path` | `String` | Filesystem metadata — file path as seen on disk (displayed by `file_info`). |
|
|
11427
12659
|
| `f_meta_type` | `Integer` | Filesystem metadata — file type. |
|
|
11428
12660
|
| `f_meta_uid` | `Integer` | Filesystem metadata — user ID (Unix). |
|
|
11429
|
-
| `f_meta_xattrs_cksum` | `String` | Filesystem metadata — checksum of extended attributes. |
|
|
11430
12661
|
| `f_meta_xattrs` | `Integer` | Filesystem metadata — extended attributes (not used). |
|
|
12662
|
+
| `f_meta_xattrs_cksum` | `String` | Filesystem metadata — checksum of extended attributes. |
|
|
11431
12663
|
| `message` | `String` | Error or status message associated with this entry. |
|
|
11432
12664
|
| `meta_lastreq_no` | `Integer` | Sequence number of the last metadata request sent. |
|
|
11433
12665
|
| `meta_lastresp_no` | `Integer` | Sequence number of the last metadata response received. |
|
|
@@ -11588,11 +12820,11 @@ To do so, set up the SMTP configuration with option `smtp`.
|
|
|
11588
12820
|
The `smtp` option is a `Hash` ([Extended Value](#extended-value-syntax)) with the following fields:
|
|
11589
12821
|
|
|
11590
12822
|
| Field | Type | Description |
|
|
11591
|
-
|
|
12823
|
+
| ---------- | ------- | -------------------------------------------------------------------------------- |
|
|
11592
12824
|
| `domain` | `String` | Email domain of the user. Defaults to the domain part of `server`.<br/>Example: `gmail.com`. |
|
|
11593
12825
|
| `from_email` | `String` | Sender address (used in `From:` header and as reply-to). Defaults to `username` when defined.<br/>Example: `johnny@example.com`. |
|
|
11594
12826
|
| `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:
|
|
12827
|
+
| `password` | `String` | Password for the above `username`.<br/>Example: `<PASSWORD>`. |
|
|
11596
12828
|
| `port` | `Integer` | Port for the SMTP service.<br/>Defaults: `587` (TLS), `465` (SSL), `25` (plain).<br/>Example: `587`. |
|
|
11597
12829
|
| `server` | `String` | SMTP server address.<br/>Required.<br/>Example: `smtp.gmail.com`. |
|
|
11598
12830
|
| `ssl` | `Bool` | Enable `TLS/SSL` (port 465).<br/>Default: `false`. |
|
|
@@ -11610,14 +12842,13 @@ ascli config preset set smtp_google password <PASSWORD>
|
|
|
11610
12842
|
or
|
|
11611
12843
|
|
|
11612
12844
|
```shell
|
|
11613
|
-
ascli config preset
|
|
12845
|
+
ascli config preset set smtp_google @json:'{"server":"smtp.google.com","username":"john@gmail.com","password":"<PASSWORD>"}'
|
|
11614
12846
|
```
|
|
11615
12847
|
|
|
11616
12848
|
or
|
|
11617
12849
|
|
|
11618
|
-
|
|
11619
12850
|
```shell
|
|
11620
|
-
ascli config preset
|
|
12851
|
+
ascli config preset set smtp_google @: server=smtp.google.com username=john@gmail.com password=<PASSWORD>
|
|
11621
12852
|
```
|
|
11622
12853
|
|
|
11623
12854
|
Set this configuration as global default, for instance:
|
|
@@ -11821,28 +13052,26 @@ This also requires Ruby header files.
|
|
|
11821
13052
|
If Ruby was installed as a Linux package, then also install the Ruby development package:
|
|
11822
13053
|
`ruby-dev` or `ruby-devel`, depending on distribution.
|
|
11823
13054
|
|
|
11824
|
-
### Private key type: `ed25519`
|
|
11825
|
-
|
|
11826
|
-
There are a few aspects concerning ED25519 keys.
|
|
13055
|
+
### Private key type: `ed25519`
|
|
11827
13056
|
|
|
11828
|
-
|
|
11829
|
-
|
|
11830
|
-
If you want to use `ed25519` keys, then install the required gems:
|
|
13057
|
+
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.
|
|
13058
|
+
Only OpenSSH private keys protected by a passphrase require the `bcrypt_pbkdf` gem, which requires compilation of native code:
|
|
11831
13059
|
|
|
11832
13060
|
```shell
|
|
11833
|
-
gem install
|
|
13061
|
+
gem install bcrypt_pbkdf
|
|
11834
13062
|
```
|
|
11835
13063
|
|
|
11836
|
-
|
|
13064
|
+
If the gem is missing, then loading such a key fails with an error mentioning `bcrypt_pbkdf`.
|
|
13065
|
+
|
|
13066
|
+
If the OpenSSL backend does not support Ed25519, then the following message is displayed:
|
|
11837
13067
|
|
|
11838
13068
|
```text
|
|
11839
13069
|
OpenSSH keys only supported if ED25519 is available (NotImplementedError)
|
|
11840
|
-
net-ssh requires
|
|
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
|
|
13070
|
+
net-ssh requires openssl >= 3.2.0 and a crypto backend with Ed25519 enabled for ed25519 support.
|
|
11844
13071
|
```
|
|
11845
13072
|
|
|
13073
|
+
To ignore the `ed25519` keys of the default identities (`~/.ssh/id_ed25519`), set env var `ASCLI_ENABLE_ED25519` to `false`.
|
|
13074
|
+
|
|
11846
13075
|
In addition, if **JRuby** is used, host keys of type: `ecdsa-sha2` and `ecdh-sha2` are also deactivated by default.
|
|
11847
13076
|
To activate, set env var `ASCLI_ENABLE_ECDSHA2` to `true`.
|
|
11848
13077
|
|
|
@@ -11878,7 +13107,7 @@ This happens on Linux x86 if you try to install `transferd` on a Linux version t
|
|
|
11878
13107
|
Workaround: Install an older version of `transferd`:
|
|
11879
13108
|
|
|
11880
13109
|
```shell
|
|
11881
|
-
ascli
|
|
13110
|
+
ascli transferd install 1.1.2
|
|
11882
13111
|
```
|
|
11883
13112
|
|
|
11884
13113
|
See [Single file executable](#single-file-executable).
|
|
@@ -11919,11 +13148,45 @@ Another possibility is to add this option: `--transfer=@json:'{"ascp_args":["--p
|
|
|
11919
13148
|
> 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
13149
|
> Use `flock` instead.
|
|
11921
13150
|
|
|
13151
|
+
## Security and Trust
|
|
13152
|
+
|
|
13153
|
+
This section is for security and compliance reviewers who evaluate `ascli` before its use in an organization.
|
|
13154
|
+
It summarizes how `ascli` protects credentials, communications and the system that runs it, and how the project is developed and released.
|
|
13155
|
+
The detailed reasoning is in the [Security Assurance Case](ASSURANCE_CASE.md).
|
|
13156
|
+
|
|
13157
|
+
### Protection by area
|
|
13158
|
+
|
|
13159
|
+
| Area | How `ascli` protects it | Details |
|
|
13160
|
+
| ---- | ------------------------ | ------- |
|
|
13161
|
+
| 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) |
|
|
13162
|
+
| 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) |
|
|
13163
|
+
| 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) |
|
|
13164
|
+
| 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) |
|
|
13165
|
+
| 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) |
|
|
13166
|
+
| 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) |
|
|
13167
|
+
| 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) |
|
|
13168
|
+
|
|
13169
|
+
### Supply chain
|
|
13170
|
+
|
|
13171
|
+
- The gem is signed: its signature can be verified at installation, see [Verifying gem installation signature](#verifying-gem-installation-signature).
|
|
13172
|
+
- Publishing the gem on RubyGems requires multi-factor authentication.
|
|
13173
|
+
- Release packages (gem, single executable, portable packages, container image) are built by GitHub Actions from the repository.
|
|
13174
|
+
- Dependencies are gems, updated with Renovate.
|
|
13175
|
+
- 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).
|
|
13176
|
+
|
|
13177
|
+
### Project practices
|
|
13178
|
+
|
|
13179
|
+
- Open source, Apache 2.0 license, developed in the [IBM GitHub organization](https://github.com/IBM/aspera-cli).
|
|
13180
|
+
- [OpenSSF Best Practices](https://www.bestpractices.dev/projects/5861): silver badge.
|
|
13181
|
+
- Vulnerabilities are reported and handled as described in [SECURITY.md](../SECURITY.md).
|
|
13182
|
+
- Roles, decisions and continuity of the project: [GOVERNANCE.md](../GOVERNANCE.md).
|
|
13183
|
+
- Structure of the code: [ARCHITECTURE.md](ARCHITECTURE.md).
|
|
13184
|
+
|
|
11922
13185
|
## About
|
|
11923
13186
|
|
|
11924
13187
|
### Hootput, the mascot
|
|
11925
13188
|
|
|
11926
|
-

|
|
13189
|
+

|
|
11927
13190
|
|
|
11928
13191
|
Hootput lives in the terminal, watching over every command with wide, unblinking eyes.
|
|
11929
13192
|
Known for concise output and sharp insight, this owl thrives where others get lost in the dark.
|