aspera-cli 4.28.0 → 4.29.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- checksums.yaml +4 -4
- checksums.yaml.gz.sig +0 -0
- data/BUGS.md +5 -10
- data/CHANGELOG.md +143 -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 +103 -26
- data/SECURITY.md +70 -0
- data/bin/ascli +8 -5
- data/bin/asession +9 -6
- data/docs/README.md +1633 -609
- 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 +20 -20
- data/lib/aspera/ascmd.rb +8 -5
- data/lib/aspera/ascp/installation.rb +71 -65
- 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 +354 -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 +176 -0
- data/lib/aspera/cli/async_transfer_store.rb +7 -4
- data/lib/aspera/cli/bootstrapper.rb +37 -33
- data/lib/aspera/cli/command_line.rb +24 -6
- data/lib/aspera/cli/command_registry.rb +6 -1
- data/lib/aspera/cli/command_spec.rb +34 -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 +3 -0
- data/lib/aspera/cli/extended_value.rb +61 -27
- data/lib/aspera/cli/formatter.rb +29 -22
- data/lib/aspera/cli/gem_checker.rb +9 -6
- data/lib/aspera/cli/hints.rb +22 -10
- data/lib/aspera/cli/http.rb +12 -9
- 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 +15 -14
- 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 +65 -12
- data/lib/aspera/cli/options.schema.yaml +487 -63
- data/lib/aspera/cli/parser.rb +56 -32
- data/lib/aspera/cli/plugins/alee.rb +7 -4
- data/lib/aspera/cli/plugins/aoc.rb +244 -35
- data/lib/aspera/cli/plugins/ats.rb +9 -8
- data/lib/aspera/cli/plugins/base.rb +17 -12
- data/lib/aspera/cli/plugins/basic_auth.rb +5 -2
- data/lib/aspera/cli/plugins/config.rb +198 -103
- 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 +28 -25
- 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 +28 -22
- data/lib/aspera/cli/plugins/node.rb +31 -30
- data/lib/aspera/cli/plugins/oauth.rb +5 -1
- data/lib/aspera/cli/plugins/orchestrator.rb +272 -72
- data/lib/aspera/cli/plugins/preview.rb +69 -44
- data/lib/aspera/cli/plugins/server.rb +63 -11
- data/lib/aspera/cli/plugins/shares.rb +86 -16
- data/lib/aspera/cli/plugins/transferd.rb +223 -0
- data/lib/aspera/cli/preset_actions.rb +144 -30
- data/lib/aspera/cli/preset_manager.rb +52 -18
- data/lib/aspera/cli/prompt.rb +4 -1
- data/lib/aspera/cli/result.rb +12 -8
- data/lib/aspera/cli/runner.rb +69 -46
- data/lib/aspera/cli/secret_finder.rb +4 -1
- data/lib/aspera/cli/security.rb +79 -9
- data/lib/aspera/cli/special_values.rb +4 -1
- data/lib/aspera/cli/sync_actions.rb +13 -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 +29 -20
- data/lib/aspera/cli/transfer_progress.rb +13 -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/duration.rb +5 -2
- data/lib/aspera/environment.rb +21 -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 +4 -2
- 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 +91 -70
- data/lib/aspera/oauth/client/boot.rb +7 -4
- data/lib/aspera/oauth/client/factory.rb +6 -3
- data/lib/aspera/oauth/client/generic.rb +5 -1
- data/lib/aspera/oauth/client/json_credentials.rb +4 -1
- data/lib/aspera/oauth/client/jwt.rb +6 -3
- data/lib/aspera/oauth/client/shares_web.rb +85 -0
- data/lib/aspera/oauth/client/url_json.rb +4 -1
- data/lib/aspera/oauth/client/web.rb +39 -12
- data/lib/aspera/oauth/server/pkce.rb +6 -5
- data/lib/aspera/orchestrator_workflow_checker.rb +119 -1
- 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 +8 -4
- data/lib/aspera/preview/utils.rb +6 -4
- data/lib/aspera/products/connect.rb +5 -2
- data/lib/aspera/products/desktop.rb +4 -1
- 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 +22 -29
- 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 +43 -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 +166 -0
- data/lib/aspera/secret/hider.rb +201 -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 +110 -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 +16 -14
- 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 +3 -0
- data/lib/aspera/transfer/resumer.rb +6 -4
- data/lib/aspera/transfer/spec.rb +9 -22
- data/lib/aspera/transfer/units.rb +75 -0
- data/lib/aspera/uri_reader.rb +57 -7
- 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.txt +81 -0
- data/skills/ascli/SKILL.md +88 -0
- data.tar.gz.sig +0 -0
- metadata +72 -19
- metadata.gz.sig +0 -0
- 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.0"
|
|
20
|
+
author: "Laurent Martin"
|
|
21
|
+
-->
|
|
22
|
+
|
|
21
23
|
<!-- Admonitions: NOTE CAUTION WARNING IMPORTANT TIP INFO -->
|
|
22
24
|
|
|
23
25
|
<!-- markdownlint-disable MD028 -->
|
|
@@ -28,9 +30,17 @@ PANDOC_DEFAULTS_END
|
|
|
28
30
|
|
|
29
31
|
### Overview
|
|
30
32
|
|
|
33
|
+
**The automation interface for IBM Aspera. From command line to AI agents.**
|
|
34
|
+
|
|
31
35
|
The IBM Aspera Command Line Interface (`ascli`) is an enterprise-grade tool that provides comprehensive command-line access to IBM Aspera's suite of high-speed file transfer products and services.
|
|
32
36
|
Designed for automation, scripting, and integration scenarios, `ascli` enables organizations to leverage Aspera's FASP technology within their existing workflows and DevOps pipelines.
|
|
33
37
|
|
|
38
|
+
> [!TIP]
|
|
39
|
+
> For any question about `ascli` (behavior, options), or to build a command line, give this manual to an AI assistant as a reference and ask it.
|
|
40
|
+
> See [Leveraging AI Assistance](#leveraging-ai-assistance).
|
|
41
|
+
|
|
42
|
+

|
|
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.0-linux-x86_64.tgz
|
|
170
199
|
export PATH=$PATH:$HOME/bin
|
|
171
200
|
```
|
|
172
201
|
|
|
@@ -180,13 +209,13 @@ ascli -v
|
|
|
180
209
|
```
|
|
181
210
|
|
|
182
211
|
```text
|
|
183
|
-
4.
|
|
212
|
+
4.29.0
|
|
184
213
|
```
|
|
185
214
|
|
|
186
215
|
- Install the Aspera transfer runtime (tested version), as it is not included in the `ascli` package:
|
|
187
216
|
|
|
188
217
|
```shell
|
|
189
|
-
ascli
|
|
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,34 @@ If you'd prefer to test against Aspera on Cloud, skip ahead to the [AoC Wizard](
|
|
|
267
296
|
|
|
268
297
|
### Leveraging AI Assistance
|
|
269
298
|
|
|
270
|
-
You can significantly accelerate your workflow by using an AI assistant
|
|
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
|
+
With an AI client that supports agent skills, install the skill instead: the AI loads it by itself when a request is about IBM Aspera.
|
|
306
|
+
The skill, in the [Agent Skills](https://agentskills.io) format, is the folder `skills/ascli` of the gem (and of the GitHub repository): copy it to the skills folder of the AI client, for example:
|
|
307
|
+
|
|
308
|
+
```shell
|
|
309
|
+
cp -R "$(gem contents aspera-cli | grep 'skills/ascli/SKILL.md$' | xargs dirname)" ~/.claude/skills/
|
|
310
|
+
```
|
|
311
|
+
|
|
312
|
+
With Claude Code, install it as a plugin from the GitHub repository, which is also a plugin marketplace: it is updated with the repository.
|
|
313
|
+
|
|
314
|
+
```text
|
|
315
|
+
/plugin install ascli --marketplace IBM/aspera-cli
|
|
316
|
+
```
|
|
317
|
+
|
|
318
|
+
- **The AI executes commands through MCP**: for an AI client without a shell, start the [MCP server](#plugin-mcp-model-context-protocol-server) and register it in the AI client.
|
|
319
|
+
The AI discovers commands and their arguments by itself, and executes them.
|
|
320
|
+
By default, the server restricts what the AI can do (see [Security](#security)), and the AI never sees secrets.
|
|
321
|
+
|
|
322
|
+
- **The AI generates commands that you execute** (chat assistant that cannot execute commands): it cannot read the documentation through `ascli`, so provide it as context, as described below.
|
|
323
|
+
|
|
324
|
+
In the first two ways, the AI reads the documentation by itself, one section at a time, with `ascli config documentation`: there is no need to provide the manual.
|
|
272
325
|
|
|
273
|
-
Recommended Workflow:
|
|
326
|
+
Recommended Workflow for a chat assistant:
|
|
274
327
|
|
|
275
328
|
- **Contextualize**: Download the project manual (this manual in Markdown format, [`docs/README.md`](https://raw.githubusercontent.com/IBM/aspera-cli/refs/heads/main/docs/README.md)) from the GitHub repository.
|
|
276
329
|
|
|
@@ -347,7 +400,7 @@ This executable includes the Ruby runtime and gems, but not the transfer SDK.
|
|
|
347
400
|
|
|
348
401
|
```shell
|
|
349
402
|
tar zxvf aspera-cli-<VERSION>-<PLATFORM>.tgz
|
|
350
|
-
./ascli
|
|
403
|
+
./ascli transferd install
|
|
351
404
|
```
|
|
352
405
|
|
|
353
406
|
#### Linux: Checking the GLIBC version
|
|
@@ -406,7 +459,7 @@ The GLIBC of the system must be at least the version in the archive name, see [C
|
|
|
406
459
|
|
|
407
460
|
> [!NOTE]
|
|
408
461
|
> The launcher `ascli` uses the `ascp` located in folder `sdk` of the package, unless environment variable `ASCLI_SDK_FOLDER` is set.
|
|
409
|
-
> So, `ascli
|
|
462
|
+
> So, `ascli transferd install` is not needed.
|
|
410
463
|
|
|
411
464
|
The configuration is stored in the [main folder](#main-configuration-and-persistency-folder), like for other installation methods.
|
|
412
465
|
To upgrade, extract the new version, and update the symbolic link.
|
|
@@ -443,7 +496,7 @@ Apart from the prerequisite below, no installation step, no administrator rights
|
|
|
443
496
|
|
|
444
497
|
> [!NOTE]
|
|
445
498
|
> The launcher `ascli.cmd` uses the `ascp` located in folder `sdk` of the package, unless environment variable `ASCLI_SDK_FOLDER` is set.
|
|
446
|
-
> So, `ascli
|
|
499
|
+
> So, `ascli transferd install` is not needed.
|
|
447
500
|
|
|
448
501
|
The configuration is stored in the [main folder](#main-configuration-and-persistency-folder), like for other installation methods.
|
|
449
502
|
To upgrade, extract the new version, and update the `PATH` if the folder name changed.
|
|
@@ -465,10 +518,10 @@ Then, install the Aspera Transfer Daemon, see [Installing `ascp` through `transf
|
|
|
465
518
|
|
|
466
519
|
A Ruby interpreter is required to run `ascli`.
|
|
467
520
|
|
|
468
|
-
Required Ruby version is version: >= 3.
|
|
521
|
+
Required Ruby version is version: >= 3.3.
|
|
469
522
|
|
|
470
523
|
> [!WARNING]
|
|
471
|
-
> The minimum Ruby version will be 3.
|
|
524
|
+
> The minimum Ruby version will be 3.4 in a future version.
|
|
472
525
|
|
|
473
526
|
**Ruby can be installed using any of the following methods**: `rpm`, `yum`, `dnf`, `rvm`, `rbenv`, `brew`, Windows installer, ...
|
|
474
527
|
|
|
@@ -479,10 +532,21 @@ Required Ruby version is version: >= 3.2.
|
|
|
479
532
|
|
|
480
533
|
For convenience, you may refer to the following sections for a proposed method for specific operating systems.
|
|
481
534
|
|
|
482
|
-
`ascli` supports a Ruby version until
|
|
535
|
+
`ascli` supports a Ruby version until 6 months after its [end of official support](https://www.ruby-lang.org/en/downloads/branches/).
|
|
483
536
|
The minimum version is increased accordingly, and announced in advance.
|
|
484
537
|
If only an older Ruby version must be used due to system constraints, use an older version of `ascli` that supports it; refer to [rubygems.org](https://rubygems.org/gems/aspera-cli).
|
|
485
538
|
|
|
539
|
+
The following table summarizes Ruby version life cycles and `ascli` support status:
|
|
540
|
+
|
|
541
|
+
| Ruby Version | Official EOL Date | ascli Support End (EOL + 6 mo) | ascli Status |
|
|
542
|
+
| ------------ | ----------------- | ------------------------------ | --------------------------------- |
|
|
543
|
+
| 4.0 | 2029-03-31 | 2029-09-30 | **Supported (Tested & Packaged)** |
|
|
544
|
+
| 3.4 | 2028-03-31 | 2028-09-30 | **Supported (Future minimum)** |
|
|
545
|
+
| 3.3 | 2027-03-31 | 2027-09-30 | **Supported (Current minimum)** |
|
|
546
|
+
| 3.2 | 2026-03-31 | 2026-09-30 | End of Support |
|
|
547
|
+
| 3.1 | 2025-03-26 | 2025-09-26 | End of Support |
|
|
548
|
+
| 3.0 | 2024-04-23 | 2024-10-23 | End of Support |
|
|
549
|
+
|
|
486
550
|
#### Windows: Installer
|
|
487
551
|
|
|
488
552
|
Manual installation:
|
|
@@ -545,6 +609,24 @@ Add it to your shell configuration file:
|
|
|
545
609
|
|
|
546
610
|
#### Linux: Package
|
|
547
611
|
|
|
612
|
+
`ascli` supports Linux distributions that are officially maintained by their vendor (Red Hat for RHEL / UBI, Canonical for Ubuntu LTS).
|
|
613
|
+
|
|
614
|
+
- **GLIBC Requirement:** The Transfer SDK executables (`ascp`, `transferd`) and the Linux portable package require **`glibc >= 2.28`**.
|
|
615
|
+
- **Installation Compatibility:**
|
|
616
|
+
- If the OS provides a Ruby package or DNF module stream meeting the required version (≥ 3.3), the `aspera-cli` gem can be installed directly with `gem install`.
|
|
617
|
+
- If the OS is under maintenance but ships an older default system Ruby (e.g. Ubuntu 22.04 LTS with Ruby 3.0), `ascli` is fully supported via the [Linux portable package](#linux-portable-package), the [container image](#container), or a Ruby version manager (`rbenv`, `rvm`).
|
|
618
|
+
|
|
619
|
+
The following table summarizes supported Linux distributions, vendor end of support dates, GLIBC versions, available Ruby streams, and recommended `ascli` installation modes:
|
|
620
|
+
|
|
621
|
+
| Linux Distribution | OS Support End (EOL) | GLIBC (>= 2.28) | OS Ruby Version(s) | ascli Support / Mode |
|
|
622
|
+
| -------------------- | -------------------- | ------------------ | ------------------------------------ | ----------------------------------------------------- |
|
|
623
|
+
| **RHEL / UBI 10** | 2035-05-31 | 2.39+ (Compatible) | >= 3.3 (default) | Gem, Portable, Container |
|
|
624
|
+
| **RHEL / UBI 9** | 2032-05-31 | 2.34 (Compatible) | 3.0 (default), 3.1, 3.3 (DNF module) | Gem (`dnf module enable ruby:3.3`), Portable, Container |
|
|
625
|
+
| **RHEL / UBI 8** | 2029-05-31 | 2.28 (Compatible) | 3.1, 3.3 (DNF module) | Gem (`dnf module enable ruby:3.3`), Portable, Container |
|
|
626
|
+
| **Ubuntu 26.04 LTS** | 2031-05-29 | 2.43+ (Compatible) | >= 3.3 (APT package) | Gem, Portable, Container |
|
|
627
|
+
| **Ubuntu 24.04 LTS** | 2029-05-31 | 2.39 (Compatible) | 3.2 (APT package) | Gem (`apt install ruby-full`), Portable, Container |
|
|
628
|
+
| **Ubuntu 22.04 LTS** | 2027-06-01 | 2.35 (Compatible) | 3.0 (APT package) | Portable, Container, rbenv (OS Ruby < 3.2) |
|
|
629
|
+
|
|
548
630
|
If your Linux distribution provides a standard Ruby package, you can use it provided that the version is supported.
|
|
549
631
|
|
|
550
632
|
**Example:** RHEL 8+, Rocky Linux 8+: with extensions to compile native gems:
|
|
@@ -754,30 +836,30 @@ Those are not installed as part of dependencies because they involve compilation
|
|
|
754
836
|
See [Gemfile](../Gemfile):
|
|
755
837
|
|
|
756
838
|
| name | version | comment |
|
|
757
|
-
|
|
839
|
+
| ---------------------- | --------- | -------------------------------------------------------------------------------- |
|
|
758
840
|
| rake | ~> 13.0 | |
|
|
759
841
|
| debug | ~> 1.11 | (no jruby) |
|
|
760
842
|
| grpc-tools | ~> 1.67 | |
|
|
761
|
-
| reek | ~> 6.
|
|
843
|
+
| reek | ~> 6.6.0 | |
|
|
762
844
|
| rspec | ~> 3.0 | |
|
|
763
845
|
| rubocop | ~> 1.75 | |
|
|
764
846
|
| rubocop-ast | ~> 1.4 | |
|
|
765
847
|
| rubocop-performance | ~> 1.10 | (no jruby) |
|
|
766
|
-
| rubocop-shopify | ~>
|
|
767
|
-
| simplecov | ~>
|
|
848
|
+
| rubocop-shopify | ~> 3.1 | |
|
|
849
|
+
| simplecov | ~> 1.3 | |
|
|
768
850
|
| solargraph | ~> 0.48 | (no jruby) |
|
|
769
|
-
| ferrum | ~> 0.
|
|
851
|
+
| ferrum | ~> 0.20.1 | (no jruby) |
|
|
770
852
|
| mcp | ~> 1.2 | for ascli mcp server (MCP protocol support) |
|
|
771
853
|
| rack | ~> 3.0 | for ascli mcp server HTTP transport (required by mcp StreamableHTTPTransport) |
|
|
772
854
|
| grpc | ~> 1.71 | (no jruby) for Aspera Transfer Daemon |
|
|
773
855
|
| sqlite3 | ~> 2.7 | (no jruby) for async DB |
|
|
774
856
|
| jdbc-sqlite3 | ~> 3.46 | (jruby) for async DB |
|
|
775
857
|
| sequel | ~> 5.96 | (jruby) for async DB |
|
|
776
|
-
|
|
|
777
|
-
| bcrypt_pbkdf | ~> 1.1 | (no jruby) for ed25519 and OpenSSH file format |
|
|
858
|
+
| bcrypt_pbkdf | ~> 1.1 | (no jruby) for passphrase-protected OpenSSH private keys (ed25519 is native in net-ssh 8) |
|
|
778
859
|
| syslog | ~> 0.3 | (no jruby) for logger=syslog |
|
|
779
860
|
| zxcvbn | ~> 1.0 | for better estimate of secret strength (faspex5 postprocessing secret_token) |
|
|
780
|
-
|
|
|
861
|
+
| keeper_secrets_manager | ~> 17.2 | for vault of type keeper (Keeper Secrets Manager) |
|
|
862
|
+
| rmagick | ~> 7.2 | (no jruby) for terminal view |
|
|
781
863
|
|
|
782
864
|
Install like this:
|
|
783
865
|
|
|
@@ -785,26 +867,26 @@ Install like this:
|
|
|
785
867
|
gem install rake -v '~> 13.0'
|
|
786
868
|
gem install debug -v '~> 1.11'
|
|
787
869
|
gem install grpc-tools -v '~> 1.67'
|
|
788
|
-
gem install reek -v '~> 6.
|
|
870
|
+
gem install reek -v '~> 6.6.0'
|
|
789
871
|
gem install rspec -v '~> 3.0'
|
|
790
872
|
gem install rubocop -v '~> 1.75'
|
|
791
873
|
gem install rubocop-ast -v '~> 1.4'
|
|
792
874
|
gem install rubocop-performance -v '~> 1.10'
|
|
793
|
-
gem install rubocop-shopify -v '~>
|
|
794
|
-
gem install simplecov -v '~>
|
|
875
|
+
gem install rubocop-shopify -v '~> 3.1'
|
|
876
|
+
gem install simplecov -v '~> 1.3'
|
|
795
877
|
gem install solargraph -v '~> 0.48'
|
|
796
|
-
gem install ferrum -v '~> 0.
|
|
878
|
+
gem install ferrum -v '~> 0.20.1'
|
|
797
879
|
gem install mcp -v '~> 1.2'
|
|
798
880
|
gem install rack -v '~> 3.0'
|
|
799
881
|
gem install grpc -v '~> 1.71'
|
|
800
882
|
gem install sqlite3 -v '~> 2.7'
|
|
801
883
|
gem install jdbc-sqlite3 -v '~> 3.46'
|
|
802
884
|
gem install sequel -v '~> 5.96'
|
|
803
|
-
gem install ed25519 -v '~> 1.4'
|
|
804
885
|
gem install bcrypt_pbkdf -v '~> 1.1'
|
|
805
886
|
gem install syslog -v '~> 0.3'
|
|
806
887
|
gem install zxcvbn -v '~> 1.0'
|
|
807
|
-
gem install
|
|
888
|
+
gem install keeper_secrets_manager -v '~> 17.2'
|
|
889
|
+
gem install rmagick -v '~> 7.2'
|
|
808
890
|
```
|
|
809
891
|
|
|
810
892
|
### Ruby gem: `aspera-cli`
|
|
@@ -880,7 +962,7 @@ The easiest option to install `ascp` is through the use of the IBM Aspera Transf
|
|
|
880
962
|
Install it using `ascli` (for the current platform) with:
|
|
881
963
|
|
|
882
964
|
```shell
|
|
883
|
-
ascli
|
|
965
|
+
ascli transferd install
|
|
884
966
|
```
|
|
885
967
|
|
|
886
968
|
The installation of the transfer binaries follows those steps:
|
|
@@ -903,30 +985,33 @@ The installation of the transfer binaries follows those steps:
|
|
|
903
985
|
| `locations_url` | List of URLs to get download URLs of Aspera Transfer Daemon from IBM official repository, tried in order.<br/>A list given in options replaces the default list.<br/>Default:<br/>- `https://ibm.biz/sdk_location`<br/>- `https://raw.githubusercontent.com/IBM/aspera-cli/refs/heads/main/docs/sdk_location.yaml`|
|
|
904
986
|
| `sdk_folder` | Folder where the SDK archive is extracted.<br/>Default: `$HOME/.aspera/sdk` |
|
|
905
987
|
|
|
906
|
-
|
|
988
|
+
> [!NOTE]
|
|
989
|
+
> Commands `config transferd ...` and `config ascp install` are deprecated aliases of `transferd ...` and `transferd install`.
|
|
990
|
+
|
|
991
|
+
Transfer Daemon versions available from `locations_url` can be listed with: `ascli transferd list`
|
|
907
992
|
|
|
908
993
|
To install a specific version, for example, 1.1.3:
|
|
909
994
|
|
|
910
995
|
```shell
|
|
911
|
-
ascli
|
|
996
|
+
ascli transferd install 1.1.3
|
|
912
997
|
```
|
|
913
998
|
|
|
914
999
|
To get the download URL for a specific platform and version:
|
|
915
1000
|
|
|
916
1001
|
```shell
|
|
917
|
-
ascli
|
|
1002
|
+
ascli transferd list --select.platform=osx-arm64 --select.version=1.1.3 --fields=url
|
|
918
1003
|
```
|
|
919
1004
|
|
|
920
1005
|
To download it, pipe to `config download`:
|
|
921
1006
|
|
|
922
1007
|
```shell
|
|
923
|
-
ascli
|
|
1008
|
+
ascli transferd list --select.platform=osx-arm64 --select.version=1.1.3 --fields=url | ascli config download @stdin:
|
|
924
1009
|
```
|
|
925
1010
|
|
|
926
1011
|
To install from a local file (air-gapped installation) instead of fetching from the internet, specify the location of the SDK file with option `sdk_url`:
|
|
927
1012
|
|
|
928
1013
|
```shell
|
|
929
|
-
ascli
|
|
1014
|
+
ascli transferd install --sdk-url=file:///macos-arm64-1.1.3-c6c7a2a.zip
|
|
930
1015
|
```
|
|
931
1016
|
|
|
932
1017
|
The format is: `file:///<PATH>` (canonical form) or `file:<PATH>` (short form), where `<PATH>` can be either a relative path (not starting with `/`), or an absolute path (starting with `/`).
|
|
@@ -942,7 +1027,7 @@ Supported platforms are listed in the [Release Notes](https://developer.ibm.com/
|
|
|
942
1027
|
|
|
943
1028
|
If the embedded method is not used, the following packages are also suitable:
|
|
944
1029
|
|
|
945
|
-
- IBM Aspera Connect Client (Free)
|
|
1030
|
+
- IBM Aspera Connect Client (Free, to be deprecated in 2027, use IBM Aspera for Desktop)
|
|
946
1031
|
- IBM Aspera Desktop Client (Free)
|
|
947
1032
|
- IBM Aspera for Desktop (Free)
|
|
948
1033
|
- IBM Aspera High Speed Transfer Server (Licensed)
|
|
@@ -980,13 +1065,13 @@ For an air-gapped installation, two alternatives are available:
|
|
|
980
1065
|
On a system with internet access, retrieve the SDK archive for the target platform and version:
|
|
981
1066
|
|
|
982
1067
|
```shell
|
|
983
|
-
ascli
|
|
1068
|
+
ascli transferd list --select.platform=<PLATFORM> --select.version=<VERSION> --fields=url | ascli config download @stdin:
|
|
984
1069
|
```
|
|
985
1070
|
|
|
986
1071
|
On the air-gapped system, install from the downloaded file using option `--sdk-url`:
|
|
987
1072
|
|
|
988
1073
|
```shell
|
|
989
|
-
ascli
|
|
1074
|
+
ascli transferd install --sdk-url=file:///<SDK_ARCHIVE_PATH>
|
|
990
1075
|
```
|
|
991
1076
|
|
|
992
1077
|
2. Retrieve the [single file executable](#single-file-executable) from the release, if available, and the SDK (not included) as described above.
|
|
@@ -999,11 +1084,11 @@ Alternatively, the necessary gems can be packaged into a `tar.gz` archive as fol
|
|
|
999
1084
|
|
|
1000
1085
|
```shell
|
|
1001
1086
|
mkdir temp_folder
|
|
1002
|
-
gem install aspera-cli:4.
|
|
1087
|
+
gem install aspera-cli:4.29.0 --no-document --install-dir temp_folder
|
|
1003
1088
|
find temp_folder
|
|
1004
|
-
mv temp_folder/cache aspera-cli-4.
|
|
1089
|
+
mv temp_folder/cache aspera-cli-4.29.0-gems
|
|
1005
1090
|
rm -fr temp_folder
|
|
1006
|
-
tar zcvf aspera-cli-4.
|
|
1091
|
+
tar zcvf aspera-cli-4.29.0-gems.tgz aspera-cli-4.29.0-gems
|
|
1007
1092
|
```
|
|
1008
1093
|
|
|
1009
1094
|
#### Unix-like: Alternative installation using `rvm`
|
|
@@ -1028,7 +1113,7 @@ The following procedure applies when using RVM for the Ruby installation:
|
|
|
1028
1113
|
cd $HOME
|
|
1029
1114
|
tar zxvf rvm-ascli.tgz
|
|
1030
1115
|
source ~/.rvm/scripts/rvm
|
|
1031
|
-
ascli
|
|
1116
|
+
ascli transferd install --sdk-url=file:///<SDK_ARCHIVE_PATH>
|
|
1032
1117
|
```
|
|
1033
1118
|
|
|
1034
1119
|
6. Add the following line to the shell environment file (`.profile`):
|
|
@@ -1076,7 +1161,7 @@ On the target system:
|
|
|
1076
1161
|
4. Install the Aspera Transfer Daemon SDK:
|
|
1077
1162
|
|
|
1078
1163
|
```shell
|
|
1079
|
-
ascli
|
|
1164
|
+
ascli transferd install --sdk-url=file:///<SDK_ARCHIVE_PATH>
|
|
1080
1165
|
```
|
|
1081
1166
|
|
|
1082
1167
|
### Container
|
|
@@ -1139,7 +1224,7 @@ ascli -v
|
|
|
1139
1224
|
```
|
|
1140
1225
|
|
|
1141
1226
|
```text
|
|
1142
|
-
4.
|
|
1227
|
+
4.29.0
|
|
1143
1228
|
```
|
|
1144
1229
|
|
|
1145
1230
|
To persist the configuration on the host, specify your user's configuration folder as a volume for the container.
|
|
@@ -1464,7 +1549,6 @@ Command line arguments that are not options are referred to as **Positional Argu
|
|
|
1464
1549
|
|
|
1465
1550
|
For example:
|
|
1466
1551
|
|
|
1467
|
-
|
|
1468
1552
|
```shell
|
|
1469
1553
|
ascli plugin command verb --option-name=VAL1 VAL2
|
|
1470
1554
|
```
|
|
@@ -1474,6 +1558,7 @@ ascli plugin command verb --option-name=VAL1 VAL2
|
|
|
1474
1558
|
|
|
1475
1559
|
Enumeration values (positional arguments and option names/values) support prefix matching.
|
|
1476
1560
|
See [Enumerations](#enumerations) for details.
|
|
1561
|
+
|
|
1477
1562
|
For example `ascli config pre ov --for=c` is the same as `ascli config preset overview --format=csv`.
|
|
1478
1563
|
|
|
1479
1564
|
The value of **Options** and **Command Parameters** is evaluated with the [Extended Value](#extended-value-syntax) syntax.
|
|
@@ -1580,7 +1665,6 @@ The following are enumerations:
|
|
|
1580
1665
|
|
|
1581
1666
|
Examples:
|
|
1582
1667
|
|
|
1583
|
-
|
|
1584
1668
|
- Positional: `ascli config pre ov --for=c` is the same as `ascli config preset overview --format=csv`
|
|
1585
1669
|
- Option name: `--log-l=debug` is the same as `--log-level=debug`
|
|
1586
1670
|
- Option value: `--format=c` is the same as `--format=csv`
|
|
@@ -1602,7 +1686,7 @@ Understanding this concept once makes it immediately usable everywhere it appear
|
|
|
1602
1686
|
| [Option](#options) names | `--opt.key.sub=value` | Input | write |
|
|
1603
1687
|
| [Positional arguments](#positional-arguments) | `@: key.sub=value ... [END]` | Input | write |
|
|
1604
1688
|
| [Extended value](#extended-value-syntax) `@preset:` | `@preset:key.sub` | Input | read |
|
|
1605
|
-
| [Output field names](#
|
|
1689
|
+
| [Output field names](#filtering-results) | `--out.fields=key.sub` | Output | read |
|
|
1606
1690
|
|
|
1607
1691
|
A [dot-path](#dot-path-notation) is a `String` where segments are separated by `.` (dot), each segment designating a key in a nested structure:
|
|
1608
1692
|
|
|
@@ -1666,6 +1750,8 @@ The general syntax for this argument is:
|
|
|
1666
1750
|
The optional text after `:` sets the end marker. If it is empty, the marker is `END`.
|
|
1667
1751
|
|
|
1668
1752
|
- `<DOT_PATH>=<VALUE>`: An assignment using the standard [dot-path](#dot-path-notation) notation. Multiple assignments can be provided in sequence to build a complex object.
|
|
1753
|
+
The value is converted like any [dot-path](#dot-path-notation) value, and can be an [Extended Value](#extended-value-syntax), for example `public_key=@file:~/.ssh/id_rsa.pub`.
|
|
1754
|
+
Options placed among the assignments are not collected: they are processed as usual, for example `@: a=1 --format=json b=2`.
|
|
1669
1755
|
|
|
1670
1756
|
- `<MARKER>` (`END` by default): An optional argument that ends the collection.
|
|
1671
1757
|
|
|
@@ -1838,9 +1924,212 @@ ascli config echo @json:'{"ni":null,"es":"","ea":[],"eh":{}}'
|
|
|
1838
1924
|
╰───────┴────────────────╯
|
|
1839
1925
|
```
|
|
1840
1926
|
|
|
1841
|
-
####
|
|
1927
|
+
#### Filtering results
|
|
1928
|
+
|
|
1929
|
+
The result of a command can be filtered on the server side, by the API, and then on the client side, by `ascli`.
|
|
1930
|
+
Filtering on the server side reduces the data transferred, while filtering on the client side accepts any condition.
|
|
1931
|
+
|
|
1932
|
+
Options are evaluated in this order:
|
|
1933
|
+
|
|
1934
|
+

|
|
1935
|
+
|
|
1936
|
+
1. `--query`: parameters sent to the API.
|
|
1937
|
+
2. `--out.secrets`: secrets are hidden first, so that an expression cannot reveal them.
|
|
1938
|
+
3. `--out.query`: JMESPath expression or Ruby lambda, applied to the data as returned by the API.
|
|
1939
|
+
4. `--out.select`: selection of items (rows).
|
|
1940
|
+
5. `--out.fields`: selection of fields (columns).
|
|
1941
|
+
6. Display in the format set by `--out.format`.
|
|
1942
|
+
|
|
1943
|
+
| To | Use |
|
|
1944
|
+
|------------------------------------------|------------------------------------------|
|
|
1945
|
+
| Limit what the API returns | `--query`, with parameters `max` and `pmax` |
|
|
1946
|
+
| Filter on any condition, reshape, count | `--out.query` |
|
|
1947
|
+
| Select items by the value of fields | `--out.select` |
|
|
1948
|
+
| Choose the fields displayed | `--out.fields` |
|
|
1949
|
+
|
|
1950
|
+
##### Option: `--query`: Parameters of the API
|
|
1951
|
+
|
|
1952
|
+
The `query` option can generally be used to add URL parameters to commands that list resources.
|
|
1953
|
+
It takes a `Hash`, corresponding to key/value pairs that appear in the query part of the request.
|
|
1954
|
+
|
|
1955
|
+
For example: `--query=@json:'{"p1":"v1","p2":"v2"}'` leads to query: `?p1=v1&p2=v2`.
|
|
1956
|
+
|
|
1957
|
+
If the same parameter needs to be provided several times, then it is also possible to provide an `Array`.
|
|
1958
|
+
|
|
1959
|
+
For example: `--query=@json:'{"p":["v1","v2"]}'` leads to query: `?p=v1&p=v2`.
|
|
1960
|
+
|
|
1961
|
+
If PHP-style arrays are expected in the API, add `[]` to the name of the parameter.
|
|
1962
|
+
|
|
1963
|
+
For example: `--query=@json:'{"p[]":["v1","v2"]}'` leads to query: `?p[]=v1&p[]=v2`.
|
|
1964
|
+
|
|
1965
|
+
Commands that read a list by pages (for example, `aoc admin user list`) also accept parameters `max` and `pmax`.
|
|
1966
|
+
They are processed by `ascli`, not sent to the API: they limit the number of items (`max`) and of pages (`pmax`) requested.
|
|
1967
|
+
|
|
1968
|
+
For example: `--query.max=10` reads the first 10 items.
|
|
1969
|
+
|
|
1970
|
+
> [!TIP]
|
|
1971
|
+
> Use `--query=help` on any `list` command to display the available query parameters and their types, as documented in the API.
|
|
1972
|
+
> For example: `ascli faspex5 admin accounts list --query=help`
|
|
1973
|
+
|
|
1974
|
+
##### Option: `--out.query`: JMESPath expression
|
|
1975
|
+
|
|
1976
|
+
Option `--out.query` applies a [JMESPath](https://jmespath.org) expression to the result of a command, when it is an object or a list.
|
|
1977
|
+
JMESPath is a standard query language for JSON, also used by option `--query` of the AWS and Azure CLIs.
|
|
1978
|
+
|
|
1979
|
+
The expression is applied to the data as returned by the API (secrets hidden), before options `--out.select` and `--out.fields`.
|
|
1980
|
+
Its syntax is checked before the command is executed.
|
|
1981
|
+
Results of other types (status, no result) are not changed.
|
|
1982
|
+
|
|
1983
|
+
Examples:
|
|
1984
|
+
|
|
1985
|
+
```shell
|
|
1986
|
+
# Name and email of ATS administrators
|
|
1987
|
+
ascli aoc admin user list --out.query='[?ats_admin].{name: name, email: email}'
|
|
1988
|
+
# Number of users
|
|
1989
|
+
ascli aoc admin user list --out.query='length(@)'
|
|
1990
|
+
# Email of users, one per line, for use in a shell loop
|
|
1991
|
+
ascli aoc admin user list --out.query='[].email' --format=text
|
|
1992
|
+
```
|
|
1993
|
+
|
|
1994
|
+
> [!TIP]
|
|
1995
|
+
> Enclose the expression in single quotes for the shell.
|
|
1996
|
+
> In JMESPath, literal values are enclosed in backticks, for example: ``[?size > `1000`]``.
|
|
1997
|
+
> An expression with string literals in single quotes (`'...'`) is enclosed in double quotes, for example: `"[?name=='Ann']"`.
|
|
1998
|
+
|
|
1999
|
+
For processing that JMESPath does not provide (regular expressions, string manipulation, grouping), the value can be a Ruby lambda (`@ruby:`): it is called with the data, and returns the new data, converted to JSON data (for example, symbols and dates become strings).
|
|
2000
|
+
It is refused at [Security Level](#security-level) `medium` and `high`.
|
|
2001
|
+
|
|
2002
|
+
```shell
|
|
2003
|
+
# Number of users per email domain
|
|
2004
|
+
ascli aoc admin user list --out.query=@ruby:'->(users){users.group_by{|u|u["email"].split("@").last}.transform_values(&:count)}'
|
|
2005
|
+
```
|
|
2006
|
+
|
|
2007
|
+
The result of the query is displayed according to its type: a list of objects as a table, a list of values with one value per line, a single value as is.
|
|
2008
|
+
A list of lists (for example, `[].[name, email]`) is displayed only with a structured format (`json`, `yaml`, ...): to display a table, or CSV, use a multi-select hash instead, for example, `[].{name: name, email: email}`.
|
|
2009
|
+
|
|
2010
|
+
> [!NOTE]
|
|
2011
|
+
> Option `--query` gives filtering parameters to the API, while option `--out.query` filters and reshapes the result received.
|
|
2012
|
+
> Option `--out.query` is the equivalent of option `--query` of the AWS and Azure CLIs.
|
|
2013
|
+
|
|
2014
|
+
##### Option: `--out.select`: Selection of items
|
|
2015
|
+
|
|
2016
|
+
A list of objects (`object_list`) can be filtered with option `--out.select` (or `--select`).
|
|
2017
|
+
Its value is either a `Hash` or a `Proc`:
|
|
2018
|
+
|
|
2019
|
+
- `Hash`: an item is selected if each key of the `Hash` is a field of the item with the same value, and the same type: `true` (`Boolean`) is not `"true"` (`String`).
|
|
2020
|
+
- `Proc`: a Ruby lambda called with each item (`Hash`), that returns `true` to select it, or `false` to remove it.
|
|
2021
|
+
|
|
2022
|
+
Example:
|
|
2023
|
+
|
|
2024
|
+
```shell
|
|
2025
|
+
ascli aoc admin user list --out.fields=name,email,ats_admin --query=@json:'{"sort":"name"}' --out.select=@json:'{"ats_admin":true}'
|
|
2026
|
+
```
|
|
2027
|
+
|
|
2028
|
+
```text
|
|
2029
|
+
╭────────────────┬─────────────────────┬───────────╮
|
|
2030
|
+
│ name │ email │ ats_admin │
|
|
2031
|
+
╞════════════════╪═════════════════════╪═══════════╡
|
|
2032
|
+
│ John Curtis │ john@example.com │ true │
|
|
2033
|
+
│ Laurent Martin │ laurent@example.com │ true │
|
|
2034
|
+
╰────────────────┴─────────────────────┴───────────╯
|
|
2035
|
+
```
|
|
2036
|
+
|
|
2037
|
+
In the above example, the same result is obtained with option:
|
|
2038
|
+
|
|
2039
|
+
```shell
|
|
2040
|
+
--out.select=@ruby:'->(i){i["ats_admin"]}'
|
|
2041
|
+
```
|
|
2042
|
+
|
|
2043
|
+
A key can be a [dot-path](#dot-path-notation), for example, `directory_user.type`, with all formats.
|
|
2044
|
+
|
|
2045
|
+
##### Option: `--out.fields`: Selection of fields
|
|
2046
|
+
|
|
2047
|
+
Depending on the command, results may include by default all fields, or only some selected fields.
|
|
2048
|
+
It is possible to define specific columns to be displayed, by setting option `--out.fields` (or `--fields`).
|
|
2049
|
+
|
|
2050
|
+
The `--out.fields` option is a list that can be either a comma-separated list or an [Extended Value](#extended-value-syntax) `Array`.
|
|
2051
|
+
|
|
2052
|
+
Individual elements of the list can be:
|
|
2053
|
+
|
|
2054
|
+
- **property**: add property to the current list
|
|
2055
|
+
- `-`**property**: remove property from the current list
|
|
2056
|
+
- `DEF`: default list of fields (that is the default, when not set)
|
|
2057
|
+
- `ALL`: all fields
|
|
2058
|
+
- A Ruby `RegEx`: using `@ruby:'/.../'`, or `@re:...` add those matching to the list
|
|
2059
|
+
|
|
2060
|
+
To display a **property** inside a complex structure (`Hash`, `Array`), use [dot-path](#dot-path-notation) notation, only with `--format=table` or `csv` (see option `--out.flat`).
|
|
2061
|
+
With other formats, use a JMESPath multi-select hash with option `--out.query`, for example: `--out.query='[].{name: name, type: directory_user.type}'`.
|
|
2062
|
+
|
|
2063
|
+
Examples:
|
|
2064
|
+
|
|
2065
|
+
- `a,b,c`: the list of attributes specified as a comma-separated list (overrides the default)
|
|
2066
|
+
- `@list:,a,b,c`: `Array` [Extended Value](#extended-value-syntax): same as above
|
|
2067
|
+
- `@json:'["a","b","c"]'`: `Array` [Extended Value](#extended-value-syntax): same as above
|
|
2068
|
+
- `b,DEF,-a`: default property list, remove `a` and add `b` in first position
|
|
2069
|
+
- `@ruby:'/^server/'`: Display all fields whose name begins with `server`
|
|
2070
|
+
|
|
2071
|
+
##### `--out.select` or `--out.query`
|
|
2072
|
+
|
|
2073
|
+
Option `--out.select` is shorter for a test of equality, while option `--out.query` accepts any condition.
|
|
2074
|
+
|
|
2075
|
+
| Condition | `--out.select` | `--out.query` |
|
|
2076
|
+
|--------------------------|----------------------------------------------------|--------------------------------------------------|
|
|
2077
|
+
| Equal to a `Boolean` | `@json:'{"ats_admin":true}'` | `'[?ats_admin]'` |
|
|
2078
|
+
| Equal to a `String` | `@json:'{"name":"Ann"}'` | `"[?name=='Ann']"` |
|
|
2079
|
+
| Field of a nested object | `@json:'{"directory_user.type":"active_directory"}'` | `"[?directory_user.type=='active_directory']"` |
|
|
2080
|
+
| Several conditions (and) | `@json:'{"ats_admin":true,"name":"Ann"}'` | `"[?ats_admin && name=='Ann']"` |
|
|
2081
|
+
| Negation, or | Ruby lambda (`@ruby:`) | `'[?!ats_admin]'`, or: see [Recipes](#recipes) |
|
|
2082
|
+
| Number comparison | Ruby lambda (`@ruby:`) | ``'[?size > `1000000`]'`` |
|
|
2083
|
+
| Substring | Ruby lambda (`@ruby:`) | ``'[?contains(email, `@example`)]'`` |
|
|
2084
|
+
| Choice of fields | With option `--out.fields` | `'[].{name: name, email: email}'` |
|
|
2085
|
+
| Count | Not possible | `'length(@)'` |
|
|
2086
|
+
|
|
2087
|
+
> [!WARNING]
|
|
2088
|
+
>
|
|
2089
|
+
> - Values are compared with their type. With `--out.select`, `"true"` (`String`) does not match `true` (`Boolean`). In JMESPath, ``[?ats_admin == `true`]`` matches, but `[?ats_admin == 'true']` does not: `'...'` is a string literal.
|
|
2090
|
+
> - After `--out.query`, the default fields of the command no longer apply: all the fields of the result are displayed. Choose fields in the expression (multi-select hash), or with option `--out.fields`.
|
|
2091
|
+
> - Secrets are hidden before `--out.query` is applied, so that the expression cannot reveal them.
|
|
2092
|
+
|
|
2093
|
+
##### Recipes
|
|
2094
|
+
|
|
2095
|
+
```shell
|
|
2096
|
+
# Users of Active Directory, with user name and email
|
|
2097
|
+
ascli shares admin user all list --out.query="[?directory_user.type=='active_directory'].{username: username, email: email}"
|
|
2098
|
+
# Users without directory (field missing or null)
|
|
2099
|
+
ascli shares admin user all list --out.query='[?directory_user == null].username'
|
|
2100
|
+
# Number of ATS administrators
|
|
2101
|
+
ascli aoc admin user list --out.query='length([?ats_admin])'
|
|
2102
|
+
# Users who are ATS administrators, or have no email
|
|
2103
|
+
ascli aoc admin user list --out.query='[?ats_admin || !email].name'
|
|
2104
|
+
# Emails of a domain, one per line
|
|
2105
|
+
ascli aoc admin user list --out.query='[?ends_with(email, `@example.com`)].email' --format=text
|
|
2106
|
+
# Largest file of a folder
|
|
2107
|
+
ascli node browse / --out.query='max_by([?type==`file`], &size).path'
|
|
2108
|
+
# Files larger than 1 MB
|
|
2109
|
+
ascli node browse / --out.query='[?size > `1000000`].{path: path, size: size}'
|
|
2110
|
+
# Files modified since a date
|
|
2111
|
+
ascli node browse / --out.query='[?mtime >= `"2025-06-01"`].path'
|
|
2112
|
+
```
|
|
2113
|
+
|
|
2114
|
+
> [!NOTE]
|
|
2115
|
+
> The JMESPath implementation of `ascli` (gem `jmespath`) also compares strings with `<`, `<=`, `>` and `>=`, which the JMESPath specification defines only for numbers.
|
|
2116
|
+
> Dates in ISO 8601 format, in the same time zone, are compared in chronological order.
|
|
1842
2117
|
|
|
1843
|
-
The
|
|
2118
|
+
The result in JSON (`--format=json`) can also be processed by other tools, such as [`jq`](https://jqlang.org), whose language differs from JMESPath: for example, `jq 'map(select(.directory_user.type == "active_directory"))'`.
|
|
2119
|
+
|
|
2120
|
+
##### Other filters
|
|
2121
|
+
|
|
2122
|
+
Some commands provide their own filters:
|
|
2123
|
+
|
|
2124
|
+
- [Percent selector](#percent-selector) `%<field>:<value>`: selects a single resource by the value of one of its fields.
|
|
2125
|
+
- `find` of plugin `node` (gen4) and `aoc files find`: recursive search of files on the client side, with a glob or a Ruby lambda (see [Operation `find`](#operation-find-on-gen4access-key)).
|
|
2126
|
+
- `faspex5 packages list`: a Ruby lambda as last argument (see [Faspex 5: List packages](#faspex-5-list-packages)).
|
|
2127
|
+
- `console transfer`: query parameter `filter` (see [Transfer filter](#transfer-filter)).
|
|
2128
|
+
- `preview`: options `--filter` and `--skip-folders` (see [Candidate detection](#candidate-detection-for-creation-or-update-or-deletion)).
|
|
2129
|
+
|
|
2130
|
+
#### Option: `--out.format`
|
|
2131
|
+
|
|
2132
|
+
The style of output can be set using option `--out.format` (or `--format`):
|
|
1844
2133
|
|
|
1845
2134
|
| `format` | Output formatting |
|
|
1846
2135
|
| -------- | -------- |
|
|
@@ -1894,7 +2183,7 @@ ascli config echo @json:'[{"name":"foo","id":1},{"name":"bar","id":8}]' --format
|
|
|
1894
2183
|
|
|
1895
2184
|
This option controls how object fields are displayed for complex objects.
|
|
1896
2185
|
|
|
1897
|
-
Effective only when `format` is `table` to display `single_object` or `object_list`.
|
|
2186
|
+
Effective only when `format` is `table` or `csv` to display `single_object` or `object_list`.
|
|
1898
2187
|
|
|
1899
2188
|
If value is `no`, then object's `field` names are only the first level keys of the `Hash` result and values that are `Hash` are displayed as such in Ruby syntax.
|
|
1900
2189
|
|
|
@@ -2076,110 +2365,12 @@ ascli config preset overview --out.colors=no --out.utf8=no
|
|
|
2076
2365
|
> [!NOTE]
|
|
2077
2366
|
> Logs issued before the option is processed (e.g. at startup) use the detected value.
|
|
2078
2367
|
|
|
2079
|
-
#### Option: `fields`: Selection of output object fields
|
|
2080
|
-
|
|
2081
|
-
Depending on the command, results may include by default all fields, or only some selected fields.
|
|
2082
|
-
It is possible to define specific columns to be displayed, by setting the `fields` option.
|
|
2083
|
-
|
|
2084
|
-
The `fields` option is a list that can be either a comma-separated list or an [Extended Value](#extended-value-syntax) `Array`.
|
|
2085
|
-
|
|
2086
|
-
Individual elements of the list can be:
|
|
2087
|
-
|
|
2088
|
-
- **property**: add property to the current list
|
|
2089
|
-
- `-`**property**: remove property from the current list
|
|
2090
|
-
- `DEF`: default list of fields (that is the default, when not set)
|
|
2091
|
-
- `ALL`: all fields
|
|
2092
|
-
- A Ruby `RegEx`: using `@ruby:'/.../'`, or `@re:...` add those matching to the list
|
|
2093
|
-
|
|
2094
|
-
To display a **property** inside a complex structure (`Hash`, `Array`) use [dot-path](#dot-path-notation) notation.
|
|
2095
|
-
|
|
2096
|
-
Examples:
|
|
2097
|
-
|
|
2098
|
-
- `a,b,c`: the list of attributes specified as a comma-separated list (overrides the default)
|
|
2099
|
-
- `@list:,a,b,c`: `Array` [Extended Value](#extended-value-syntax): same as above
|
|
2100
|
-
- `@json:'["a","b","c"]'`: `Array` [Extended Value](#extended-value-syntax): same as above
|
|
2101
|
-
- `b,DEF,-a`: default property list, remove `a` and add `b` in first position
|
|
2102
|
-
- `@ruby:'/^server/'`: Display all fields whose name begins with `server`
|
|
2103
|
-
|
|
2104
|
-
#### Option: `select`
|
|
2105
|
-
|
|
2106
|
-
Table output (`object_list`) can be filtered using option `select`.
|
|
2107
|
-
This option is either a `Hash` or `Proc`.
|
|
2108
|
-
The `Proc` takes as argument a line (`Hash`) in the table and is a Ruby lambda expression that shall return `true` to select or `false` to remove an entry.
|
|
2109
|
-
|
|
2110
|
-
Example:
|
|
2111
|
-
|
|
2112
|
-
```shell
|
|
2113
|
-
ascli aoc admin user list --fields=name,email,ats_admin --query=@json:'{"sort":"name"}' --select=@json:'{"ats_admin":true}'
|
|
2114
|
-
```
|
|
2115
|
-
|
|
2116
|
-
```text
|
|
2117
|
-
╭────────────────┬─────────────────────┬───────────╮
|
|
2118
|
-
│ name │ email │ ats_admin │
|
|
2119
|
-
╞════════════════╪═════════════════════╪═══════════╡
|
|
2120
|
-
│ John Curtis │ john@example.com │ true │
|
|
2121
|
-
│ Laurent Martin │ laurent@example.com │ true │
|
|
2122
|
-
╰────────────────┴─────────────────────┴───────────╯
|
|
2123
|
-
```
|
|
2124
|
-
|
|
2125
|
-
> [!NOTE]
|
|
2126
|
-
> Option `select` filters elements from the result of command, while the `query` option gives filtering parameters to the API when listing elements.
|
|
2127
|
-
|
|
2128
|
-
In the above example, the same result is obtained with option:
|
|
2129
|
-
|
|
2130
|
-
```shell
|
|
2131
|
-
--select=@ruby:'->(i){i["ats_admin"]}'
|
|
2132
|
-
```
|
|
2133
|
-
|
|
2134
|
-
Option `select` applies the filter after a possible "flattening" with option `--out.flat`.
|
|
2135
|
-
|
|
2136
|
-
For comparisons, functions or reshaping of results, use option `--out.query`.
|
|
2137
|
-
|
|
2138
|
-
#### Option: `--out.query`
|
|
2139
|
-
|
|
2140
|
-
Option `--out.query` applies a [JMESPath](https://jmespath.org) expression to the result of a command, when it is an object or a list.
|
|
2141
|
-
JMESPath is a standard query language for JSON, also used by option `--query` of the AWS and Azure CLIs.
|
|
2142
|
-
|
|
2143
|
-
The expression is applied to the data as returned by the API, before the options `select` and `fields`, and before flattening with `--out.flat`.
|
|
2144
|
-
Its syntax is checked before the command is executed.
|
|
2145
|
-
Results of other types (status, no result) are not changed.
|
|
2146
|
-
|
|
2147
|
-
Examples:
|
|
2148
|
-
|
|
2149
|
-
```shell
|
|
2150
|
-
# Name and email of ATS administrators
|
|
2151
|
-
ascli aoc admin user list --out.query='[?ats_admin].{name: name, email: email}'
|
|
2152
|
-
# Number of users
|
|
2153
|
-
ascli aoc admin user list --out.query='length(@)'
|
|
2154
|
-
# Email of users, one per line, for use in a shell loop
|
|
2155
|
-
ascli aoc admin user list --out.query='[].email' --format=text
|
|
2156
|
-
```
|
|
2157
|
-
|
|
2158
|
-
> [!TIP]
|
|
2159
|
-
> Enclose the expression in single quotes for the shell.
|
|
2160
|
-
> In JMESPath, literal values are enclosed in backticks, for example: ``[?size > `1000`]``.
|
|
2161
|
-
|
|
2162
|
-
For processing that JMESPath does not provide (regular expressions, string manipulation, grouping), the value can be a Ruby lambda (`@ruby:`): it is called with the data, and returns the new data, converted to JSON data (for example, symbols and dates become strings).
|
|
2163
|
-
It is refused at [Security Level](#security-level) `medium` and `high`.
|
|
2164
|
-
|
|
2165
|
-
```shell
|
|
2166
|
-
# Number of users per email domain
|
|
2167
|
-
ascli aoc admin user list --out.query=@ruby:'->(users){users.group_by{|u|u["email"].split("@").last}.transform_values(&:count)}'
|
|
2168
|
-
```
|
|
2169
|
-
|
|
2170
|
-
The result of the query is displayed according to its type: a list of objects as a table, a list of values with one value per line, a single value as is.
|
|
2171
|
-
A list of lists (for example, `[].[name, email]`) is displayed only with a structured format (`json`, `yaml`, ...): to display a table, or CSV, use a multi-select hash instead, for example, `[].{name: name, email: email}`.
|
|
2172
|
-
|
|
2173
|
-
> [!NOTE]
|
|
2174
|
-
> Option `--query` gives filtering parameters to the API, while option `--out.query` filters and reshapes the result received.
|
|
2175
|
-
> Option `--out.query` is the equivalent of option `--query` of the AWS and Azure CLIs.
|
|
2176
|
-
|
|
2177
2368
|
### Exit status
|
|
2178
2369
|
|
|
2179
2370
|
The exit code of `ascli` indicates the category of error, so that scripts can react to it:
|
|
2180
2371
|
|
|
2181
2372
|
| Code | Description |
|
|
2182
|
-
|
|
2373
|
+
| ---- | -------------------------------------------------------------------------- |
|
|
2183
2374
|
| `0` | Success |
|
|
2184
2375
|
| `1` | Other error |
|
|
2185
2376
|
| `2` | Command line error: unknown command or option, invalid or missing argument |
|
|
@@ -2256,10 +2447,10 @@ The following decoders are supported:
|
|
|
2256
2447
|
| `stdin` | `String` | `String` | Read from stdin in text mode. Argument: `<empty>`, `bin` or `chomp`. |
|
|
2257
2448
|
| `uri` | `String` | `String` | Read value from specified URL. Supported schemes: `http:`, `https:`, `data:`, `file:`. For example, `--fpac=@uri:http://serv/f.pac` or `--key=@uri:file:/path/to/key.pem` |
|
|
2258
2449
|
| `val` | `String` | `String` | Prevent decoding by the decoders on the right. For example, `--key=@val:@file:foo` sets the option `key` to value `@file:foo`. |
|
|
2259
|
-
| `vault` | `String` | `String` | Read a secret from the [Secret Vault](#secret-vault): `<label>.<field
|
|
2450
|
+
| `vault` | `String` | `String` | Read a secret from the [Secret Vault](#secret-vault): `<label>.<field>`, or a [reference](#vault-secret-references) `//<store>/<path>[?<options>][#<field>]`. For example, `--password=@vault:my_label.password` |
|
|
2260
2451
|
| `yaml` | `String` | Any | Decode YAML. |
|
|
2261
2452
|
| `zlib` | `String` | `String` | Decompress data using zlib. |
|
|
2262
|
-
| `<empty>`|
|
|
2453
|
+
| `<empty>`| `String` | Any | The **dot-path** modifier: argument `@:` collects the following positional arguments as `key.subkey=value` assignments and builds a `Hash` or `Array` using [dot-path](#dot-path-notation) notation. Shell-friendly alternative to `@json:` for structured values.<br/>Argument is the end marker: `<empty>` for `END`, or a custom marker (e.g. `@:STOP`). Use the end marker to stop collection when further positional arguments must follow.<br/>See [Positional Arguments with Dot-path](#positional-arguments-with-dot-path) for full syntax. |
|
|
2263
2454
|
|
|
2264
2455
|
> [!NOTE]
|
|
2265
2456
|
> A few commands support a value of type `Proc` (lambda expression).
|
|
@@ -2550,7 +2741,6 @@ Adding `--show-config` to any command line performs a dry run and displays the r
|
|
|
2550
2741
|
To display a specific option, add `--fields=<option_name>`.
|
|
2551
2742
|
Add `--out.flat=no` when the option holds a structured value (`Hash`, `Array`) to display it as-is rather than flattened into dot-path keys:
|
|
2552
2743
|
|
|
2553
|
-
|
|
2554
2744
|
```shell
|
|
2555
2745
|
ascli --opt=@json:'{"a":1,"b":"two"}' some_plugin --show-config --fields=opt --out.flat=no
|
|
2556
2746
|
ascli --opt.a=1 --opt.b=two some_plugin --show-config --fields=opt --out.flat=no
|
|
@@ -2588,18 +2778,48 @@ It is a `Hash` with the following keys:
|
|
|
2588
2778
|
|-----|-----|-----|-----|
|
|
2589
2779
|
| `level` | `string` | `low` | `low`, `medium`, or `high` |
|
|
2590
2780
|
| `allowed_paths` | `Array<string>` | - | With level `medium`: files and folders that `@file:` can read |
|
|
2781
|
+
| `writable_paths` | `Array<string>` | - | With levels `medium` and `high`: folders where files can be written |
|
|
2591
2782
|
|
|
2592
|
-
| Level | `@file:` | `@ruby:`, `@uri:`, and `@env:` | Secret processed by another extended value |
|
|
2593
|
-
|
|
2594
|
-
| `low` | Allowed | Allowed | Allowed |
|
|
2595
|
-
| `medium` | Only files in `allowed_paths` | Refused | Refused |
|
|
2596
|
-
| `high` | Refused | Refused | Refused |
|
|
2783
|
+
| Level | `@file:` | `@ruby:`, `@uri:`, and `@env:` | Secret processed by another extended value | Write files | Features that execute code |
|
|
2784
|
+
|---|---|---|---|---|---|
|
|
2785
|
+
| `low` | Allowed | Allowed | Allowed | Allowed | Allowed |
|
|
2786
|
+
| `medium` | Only files in `allowed_paths` | Refused | Refused | Only in `writable_paths` | Refused |
|
|
2787
|
+
| `high` | Refused | Refused | Refused | Only in `writable_paths` | Refused |
|
|
2597
2788
|
|
|
2598
2789
|
With level `medium`, the real path of the file is checked: a symbolic link leading outside of `allowed_paths` is refused.
|
|
2599
2790
|
|
|
2791
|
+
With levels `medium` and `high`, files are written only in `writable_paths` (none by default): downloaded files (`config download`, and transfers that receive files), because a file written where the client chooses could replace a file that is used later, for example a plugin or a shell startup file.
|
|
2792
|
+
The real path of the folder is checked: neither `..` nor a symbolic link leading outside of `writable_paths` is accepted.
|
|
2793
|
+
|
|
2794
|
+
> [!NOTE]
|
|
2795
|
+
> Reading files is not restricted for transfers: a command that sends files (for example `server upload`) reads the files that it is given, whatever the level.
|
|
2796
|
+
> The security level restricts extended values, not the paths of transfers.
|
|
2797
|
+
|
|
2798
|
+
The same applies to `@file:<path>` in the parameters of stores of option `vault`, and in option `vault_password` (for example, `token`), although the file is read when used, not when the option is evaluated.
|
|
2799
|
+
|
|
2600
2800
|
A secret (read by `@secret:`, `@vault:`, or `@preset:`) is hidden in results by its value: processed by another extended value, it could be revealed (for example, split by `@list:@vault:...`, or with a short value in a text by `@extend:`).
|
|
2601
2801
|
With levels `medium` and `high`, a secret must be the whole value of an option or argument, for example `@preset:<PRESET_NAME>.password` for option `password`, and it cannot be a parameter name of `config preset set`.
|
|
2602
2802
|
|
|
2803
|
+
Features that execute code (own, or downloaded), load code, or write a file chosen by the client, are available only at level `low`:
|
|
2804
|
+
|
|
2805
|
+
| Feature | Why |
|
|
2806
|
+
|---|---|
|
|
2807
|
+
| Option `notify_template` | ERB template: Ruby code |
|
|
2808
|
+
| Option `fpac` | Proxy auto configuration: JavaScript code |
|
|
2809
|
+
| Option `ui`, key `command` | Command executed to open a URL |
|
|
2810
|
+
| Options `sdk_url` and `locations_url` | The SDK, including `ascp`, is downloaded from this location, then executed |
|
|
2811
|
+
| Option `out`, key `file` (and `output`), option `pid_file` | Write (or truncate, or delete) a file chosen by the client |
|
|
2812
|
+
| Option `home` | Configuration folder: its presets, and its folder `plugins` (Ruby code) are used |
|
|
2813
|
+
| Option `plugin_folder` | Plugins are Ruby code |
|
|
2814
|
+
| Plugins of the folder `plugins` of the configuration folder, and of option `plugin_folder` | Ruby code: not loaded at other levels, also if the file was there before |
|
|
2815
|
+
| Command `config plugins create` | Creates Ruby code, loaded as a plugin |
|
|
2816
|
+
| Command `faspex5 postprocessing` | Executes scripts, or Ruby code |
|
|
2817
|
+
|
|
2818
|
+
At other levels, an option is refused whatever the way it is set (command line, or preset), and a command is not listed by `config commands`.
|
|
2819
|
+
Values from the environment of the process (for example `ASCLI_HOME`) are not restricted: they are set by the one who starts the process, not by a client.
|
|
2820
|
+
A sub-option of an option is restricted in the same way: it is marked `x-security: low` in the schema of the option (for example, `file` of option `out`), and refused when given, by dot notation (`--out.file=...`) or in a `Hash`.
|
|
2821
|
+
A preset is used later, maybe at level `low`: at level `medium` and `high`, `config preset set` refuses such an option, and a value that contains an extended value that the level refuses (for example `@val:@ruby:...`).
|
|
2822
|
+
|
|
2603
2823
|
Options are evaluated in the order of the command line: place `--security` before options that use extended values.
|
|
2604
2824
|
|
|
2605
2825
|
```shell
|
|
@@ -2607,7 +2827,7 @@ ascli config echo @file:/etc/hosts --security.level=high
|
|
|
2607
2827
|
```
|
|
2608
2828
|
|
|
2609
2829
|
```text
|
|
2610
|
-
ERRR Argument: Evaluation of file for argument: value: @file: extended value is disabled by security level high
|
|
2830
|
+
ERRR Argument: Evaluation of @file: for argument: value: @file: extended value is disabled by security level high: use level medium with the file in security.allowed_paths (option security), or give the value itself
|
|
2611
2831
|
```
|
|
2612
2832
|
|
|
2613
2833
|
### Main, configuration and Persistency Folder
|
|
@@ -2740,61 +2960,56 @@ An [Option Preset](#option-preset) is a collection of options and their associat
|
|
|
2740
2960
|
A named [Option Preset](#option-preset) can be modified directly using `ascli`, which will update the configuration file:
|
|
2741
2961
|
|
|
2742
2962
|
```text
|
|
2743
|
-
ascli config preset <show|delete|get|
|
|
2963
|
+
ascli config preset <show|delete|get|set|ask> <PRESET_NAME> ...
|
|
2744
2964
|
```
|
|
2745
2965
|
|
|
2746
2966
|
The syntax of all `config preset` commands, including `list` and `overview`, is displayed with `ascli config commands config preset`.
|
|
2747
2967
|
|
|
2748
|
-
The command `
|
|
2968
|
+
The command `set` merges values into the configuration, at one of three levels, depending on its arguments:
|
|
2749
2969
|
|
|
2750
|
-
|
|
2751
|
-
|
|
2752
|
-
|
|
2970
|
+
| Arguments | Merged into | Example |
|
|
2971
|
+
| --------- | ----------- | ------- |
|
|
2972
|
+
| `<Hash>` | Presets, by name | `ascli config preset set @: demo_server.url=ssh://demo.asperasoft.com:33001 default.server=demo_server` |
|
|
2973
|
+
| `<preset_name> <Hash>` | Parameters of a preset | `ascli config preset set demo_server @: url=ssh://demo.asperasoft.com:33001 username=asperaweb` |
|
|
2974
|
+
| `<preset_name> <parameter_name> <value>` | One parameter of a preset | `ascli config preset set demo_server password <PASSWORD>` |
|
|
2753
2975
|
|
|
2754
|
-
|
|
2976
|
+
The `Hash` is usually given with [dot-path](#positional-arguments-with-dot-path) (`@:`), or with `@json:`.
|
|
2977
|
+
Parameters have the names of options, without `--`, for example:
|
|
2755
2978
|
|
|
2756
2979
|
```shell
|
|
2757
|
-
ascli config preset
|
|
2980
|
+
ascli config preset set demo_server @: url=ssh://demo.asperasoft.com:33001 username=asperaweb password=<PASSWORD> ts.precalculate_job_size=true
|
|
2981
|
+
ascli config preset set demo_server @json:'{"url":"ssh://demo.asperasoft.com:33001","username":"asperaweb","password":"<PASSWORD>","ts":{"precalculate_job_size":true}}'
|
|
2758
2982
|
```
|
|
2759
2983
|
|
|
2760
|
-
|
|
2984
|
+
A preset is created if needed.
|
|
2985
|
+
Values are **deep-merged** (as JSON Merge Patch, RFC 7396): parameters not given are kept, also in a nested `Hash`: for example, `@: out.level=data` keeps `out.format`.
|
|
2761
2986
|
|
|
2762
|
-
|
|
2763
|
-
ascli config preset update demo_server --url=ssh://demo.asperasoft.com:33001 --username=asperaweb --password=<PASSWORD> --ts=@json:'{"precalculate_job_size":true}'
|
|
2764
|
-
```
|
|
2765
|
-
|
|
2766
|
-
This creates an [Option Preset](#option-preset) `demo_server` with all provided options.
|
|
2767
|
-
|
|
2768
|
-
> [!NOTE]
|
|
2769
|
-
> `update` takes **ALL** options provided on the command line (starting with `--` with a value).
|
|
2770
|
-
|
|
2771
|
-
The command `set` allows setting individual options in an [Option Preset](#option-preset):
|
|
2772
|
-
|
|
2773
|
-
```text
|
|
2774
|
-
ascli config preset set <PRESET_NAME> <PARAMETER_NAME> <PARAMETER_VALUE>
|
|
2775
|
-
```
|
|
2776
|
-
|
|
2777
|
-
Example:
|
|
2987
|
+
The value `@none:` (`null` in JSON) **removes** a key: a parameter, a key in a nested `Hash`, or a whole preset (with its default declarations):
|
|
2778
2988
|
|
|
2779
2989
|
```shell
|
|
2780
|
-
ascli config preset set
|
|
2990
|
+
ascli config preset set GLOBAL out.table.pivot @none:
|
|
2991
|
+
ascli config preset set demo_server @: username=@none: ts.precalculate_job_size=@none:
|
|
2992
|
+
ascli config preset set @: demo_server=@none:
|
|
2781
2993
|
```
|
|
2782
2994
|
|
|
2783
|
-
The parameter name supports **dot-notation** to set nested hash options
|
|
2784
|
-
If an intermediate hash already exists, the new value is **deep-merged** into it (existing sibling keys are preserved).
|
|
2995
|
+
The parameter name of the third form supports **dot-notation** to set nested hash options:
|
|
2785
2996
|
|
|
2786
2997
|
```shell
|
|
2787
2998
|
ascli config preset set GLOBAL out.table.pivot single
|
|
2788
2999
|
ascli config preset set GLOBAL out.level data
|
|
2789
3000
|
```
|
|
2790
3001
|
|
|
2791
|
-
|
|
3002
|
+
Values given on the command line (with `@:`, or the value of the third form) are **automatically coerced** to their natural type: integers, floats and booleans (`true`/`yes`/`false`/`no`) are stored as native YAML types rather than strings.
|
|
2792
3003
|
|
|
2793
|
-
|
|
3004
|
+
Options of the command line are not saved in the preset: they apply to the command `set` itself (for example `--log-level`).
|
|
3005
|
+
The section `config` of the configuration file cannot be changed.
|
|
2794
3006
|
|
|
2795
|
-
|
|
2796
|
-
|
|
2797
|
-
|
|
3007
|
+
> [!NOTE]
|
|
3008
|
+
> Commands `update`, `initialize` and `unset` are deprecated, and show the command to use instead:
|
|
3009
|
+
>
|
|
3010
|
+
> - `update <preset_name> --url=...` is replaced by `set <preset_name> @: url=...`. It takes only the options placed after `update`.
|
|
3011
|
+
> - `initialize <preset_name> <Hash>`, which replaces a preset, is replaced by `delete <preset_name>`, then `set <preset_name> <Hash>`.
|
|
3012
|
+
> - `unset <preset_name> <parameter_name>` is replaced by `set <preset_name> <parameter_name> @none:`.
|
|
2798
3013
|
|
|
2799
3014
|
A full terminal based overview of the configuration can be displayed using:
|
|
2800
3015
|
|
|
@@ -2822,6 +3037,10 @@ demo_server:
|
|
|
2822
3037
|
> [!NOTE]
|
|
2823
3038
|
> Comment keys are preserved and visible in `config preset overview` for inspection, but are never injected as CLI options.
|
|
2824
3039
|
|
|
3040
|
+
By convention, `_comment` holds a short description of the preset.
|
|
3041
|
+
The [shell completion](#shell-completion) of preset names (e.g. `-P <tab>`) shows it next to each name.
|
|
3042
|
+
The wizard sets it for the presets it creates: `_comment: "wizard: <application>"`.
|
|
3043
|
+
|
|
2825
3044
|
A good practice is to not manually edit the configuration file and use modification commands instead.
|
|
2826
3045
|
If necessary, the configuration file can be opened in a text editor with:
|
|
2827
3046
|
|
|
@@ -2894,10 +3113,10 @@ Some temporary files may be needed during runtime, for example the file list of
|
|
|
2894
3113
|
The composite option `temp` (use `--temp=help` to display this schema) controls them:
|
|
2895
3114
|
|
|
2896
3115
|
| Field | Type | Description |
|
|
2897
|
-
|
|
3116
|
+
| ------ | -------------------- | -------------------------------------------------------------------------------- |
|
|
2898
3117
|
| `clean` | `Bool` | Delete temporary files created by the command when it ends. `false` keeps them, e.g. for debugging. Files left by previous commands are still deleted according to `expiry`.<br/>Default: `true`. |
|
|
2899
3118
|
| `expiry` | `String, Number, Bool` | Age after which file lists of `ascp` left by previous commands (e.g. interrupted) are deleted, when a command starts. They are in folder `filelists` of the main folder (option `home`). A duration, e.g. `5d`, `12h`, `1w`, `1h 30m`, `1d 02:00:00`, a plain number is seconds. `false` or `null` (`@none:`): never delete them. `0`: delete all of them, including file lists of transfers in progress in other executions of ascli. Such a transfer fails if `ascp` reads its file list again: next session of a multi-session transfer, or resume after an error. Use `0` only when no other transfer is in progress, not in a permanent configuration.<br/>Default: `5d`. |
|
|
2900
|
-
| `folder` | `String` | Folder for temporary files, e.g. certificate for WSS transfers, logs of `transferd
|
|
3119
|
+
| `folder` | `String` | Folder for temporary files, e.g. certificate for WSS transfers, logs of `transferd`.<br/>- `@sys`: temporary folder of the system for the current user (Ruby `Etc.systmpdir`).<br/>- `@env`: from environment variables, e.g. `TMPDIR` (Ruby `Dir.tmpdir`).<br/>Default: `@sys`. |
|
|
2901
3120
|
|
|
2902
3121
|
A plain value is the `folder`, for example: `--temp=/data/tmp`.
|
|
2903
3122
|
|
|
@@ -2918,7 +3137,7 @@ Plugin `config` provides general commands for `ascli`:
|
|
|
2918
3137
|
- `wizard`
|
|
2919
3138
|
- `vault`
|
|
2920
3139
|
- `ascp`
|
|
2921
|
-
- `transferd`
|
|
3140
|
+
- `transferd` (deprecated, use plugin [`transferd`](#plugin-transferd-transfer-daemon))
|
|
2922
3141
|
|
|
2923
3142
|
The default preset for `config` is read for any plugin invocation: this allows setting global options, such as `--log-level` or `--interactive`.
|
|
2924
3143
|
When `ascli` starts, it looks for the `default` Option Preset and checks the value for `config`.
|
|
@@ -2960,6 +3179,9 @@ ascli config preset set GLOBAL version_check_days 0
|
|
|
2960
3179
|
> Add `ascli config` in front of the following commands:
|
|
2961
3180
|
|
|
2962
3181
|
```shell
|
|
3182
|
+
agents jobs cleanup
|
|
3183
|
+
agents jobs list
|
|
3184
|
+
agents jobs status <CONF_ASYNC_NODE_UPLOAD>
|
|
2963
3185
|
agents list
|
|
2964
3186
|
agents parameters connect
|
|
2965
3187
|
agents parameters direct
|
|
@@ -2968,9 +3190,6 @@ agents show connect
|
|
|
2968
3190
|
agents show direct
|
|
2969
3191
|
ascp errors
|
|
2970
3192
|
ascp info --sdk-folder=sdk_test_dir
|
|
2971
|
-
ascp install
|
|
2972
|
-
ascp install --sdk-folder=sdk_test_dir
|
|
2973
|
-
ascp install 1.1.3
|
|
2974
3193
|
ascp products list
|
|
2975
3194
|
ascp schema --format=jsonpp
|
|
2976
3195
|
ascp show
|
|
@@ -2985,15 +3204,15 @@ commands
|
|
|
2985
3204
|
commands aoc --expand-mounts=yes
|
|
2986
3205
|
commands aoc files
|
|
2987
3206
|
commands server
|
|
2988
|
-
detect app.example.com
|
|
2989
|
-
detect https://f5.example.com/path
|
|
2990
|
-
detect https://f5.example.com/path faspex5
|
|
2991
|
-
detect https://node.example.com/path
|
|
2992
|
-
detect https://
|
|
2993
|
-
detect https://shares.example.com/path shares
|
|
2994
|
-
detect https://tst.example.com/path faspio
|
|
2995
|
-
detect https://tst.example.com/path httpgw
|
|
2996
|
-
detect my_org aoc
|
|
3207
|
+
detect @: url=app.example.com
|
|
3208
|
+
detect @: url=https://f5.example.com/path
|
|
3209
|
+
detect @: url=https://f5.example.com/path plugin=faspex5
|
|
3210
|
+
detect @: url=https://node.example.com/path
|
|
3211
|
+
detect @: url=https://server1.example.com/path
|
|
3212
|
+
detect @: url=https://shares.example.com/path plugin=shares
|
|
3213
|
+
detect @: url=https://tst.example.com/path plugin=faspio
|
|
3214
|
+
detect @: url=https://tst.example.com/path plugin=httpgw
|
|
3215
|
+
detect @: url=my_org plugin=aoc
|
|
2997
3216
|
doc
|
|
2998
3217
|
doc github transfer-parameters
|
|
2999
3218
|
doc local quick-start --ui=text
|
|
@@ -3041,18 +3260,19 @@ options server --select=@json:'{"option":"--display"}' --fields=replacement
|
|
|
3041
3260
|
plugins create my_command .
|
|
3042
3261
|
plugins list
|
|
3043
3262
|
preset delete conf_name
|
|
3044
|
-
preset initialize conf_name @json:'{"p1":"v1","p2":"v2"}'
|
|
3045
3263
|
preset list
|
|
3046
3264
|
preset overview
|
|
3265
|
+
preset set @: conf_name.p4=v4 conf_name_other.p1=v1
|
|
3266
|
+
preset set @: conf_name_other=@none:
|
|
3047
3267
|
preset set GLOBAL sdk_folder 'product:IBM Aspera Connect'
|
|
3048
|
-
preset set GLOBAL vault @: type=file
|
|
3268
|
+
preset set GLOBAL vault @: default=local stores.local.type=file stores.local.file=/secure/vault_file
|
|
3049
3269
|
preset set GLOBAL vault_password <PASSWORD>
|
|
3050
3270
|
preset set GLOBAL version_check_days 0
|
|
3271
|
+
preset set conf_name @: p1=@none: p2.sub=v2 p3=v3
|
|
3272
|
+
preset set conf_name param @none:
|
|
3051
3273
|
preset set conf_name param value
|
|
3052
3274
|
preset set default shares conf_name
|
|
3053
3275
|
preset show conf_name
|
|
3054
|
-
preset unset conf_name param
|
|
3055
|
-
preset update conf_name --p1=v1 --p2=v2
|
|
3056
3276
|
proxy_check --fpac=@file:proxy.pac https://eudemo.asperademo.com --proxy-credentials=@list:,user,pass
|
|
3057
3277
|
pubkey @file:my_key
|
|
3058
3278
|
remote_certificate chain https://node.example.com/path
|
|
@@ -3062,28 +3282,27 @@ smtp_settings
|
|
|
3062
3282
|
sync spec
|
|
3063
3283
|
tokens flush
|
|
3064
3284
|
tokens list
|
|
3065
|
-
|
|
3066
|
-
transfer list
|
|
3067
|
-
transfer status <conf_async_node_upload>
|
|
3068
|
-
transferd install
|
|
3069
|
-
transferd list
|
|
3285
|
+
vault check @vault://local/my_label
|
|
3070
3286
|
vault create @: label=my_label password=<PASSWORD> 'description=my secret'
|
|
3071
3287
|
vault delete foo --vault.type=system
|
|
3072
3288
|
vault delete my_label
|
|
3289
|
+
vault field my_label
|
|
3073
3290
|
vault ids
|
|
3074
3291
|
vault info
|
|
3075
3292
|
vault list
|
|
3293
|
+
vault overview
|
|
3076
3294
|
vault show my_label
|
|
3077
|
-
wizard https://console.example.com/path console
|
|
3078
|
-
wizard https://f5.example.com/path faspex5 --key-
|
|
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
|
|
3295
|
+
wizard @: url=https://console.example.com/path plugin=console override=yes --username=my_username --password=<PASSWORD>
|
|
3296
|
+
wizard @: url=https://f5.example.com/path plugin=faspex5 override=yes --username=my_username --private-key=@file:<PRIVATE_KEY_FILE> --client-id=<CLIENT_ID> --client-secret=<CLIENT_SECRET>
|
|
3297
|
+
wizard @: url=https://node.example.com/path plugin=node --username=test --password=<PASSWORD>
|
|
3298
|
+
wizard @: url=https://orch.example.com/path plugin=orchestrator --username=test --password=<PASSWORD>
|
|
3299
|
+
wizard @: url=https://server1.example.com/path plugin=server --username=my_username --password=<PASSWORD>
|
|
3300
|
+
wizard @: url=https://shares.example.com/path plugin=shares --username=test --password=<PASSWORD>
|
|
3301
|
+
wizard @: url=https://tst.example.com/path plugin=faspio override=yes --username=my_username --password=<PASSWORD>
|
|
3302
|
+
wizard @: url=https://tst.example.com/path plugin=httpgw
|
|
3303
|
+
wizard @: url=my_org plugin=aoc --username=my_user_email --private-key=@file:<PRIVATE_KEY_FILE> --use-generic-client=yes
|
|
3304
|
+
wizard @: url=my_org plugin=aoc override=yes --username=my_user_email --private-key=@file:<PRIVATE_KEY_FILE> --use-generic-client=no --interactive=yes
|
|
3305
|
+
wizard @: url=my_org plugin=aoc preset=my_preset --username=my_user_email --private-key=@file:<PRIVATE_KEY_FILE>
|
|
3087
3306
|
```
|
|
3088
3307
|
|
|
3089
3308
|
#### Evaluation order of options
|
|
@@ -3117,10 +3336,10 @@ ascli config preset set cli_default interactive no
|
|
|
3117
3336
|
ascli config preset set default config cli_default
|
|
3118
3337
|
```
|
|
3119
3338
|
|
|
3120
|
-
An [Option Preset](#option-preset) value can be removed with
|
|
3339
|
+
An [Option Preset](#option-preset) value can be removed with `@none:`:
|
|
3121
3340
|
|
|
3122
3341
|
```shell
|
|
3123
|
-
ascli config preset
|
|
3342
|
+
ascli config preset set cli_default interactive @none:
|
|
3124
3343
|
```
|
|
3125
3344
|
|
|
3126
3345
|
Example: Define options using command line:
|
|
@@ -3140,6 +3359,9 @@ ascli -N --preset=@json:'{"url":"<URL>","password":"<PASSWORD>","username":"<USE
|
|
|
3140
3359
|
`ascli` supports shell tab-completion for **Bash**, **Zsh**, **Fish**, and **PowerShell** (Windows PowerShell 5.1 and PowerShell 7, on any OS).
|
|
3141
3360
|
The command `ascli config completion <shell>` displays the completion script for the given shell.
|
|
3142
3361
|
|
|
3362
|
+
The default shell is Zsh on macOS, Bash on most Linux distributions, and PowerShell on Windows (its prompt starts with `PS`).
|
|
3363
|
+
In Bash and Zsh, `echo $0` displays the name of the running shell.
|
|
3364
|
+
|
|
3143
3365
|
To activate completion, add the line for your shell to its startup file:
|
|
3144
3366
|
|
|
3145
3367
|
```bash
|
|
@@ -3185,26 +3407,40 @@ In PowerShell, the words proposed are kept for the session, so only the first `T
|
|
|
3185
3407
|
|
|
3186
3408
|
Once active, press `Tab` to complete:
|
|
3187
3409
|
|
|
3188
|
-
|
|
3189
3410
|
```bash
|
|
3190
3411
|
ascli <Tab> # plugins and global options: aoc, server, node, ..., --format, ...
|
|
3191
3412
|
ascli server <Tab> # sub-commands and options of plugin: upload, download, ls, ..., --url, ...
|
|
3192
3413
|
ascli aoc admin <Tab> # sub-commands at any depth: user, node, ...
|
|
3193
3414
|
ascli server ls --u<Tab> # options, after any command: --url, --username, ...
|
|
3194
3415
|
ascli --format=<Tab> # values of option: --format=json, --format=table, ...
|
|
3195
|
-
ascli --ts.<Tab> # keys of option, from its schema: --ts.direction
|
|
3416
|
+
ascli --ts.<Tab> # keys of option, from its schema: --ts.direction=, --ts.target_rate_kbps=, ...
|
|
3417
|
+
ascli --out.t<Tab> # a sub-structure is followed by a dot: --out.table.
|
|
3196
3418
|
ascli --ts.direction=<Tab> # values of key: --ts.direction=send, --ts.direction=receive
|
|
3419
|
+
ascli --transfer=<Tab> # plain value of option, key agent: --transfer=direct, --transfer=node, ...
|
|
3420
|
+
ascli faspex5 admin accounts list --query.<Tab> # keys of --query, from the command: --query.limit=, ...
|
|
3197
3421
|
ascli server upload <Tab> # local files
|
|
3198
|
-
ascli
|
|
3422
|
+
ascli server download --to-folder <Tab> # local folders
|
|
3423
|
+
ascli config genkey <Tab> # local files, where a local path is expected
|
|
3424
|
+
ascli --temp.folder=<Tab> # local folders, for a key of option
|
|
3425
|
+
ascli --ts=@<Tab> # extended value modifiers: @json:, @file:, @preset:, @:, ...
|
|
3426
|
+
ascli --private-key=@file:<Tab> # local files, after @file: or @path:
|
|
3427
|
+
ascli -P <Tab> # presets: also for config preset show, @preset:
|
|
3428
|
+
ascli config preset get myconf <Tab> # parameters of preset: url, username, ...
|
|
3429
|
+
ascli config agents jobs status <Tab> # asynchronous transfer jobs
|
|
3430
|
+
ascli node access_keys do <Tab> # type of expected value, not inserted: <identifier>
|
|
3199
3431
|
ascli aoc packages send <Tab> # type, and keys of structure (required ones with *): <Hash> name*, workspace_id*, ...
|
|
3200
|
-
ascli aoc packages send @:
|
|
3432
|
+
ascli aoc packages send @: <Tab> # keys of structure built with @:, from its schema: name=, workspace_id=, recipients.0., ...
|
|
3433
|
+
ascli aoc packages send @: archived=<Tab> # values of key: archived=true, archived=false
|
|
3434
|
+
ascli aoc packages send @: name=x <Tab> # end marker of structure built with @: END, and the other keys
|
|
3201
3435
|
```
|
|
3202
3436
|
|
|
3203
|
-
|
|
3437
|
+
No space is inserted after a word that continues: `key=`, `key.`, `@file:`, or a folder (Bash 4 and later).
|
|
3438
|
+
Zsh, Fish and PowerShell also display the description of commands, options, keys and extended value modifiers.
|
|
3439
|
+
In PowerShell, a word starting with `@` is inserted with quotes (e.g. `'@file:README.md'`), as required by PowerShell.
|
|
3204
3440
|
Zsh lists options once `-` is typed (zsh style `prefix-needed`).
|
|
3205
3441
|
The type of an expected value is displayed by Bash and Zsh, and by PowerShell in the list of `MenuComplete` (`Ctrl+Space`).
|
|
3206
3442
|
|
|
3207
|
-
The scripts call `ascli config completion candidates -- [<word>...] <current word>`, which lists the candidates for the word at the cursor, with their description, followed by a directive for the shell.
|
|
3443
|
+
The scripts call `ascli config completion candidates -- [<word>...] <current word>`, which lists the candidates for the word at the cursor, with their description, followed by a directive for the shell: `:files` or `:folders` (local paths, followed by the beginning of the word that is not part of the path, if any, e.g. `:files --private-key=@file:`), `:hint <text>` or `:`.
|
|
3208
3444
|
The words are not evaluated (e.g. `@env:` is not replaced).
|
|
3209
3445
|
The command `ascli config completion words [<word>...]` lists the words that can follow the given ones.
|
|
3210
3446
|
It can be used directly to inspect available commands:
|
|
@@ -3217,32 +3453,36 @@ ascli config completion words aoc admin
|
|
|
3217
3453
|
|
|
3218
3454
|
The wizard is a command that asks the user for information and creates an [Option Preset](#option-preset) with the provided information for a given application.
|
|
3219
3455
|
|
|
3220
|
-
It takes
|
|
3456
|
+
It takes one optional argument: a `Hash`, usually given with [`@:`](#positional-arguments-with-dot-path) as `key=value` items, in any order:
|
|
3221
3457
|
|
|
3222
|
-
|
|
3223
|
-
|
|
3224
|
-
|
|
|
3225
|
-
|
|
|
3226
|
-
|
|
|
3458
|
+
| Key | Description | If not provided, `ascli` |
|
|
3459
|
+
|------------|---------------------------------------------------------------------------------|--------------------------------------------|
|
|
3460
|
+
| `url` | **URL** or hostname of the application | asks for it. |
|
|
3461
|
+
| `plugin` | The **plugin name** to limit search to | tries to detect known plugins from the URL |
|
|
3462
|
+
| `preset` | The **preset name** to save in config file | generates a unique preset name |
|
|
3463
|
+
| `default` | Set the preset as default configuration for the plugin (`yes`/`no`) | `yes` |
|
|
3464
|
+
| `override` | Override the existing default preset of the plugin, if it exists (`yes`/`no`) | `no` |
|
|
3227
3465
|
|
|
3228
|
-
Options
|
|
3466
|
+
Options of the plugin (for example `--username`, `--password`, `--client-id`, `--private-key`), see the plugin, are given as usual on the command line: they are added to the [Option Preset](#option-preset) created by the wizard.
|
|
3467
|
+
Options that the wizard needs, but that are not provided, are asked.
|
|
3468
|
+
An unknown key in the `Hash` is refused.
|
|
3229
3469
|
|
|
3230
|
-
|
|
3231
|
-
|
|
3232
|
-
|
|
3233
|
-
|
|
3234
|
-
|
|
3470
|
+
For example:
|
|
3471
|
+
|
|
3472
|
+
```shell
|
|
3473
|
+
ascli config wizard @: url=<URL> plugin=<PLUGIN> preset=<PRESET>
|
|
3474
|
+
```
|
|
3235
3475
|
|
|
3236
|
-
|
|
3237
|
-
|
|
3476
|
+
The command `config detect` takes the same argument, with keys `url` and `plugin`, and shows the detected applications, without creating a preset.
|
|
3477
|
+
Use `ascli config wizard help` to show the schema of the argument.
|
|
3238
3478
|
|
|
3239
|
-
The simplest invocation is:
|
|
3479
|
+
The simplest invocation (without argument: the URL is asked) is:
|
|
3240
3480
|
|
|
3241
3481
|
```shell
|
|
3242
3482
|
ascli config wizard
|
|
3243
3483
|
```
|
|
3244
3484
|
|
|
3245
|
-
If the application requires a private key, the user can provide the path
|
|
3485
|
+
If the application requires a private key, the user can provide it with option `--private-key` (the key, e.g. `@file:<path>`, not only its path), or let the wizard generate one.
|
|
3246
3486
|
The user is told where to place the associated public key PEM in the application.
|
|
3247
3487
|
|
|
3248
3488
|
#### Example of configuration for a plugin
|
|
@@ -3268,13 +3508,13 @@ ascli config preset set shares06 password <PASSWORD>
|
|
|
3268
3508
|
This can also be done with one single command:
|
|
3269
3509
|
|
|
3270
3510
|
```shell
|
|
3271
|
-
ascli config preset
|
|
3511
|
+
ascli config preset set shares06 @json:'{"url":"https://10.25.0.6","username":"john","password":"<PASSWORD>"}'
|
|
3272
3512
|
```
|
|
3273
3513
|
|
|
3274
3514
|
Or:
|
|
3275
3515
|
|
|
3276
3516
|
```shell
|
|
3277
|
-
ascli config preset
|
|
3517
|
+
ascli config preset set shares06 @: url=https://10.25.0.6 username=john password=<PASSWORD>
|
|
3278
3518
|
```
|
|
3279
3519
|
|
|
3280
3520
|
- Define this [Option Preset](#option-preset) as the default [Option Preset](#option-preset) for the specified plugin (`shares`)
|
|
@@ -3326,7 +3566,71 @@ export ASCLI_PASSWORD
|
|
|
3326
3566
|
|
|
3327
3567
|
Another possibility is to retrieve values from a secret vault.
|
|
3328
3568
|
|
|
3329
|
-
|
|
3569
|
+
Option `vault` declares named secret stores (`stores`), and the name of the default store (`default`):
|
|
3570
|
+
|
|
3571
|
+
- `@vault:<label>.<field>` reads field `<field>` of secret `<label>` of the default store, managed with command `config vault` (see [Vault: Operations](#vault-operations)).
|
|
3572
|
+
- `@vault://<store>/<path>[?<options>][#<field>]` reads a secret of any store (see [Vault: Secret references](#vault-secret-references)).
|
|
3573
|
+
|
|
3574
|
+
| Field | Type | Description |
|
|
3575
|
+
| --------- | ------ | -------------------------------------------------------------------------------- |
|
|
3576
|
+
| `cache_ttl` | `Number` | Time in seconds a value read by reference is kept in memory, `0` for no cache.<br/>Default: `60`. |
|
|
3577
|
+
| `default` | `String` | Name of the default store, in `stores`: read by `@vault:<label>.<field>`, managed by `config vault`, unlocked with option `vault_password`. No default store if not set. |
|
|
3578
|
+
| `stores` | `Hash` | Name of store (letters, digits, `_`, `.`, `-`) → parameters of store, with `type`. Secrets are read by reference with `@vault://<store>/<path>[?<options>][#<field>]` from any store.<br/>Required. |
|
|
3579
|
+
|
|
3580
|
+
For example, to use as default store an encrypted file `vault.bin` in the configuration folder (see [Vault: Encrypted file](#vault-encrypted-file)):
|
|
3581
|
+
|
|
3582
|
+
```shell
|
|
3583
|
+
ascli config preset set GLOBAL vault @json:'{"default":"local","stores":{"local":{"type":"file","file":"vault.bin"}}}'
|
|
3584
|
+
```
|
|
3585
|
+
|
|
3586
|
+
Parameters of a store, with `type` (see sections below):
|
|
3587
|
+
|
|
3588
|
+
| Field | Type | Description |
|
|
3589
|
+
| ----------------- | ------------- | -------------------------------------------------------------------------------- |
|
|
3590
|
+
| **type** | `String` | `vault`: IBM HashiCorp Vault secret store. Labels of `config vault` and `@vault:<label>.<field>` are in mount `secret` (KV v2). Reference `@vault://<store>/<mount>/<path>#<field>` (field required) in any KV v2 mount, options `version=<n>`, `mount=<mount>` (when the mount contains `/`). |
|
|
3591
|
+
| `allowed_prefixes` | `Array[String]` | Allowed prefixes of `<mount>/<path>` of references: a prefix ending with `/` is a folder, else a path or a folder. All paths are allowed if not set. |
|
|
3592
|
+
| `approle` | `Hash` | AppRole authentication: the token is obtained by login, renewed, and obtained again when refused. |
|
|
3593
|
+
| `approle.mount` | `String` | Mount path of the AppRole auth method.<br/>Default: `approle`. |
|
|
3594
|
+
| `approle.role_id` | `String` | Role ID.<br/>Required. |
|
|
3595
|
+
| `approle.secret_id` | `String` | Secret ID (if the role requires one): the value, or `@file:<path>`. |
|
|
3596
|
+
| `ca_file` | `String` | File with the CA certificates that verify the certificate of the server (HTTPS). |
|
|
3597
|
+
| `namespace` | `String` | Namespace (Vault Enterprise). |
|
|
3598
|
+
| `token` | `String` | The authentication token. Its value, or `@file:<path>` (e.g. written and renewed by Vault Agent), read again when modified. One of `token` or `approle` is required. For the default store, defaults to the value of `vault_password`, unless `approle` is set.<br/>Example: `<TOKEN>`. |
|
|
3599
|
+
| `type` | `Enum[String]` | Vault type selector.<br/>Required.<br/>Allowed values: `vault`. |
|
|
3600
|
+
| `url` | `String` | URL of the HashiCorp Vault server.<br/>Required.<br/>Example: `http://127.0.0.1:8200`. |
|
|
3601
|
+
| **type** | `String` | `system`: macOS system keychain secret store. |
|
|
3602
|
+
| `name` | `String` | Name of the keychain to use (file `<name>.keychain-db` in the keychain search list).<br/>Default: `ascli`. |
|
|
3603
|
+
| `type` | `Enum[String]` | Vault type selector.<br/>Required.<br/>Allowed values: `system`. |
|
|
3604
|
+
| **type** | `String` | `secret_service`: Linux Secret Service secret store (GNOME Keyring, KWallet, KeePassXC...), using `secret-tool`. |
|
|
3605
|
+
| `name` | `String` | Name of the group of secrets (attribute `service` of the items).<br/>Default: `ascli`. |
|
|
3606
|
+
| `type` | `Enum[String]` | Vault type selector.<br/>Required.<br/>Allowed values: `secret_service`. |
|
|
3607
|
+
| **type** | `String` | `file`: Encrypted file secret store. Reference `@vault://<store>/<label>[#<field>]`, field `password` by default. |
|
|
3608
|
+
| `file` | `String` | Path to the encrypted vault file, created when the first secret is added. Relative paths are resolved from the configuration folder. Read when used, and again when modified.<br/>Default: `vault.bin`. |
|
|
3609
|
+
| `name` | `String` | Same as `file` (compatibility). |
|
|
3610
|
+
| `password` | `String` | Password of the vault file: the value, or `@file:<path>`, read again when modified. For the default store, defaults to the value of `vault_password`. |
|
|
3611
|
+
| `type` | `Enum[String]` | Vault type selector.<br/>Required.<br/>Allowed values: `file`. |
|
|
3612
|
+
| **type** | `String` | `1password`: 1Password secret store (Connect REST API or CLI). |
|
|
3613
|
+
| `account` | `String` | Account shorthand for `op` (used when `source` is `cli`). Uses the default account if omitted. |
|
|
3614
|
+
| `source` | `Enum[String]` | Backend source. Use `api` for the Connect REST API, `cli` for the `op` CLI.<br/>Required.<br/>Allowed values: `api`, `cli`.<br/>Default: `api`. |
|
|
3615
|
+
| `token` | `String` | Bearer token for the Connect API (required when `source` is `api`). For the default store, defaults to the value of `vault_password`. |
|
|
3616
|
+
| `type` | `Enum[String]` | Vault type selector.<br/>Required.<br/>Allowed values: `1password`. |
|
|
3617
|
+
| `url` | `String` | Base URL of the 1Password Connect server (required when `source` is `api`).<br/>Example: `http://localhost:8080`. |
|
|
3618
|
+
| `vault` | `String` | Name or ID of the 1Password vault to use with the CLI (used when `source` is `cli`). Uses the default vault if omitted. |
|
|
3619
|
+
| `vault_id` | `String` | ID of the 1Password vault to use (required when `source` is `api`). |
|
|
3620
|
+
| **type** | `String` | `keeper`: Keeper Secrets Manager secret store (Keeper Vault), using gem `keeper_secrets_manager`. A secret is a record shared with the application: its label is its title or its UID. Reference `@vault://<store>/<title or uid>[#<field>]`, field `password` by default: standard field by type (`login`, `password`, `url`...), custom field by label, or `notes`. |
|
|
3621
|
+
| `config` | `String` | Configuration of the client device (base64 or JSON, e.g. from `ksm profile export`): the value, or `@file:<path>`. For the default store, defaults to the value of `vault_password`. |
|
|
3622
|
+
| `folder_uid` | `String` | UID of the shared folder where `config vault create` adds records (not needed to read). |
|
|
3623
|
+
| `type` | `Enum[String]` | Vault type selector.<br/>Required.<br/>Allowed values: `keeper`. |
|
|
3624
|
+
|
|
3625
|
+
> [!NOTE]
|
|
3626
|
+
> The parameters of one store, without `stores` (for example, `{"type":"file","name":"vault.bin"}`), are deprecated: they define a store named after its type (for example, `file`), which is the default store.
|
|
3627
|
+
> Set the store in `stores`, and its name in `default` instead: `{"default":"local","stores":{"local":{"type":"file","file":"vault.bin"}}}`.
|
|
3628
|
+
|
|
3629
|
+
Secrets used to access a store (`token`, `approle.secret_id`, `password`) are the value, or `@file:<path>` (for example, a credential of `systemd`, or a token written by Vault Agent): the file is read when used, and again when it is modified.
|
|
3630
|
+
As for extended value `@file:`, reading the file is restricted by option `security` (see [Security Level](#security-level)).
|
|
3631
|
+
In a YAML file, quote the value: `@` cannot start a plain scalar.
|
|
3632
|
+
|
|
3633
|
+
The secret of the default store (`password` of type `file`, `token` of type `vault` without `approle`, of type `1password` with `source` `api`, and `config` of type `keeper`), if not in its parameters, is the value of option `vault_password`.
|
|
3330
3634
|
To avoid exposing the vault password in the shell history, provide it via an environment variable:
|
|
3331
3635
|
|
|
3332
3636
|
```shell
|
|
@@ -3352,29 +3656,20 @@ brew install hashicorp/tap/vault
|
|
|
3352
3656
|
vault server -dev -dev-root-token-id=<TOKEN>
|
|
3353
3657
|
```
|
|
3354
3658
|
|
|
3355
|
-
|
|
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. |
|
|
3659
|
+
```shell
|
|
3660
|
+
--vault=@json:'{"default":"corp","stores":{"corp":{"type":"vault","url":"http://127.0.0.1:8200"}}}' --vault-password=<TOKEN>
|
|
3661
|
+
```
|
|
3662
|
+
|
|
3663
|
+
With a token in a file (for example, written and renewed by Vault Agent), read again when the file is modified:
|
|
3664
|
+
|
|
3665
|
+
```shell
|
|
3666
|
+
--vault=@json:'{"default":"corp","stores":{"corp":{"type":"vault","url":"https://vault.example.com:8200","token":"@file:/run/vault/token"}}}'
|
|
3667
|
+
```
|
|
3668
|
+
|
|
3669
|
+
With AppRole authentication, the token is obtained by login, and renewed:
|
|
3375
3670
|
|
|
3376
3671
|
```shell
|
|
3377
|
-
--vault=@json:'{"type":"vault","url":"
|
|
3672
|
+
--vault=@json:'{"default":"corp","stores":{"corp":{"type":"vault","url":"https://vault.example.com:8200","approle":{"role_id":"<ROLE_ID>","secret_id":"@file:/etc/vault/secret_id"}}}}'
|
|
3378
3673
|
```
|
|
3379
3674
|
|
|
3380
3675
|
#### Vault: System keychain
|
|
@@ -3386,28 +3681,42 @@ It is possible to manage secrets in macOS keychain.
|
|
|
3386
3681
|
Commands `list`, `ids` and `delete` are not supported: use the **Keychain Access** app.
|
|
3387
3682
|
|
|
3388
3683
|
```shell
|
|
3389
|
-
--vault=@json:'{"type":"system","name":"ascli"}'
|
|
3684
|
+
--vault=@json:'{"default":"keychain","stores":{"keychain":{"type":"system","name":"ascli"}}}'
|
|
3685
|
+
```
|
|
3686
|
+
|
|
3687
|
+
#### Vault: Linux Secret Service
|
|
3688
|
+
|
|
3689
|
+
> [!WARNING]
|
|
3690
|
+
> **Linux only**
|
|
3691
|
+
|
|
3692
|
+
It is possible to manage secrets in the Linux Secret Service (GNOME Keyring, KWallet, KeePassXC...), using the `secret-tool` command of `libsecret` (for example, package `libsecret-tools` on Debian and Ubuntu).
|
|
3693
|
+
A session with an unlocked keyring is required.
|
|
3694
|
+
Secrets are grouped with attribute `service`, which is parameter `name` (default: `ascli`).
|
|
3695
|
+
|
|
3696
|
+
```shell
|
|
3697
|
+
--vault=@json:'{"default":"keyring","stores":{"keyring":{"type":"secret_service","name":"ascli"}}}'
|
|
3390
3698
|
```
|
|
3391
3699
|
|
|
3392
3700
|
#### Vault: Encrypted file
|
|
3393
3701
|
|
|
3394
|
-
It is possible to store and use secrets encrypted in a file
|
|
3702
|
+
It is possible to store and use secrets encrypted in a file, with a store of type `file`:
|
|
3395
3703
|
|
|
3396
3704
|
```json
|
|
3397
|
-
{"type":"file","
|
|
3705
|
+
{"default":"local","stores":{"local":{"type":"file","file":"vault.bin"}}}
|
|
3398
3706
|
```
|
|
3399
3707
|
|
|
3400
|
-
To configure the encrypted file vault as the default, set the `vault` option in the global preset:
|
|
3708
|
+
To configure the encrypted file vault as the default store, set the `vault` option in the global preset:
|
|
3401
3709
|
|
|
3402
3710
|
```shell
|
|
3403
|
-
ascli config preset set GLOBAL vault
|
|
3711
|
+
ascli config preset set GLOBAL vault @json:'{"default":"local","stores":{"local":{"type":"file","file":"vault.bin"}}}'
|
|
3404
3712
|
```
|
|
3405
3713
|
|
|
3406
|
-
The vault file is created automatically
|
|
3714
|
+
The vault file is created automatically when the first secret is added - no explicit initialization is needed.
|
|
3715
|
+
It is read when used, and again when it is modified.
|
|
3407
3716
|
|
|
3408
3717
|
> [!WARNING]
|
|
3409
3718
|
> The `vault_password` option should **not** be stored in the config file: doing so would protect secrets with a password that is itself stored in plain text, defeating the purpose of the vault.
|
|
3410
|
-
> Use an environment variable as described above.
|
|
3719
|
+
> Use an environment variable as described above, or parameter `password` with `@file:<path>` (for example, a credential of `systemd`).
|
|
3411
3720
|
|
|
3412
3721
|
#### Vault: 1Password
|
|
3413
3722
|
|
|
@@ -3428,7 +3737,7 @@ docker run -d --name op-connect \
|
|
|
3428
3737
|
```
|
|
3429
3738
|
|
|
3430
3739
|
```shell
|
|
3431
|
-
--vault=@json:'{"type":"1password","source":"api","url":"http://localhost:8080","vault_id":"<VAULT_ID>"}' \
|
|
3740
|
+
--vault=@json:'{"default":"op","stores":{"op":{"type":"1password","source":"api","url":"http://localhost:8080","vault_id":"<VAULT_ID>"}}}' \
|
|
3432
3741
|
--vault-password=<CONNECT_TOKEN>
|
|
3433
3742
|
```
|
|
3434
3743
|
|
|
@@ -3448,9 +3757,9 @@ Requires the `op` CLI to be installed and signed in.
|
|
|
3448
3757
|
No server to deploy: authentication is handled by the 1Password desktop app (biometric unlock) or by `op signin`.
|
|
3449
3758
|
|
|
3450
3759
|
```shell
|
|
3451
|
-
--vault=@json:'{"type":"1password","source":"cli"}'
|
|
3760
|
+
--vault=@json:'{"default":"op","stores":{"op":{"type":"1password","source":"cli"}}}'
|
|
3452
3761
|
# or, to target a specific vault and account:
|
|
3453
|
-
--vault=@json:'{"type":"1password","source":"cli","vault":"<VAULT_NAME>","account":"<ACCOUNT_SHORTHAND>"}'
|
|
3762
|
+
--vault=@json:'{"default":"op","stores":{"op":{"type":"1password","source":"cli","vault":"<VAULT_NAME>","account":"<ACCOUNT_SHORTHAND>"}}}'
|
|
3454
3763
|
```
|
|
3455
3764
|
|
|
3456
3765
|
> [!TIP]
|
|
@@ -3469,18 +3778,57 @@ An item can be referenced by its title (label) or by its 1Password ID, in `@vaul
|
|
|
3469
3778
|
> [!NOTE]
|
|
3470
3779
|
> If several items share the same title, use the item ID (or the `vault` parameter to restrict the search).
|
|
3471
3780
|
|
|
3781
|
+
#### Vault: Keeper
|
|
3782
|
+
|
|
3783
|
+
<https://docs.keeper.io/keeperpam/secrets-manager/overview>
|
|
3784
|
+
|
|
3785
|
+
Keeper Secrets Manager (KSM) gives an application access to the records of shared folders of a Keeper vault, without the credentials of a user.
|
|
3786
|
+
It requires the optional gem `keeper_secrets_manager`:
|
|
3787
|
+
|
|
3788
|
+
```shell
|
|
3789
|
+
gem install keeper_secrets_manager
|
|
3790
|
+
```
|
|
3791
|
+
|
|
3792
|
+
Create an application and a client device in Keeper (see the [Quick Start Guide](https://docs.keeper.io/keeperpam/secrets-manager/quick-start-guide)), share the folders of secrets with the application, and get the configuration of the device (base64 or JSON, for example with `ksm profile export`).
|
|
3793
|
+
Parameter `config` is the value, or `@file:<path>`:
|
|
3794
|
+
|
|
3795
|
+
```shell
|
|
3796
|
+
--vault=@json:'{"default":"keeper","stores":{"keeper":{"type":"keeper","config":"@file:<KSM_CONFIG_FILE>"}}}'
|
|
3797
|
+
```
|
|
3798
|
+
|
|
3799
|
+
If `config` is not set in the default store, it is the value of option `vault_password`.
|
|
3800
|
+
|
|
3801
|
+
A secret is a record of the vault: its label is its title, or its UID.
|
|
3802
|
+
The field of a reference is `password` by default: standard field of the record (`login`, `password`, `url`...), custom field by its label, or `notes`.
|
|
3803
|
+
Field `username` is an alias of `login`.
|
|
3804
|
+
|
|
3805
|
+
```shell
|
|
3806
|
+
--password=@vault:<RECORD_TITLE>.password
|
|
3807
|
+
--password=@vault://keeper/<RECORD_TITLE>#<FIELD>
|
|
3808
|
+
```
|
|
3809
|
+
|
|
3810
|
+
To create records with `config vault create` (type `login`), set parameter `folder_uid`: UID of the shared folder where records are added.
|
|
3811
|
+
Reading does not need it.
|
|
3812
|
+
|
|
3813
|
+
> [!NOTE]
|
|
3814
|
+
> If several records share the same title, use the UID.
|
|
3815
|
+
> Deleting a record with `config vault delete` requires that the application has edit permission.
|
|
3816
|
+
|
|
3472
3817
|
#### Vault: Operations
|
|
3473
3818
|
|
|
3474
|
-
Secrets can be manipulated using the `config vault` command:
|
|
3819
|
+
Secrets of the default store can be manipulated using the `config vault` command:
|
|
3475
3820
|
|
|
3476
3821
|
- `info` : Show vault information
|
|
3477
3822
|
- `ids` : List secret labels in the vault
|
|
3478
3823
|
- `list` : List all secrets with full details
|
|
3824
|
+
- `overview` : List labels of all secrets with their field names, without values
|
|
3825
|
+
- `field` : List field names of a secret by label, without values
|
|
3479
3826
|
- `show` : Show a secret by label (or id)
|
|
3480
3827
|
- `create` : Add a new secret to the vault
|
|
3481
3828
|
- `delete` : Delete a secret by label (or id)
|
|
3482
3829
|
- `password` : Set a new password for the vault
|
|
3483
3830
|
- `import` : Import secrets from a JSON array (supports `--bulk`)
|
|
3831
|
+
- `check` : Check that a [Secret Reference](#vault-secret-references) can be read, without its value
|
|
3484
3832
|
|
|
3485
3833
|
To add a new password entry in the vault for label `<NAME>`:
|
|
3486
3834
|
|
|
@@ -3497,10 +3845,10 @@ To migrate all secrets from one vault backend to another (for example, from the
|
|
|
3497
3845
|
|
|
3498
3846
|
```shell
|
|
3499
3847
|
ascli config vault list --format=json --out.level=data --out.secrets=yes \
|
|
3500
|
-
--vault=@json:'{"type":"file","
|
|
3848
|
+
--vault=@json:'{"default":"local","stores":{"local":{"type":"file","file":"<SOURCE_VAULT_FILE>"}}}' \
|
|
3501
3849
|
--vault-password=<SOURCE_PASSWORD> | \
|
|
3502
3850
|
ascli config vault import @json:@stdin: --bulk=yes \
|
|
3503
|
-
--vault=@json:'{"type":"1password","url":"<CONNECT_URL>","vault_id":"<VAULT_ID>"}' \
|
|
3851
|
+
--vault=@json:'{"default":"op","stores":{"op":{"type":"1password","url":"<CONNECT_URL>","vault_id":"<VAULT_ID>"}}}' \
|
|
3504
3852
|
--vault-password=<CONNECT_TOKEN>
|
|
3505
3853
|
```
|
|
3506
3854
|
|
|
@@ -3512,6 +3860,44 @@ The `import` command accepts a JSON array where each element is a vault secret o
|
|
|
3512
3860
|
On error (for example a duplicate label), the default behavior is to stop (`--bfail=yes`).
|
|
3513
3861
|
Pass `--bfail=no` to skip failures and continue with the remaining entries.
|
|
3514
3862
|
|
|
3863
|
+
#### Vault: Secret references
|
|
3864
|
+
|
|
3865
|
+
Secrets can also be read by reference, from any store of option `vault`:
|
|
3866
|
+
|
|
3867
|
+
```text
|
|
3868
|
+
@vault://<store>/<path>[?<options>][#<field>]
|
|
3869
|
+
```
|
|
3870
|
+
|
|
3871
|
+
- `<store>`: name of a store in `stores` of option `vault`.
|
|
3872
|
+
- `<path>`: path of the secret in the store, and `<field>`: field of the secret. Both are percent-decoded (for example, `%20` for a space).
|
|
3873
|
+
For most types, the path is the label, and the field is `password` by default.
|
|
3874
|
+
For type `vault`, the path is `<mount>/<path>` in a KV v2 secrets engine, and the field is required.
|
|
3875
|
+
- `<options>`: options of the store, as a URL query (for example, `version=2`).
|
|
3876
|
+
|
|
3877
|
+
References only read secrets: they are managed with the tools of the store (for example, `vault kv put` for HashiCorp Vault), or with `config vault` for the default store.
|
|
3878
|
+
Compared to `@vault:<label>.<field>`, several stores can be used in the same command, and a HashiCorp Vault store reads any KV v2 mount, a given version, and limits the paths that can be read by reference (`allowed_prefixes`).
|
|
3879
|
+
Values read by reference are kept in memory for `cache_ttl` seconds.
|
|
3880
|
+
The configuration of stores is the same as in applications that use the library with references `secret://<store>/<path>` (for example, IBM Aspera Orchestrator).
|
|
3881
|
+
|
|
3882
|
+
For example, a HashiCorp Vault server with AppRole authentication, limited to secrets under `kv/aspera/`, and the encrypted file of `config vault` as default store, unlocked with option `vault_password`:
|
|
3883
|
+
|
|
3884
|
+
```shell
|
|
3885
|
+
--vault=@json:'{"default":"local","stores":{"corp":{"type":"vault","url":"https://vault.example.com:8200","approle":{"role_id":"<ROLE_ID>","secret_id":"@file:/etc/vault/secret_id"},"allowed_prefixes":["kv/aspera/"]},"local":{"type":"file","file":"vault.bin"}}}'
|
|
3886
|
+
```
|
|
3887
|
+
|
|
3888
|
+
References in a preset: to field `password` of secret `aspera/faspex` in mount `kv`, and to field `password` (default field of type `file`) of label `<VAULT_LABEL>` in the encrypted file:
|
|
3889
|
+
|
|
3890
|
+
```shell
|
|
3891
|
+
ascli config preset set <PRESET_NAME> @: url=... username=... password=@val:@vault://corp/kv/aspera/faspex#password
|
|
3892
|
+
ascli config preset set <PRESET_NAME> @: url=... username=... password=@val:@vault://local/<VAULT_LABEL>
|
|
3893
|
+
```
|
|
3894
|
+
|
|
3895
|
+
To check that a reference can be read, without its value (store, version, time of update):
|
|
3896
|
+
|
|
3897
|
+
```shell
|
|
3898
|
+
ascli config vault check @vault://corp/kv/aspera/faspex#password
|
|
3899
|
+
```
|
|
3900
|
+
|
|
3515
3901
|
#### Configuration Finder
|
|
3516
3902
|
|
|
3517
3903
|
When a secret is needed by a sub command, the command can search for existing configurations in the configuration file by setting option `secret` to the special value `PRESET`.
|
|
@@ -3524,13 +3910,13 @@ A password can be saved in clear in an [Option Preset](#option-preset) together
|
|
|
3524
3910
|
Example:
|
|
3525
3911
|
|
|
3526
3912
|
```shell
|
|
3527
|
-
ascli config preset
|
|
3913
|
+
ascli config preset set <PRESET_NAME> @: url=... username=... password=...
|
|
3528
3914
|
```
|
|
3529
3915
|
|
|
3530
3916
|
For more secure storage, first create a vault entry (see [Vault: Operations](#vault-operations)), then refer to it in the preset:
|
|
3531
3917
|
|
|
3532
3918
|
```shell
|
|
3533
|
-
ascli config preset
|
|
3919
|
+
ascli config preset set <PRESET_NAME> @: url=... username=... password=@val:@vault:<VAULT_LABEL>.password
|
|
3534
3920
|
```
|
|
3535
3921
|
|
|
3536
3922
|
> [!NOTE]
|
|
@@ -3549,7 +3935,7 @@ This scans all presets (or a single one if a name is provided) and, for every op
|
|
|
3549
3935
|
ascli config preset secure <PRESET_NAME>
|
|
3550
3936
|
```
|
|
3551
3937
|
|
|
3552
|
-
When a vault is configured, the `
|
|
3938
|
+
When a vault is configured, the `set` and `ask` preset commands automatically move secret values (options ending with `password` or `secret`) into the vault as they are written, so no manual migration is needed.
|
|
3553
3939
|
To disable this behavior for a single command, pass `--vault=@none:`.
|
|
3554
3940
|
|
|
3555
3941
|
### Private Key
|
|
@@ -3565,13 +3951,12 @@ The file containing the private key (key pair) can optionally be protected by a
|
|
|
3565
3951
|
If the key is protected by a passphrase, then the passphrase is prompted when the key is used.
|
|
3566
3952
|
Some plugins support option `passphrase`.
|
|
3567
3953
|
|
|
3568
|
-
|
|
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:
|
|
3954
|
+
Keys of type `ed25519` and OpenSSH encoded keys (default on modern Linux) are supported.
|
|
3955
|
+
See section: [Private key type ed25519](#private-key-type-ed25519).
|
|
3956
|
+
For OpenSSH encoded keys protected by a passphrase, install gem `bcrypt_pbkdf` (not available for JRuby):
|
|
3572
3957
|
|
|
3573
3958
|
```shell
|
|
3574
|
-
gem install
|
|
3959
|
+
gem install bcrypt_pbkdf
|
|
3575
3960
|
```
|
|
3576
3961
|
|
|
3577
3962
|
The following sample commands use the shell variable `KEY_PAIR_PATH`.
|
|
@@ -3650,9 +4035,35 @@ For example: <https://cryptotools.net/rsagen>
|
|
|
3650
4035
|
|
|
3651
4036
|
### Web service
|
|
3652
4037
|
|
|
3653
|
-
|
|
3654
|
-
|
|
4038
|
+
`ascli` is a command-line tool: it runs in a shell, with the credentials and presets of the user who starts it, and it assumes that only this user uses it.
|
|
4039
|
+
It is not intended to be a public-facing web server.
|
|
4040
|
+
When commands come from another program, for example an MCP client, see [Security Level](#security-level).
|
|
4041
|
+
|
|
4042
|
+
Some commands start a web server, for a specific client:
|
|
4043
|
+
|
|
4044
|
+
| Command | Client | Protection required when `url` is not loopback |
|
|
4045
|
+
|---|---|---|
|
|
4046
|
+
| `mcp server`, `http` transport | MCP client | `auth_token`, see [MCP Security](#security) |
|
|
4047
|
+
| `faspex5 postprocessing` | Faspex 5 web hooks | `secret_token` or `allowed_ips`, see [Faspex 4-style post-processing](#faspex-5-faspex-4-style-post-processing) |
|
|
4048
|
+
| `faspex5 gateway`, `aoc gateway` | Faspex 4 client applications | `username` and `password`, see [Faspex 4 Gateway](#faspex-5-faspex-4-gateway) |
|
|
4049
|
+
| `node emulator` | Node API clients, for tests | `username` and `password`, see [Node emulator](#node-emulator) |
|
|
4050
|
+
|
|
4051
|
+
By default, the server listens on a loopback address: `localhost`, an address of `127.0.0.0/8`, or `::1`.
|
|
4052
|
+
It can be reached only from the same host.
|
|
4053
|
+
|
|
4054
|
+
> [!WARNING]
|
|
4055
|
+
> Loopback restricts the host, not the user: on a host shared with other users, they can also reach the server.
|
|
4056
|
+
> On such a host, also set the protection of the command.
|
|
4057
|
+
|
|
4058
|
+
When the host of `url` is not a loopback address, for example `0.0.0.0` (all interfaces), the server can be reached from the network: the command refuses to start without its protection.
|
|
4059
|
+
On a network, use HTTPS (`https://` in `url`) or a reverse proxy with TLS: with HTTP, passwords and tokens are sent in clear.
|
|
3655
4060
|
|
|
4061
|
+
Other features listen on a loopback address only, to receive input from the browser of the user:
|
|
4062
|
+
|
|
4063
|
+
- [Web login flow](#web-login-flow): the result of the login, on `redirect_uri`.
|
|
4064
|
+
- `@secret:`, with option `ui` set to `graphical` (see [Secret Vault](#secret-vault)), or with `mcp server` and the `stdio` transport (see [Secrets entered in a web page](#secrets-entered-in-a-web-page)): the secret entered by the user.
|
|
4065
|
+
|
|
4066
|
+
The server serves HTTP, or HTTPS with a certificate.
|
|
3656
4067
|
The following parameters are supported:
|
|
3657
4068
|
|
|
3658
4069
|
| Parameter | Type | Default | Description |
|
|
@@ -3692,7 +4103,7 @@ This feature can be used:
|
|
|
3692
4103
|
The following options can be specified in option `--out.img`:
|
|
3693
4104
|
|
|
3694
4105
|
| Field | Type | Description |
|
|
3695
|
-
|
|
4106
|
+
| ---------- | ------- | -------------------------------------------------------------------------------- |
|
|
3696
4107
|
| `double` | `Bool` | Use double vertical resolution via half-block characters (Unicode). Default is `true` if the terminal supports Unicode (see `utf8`). |
|
|
3697
4108
|
| `font_ratio` | `Number` | Terminal font aspect ratio (height divided by width).<br/>Default: `2.3`. |
|
|
3698
4109
|
| `reserve` | `Integer` | Number of terminal lines reserved for non-image output.<br/>Default: `3`. |
|
|
@@ -3726,28 +4137,189 @@ Some actions may require the use of a graphical tool:
|
|
|
3726
4137
|
- A browser to enter a secret requested with `@secret:`
|
|
3727
4138
|
- A text editor for editing the configuration file
|
|
3728
4139
|
|
|
3729
|
-
By default, `ascli` assumes that a graphical environment is available on Windows; on other systems, it relies on the presence of the `DISPLAY` environment variable.
|
|
3730
|
-
The composite option `ui` (use `--ui=help` to display this schema) selects the mode and the browser command:
|
|
4140
|
+
By default, `ascli` assumes that a graphical environment is available on Windows and macOS; on other systems, it relies on the presence of the `DISPLAY` environment variable.
|
|
4141
|
+
The composite option `ui` (use `--ui=help` to display this schema) selects the mode, the way a web login is received, and the browser command:
|
|
3731
4142
|
|
|
3732
4143
|
| Field | Type | Description |
|
|
3733
|
-
|
|
3734
|
-
| `command` | `Array[String]` | Command that opens a URL, instead of the system default. First item is the executable, then its arguments. The URL is added as last argument. When set, it is used to open URLs, whatever the `mode`. |
|
|
3735
|
-
| `mode` | `String` | `auto`: `browser` on Windows and macOS, or if env var `DISPLAY` is set, else `terminal
|
|
4144
|
+
| -------- | ------------- | -------------------------------------------------------------------------------- |
|
|
4145
|
+
| `command` | `Array[String]` | Command that opens a URL, instead of the system default. First item is the executable (full path, or name of an executable found in `PATH`), then its arguments. The URL is added as last argument. When set, it is used to open URLs, whatever the `mode`. |
|
|
4146
|
+
| `mode` | `Enum[String]` | - `auto`: `browser` on Windows and macOS, or if env var `DISPLAY` is set, else `terminal`.<br/>- `terminal`: URLs to open are displayed on terminal, and secrets are entered on terminal.<br/>- `browser`: a browser opens URLs, and secrets are entered on a web page.<br/>`text` is an alias for `terminal`, and `graphical` is an alias for `browser`.<br/>Files to edit are always opened with a text editor, whatever the `mode`.<br/>Allowed values: `auto`, `terminal`, `browser`, `text`, `graphical`.<br/>Default: `auto`. |
|
|
4147
|
+
| `web_auth` | `Enum[String]` | How the result of a web login (`--auth=web`, SSO) is received.<br/>- `port`: `ascli` listens on the loopback port of `redirect_uri`, the browser is redirected to it.<br/>- `paste`: no port is opened. After login, the browser shows a connection error on `redirect_uri`: copy the full URL from the address bar of the browser and paste it in the terminal. Use it when the browser cannot reach the host that runs `ascli` and a SSH tunnel is not possible. For `shares`, Shares displays a code (a long text of letters, digits, `-` and `_`) instead: paste it in the terminal.<br/>Allowed values: `port`, `paste`.<br/>Default: `port`. |
|
|
4148
|
+
|
|
4149
|
+
A plain value is the `mode`:
|
|
4150
|
+
|
|
4151
|
+
- `--ui=browser` (or `graphical`) forces a graphical environment: a browser is opened for URLs or secrets.
|
|
4152
|
+
- `--ui=terminal` (or `text`) forces a text environment: the URL to open is displayed on terminal, and secrets are entered on terminal.
|
|
4153
|
+
- `--ui=auto` selects the mode from the environment (default).
|
|
4154
|
+
|
|
4155
|
+
The browser is opened, by priority, with: `--ui.command`, or the system default.
|
|
4156
|
+
The system default is opened with the following command:
|
|
4157
|
+
|
|
4158
|
+
| OS | Command |
|
|
4159
|
+
|---------|------------------------|
|
|
4160
|
+
| macOS | `open <url>` |
|
|
4161
|
+
| Windows | `start explorer "<url>"` |
|
|
4162
|
+
| Linux | `xdg-open <url>` |
|
|
4163
|
+
|
|
4164
|
+
To edit a file (for example `config open`), whatever the `mode`, the editor is, by priority: the command in the environment variable `EDITOR`, else `notepad.exe` on Windows, else the system default above (or `--ui.command` if defined).
|
|
4165
|
+
|
|
4166
|
+
When a command is defined, it is used to open URLs whatever the `mode`.
|
|
4167
|
+
The command is an array: the URL is appended as last argument.
|
|
4168
|
+
The executable is either a full path, or the name of an executable found in the `PATH`.
|
|
4169
|
+
For example, to use Firefox:
|
|
4170
|
+
|
|
4171
|
+
```bash
|
|
4172
|
+
ascli config echo @secret: --ui=browser --ui.command=@json:'["firefox","--private-window"]'
|
|
4173
|
+
```
|
|
4174
|
+
|
|
4175
|
+
### Web login flow
|
|
4176
|
+
|
|
4177
|
+
Authentication methods that need a user login in a browser (`--auth=web`, including for Shares) all work the same way: `ascli` listens on a local port, the browser is redirected to it after login.
|
|
4178
|
+
|
|
4179
|
+

|
|
4180
|
+
|
|
4181
|
+
1. `ascli` generates a random `state` and starts a local HTTP server on the loopback address of `redirect_uri` (default: `http://localhost:12345`).
|
|
4182
|
+
2. `ascli` opens the login URL in the browser (see [Graphical Interactions](#graphical-interactions-browser-and-text-editor)): the authorization endpoint with `redirect_uri` and `state` for `web`, or, for Shares, the SAML login page with `RelayState`.
|
|
4183
|
+
If no graphical environment is available, the URL is displayed, to be opened on any browser of the same host.
|
|
4184
|
+
3. The user logs in on the server, possibly redirected to an identity provider.
|
|
4185
|
+
4. The server redirects the browser to `redirect_uri`, with the OAuth code (`web`), or, for Shares, the tokens, and the `state`.
|
|
4186
|
+
5. The browser sends this request to `ascli`, which checks that `state` is the one it generated, and stops listening.
|
|
4187
|
+
6. `ascli` requests the token to the server: exchange of the code (`web`) or, for Shares, of the refresh token, and saves it in the cache.
|
|
4188
|
+
For Faspex 5, the code is protected with PKCE: `ascli` sends a challenge with the login URL, and the matching verifier with the code.
|
|
4189
|
+
Next calls use the cached token, renewed if needed without a browser.
|
|
4190
|
+
|
|
4191
|
+
The code or tokens never go to another host than the local one: the host of `redirect_uri` shall be loopback.
|
|
4192
|
+
|
|
4193
|
+
#### Option `ui.web_auth`
|
|
4194
|
+
|
|
4195
|
+
Option `ui.web_auth` (part of the composite option `ui`, see [Graphical Interactions](#graphical-interactions-browser-and-text-editor)) selects how the result of a web login is received:
|
|
4196
|
+
|
|
4197
|
+
| Value | Local port | Use when |
|
|
4198
|
+
|------------------|------------|----------|
|
|
4199
|
+
| `port` (default) | Yes: `ascli` listens on the loopback address of `redirect_uri` | The browser runs on the same system as `ascli`, or an SSH tunnel is possible. |
|
|
4200
|
+
| `paste` | No: `redirect_uri` is only used in the login URL | The browser cannot reach the system that runs `ascli`, and no tunnel is possible. |
|
|
4201
|
+
|
|
4202
|
+
With `paste`, after login the user gives the result to `ascli` through the terminal (nothing is displayed, as it contains a code or tokens):
|
|
4203
|
+
|
|
4204
|
+
- the code displayed by Shares (a long text of letters, digits, `-` and `_`), or the code shown by `ascli config web_login` on the workstation,
|
|
4205
|
+
- or the full URL (or only the query) from the address bar of the browser, which shows a connection error on `redirect_uri`: this is expected.
|
|
4206
|
+
|
|
4207
|
+
In all cases the `state` is checked.
|
|
4208
|
+
Details are in the following sections.
|
|
4209
|
+
|
|
4210
|
+
Example:
|
|
4211
|
+
|
|
4212
|
+
```shell
|
|
4213
|
+
ascli <PLUGIN> <COMMAND> --ui=terminal --ui.web_auth=paste
|
|
4214
|
+
```
|
|
4215
|
+
|
|
4216
|
+
#### Web login when the browser is on another system
|
|
4217
|
+
|
|
4218
|
+
The browser sends the result of the login to `redirect_uri`, on the loopback address of the system where the browser runs.
|
|
4219
|
+
If `ascli` runs on another system than the browser (for example, `ascli` is installed on a server, and the user is connected with SSH from a workstation), the redirection does not reach `ascli`.
|
|
4220
|
+
|
|
4221
|
+
To solve this, forward the port of `redirect_uri` from the workstation to the server with an SSH tunnel, and open the login URL in the browser of the workstation:
|
|
4222
|
+
|
|
4223
|
+
1. On the workstation, open the SSH session with a tunnel (same port on both sides, default `12345`):
|
|
4224
|
+
|
|
4225
|
+
```shell
|
|
4226
|
+
ssh -L 127.0.0.1:12345:127.0.0.1:12345 <SERVER_USER>@<SERVER_HOST>
|
|
4227
|
+
```
|
|
4228
|
+
|
|
4229
|
+
2. In this session, run the command with `--ui=terminal`, so that the login URL is displayed instead of opening a browser on the server (this is the default if the server has no graphical environment):
|
|
4230
|
+
|
|
4231
|
+
```shell
|
|
4232
|
+
ascli <PLUGIN> <COMMAND> --ui=terminal
|
|
4233
|
+
```
|
|
4234
|
+
|
|
4235
|
+
3. Copy the displayed URL in the browser of the workstation, and log in.
|
|
4236
|
+
4. The browser is redirected to `http://localhost:12345`: the tunnel sends the request to `ascli` on the server, and the flow continues as described above.
|
|
4237
|
+
|
|
4238
|
+
The tunnel only exists as long as the SSH session is open.
|
|
4239
|
+
|
|
4240
|
+
If no tunnel is possible (for example, a jump server between the workstation and the server), use `--ui.web_auth=paste`: `ascli` then opens no local port, and the result of the login is given through the terminal.
|
|
4241
|
+
There are two ways, depending on whether `ascli` is also installed on the workstation.
|
|
4242
|
+
|
|
4243
|
+
With `--ui.web_auth=port` (default), in an SSH session with `--ui=terminal`, a warning reminds this option.
|
|
4244
|
+
|
|
4245
|
+
##### With `ascli` on the workstation
|
|
4246
|
+
|
|
4247
|
+
`ascli` on the workstation opens the login page, receives the redirection of the browser, and shows a code to paste in the terminal of the server.
|
|
4248
|
+
Nothing else is needed on the workstation: no configuration, no preset, no access to the server of the application.
|
|
4249
|
+
The exchange of the code for a token is done by `ascli` on the server: the secret of the client does not leave it.
|
|
3736
4250
|
|
|
3737
|
-
|
|
4251
|
+
1. In the SSH session, run the command with `--ui=terminal --ui.web_auth=paste`:
|
|
3738
4252
|
|
|
3739
|
-
|
|
3740
|
-
|
|
3741
|
-
|
|
4253
|
+
```shell
|
|
4254
|
+
ascli <PLUGIN> <COMMAND> --ui=terminal --ui.web_auth=paste
|
|
4255
|
+
```
|
|
3742
4256
|
|
|
3743
|
-
|
|
3744
|
-
|
|
3745
|
-
|
|
3746
|
-
|
|
4257
|
+
2. `ascli` displays a message that proposes the two ways to log in, with the login URL for the first one, and a command to run on the workstation for the second one: it contains a code made of letters, digits, `-` and `_`. Then `ascli` waits:
|
|
4258
|
+
|
|
4259
|
+
```text
|
|
4260
|
+
USER ACTION: To continue, choose one of these two ways:
|
|
4261
|
+
1. With any browser (ascli is not needed on the workstation):
|
|
4262
|
+
- Open this URL in a browser and log in:
|
|
4263
|
+
https://...
|
|
4264
|
+
- The browser shows a connection error on http://localhost:12345: this is expected.
|
|
4265
|
+
- Copy the full URL from the address bar of the browser, and paste it in the prompt below.
|
|
4266
|
+
2. If ascli is installed on the workstation that has the browser:
|
|
4267
|
+
- Run there:
|
|
4268
|
+
ascli config web_login <CODE>
|
|
4269
|
+
- Log in in the page that opens.
|
|
4270
|
+
- Copy the code shown by the browser, and paste it in the prompt below.
|
|
4271
|
+
```
|
|
3747
4272
|
|
|
3748
|
-
|
|
3749
|
-
|
|
3750
|
-
|
|
4273
|
+
The command is displayed only if `ascli` does not start the browser itself (`--ui=terminal` without `--ui.command`).
|
|
4274
|
+
If the browser is started by `ascli` (`--ui=graphical`, or `--ui.command`), it is on the same host as `ascli`, and the redirection may be immediate (user already logged in): only the steps to log in, copy the URL from the browser and paste it are displayed.
|
|
4275
|
+
|
|
4276
|
+
3. On the workstation, run this command.
|
|
4277
|
+
The first time for a login host, `ascli` displays the host of the login page, and asks to trust it (`yes`): it opens a URL that comes from another system.
|
|
4278
|
+
Trusted hosts are saved; without a terminal, an unknown host is refused.
|
|
4279
|
+
`ascli` then opens the browser on the login page and listens on `redirect_uri`.
|
|
4280
|
+
4. Log in. The browser shows a page "Login Complete" with the code to paste, hidden by default:
|
|
4281
|
+
- The button **Copy** puts the code in the clipboard.
|
|
4282
|
+
- The **eye** button shows or hides the code, to select it manually.
|
|
4283
|
+
5. Paste the code in the terminal of the server (nothing is displayed). `ascli` on the server checks the `state`, and the flow continues as described above, from step 6.
|
|
4284
|
+
|
|
4285
|
+
The command on the workstation:
|
|
4286
|
+
|
|
4287
|
+
- accepts only a login page in `https`, and a `redirect_uri` on a loopback address; the host shown for confirmation is the one of the URL, not a label given in the code;
|
|
4288
|
+
- is available only at security level `low`;
|
|
4289
|
+
- ends once the browser has received the page with the code; the port of `redirect_uri` shall be free on the workstation (the URL is registered for the login and cannot be changed);
|
|
4290
|
+
- gives to the server only the parameters it needs (the `code` and the `state`).
|
|
4291
|
+
|
|
4292
|
+
The codes are compressed and encrypted with a key that is not secret (derived from a constant and the current time, in slots of 15 minutes): they are hard to read and are valid for 15 to 30 minutes (the clocks of both computers must be correct), but they are **not confidential**: do not keep them, nor send them. The code shown by Shares also uses the random `state` of the login in its key.
|
|
4293
|
+
The codes are authenticated: a code that is incomplete, mistyped or modified is detected.
|
|
4294
|
+
Spaces and line breaks are ignored (letter case matters): a code displayed on several lines can be pasted.
|
|
4295
|
+
|
|
4296
|
+
##### Without `ascli` on the workstation
|
|
4297
|
+
|
|
4298
|
+
If `ascli` is not installed on the workstation, the URL of the error page is used:
|
|
4299
|
+
|
|
4300
|
+
1. In the SSH session, run the command with `--ui=terminal --ui.web_auth=paste`.
|
|
4301
|
+
2. Copy the displayed login URL in the browser of the workstation, and log in.
|
|
4302
|
+
3. The browser is redirected to `redirect_uri` (for example `http://localhost:12345/?code=...&state=...`) and shows a connection error: this is expected.
|
|
4303
|
+
4. Copy the full URL from the address bar of the browser, and paste it in the terminal (nothing is displayed, as it contains a code or tokens).
|
|
4304
|
+
The query alone (`code=...&state=...`) is also accepted.
|
|
4305
|
+
The `state` is mandatory: it is checked like in the standard flow, then the flow continues from step 6.
|
|
4306
|
+
|
|
4307
|
+
Both ways accept, at the prompt, the code, the URL or the query.
|
|
4308
|
+
If standard input is not a terminal, the line is read from it.
|
|
4309
|
+
The size of a pasted line may be limited by the terminal: the code of the reply contains only what is needed.
|
|
4310
|
+
|
|
4311
|
+
Notes:
|
|
4312
|
+
|
|
4313
|
+
- For Shares with `--auth=web`, `paste` is simpler: Shares itself displays the code, so neither the tunnel, nor `ascli config web_login`, nor the URL of the error page is used (see [Authentication of SAML users](#authentication-of-saml-users)).
|
|
4314
|
+
- The port must be free on the workstation.
|
|
4315
|
+
To use another port, change it in the tunnel and in `--redirect-uri`, for example `--redirect-uri=http://localhost:23456` and `-L 127.0.0.1:23456:127.0.0.1:23456`.
|
|
4316
|
+
For Aspera on Cloud, this `redirect_uri` shall also be declared in the API client (see [API Client Registration](#api-client-registration)).
|
|
4317
|
+
- The tunnel listens on `127.0.0.1`: if the browser resolves `localhost` to `::1`, use `--redirect-uri=http://127.0.0.1:12345`.
|
|
4318
|
+
- On Windows, `ssh` is the OpenSSH client provided with the system; with PuTTY, add a local port forwarding (Connection → SSH → Tunnels) from `127.0.0.1:12345` to `127.0.0.1:12345`.
|
|
4319
|
+
- Another solution is X11 forwarding: run an X server on the workstation (for example `VcXsrv` or X410 on Windows) and connect with `ssh -X`.
|
|
4320
|
+
The browser then runs on the server and is displayed on the workstation, so no tunnel is needed.
|
|
4321
|
+
It is heavier (X server to install, slower display), and the browser is the one of the server.
|
|
4322
|
+
- Without interaction (automation), prefer a method that needs no browser, such as `--auth=jwt` for Aspera on Cloud.
|
|
3751
4323
|
|
|
3752
4324
|
### Logging, Debugging
|
|
3753
4325
|
|
|
@@ -3755,11 +4327,11 @@ The gem is equipped with traces, mainly for debugging and learning APIs.
|
|
|
3755
4327
|
The composite option `log` groups all logging parameters (use `--log=help` to display this schema):
|
|
3756
4328
|
|
|
3757
4329
|
| Field | Type | Description |
|
|
3758
|
-
|
|
3759
|
-
| `format` | `String` | Log line formatter. Use `@ruby:` for a custom lambda.<br/>Allowed values: `default`, `caller`, `standard`.<br/>Default: `default`. |
|
|
3760
|
-
| `level` | `String` | Minimum log level displayed.<br/>Allowed values: `trace2`, `trace1`, `debug`, `info`, `warn`, `error`, `fatal`, `unknown`.<br/>Default: `warn`. |
|
|
4330
|
+
| ------- | ------------ | ------------------------------------------------------------------------- |
|
|
4331
|
+
| `format` | `Enum[String]` | Log line formatter. Use `@ruby:` for a custom lambda.<br/>Allowed values: `default`, `caller`, `standard`.<br/>Default: `default`. |
|
|
4332
|
+
| `level` | `Enum[String]` | Minimum log level displayed.<br/>Allowed values: `trace2`, `trace1`, `debug`, `info`, `warn`, `error`, `fatal`, `unknown`.<br/>Default: `warn`. |
|
|
3761
4333
|
| `secrets` | `Bool` | Show passwords and secrets in logs.<br/>Default: `false`. |
|
|
3762
|
-
| `type` | `String` | Log output destination.<br/>Allowed values: `stderr`, `stdout`, `syslog`.<br/>Default: `stderr`. |
|
|
4334
|
+
| `type` | `Enum[String]` | Log output destination.<br/>Allowed values: `stderr`, `stdout`, `syslog`.<br/>Default: `stderr`. |
|
|
3763
4335
|
|
|
3764
4336
|
> [!TIP]
|
|
3765
4337
|
> Individual options `log_level`, `log_format`, `logger`, and `log_secrets` are also available as aliases for `log.level`, `log.format`, `log.type`, and `log.secrets` respectively.
|
|
@@ -3840,7 +4412,7 @@ To disable this warning, set the option `warn_insecure` to `no`.
|
|
|
3840
4412
|
HTTP connection parameters (not `ascp` WSS) can be adjusted using option `http_options`:
|
|
3841
4413
|
|
|
3842
4414
|
| Field | Type | Description |
|
|
3843
|
-
|
|
4415
|
+
| ----------------------- | ------------- | -------------------------------------------------------------------------------- |
|
|
3844
4416
|
| `download_partial_suffix` | `String` | File suffix appended to the target filename while a download is in progress. (Rest)<br/>Default: `.http_partial`. |
|
|
3845
4417
|
| `keep_alive_timeout` | `Number` | Maximum time in seconds to keep an idle persistent connection open. (Net::HTTP)<br/>Default: `2`. |
|
|
3846
4418
|
| `open_timeout` | `Number` | Maximum time in seconds to wait for a connection to be established. (Net::HTTP)<br/>Default: `60`. |
|
|
@@ -3993,7 +4565,7 @@ Or, alternatively, (prefer transfer spec like above, generally):
|
|
|
3993
4565
|
|
|
3994
4566
|
By default, it uses the `direct` agent, which is a local `ascp`.
|
|
3995
4567
|
Nevertheless, `ascli` does not come with `ascp` installed.
|
|
3996
|
-
This is the reason why it is advised to install the Aspera Transfer Daemon during installation (`ascli
|
|
4568
|
+
This is the reason why it is advised to install the Aspera Transfer Daemon during installation (`ascli transferd install`).
|
|
3997
4569
|
|
|
3998
4570
|
By default, `ascli` uses the `ascp` binary found in **well known locations**, that is, typical Aspera product installation paths.
|
|
3999
4571
|
|
|
@@ -4002,7 +4574,7 @@ It provides the following commands for `ascp` sub-command:
|
|
|
4002
4574
|
|
|
4003
4575
|
- `show` : Show the path of `ascp` used
|
|
4004
4576
|
- `info` : Show information on `ascp` and its environment
|
|
4005
|
-
- `install` : Install the Transfer SDK (same as `
|
|
4577
|
+
- `install` : Install the Transfer SDK (deprecated, same as `transferd install`)
|
|
4006
4578
|
- `spec` : List transfer spec parameters supported by `ascp`
|
|
4007
4579
|
- `schema` : Show the JSON schema of the transfer spec
|
|
4008
4580
|
- `errors` : List known `ascp` errors and whether they are retry-able
|
|
@@ -4011,7 +4583,7 @@ It provides the following commands for `ascp` sub-command:
|
|
|
4011
4583
|
#### Selection of `ascp` location for [`direct`](#agent-direct) agent
|
|
4012
4584
|
|
|
4013
4585
|
Option: `sdk_folder` is used to specify the location of `ascp`.
|
|
4014
|
-
By default, `ascli` uses `ascp` from the Transfer SDK installed in its configuration folder (see `
|
|
4586
|
+
By default, `ascli` uses `ascp` from the Transfer SDK installed in its configuration folder (see `transferd install`).
|
|
4015
4587
|
|
|
4016
4588
|
To override and use an alternate `ascp` path, use option `sdk_folder` (`--sdk-folder=`).
|
|
4017
4589
|
|
|
@@ -4099,7 +4671,7 @@ The following agents are supported and selected with option `transfer`:
|
|
|
4099
4671
|
|----------|----------|-------------------------------|
|
|
4100
4672
|
| [`direct`](#agent-direct) | local | direct execution of `ascp` |
|
|
4101
4673
|
| [`transferd`](#agent-transfer-daemon) | local | Aspera Transfer Daemon |
|
|
4102
|
-
| [`connect`](#agent-connect-client) | local | Aspera Connect Client
|
|
4674
|
+
| [`connect`](#agent-connect-client) | local | Aspera Connect Client (to be deprecated in 2027, use `desktop`) |
|
|
4103
4675
|
| [`desktop`](#agent-desktop-client) | local | Aspera for Desktop |
|
|
4104
4676
|
| [`node`](#agent-node-api) | remote | Aspera Transfer Node |
|
|
4105
4677
|
| [`httpgw`](#agent-http-gateway) | remote | Aspera HTTP Gateway |
|
|
@@ -4154,15 +4726,18 @@ ascli server download /remote/big-file.bin --to-folder=/tmp \
|
|
|
4154
4726
|
'--transfer=@json:{"agent":"desktop","asynchronous":true}'
|
|
4155
4727
|
|
|
4156
4728
|
# Poll status later
|
|
4157
|
-
ascli config
|
|
4729
|
+
ascli config agents jobs status <job_id>
|
|
4158
4730
|
|
|
4159
4731
|
# List all pending/completed async transfers
|
|
4160
|
-
ascli config
|
|
4732
|
+
ascli config agents jobs list
|
|
4161
4733
|
|
|
4162
4734
|
# Remove completed/failed entries
|
|
4163
|
-
ascli config
|
|
4735
|
+
ascli config agents jobs cleanup
|
|
4164
4736
|
```
|
|
4165
4737
|
|
|
4738
|
+
> [!NOTE]
|
|
4739
|
+
> `config transfer` (`list`, `status`, `cleanup`) is deprecated after 4.28.0: use `config agents jobs`. It still works, with a warning.
|
|
4740
|
+
|
|
4166
4741
|
All transfer agents support asynchronous mode:
|
|
4167
4742
|
|
|
4168
4743
|
| Agent | Status source | Persisted across restart |
|
|
@@ -4176,16 +4751,16 @@ All transfer agents support asynchronous mode:
|
|
|
4176
4751
|
|
|
4177
4752
|
For `direct` and `httpgw`, the transfer runs as a Ruby thread inside the `ascli` process.
|
|
4178
4753
|
The `job_id` is persisted on disk but the live thread state is only available as long as the same process is running.
|
|
4179
|
-
If the process is restarted, `config
|
|
4754
|
+
If the process is restarted, `config agents jobs status` returns `unknown` for those jobs.
|
|
4180
4755
|
|
|
4181
|
-
Parameters of the agent are persisted, except secrets (e.g. `password` of agent `node`): `config
|
|
4756
|
+
Parameters of the agent are persisted, except secrets (e.g. `password` of agent `node`): `config agents jobs status` takes them from the current `transfer` option, if it is for the same agent (e.g. same option on command line, or in a preset).
|
|
4182
4757
|
|
|
4183
4758
|
> [!NOTE]
|
|
4184
4759
|
> **`asynchronous` and MCP** - When `ascli` is used as an MCP server, an AI assistant calling
|
|
4185
4760
|
> a transfer command may time out or cancel the request and retry, causing duplicate transfers.
|
|
4186
4761
|
> Using `asynchronous: true` eliminates this risk: the transfer is submitted immediately,
|
|
4187
4762
|
> the `job_id` is returned, and the AI can poll
|
|
4188
|
-
> `config
|
|
4763
|
+
> `config agents jobs status <job_id>` to track progress without any risk of duplication.
|
|
4189
4764
|
> This works with all agents, including `direct` and `httpgw`.
|
|
4190
4765
|
|
|
4191
4766
|
#### Agent: Direct
|
|
@@ -4200,18 +4775,18 @@ See [FASP](#fasp-configuration).
|
|
|
4200
4775
|
The `transfer` option accepts the following optional parameters to control multi-session, Web Socket Session, Resume policy and add any argument to `ascp`:
|
|
4201
4776
|
|
|
4202
4777
|
| Field | Type | Description |
|
|
4203
|
-
|
|
4778
|
+
| -------------------- | ------------- | -------------------------------------------------------------------------------- |
|
|
4204
4779
|
| `ascp_args` | `Array[String]` | List of native `ascp` command-line arguments.<br/>Default: `[]`. |
|
|
4205
|
-
| `client_ssh_key` | `String` | SSH key type to use for token-based transfers.<br/>Allowed values: `rsa`, `dsa_rsa`, `per_client`.<br/>Default: `rsa`. |
|
|
4780
|
+
| `client_ssh_key` | `Enum[String]` | SSH key type to use for token-based transfers.<br/>Allowed values: `rsa`, `dsa_rsa`, `per_client`.<br/>Default: `rsa`. |
|
|
4206
4781
|
| `file_list` | `Bool` | If `true`, source paths are written to a temp file passed to `ascp` via `--file-list` or `--file-pair-list`.<br/>If `false`, source paths are placed directly on the `ascp` command line.<br/>Default: `true`. |
|
|
4207
4782
|
| `monitor` | `Bool` | Enable use of the `ascp` management port for transfer monitoring.<br/>Default: `true`. |
|
|
4208
4783
|
| `multi_incr_udp` | `Bool` | Multi session - Increment UDP port for each session.<br/>If `true`, each session uses a different UDP port starting at `fasp_port` (default: 33001).<br/>If `false`, all sessions use the same `fasp_port` (or `ascp` default).<br/>Default: `true` on Windows, `false` on other platforms. |
|
|
4209
4784
|
| `quiet` | `Bool` | Suppress the `ascp` progress bar display.<br/>If `false`, the progress bar of option `progress_bar` is not displayed, unless that option is set.<br/>Default: `true`. |
|
|
4785
|
+
| `resume` | `Hash` | Configuration for automatic transfer resume on interruption. |
|
|
4210
4786
|
| `resume.iter_max` | `Integer` | Maximum number of retry attempts on error.<br/>Default: `7`. |
|
|
4211
4787
|
| `resume.sleep_factor` | `Integer` | Multiplier applied to sleep duration between consecutive retry attempts.<br/>Default: `2`. |
|
|
4212
4788
|
| `resume.sleep_initial` | `Integer` | Initial sleep duration (in seconds) before first retry.<br/>Default: `2`. |
|
|
4213
4789
|
| `resume.sleep_max` | `Integer` | Maximum sleep duration (in seconds) between retry attempts.<br/>Default: `60`. |
|
|
4214
|
-
| `resume` | `Hash` | Configuration for automatic transfer resume on interruption. |
|
|
4215
4790
|
| `spawn_delay_sec` | `Number` | Multi session - Delay (in seconds) between starting each `ascp` session.<br/>Default: `2`. |
|
|
4216
4791
|
| `spawn_timeout_sec` | `Number` | Multi session - Maximum time (in seconds) to verify that `ascp` is running.<br/>Default: `2`. |
|
|
4217
4792
|
| `trusted_certs` | `Array[String]` | List of trusted certificate repositories. |
|
|
@@ -4252,6 +4827,12 @@ The list of known protocol errors and retry level can be listed:
|
|
|
4252
4827
|
ascli config ascp errors
|
|
4253
4828
|
```
|
|
4254
4829
|
|
|
4830
|
+
Error codes of sessions (`errcode` in `ascp` logs) are a different numbering, listed with their category and the corresponding error above:
|
|
4831
|
+
|
|
4832
|
+
```shell
|
|
4833
|
+
ascli config ascp errors session
|
|
4834
|
+
```
|
|
4835
|
+
|
|
4255
4836
|
Examples:
|
|
4256
4837
|
|
|
4257
4838
|
```shell
|
|
@@ -4270,6 +4851,104 @@ This is useful to debug if a transfer fails.
|
|
|
4270
4851
|
|
|
4271
4852
|
To store `ascp` logs in file `aspera-scp-transfer.log` in a folder, use `--transfer=@json:'{"ascp_args":["-L","/path/to/folder"]}'`.
|
|
4272
4853
|
|
|
4854
|
+
To analyze `ascp` log files (`ascp` 4.0 and later), give log files, or folders with log files, to `config ascp logs`:
|
|
4855
|
+
|
|
4856
|
+
```shell
|
|
4857
|
+
ascli config ascp logs summary /path/to/folder
|
|
4858
|
+
ascli config ascp logs sessions /path/to/folder/aspera-scp-transfer.log
|
|
4859
|
+
```
|
|
4860
|
+
|
|
4861
|
+
| Command | Result |
|
|
4862
|
+
|---------------------|-----------------------------------------------------------------|
|
|
4863
|
+
| `summary` | Statistics of sessions, errors by category, maximum throughput, findings. |
|
|
4864
|
+
| `health` | Health check for monitoring in Nagios format (failed sessions and low efficiency over last N minutes). |
|
|
4865
|
+
| `sessions` | One row per session, with diagnostics. |
|
|
4866
|
+
| `diagnostics` | One row per diagnostic of a session: `id`, `severity` (`error`, `warning`, `info`), `message` and `recommendation` (action to take, when the diagnostic has one). |
|
|
4867
|
+
| `multi_sessions` | Multi-session transfers: sessions grouped by transfer, with aggregate rate. |
|
|
4868
|
+
| `snapshots` | Aggregate rates per period. |
|
|
4869
|
+
| `snapshot_sessions` | Rates of each session per period. |
|
|
4870
|
+
| `peers` | Sessions and errors by peer address. |
|
|
4871
|
+
| `transfers` | Transferred files. |
|
|
4872
|
+
| `licenses` | Licenses of local and peer systems. |
|
|
4873
|
+
| `overdrives` | Sessions with loss due to overdriving of network or storage. |
|
|
4874
|
+
| `records` | Log lines parsed into records: `samples`, `sessions` or `transfers` (see below). |
|
|
4875
|
+
| `fields` | Description of the fields of records: `samples`, `sessions` or `transfers`. |
|
|
4876
|
+
|
|
4877
|
+
Log files compressed with gzip (e.g. rotations `aspera.log-20261101.gz`, `aspera-scp-transfer.1.log.gz`) are read directly, in a folder or given as argument; gzip is detected from the first bytes of the file, not from its name. Argument `-` reads the logs from the standard input, plain or compressed with gzip:
|
|
4878
|
+
|
|
4879
|
+
```shell
|
|
4880
|
+
ascli config ascp logs summary /var/log/aspera.log-20261101.gz
|
|
4881
|
+
zcat /var/log/aspera.log-2026*.gz | ascli config ascp logs summary -
|
|
4882
|
+
```
|
|
4883
|
+
|
|
4884
|
+
To analyze the logs of an HSTS read over SSH, instead of files of the local machine, use command `logs` of the plugin [`server`](#analyze-ascp-logs-of-the-server).
|
|
4885
|
+
|
|
4886
|
+
A file must contain `ascp` log lines (`FASP` messages, or lines of process `ascp` in syslog): in a folder, other files are ignored; a file given as argument that is not an `ascp` log is refused.
|
|
4887
|
+
|
|
4888
|
+
When logs of both sides of a session are analyzed (client and server), each session includes the status, error and diagnostics of the other side (`peer_side`, `peer_diagnostics`).
|
|
4889
|
+
|
|
4890
|
+
For example, to list only errors:
|
|
4891
|
+
|
|
4892
|
+
```shell
|
|
4893
|
+
ascli config ascp logs diagnostics /path/to/folder --select=@json:'{"severity":"error"}'
|
|
4894
|
+
```
|
|
4895
|
+
|
|
4896
|
+
Besides the default columns, `sessions` rows have context columns to filter sessions (show them with `--fields=ALL`, or select with `--fields=session,product_name,transport,authentication`, or filter with `--select`/`--query`); a column is absent when the log does not give it:
|
|
4897
|
+
|
|
4898
|
+
| Column | Value |
|
|
4899
|
+
|------------------|--------------------------------------------------------------------------------------------------------------------|
|
|
4900
|
+
| `product_name` | Product that wrote the log, from the line `<product> version <version>` (e.g. `Aspera High-Speed Transfer Server`, `Aspera Transfer SDK`, `Aspera Connect`), without `IBM`. |
|
|
4901
|
+
| `transport` | `ssh` if `Session Start` has `tcp_port`, `wss` if it has `wss_port`. |
|
|
4902
|
+
| `authentication` | `token` if `ascp` logs that `ASPERA_AUTH_TOKEN` is set, else `node` if it logs the storage of a node access key. Never the token, the access key or the storage root. |
|
|
4903
|
+
| `proxy` | Address of the proxy (`proxy_ip` of `Session Params`), absent if there is none. |
|
|
4904
|
+
| `fips` | `true` or `false` (`fips_enabled` of `Session Params`). |
|
|
4905
|
+
|
|
4906
|
+
Diagnostics of a session include: category of error (e.g. `udp_setup`, `storage`, `authentication`) with a hint, retry of a failed session, parameters set by the server (cipher, resume policy, virtual link), efficiency and loss of control messages, decline of the rate during the transfer (`rate_decline`: second half of the samples below 70% of the first half, not evaluated if the peer changes the rate, if another transfer session starts meanwhile, or if the session failed), and for a sender, which limit of the receiver (network, disk, virtual link) or reading from storage limits the rate. Other diagnostics: no packet received for some seconds, by the receiver (`reception_interruption`) or by the sender, which gets no feedback of the receiver (`feedback_interruption`); overflow of the retransmission timer (`rex_timer_overflow`: the retransmission RTT is very large); maximum rate of the license of `ascp` below the target rate (`license_rate_limit`); license that expires within `license_expiry_days` (default `30`) of the start of the session, or has expired (`license_expiry`); and many small files transferred (`small_files`): at least `small_files_min_count` (default 100) files with a mean size below `small_files_max_mean` (default 1 MB); path MTU measured by `ascp` below `small_mtu_max` (default 1400, `ascp` measures 1492, 1006, 508 or 296), which suggests a VPN or a tunnel (`small_mtu`). Two configuration messages, which have no effect on the transfer, are not diagnostics but only appear in `findings` of `summary`: OpenSSL modules folder not found (`ossl-modules not found`), and a schedule of virtual link capacity that could not be registered (`unable to submit change event`).
|
|
4907
|
+
|
|
4908
|
+
The `recommendation` of a diagnostic is only in the list `diagnostics` (not in `sessions`, where `diagnostics` is a list of messages, and not in `summary`): it tells what to check or change, with the `ascp` options and `aspera.conf` parameters concerned (e.g. UDP port and firewalls, target and minimum rate, storage write, SSH). Diagnostics without action (e.g. information, or cancelled by the user) have no `recommendation`; the diagnostic of the category of a failed session gives its hint in `message`.
|
|
4909
|
+
|
|
4910
|
+
Option `ascp_logs` (dot-notation) sets `period` (snapshot period in minutes, default `1`), `zero_bytes` (include sessions without transferred bytes), `mtu` (when not found in logs), `resolve` (host names of peers), `timezone`, `health_minutes` (window in minutes for health check command, default `60`), `remote_max_size` (maximum total size in bytes of the log files read from a server with [`server logs`](#analyze-ascp-logs-of-the-server), default `268435456`), and `thresholds` (diagnostic thresholds, including `rate_decline_ratio`, `rate_decline_min_samples`, `rate_decline_delay`, `rate_decline_end_fraction`, `license_expiry_days`, `small_files_min_count`, `small_files_max_mean` and `small_mtu_max`), e.g. `--ascp-logs.period=5` or `--ascp-logs.thresholds.efficiency=95`.
|
|
4911
|
+
|
|
4912
|
+
Times of log lines are read in the time zone of the analyst, and displayed in it. To read the log of another system without shifting it, set the time zone of the log with `timezone`: `UTC` or an offset `+HH:MM`, e.g. `--ascp-logs.timezone=+02:00`. Syslog lines (`Oct 25 00:02:20`) have no year: it is deduced from the modification date of the log file (the current date for the standard input), the log being before this date. So a log from December to January, analyzed in March, has its December lines in the previous year. Keep the modification date of the file when copying it (e.g. `cp -p`, `scp -p`).
|
|
4913
|
+
|
|
4914
|
+
Command `records` gives the log lines parsed into records, with the field names of the log lines, to filter them with `--out.query` (JMESPath):
|
|
4915
|
+
|
|
4916
|
+
| Record | Log lines |
|
|
4917
|
+
|-------------|-------------------------------------------------------------------------------------------------|
|
|
4918
|
+
| `samples` | `Receiver bl` or `Sender bl` line, with the `DS Qs` line that follows it in field `DS`. |
|
|
4919
|
+
| `sessions` | `Session Start`, `Session Params`, `Session Stop` and `Session Statistics` lines of a session, and lines of the process about it (see below). |
|
|
4920
|
+
| `transfers` | `Transfer Start` and `Transfer Stop` lines of a file. |
|
|
4921
|
+
|
|
4922
|
+
A group of a log line becomes an object: for example, `rate t/m/c/n/vl/vr/r=...` becomes `rate.t`, `rate.m`, `rate.c`, etc.
|
|
4923
|
+
Values are numbers when the log value is a number: rates in bps, durations in ms, s or µs, and percentages without `%`.
|
|
4924
|
+
`Session Stop` and `Transfer Stop` have the fields of `Session Start` and `Transfer Start`, with their final values.
|
|
4925
|
+
When several log files are read, field `log_file` gives the log file of each record.
|
|
4926
|
+
Field `cookie` of `Session Params` is never output.
|
|
4927
|
+
|
|
4928
|
+
A session record also has the fields of these lines of the process (`ascp`), when the log has them:
|
|
4929
|
+
|
|
4930
|
+
| Field | Log line |
|
|
4931
|
+
|----------------------------------------------------------------|-------------------------------------------------------------------------------------------------------|
|
|
4932
|
+
| `fasp_version`, `license_max_rate`, `license_expires` | `Initializing FASP version <version>, license expires on <date>, max rate=<N> Mbps, ...`: `license_max_rate` (bps) and `license_expires` are absent if the license is unlimited or has no expiry date. `account no.` and `license no.` are never output. |
|
|
4933
|
+
| `pMTU`, `start_brtt` | `Measured pMTU: <N> Bytes, start_brtt: <N> ms`. |
|
|
4934
|
+
| `datagram_size`, `block_size`, `path_mtu` | `datagram size <N>B, block size <N>B, path MTU <N>B` (no `path_mtu` in old versions). |
|
|
4935
|
+
| `peer_rate_params` | List of `Peer requested rate params adopted` lines, in the order of the log: `time`, `target_rate`, `min_rate` and `transfer_policy` of each change. |
|
|
4936
|
+
|
|
4937
|
+
For example, samples where the calculated rate is lower than the target rate, and sessions with loss of control messages from the receiver:
|
|
4938
|
+
|
|
4939
|
+
```shell
|
|
4940
|
+
ascli config ascp logs records samples /path/to/aspera-scp-transfer.log --out.query='[?rate.c < rate.t].{time: time, session: uuid, calculated: rate.c, network: rate.n, lost: bl2.l}'
|
|
4941
|
+
ascli config ascp logs records sessions /path/to/folder --out.query='[?rcvr_ctl.lost_pct > `1`]'
|
|
4942
|
+
```
|
|
4943
|
+
|
|
4944
|
+
Command `fields` gives the type and description (with unit) of each field of a kind of record (`samples`, `sessions` or `transfers`), with its path as used in `--out.query` (e.g. `rate.c`):
|
|
4945
|
+
|
|
4946
|
+
```shell
|
|
4947
|
+
ascli config ascp logs fields samples
|
|
4948
|
+
ascli config ascp logs fields sessions
|
|
4949
|
+
ascli config ascp logs fields transfers
|
|
4950
|
+
```
|
|
4951
|
+
|
|
4273
4952
|
> [!NOTE]
|
|
4274
4953
|
> When transfer agent [`direct`](#agent-direct) is used, the list of files to transfer is provided to `ascp` using either `--file-list` or `--file-pair-list` and a temp file list, unless `--file-list` or `--file-pair-list` is already provided via `transfer` parameter `ascp_args`.
|
|
4275
4954
|
> To place source paths directly on the `ascp` command line instead of using a temp file, set `file_list` to `false` in `transfer`: `--transfer.file_list=false`.
|
|
@@ -4451,6 +5130,10 @@ So, for example:
|
|
|
4451
5130
|
|
|
4452
5131
|
#### Agent: Connect Client
|
|
4453
5132
|
|
|
5133
|
+
> **Note:** IBM Aspera Connect will be deprecated in 2027.
|
|
5134
|
+
> Use [IBM Aspera for Desktop](#agent-desktop-client) instead: `--transfer=desktop`.
|
|
5135
|
+
> `ascli` displays a warning when the `connect` agent is used.
|
|
5136
|
+
|
|
4454
5137
|
By specifying option: `--transfer=connect`, `ascli` will start transfers using the locally installed **IBM Aspera Connect Client**.
|
|
4455
5138
|
There are no specific parameters for option `transfer`.
|
|
4456
5139
|
|
|
@@ -4467,7 +5150,7 @@ This is especially useful for direct node-to-node transfers.
|
|
|
4467
5150
|
Parameters provided in option `transfer` are:
|
|
4468
5151
|
|
|
4469
5152
|
| Field | Type | Description |
|
|
4470
|
-
|
|
5153
|
+
| -------- | ------ | ------------------------------------------------------------- |
|
|
4471
5154
|
| `password` | `String` | Password, secret, or bearer token.<br/>Required. |
|
|
4472
5155
|
| `root_id` | `String` | Root file ID. Mandatory only when `password` is a bearer token. |
|
|
4473
5156
|
| `url` | `String` | URL of the Node API.<br/>Required. |
|
|
@@ -4499,8 +5182,8 @@ By specifying option: `--transfer=httpgw`, `ascli` will start transfers using th
|
|
|
4499
5182
|
Parameters provided in option `transfer` are:
|
|
4500
5183
|
|
|
4501
5184
|
| Field | Type | Description |
|
|
4502
|
-
|
|
4503
|
-
| `api_version` | `String` | Force use of a specific API version.<br/>Allowed values: `v1`, `v2`.<br/>Default: `v2`. |
|
|
5185
|
+
| ----------------- | ------------ | ------------------------------------------- |
|
|
5186
|
+
| `api_version` | `Enum[String]` | Force use of a specific API version.<br/>Allowed values: `v1`, `v2`.<br/>Default: `v2`. |
|
|
4504
5187
|
| `synchronous` | `Bool` | Wait for acknowledgment after each message.<br/>Default: `false`. |
|
|
4505
5188
|
| `upload_chunk_size` | `Integer` | Size in bytes of each upload chunk.<br/>Default: `64000`. |
|
|
4506
5189
|
| `url` | `String` | URL of the HTTP Gateway.<br/>Required. |
|
|
@@ -4524,7 +5207,9 @@ Set option `transfer` to `transferd`.
|
|
|
4524
5207
|
Options for `transfer` are:
|
|
4525
5208
|
|
|
4526
5209
|
| Field | Type | Description |
|
|
4527
|
-
|
|
5210
|
+
| ------- | ------ | -------------------------------------------------------------------------------- |
|
|
5211
|
+
| `api_key` | `String` | API key of an existing daemon (`start` is `false`) that has `authentication` enabled in its configuration. It is sent in the metadata `api_key` of each call. |
|
|
5212
|
+
| `ca_file` | `String` | Path to the certificate authority file (PEM) that signed the certificate of an existing daemon (`start` is `false`) that has `tls` enabled in its configuration. A self-signed certificate is its own authority. |
|
|
4528
5213
|
| `start` | `Bool` | Start a new daemon instance.<br/>Default: `true`. |
|
|
4529
5214
|
| `stop` | `Bool` | Stop the daemon when `ascli` exits.<br/>Default: `true`. |
|
|
4530
5215
|
| `url` | `String` | Address and port listened by the daemon (e.g. `:55002`). If port is `0`, the daemon listens on a random available port. If no address is given, `127.0.0.1` is used.<br/>Default: `:0`. |
|
|
@@ -4568,6 +5253,165 @@ On Windows the compilation may fail for various reasons (3.1.1):
|
|
|
4568
5253
|
|
|
4569
5254
|
<!-- spellchecker: enable -->
|
|
4570
5255
|
|
|
5256
|
+
#### Transfer Daemon as a system service
|
|
5257
|
+
|
|
5258
|
+
The Transfer Daemon (`transferd`) can run permanently as a `systemd` service, for applications that use an existing daemon (see [Agent: Transfer Daemon](#agent-transfer-daemon), `start` set to `false`).
|
|
5259
|
+
`ascli` installs the SDK, writes the configuration file of the daemon (`/etc/transferd/transferd.json`) and the `systemd` unit, then enables and starts the service.
|
|
5260
|
+
|
|
5261
|
+
Commands are in `transferd service` (plugin [`transferd`](#plugin-transferd-transfer-daemon)):
|
|
5262
|
+
|
|
5263
|
+
| Command | Action |
|
|
5264
|
+
|-------------|--------|
|
|
5265
|
+
| `spec` | Show the schema of the configuration file of the daemon (`transferd.json`). Works on any system. |
|
|
5266
|
+
| `install` | Install the SDK if it is missing, then do `configure`. |
|
|
5267
|
+
| `configure` | Merge the given configuration into the existing file, validate it, write the file and the unit, reload `systemd`, enable and restart the service, and wait until the daemon listens. |
|
|
5268
|
+
| `status` | Show the version, the state of the service, the endpoint and whether it listens. The API key is never shown. |
|
|
5269
|
+
| `uninstall` | Stop and remove the service. With `purge` set to `true` in `service`, also remove the configuration file and the log folder. |
|
|
5270
|
+
| `use` | Switch to an installed version of the SDK and restart the service (see below). |
|
|
5271
|
+
| `versions` | List the installed versions of the SDK (see below). |
|
|
5272
|
+
|
|
5273
|
+
Except `spec` and `versions`, commands take the optional **last** positional argument `CONFIG`: a `Hash` ([Extended Value](#extended-value-syntax)) with two optional sections:
|
|
5274
|
+
|
|
5275
|
+
- `service`: how the service is installed.
|
|
5276
|
+
- `config`: content of `transferd.json`.
|
|
5277
|
+
|
|
5278
|
+
```json
|
|
5279
|
+
{
|
|
5280
|
+
"service": {
|
|
5281
|
+
"user": "asperadaemon"
|
|
5282
|
+
},
|
|
5283
|
+
"config": {
|
|
5284
|
+
"address": "127.0.0.1",
|
|
5285
|
+
"port": 55002,
|
|
5286
|
+
"log_directory": "/var/log/aspera-transferd",
|
|
5287
|
+
"workers": {"max_concurrent": 10},
|
|
5288
|
+
"authentication": {"enabled": true}
|
|
5289
|
+
}
|
|
5290
|
+
}
|
|
5291
|
+
```
|
|
5292
|
+
|
|
5293
|
+
Parameters of section `service`:
|
|
5294
|
+
|
|
5295
|
+
| Field | Type | Description |
|
|
5296
|
+
| ----------- | ------------- | -------------------------------------------------------------------------------- |
|
|
5297
|
+
| `after` | `Array[String]` | Units that shall be started before the daemon (`After=` in the unit).<br/>Default: `["network.target"]`. |
|
|
5298
|
+
| `environment` | `Hash` | Environment variables set in the unit. None is set unless given here. `TRANSFERD_ADDRESS`, `TRANSFERD_PORT`, `TRANSFERD_MGMT_PORT` and `TRANSFERD_MGMT_ADDRESS` override the configuration file. |
|
|
5299
|
+
| `group` | `String` | Group that runs the daemon. Defaults to the primary group of `user`. |
|
|
5300
|
+
| `name` | `String` | Name of the service. The unit file is `<name>.service`.<br/>Default: `aspera-transferd`. |
|
|
5301
|
+
| `purge` | `Bool` | Used by `uninstall`. Also remove the configuration file and the log folder.<br/>Default: `false`. |
|
|
5302
|
+
| `unit_dir` | `String` | Folder where the unit file is created.<br/>Default: `/etc/systemd/system`. |
|
|
5303
|
+
| `user` | `String` | Account that runs the daemon. It must exist, it is not created.<br/>Default: `asperadaemon`. |
|
|
5304
|
+
| `version` | `String` | Version of the SDK to install, used by `install` when the SDK folder is named `current` (versions side by side). Defaults to the SDK version of this tool. |
|
|
5305
|
+
|
|
5306
|
+
Section `config` follows the JSON schema of the daemon, displayed with:
|
|
5307
|
+
|
|
5308
|
+
```shell
|
|
5309
|
+
ascli transferd service spec
|
|
5310
|
+
```
|
|
5311
|
+
|
|
5312
|
+
| Field | Type | Description |
|
|
5313
|
+
| ---------------------------------------- | ------------- | -------------------------------------------------------------------------------- |
|
|
5314
|
+
| `$schema` | `String` | Optional URI or path of this schema, used by editors for completion and validation. Ignored by transferd. |
|
|
5315
|
+
| `address` | `String` | IP address or host name on which the gRPC API listens. Use 0.0.0.0 to listen on all IPv4 interfaces (for example in a container); when not listening on a loopback address, consider enabling tls and authentication. Overridden by environment variable TRANSFERD_ADDRESS, and by option --address (-a), which takes precedence.<br/>Default: `127.0.0.1`.<br/>Example: `127.0.0.1`. |
|
|
5316
|
+
| `api_time_settings` | `Hash` | Keepalive and connection lifetime settings of the gRPC API server, in seconds. |
|
|
5317
|
+
| `api_time_settings.max_conn_age` | `Integer` | Maximum lifetime of a client connection, with a random variation of +/-10%; the client must then reconnect. 0 or omitted: no limit.<br/>Default: `0`.<br/>Example: `3600`. |
|
|
5318
|
+
| `api_time_settings.max_conn_age_grace` | `Integer` | Additional time given to ongoing calls once max_conn_age is reached, before the connection is forcibly closed. 0 or omitted: no limit.<br/>Default: `0`.<br/>Example: `10`. |
|
|
5319
|
+
| `api_time_settings.max_conn_idle` | `Integer` | Time after which a client connection with no ongoing call is closed. 0 or omitted: 86400 (24 hours).<br/>Default: `86400`.<br/>Example: `120`. |
|
|
5320
|
+
| `api_time_settings.time` | `Integer` | Time without activity from a client after which the server pings it to check that the connection is still alive. 0 or omitted: 7200 (2 hours).<br/>Default: `7200`.<br/>Example: `60`. |
|
|
5321
|
+
| `api_time_settings.timeout` | `Integer` | Time the server waits for activity after a keepalive ping before closing the connection. 0 or omitted: 20.<br/>Default: `20`.<br/>Example: `3`. |
|
|
5322
|
+
| `authentication` | `Hash` | API key authentication of clients of the gRPC API. |
|
|
5323
|
+
| `authentication.api_key` | `String` | Value that clients must send in gRPC request metadata entry api_key. It is stored in clear text: restrict read access to this file.<br/>Example: `change-me-to-a-long-random-value`. |
|
|
5324
|
+
| `authentication.enabled` | `Bool` | Requires every call to carry the API key; other calls are rejected with status UNAUTHENTICATED. api_key is then required.<br/>Default: `false`. |
|
|
5325
|
+
| `fasp_management` | `Hash` | Management port on which the ascp processes started by transferd report transfer progress. |
|
|
5326
|
+
| `fasp_management.address` | `String` | IP address on which the management server listens. Change it only when ascp must reach transferd through an interface other than loopback. Overridden by environment variable TRANSFERD_MGMT_ADDRESS, and by option --mgmtaddress (-A), which takes precedence.<br/>Default: `127.0.0.1`.<br/>Example: `127.0.0.1`. |
|
|
5327
|
+
| `fasp_management.port` | `Integer` | TCP port of the management server. 0 or omitted: a free port is selected at startup. Overridden by environment variable TRANSFERD_MGMT_PORT, and by option --mgmtport (-P), which takes precedence.<br/>Default: `0`.<br/>Example: `23456`. |
|
|
5328
|
+
| `fasp_management.promiscuous_mode_enabled` | `Bool` | When true, transferd also reports transfers of ascp processes that it did not start. So that those processes find the management port, transferd writes it in file transferd.<port>.optport of directory ../var/run/aspera, relative to the FASP runtime bin directory. Those ascp processes must use the same FASP runtime as transferd (see fasp_runtime).<br/>Default: `false`. |
|
|
5329
|
+
| `fasp_runtime` | `Hash` | FASP runtime (ascp, async, license, aspera.conf) used for transfers. Omitted: the runtime embedded in the SDK is used. When this section is present, set use_embedded explicitly: if it is not true, user_defined is required. |
|
|
5330
|
+
| `fasp_runtime.extra_config` | `Array[Hash]` | Extra command line options added to the executables started for transfers. Does not apply to async. |
|
|
5331
|
+
| `fasp_runtime.extra_config[].command` | `String` | End of the path of the executable to which options are added, for example ascp (ascp.exe on Windows). Only the first matching entry is used.<br/>Required.<br/>Example: `ascp`. |
|
|
5332
|
+
| `fasp_runtime.extra_config[].options` | `Array[String]` | Options added to the command line, one argument per item, before the transfer arguments.<br/>Example: `["--save-before-overwrite"]`. |
|
|
5333
|
+
| `fasp_runtime.force_version` | `String` | Accepted for backward compatibility. Has no effect. |
|
|
5334
|
+
| `fasp_runtime.log` | `Hash` | Default logging of ascp, for transfers whose request configuration does not set localLog or logLevel. Does not apply to async. |
|
|
5335
|
+
| `fasp_runtime.log.dir` | `String` | Directory where ascp writes its log (ascp option -L). Empty or omitted: default location of ascp.<br/>Example: `/var/log/aspera`. |
|
|
5336
|
+
| `fasp_runtime.log.level` | `Integer` | Level of detail of the ascp log: 0 for basic information (files transferred, transfer rate), 1 to 4 for increasingly detailed debug messages (ascp options -D to -DDDD).<br/>Default: `0`. |
|
|
5337
|
+
| `fasp_runtime.use_embedded` | `Bool` | true: use the FASP runtime embedded in the SDK, and ignore user_defined. false: use the runtime located by user_defined. Omitted while the fasp_runtime section is present: false.<br/>Example: `true`. |
|
|
5338
|
+
| `fasp_runtime.user_defined` | `Hash` | Location of a separately installed FASP runtime. Required when use_embedded is not true, ignored otherwise. Both directories must exist at startup. |
|
|
5339
|
+
| `fasp_runtime.user_defined.bin` | `String` | Directory containing the ascp and async executables. A relative path is resolved from the working directory of transferd.<br/>Required.<br/>Example: `/opt/aspera/bin`. |
|
|
5340
|
+
| `fasp_runtime.user_defined.etc` | `String` | Directory containing the license file aspera-license and the configuration file aspera.conf. A relative path is resolved from the working directory of transferd.<br/>Required.<br/>Example: `/opt/aspera/etc`. |
|
|
5341
|
+
| `log_directory` | `String` | Directory of the transferd log file transferd.log (rotated at 10 MiB, 10 files kept). A relative path is resolved from the directory of the transferd executable. The directory is created if missing. Empty or omitted: logs are written to standard output.<br/>Example: `/var/log/aspera`. |
|
|
5342
|
+
| `log_format` | `Enum[String]` | Format of the transferd log: text for human-readable lines, json for one JSON object per line. Any value other than text gives json.<br/>Allowed values: `text`, `json`.<br/>Default: `text`. |
|
|
5343
|
+
| `log_level` | `Enum[String]` | Level of detail of the transferd log, from most (trace) to least (panic) verbose. Omitted or unrecognized value: info.<br/>Allowed values: `trace`, `debug`, `info`, `warning`, `error`, `fatal`, `panic`.<br/>Default: `info`. |
|
|
5344
|
+
| `port` | `Integer` | TCP port on which the gRPC API listens. 0 or omitted: a free port is selected at startup; it is written in the log and in file transferd.<port>.optport of runtime_dir. The configuration file shipped with the SDK sets 55002. Overridden by environment variable TRANSFERD_PORT, and by option --port (-p), which takes precedence.<br/>Default: `0`.<br/>Example: `55002`. |
|
|
5345
|
+
| `reflection` | `Bool` | Enables the gRPC server reflection service, so that tools such as `grpcurl` or `grpcui` can list and call the API without the transferd.proto file. Useful for debugging; leave disabled otherwise.<br/>Default: `false`. |
|
|
5346
|
+
| `runtime_dir` | `String` | Directory for runtime files. When port is 0, transferd writes the selected port in file transferd.<port>.optport there. Created with owner-only permissions if missing. Omitted: ../var/run/aspera relative to the directory of the transferd executable.<br/>Example: `/var/run/aspera`. |
|
|
5347
|
+
| `tls` | `Hash` | TLS for the gRPC API. When enabled, clients must connect using TLS. |
|
|
5348
|
+
| `tls.certificate` | `String` | Path of the PEM server certificate file, which may include intermediate certificates. A relative path is resolved from the working directory of transferd.<br/>Example: `/etc/transferd/server.crt`. |
|
|
5349
|
+
| `tls.enabled` | `Bool` | Enables TLS. certificate and key are then required.<br/>Default: `false`. |
|
|
5350
|
+
| `tls.key` | `String` | Path of the PEM private key file matching certificate. A relative path is resolved from the working directory of transferd.<br/>Example: `/etc/transferd/server.key`. |
|
|
5351
|
+
| `tls.min_tls_version` | `Enum[String]` | Minimum TLS version accepted from clients. Omitted or other value: TLSv12.<br/>Allowed values: `TLSv12`, `TLSv13`.<br/>Default: `TLSv12`. |
|
|
5352
|
+
| `workers` | `Hash` | Transfer execution and retention. |
|
|
5353
|
+
| `workers.max_concurrent` | `Integer` | Maximum number of transfers running at the same time. Additional transfers wait in a queue until a running one ends. 0 or omitted: 100.<br/>Default: `100`.<br/>Example: `10`. |
|
|
5354
|
+
| `workers.transfer_cleaning_period` | `Integer` | Interval, in seconds, at which transferd removes ended transfers older than transfer_max_age. 0 or omitted: 3600 (1 hour).<br/>Default: `3600`. |
|
|
5355
|
+
| `workers.transfer_max_age` | `Integer` | Time, in seconds, during which an ended transfer remains known to transferd (status queries, events) before it can be removed. Removal happens at the next cleaning, so a transfer may remain up to transfer_max_age + transfer_cleaning_period. 0 or omitted: 7200 (2 hours).<br/>Default: `7200`.<br/>Example: `86400`. |
|
|
5356
|
+
|
|
5357
|
+
The configuration is checked before anything is written:
|
|
5358
|
+
|
|
5359
|
+
- Keys not given keep their value in the existing `transferd.json` (deep merge), and a key set to `null` is removed.
|
|
5360
|
+
- An unknown key, a value of a wrong type, or an inconsistent configuration (for example `tls.enabled` without `certificate` and `key`) is refused, with the name of the key and of the file if the faulty key is in the existing file.
|
|
5361
|
+
The daemon itself ignores unknown keys silently.
|
|
5362
|
+
- The section `fasp_runtime` is computed from the SDK folder, and can be overridden.
|
|
5363
|
+
- If `authentication.enabled` is `true` and no `api_key` is given, the key of the existing file is kept, else a random one is generated.
|
|
5364
|
+
The file is written in clear text with mode `0640`, owner `user:group`.
|
|
5365
|
+
To get the key from the [vault](#secret-vault), write `{"config":{"authentication":{"api_key":"@vault:transferd.api_key@"}}}` in an [Extended Value](#extended-value-syntax) `@json:@extend:'...'`.
|
|
5366
|
+
|
|
5367
|
+
Requirements:
|
|
5368
|
+
|
|
5369
|
+
- `systemd` on Linux only.
|
|
5370
|
+
On other systems, or without `systemctl`, commands fail with a message (only `spec` and `--dry-run` work everywhere).
|
|
5371
|
+
- Run as `root`, except with `--dry-run=yes` (option is a boolean), which shows the actions and the files without any change, and `spec` and `versions`.
|
|
5372
|
+
- The account (`asperadaemon` by default) is **not** created by `ascli`.
|
|
5373
|
+
If it does not exist, the command fails and shows the command to create it:
|
|
5374
|
+
`useradd --system --no-create-home --shell /usr/sbin/nologin asperadaemon`.
|
|
5375
|
+
This is the account used by other Aspera products on the same host, so that files have the same owner.
|
|
5376
|
+
- If the version of the SDK installed is different from the version of the schema, then a warning is displayed (it is not an error).
|
|
5377
|
+
|
|
5378
|
+
Example:
|
|
5379
|
+
|
|
5380
|
+
```shell
|
|
5381
|
+
sudo ascli transferd service install --sdk-folder=/opt/aspera/transferd/current @json:'{"config":{"port":55002,"authentication":{"enabled":true}}}'
|
|
5382
|
+
```
|
|
5383
|
+
|
|
5384
|
+
```shell
|
|
5385
|
+
ascli transferd service configure --dry-run=yes @json:'{"config":{"log_level":"debug"}}'
|
|
5386
|
+
```
|
|
5387
|
+
|
|
5388
|
+
```shell
|
|
5389
|
+
sudo ascli transferd service status
|
|
5390
|
+
```
|
|
5391
|
+
|
|
5392
|
+
```shell
|
|
5393
|
+
sudo ascli transferd service uninstall @json:'{"service":{"purge":true}}'
|
|
5394
|
+
```
|
|
5395
|
+
|
|
5396
|
+
##### Versions side by side and rollback
|
|
5397
|
+
|
|
5398
|
+
If the SDK folder (option `sdk_folder`) is named `current`, e.g. `--sdk-folder=/opt/aspera/transferd/current`, then `ascli` uses the layout `<prefix>/<version>` with a link `current` that points to the version in use:
|
|
5399
|
+
|
|
5400
|
+
```text
|
|
5401
|
+
/opt/aspera/transferd/1.1.9
|
|
5402
|
+
/opt/aspera/transferd/1.1.10
|
|
5403
|
+
/opt/aspera/transferd/current -> 1.1.10
|
|
5404
|
+
```
|
|
5405
|
+
|
|
5406
|
+
- `service install` installs the version given in `service.version` (default: version tested with this release of `ascli`) in `<prefix>/<version>`, and sets the link `current`.
|
|
5407
|
+
If the installation fails, then the link is set back to the previous version.
|
|
5408
|
+
- The unit and `transferd.json` refer to `current`: switching the link and restarting the service is enough to change the version.
|
|
5409
|
+
- `service versions` lists the installed versions and the one in use.
|
|
5410
|
+
- `service use <VERSION>` switches the link and restarts the service.
|
|
5411
|
+
If the service does not start, then the link is set back to the previous version and the service is restarted.
|
|
5412
|
+
|
|
5413
|
+
Any other folder name is used as is, with no link.
|
|
5414
|
+
|
|
4571
5415
|
### Transfer Specification
|
|
4572
5416
|
|
|
4573
5417
|
Some commands lead to file transfer (upload/download).
|
|
@@ -4656,7 +5500,7 @@ The description gives the supported agents, if not all, and the corresponding `a
|
|
|
4656
5500
|
#### Transfer Specification Reference
|
|
4657
5501
|
|
|
4658
5502
|
| ID | Name |
|
|
4659
|
-
|
|
5503
|
+
| -- | --------- |
|
|
4660
5504
|
| A | Direct |
|
|
4661
5505
|
| C | Connect |
|
|
4662
5506
|
| D | Desktop |
|
|
@@ -4665,61 +5509,61 @@ The description gives the supported agents, if not all, and the corresponding `a
|
|
|
4665
5509
|
| T | Transferd |
|
|
4666
5510
|
|
|
4667
5511
|
| Field | Type | Description |
|
|
4668
|
-
|
|
5512
|
+
| ------------------------------ | --------------- | -------------------------------------------------------------------------------- |
|
|
4669
5513
|
| `apply_local_docroot` | `Bool` | Apply local docroot to source paths.<br/>(A, T)<br/>(`--apply-local-docroot`) |
|
|
4670
5514
|
| `authentication` | `String` | Set to `token` for SSH bypass keys, else password asked if not provided.<br/>(C) |
|
|
4671
|
-
| `
|
|
4672
|
-
| `
|
|
5515
|
+
| `cipher` | `Enum[String]` | In transit encryption algorithms.<br/>Allowed values: `none`, `aes-128`, `aes-192`, `aes-256`, `aes-128-cfb`, `aes-192-cfb`, `aes-256-cfb`, `aes-128-gcm`, `aes-192-gcm`, `aes-256-gcm`.<br/>Default: `none`.<br/>(`-c (conversion){enum}`) |
|
|
5516
|
+
| `cipher_allowed` | `Enum[String]` | Returned by node API. Valid literals include `aes-128` and `none`.<br/>Allowed values: `none`, `aes-128`, `aes-192`, `aes-256`, `aes-128-cfb`, `aes-192-cfb`, `aes-256-cfb`, `aes-128-gcm`, `aes-192-gcm`, `aes-256-gcm`.<br/>(C) |
|
|
5517
|
+
| `content_protection` | `Enum[String]` | Enable client-side content protection (CSEAR, encryption-at-rest).<br/>For uploads, set to `encrypt` to transfer encrypted files and store them on the server with the extension `.aspera-env`. (`aspera.conf` parameter `transfer_encryption_content_protection_extension`). To download and decrypt encrypted files, set to `decrypt`<br/>`content_protection_password` must be specified if this option is set.<br/>Allowed values: `encrypt`, `decrypt`.<br/>(`--file-crypt={enum}`) |
|
|
4673
5518
|
| `content_protection_password` | `String` | Password for encryption/decryption of transferred assets.<br/>(env:`ASPERA_SCP_FILEPASS`) |
|
|
4674
|
-
| `content_protection` | `String` | Enable client-side content protection (CSEAR, encryption-at-rest).<br/>For uploads, set to `encrypt` to transfer encrypted files and store them on the server with the extension `.aspera-env`. (`aspera.conf` parameter `transfer_encryption_content_protection_extension`). To download and decrypt encrypted files, set to `decrypt`<br/>`content_protection_password` must be specified if this option is set.<br/>Allowed values: `encrypt`, `decrypt`.<br/>(`--file-crypt={enum}`) |
|
|
4675
5519
|
| `cookie` | `String` | Metadata for transfer specified by application.<br/>(env:`ASPERA_SCP_COOKIE`) |
|
|
4676
5520
|
| `create_dir` | `Bool` | Create target directory if it doesn't already exist.<br/>If **all** the following conditions are met, then the `destination_root` specifies a filename instead of destination folder:<br/>- `create_dir` is `false`<br/>- A single source file is given on **command line**<br/>- The target folder specified by `destination_root` does not exist<br/>In all other cases, `destination_root` specifies a folder, and it is created if it does not already exist. I.e. if **any** of those conditions is met:<br/>- `create_dir` is `true`<br/>- Multiple source files are provided<br/>- List of source files are provided in a file (list or pair), default for Node API and `ascli`.<br/>- The target folder exists<br/>(`-d`) |
|
|
4677
5521
|
| `delete_before_transfer` | `Bool` | Before transfer, delete files that exist at the destination but not at the source.<br/>The source and destination arguments must be directories that have matching names.<br/>Objects on the destination that have the same name but different type or size as objects on the source are not deleted.<br/>(`--delete-before-transfer`) |
|
|
4678
5522
|
| `delete_source` | `Bool` | Remove transferred source files after transfer success. Equivalent to `remove_after_transfer` + `remove_empty_directories` + `remove_empty_source_directory`. Take precedence over those.<br/>(A, N, T) |
|
|
4679
|
-
| `destination_root_id` | `String` | The file ID of the destination root directory.<br/>Required when using Bearer token auth for the destination node.<br/>(T) |
|
|
4680
5523
|
| `destination_root` | `String` | Destination root directory.<br/>Required. |
|
|
5524
|
+
| `destination_root_id` | `String` | The file ID of the destination root directory.<br/>Required when using Bearer token auth for the destination node.<br/>(T) |
|
|
4681
5525
|
| `dgram_size` | `Integer` | UDP datagram size in bytes.<br/>(`-Z {integer}`) |
|
|
4682
|
-
| `direction` | `String` | Direction of transfer (on client side).<br/>Required.<br/>Allowed values: `send`, `receive`.<br/>(`--mode=(conversion){enum}`) |
|
|
5526
|
+
| `direction` | `Enum[String]` | Direction of transfer (on client side).<br/>Required.<br/>Allowed values: `send`, `receive`.<br/>(`--mode=(conversion){enum}`) |
|
|
4683
5527
|
| `exclude_newer_than` | `String` | Exclude files, but not directories, from the transfer if they are newer than the specified number of seconds added to the source computer's epoch.<br/>e.g. `-86400` for newer than a day back.<br/>(`--exclude-newer-than={string}`) |
|
|
4684
5528
|
| `exclude_older_than` | `String` | Exclude files, but not directories, from the transfer if they are older than the specified number of seconds added to the source computer's epoch.<br/>e.g. `-86400` for older than a day back.<br/>(`--exclude-older-than={string}`) |
|
|
4685
5529
|
| `fail_bad_filepass` | `Bool` | Fail on bad file decryption passphrase.<br/>(A, T)<br/>(`--fail-bad-filepass`) |
|
|
4686
5530
|
| `fasp_port` | `Integer` | Specifies fasp (UDP) port.<br/>Default: `33001`.<br/>(`-O {integer}`) |
|
|
4687
5531
|
| `fasp_proxy` | `Hash` | Proxy for communications between the remote server and the (local) client.<br/>(T) |
|
|
4688
|
-
| `file_checksum` | `String` | Enable checksum reporting for transferred files by specifying the hash to use.<br/>Allowed values: `sha-512`, `sha-384`, `sha-256`, `sha1`, `md5`, `none`.<br/>Default: `none`.<br/>(A, N)<br/>(`--file-checksum={enum}`) |
|
|
4689
|
-
| `http_fallback_port` | `Integer` | Specifies HTTP port when no cipher is used.<br/>(`-t {integer}`) |
|
|
5532
|
+
| `file_checksum` | `Enum[String]` | Enable checksum reporting for transferred files by specifying the hash to use.<br/>Allowed values: `sha-512`, `sha-384`, `sha-256`, `sha1`, `md5`, `none`.<br/>Default: `none`.<br/>(A, N)<br/>(`--file-checksum={enum}`) |
|
|
4690
5533
|
| `http_fallback` | `Bool, String` | When true(1), attempts to perform an HTTP transfer if a FASP transfer cannot be performed.<br/>(`-y (conversion){boolean\|string}`) |
|
|
5534
|
+
| `http_fallback_port` | `Integer` | Specifies HTTP port when no cipher is used.<br/>(`-t {integer}`) |
|
|
4691
5535
|
| `https_fallback_port` | `Integer` | Specifies HTTPS port when cipher is used.<br/>(`-t {integer}`) |
|
|
4692
5536
|
| `icos` | `Hash` | Configuration parameters for IBM Cloud Object Storage (ICOS).<br/>(T) |
|
|
4693
5537
|
| `keepalive` | `Bool` | The session is running in persistent session mode.<br/>(A, T)<br/>(`--keepalive`) |
|
|
4694
|
-
| `lock_min_rate_kbps` | `Bool` | If `true`, lock the minimum transfer rate to the value set for min_rate_kbps.<br/>If `false`, users can adjust the transfer rate up to the value set for target_rate_cap_kbps.<br/>(C, T) |
|
|
4695
5538
|
| `lock_min_rate` | `Bool` | n/a<br/>(C) |
|
|
5539
|
+
| `lock_min_rate_kbps` | `Bool` | If `true`, lock the minimum transfer rate to the value set for min_rate_kbps.<br/>If `false`, users can adjust the transfer rate up to the value set for target_rate_cap_kbps.<br/>(C, T) |
|
|
4696
5540
|
| `lock_rate_policy` | `Bool` | If `true`, lock the rate policy to the default value.<br/>(C, T) |
|
|
4697
|
-
| `lock_target_rate_kbps` | `Bool` | If `true`, lock the target transfer rate to the default value set for `target_rate_kbps`.<br/>If `false`, users can adjust the transfer rate up to the value set for `target_rate_cap_kbps`.<br/>(C, T) |
|
|
4698
5541
|
| `lock_target_rate` | `Bool` | n/a<br/>(C) |
|
|
5542
|
+
| `lock_target_rate_kbps` | `Bool` | If `true`, lock the target transfer rate to the default value set for `target_rate_kbps`.<br/>If `false`, users can adjust the transfer rate up to the value set for `target_rate_cap_kbps`.<br/>(C, T) |
|
|
4699
5543
|
| `min_rate_cap_kbps` | `Integer` | The highest minimum rate that an incoming transfer can request, in kilobits per second.<br/>Client minimum rate requests that exceed the minimum rate cap are ignored.<br/>The default value of unlimited applies no cap to the minimum rate. (Default: 0)<br/>(C, T) |
|
|
4700
5544
|
| `min_rate_kbps` | `Integer` | Set the minimum transfer rate in kilobits per second.<br/>Default: `0`.<br/>(`-m {integer}`) |
|
|
4701
5545
|
| `move_after_transfer` | `String` | Move source files to the specified `archive-dir` directory after they are transferred correctly.<br/>Available as of 3.8.0. Details in `ascp` manual.<br/>Requires write permissions on the source.<br/>If `src_base` is specified, files are moved to `archive-dir`/`path-relative-to-srcbase`.<br/>`archive-dir` must be in the same file system (or cloud storage account) as the source files being transferred.<br/>`archive-dir` is subject to the same docroot restrictions as source files.<br/>`move_after_transfer` and `remove_after_transfer` are mutually exclusive options.<br/>After files have been moved to the archive, the original source directory structure is left in place. Empty directories are not saved to `archive-dir`. To remove empty source directories after a successful move operation, also set `remove_empty_directories` to `true`. When using `remove_empty_directories`, empty directory removal examination starts at the `srcbase` and proceeds down any subdirectories. If no `srcbase` is used and a file path (as opposed to a directory path) is specified, then only the immediate parent directory is examined and removed if it is empty following the move of the source file.<br/>(A, N, T)<br/>(`--move-after-transfer={string}`) |
|
|
4702
|
-
| `multi_session_threshold` | `Integer` | Split files across multiple `ascp` sessions if their size in bytes is greater than or equal to the specified value.<br/>(0=no file is split)<br/>(A, N, T)<br/>(`--multi-session-threshold={integer}`) |
|
|
4703
5546
|
| `multi_session` | `Integer` | Use multi-session transfer. max 128.<br/>Each participant on one host needs an independent UDP (-O) port.<br/>Large files are split between sessions only when transferring with `resume_policy`=`none`.<br/>(special:`-C {integer}`) |
|
|
5547
|
+
| `multi_session_threshold` | `Integer` | Split files across multiple `ascp` sessions if their size in bytes is greater than or equal to the specified value.<br/>(0=no file is split)<br/>(A, N, T)<br/>(`--multi-session-threshold={integer}`) |
|
|
4704
5548
|
| `obfuscate_file_names` | `Bool` | HTTP Gateway obfuscates file names when set to `true`.<br/>(H) |
|
|
4705
|
-
| `overwrite` | `String` | Overwrite files at the destination with source files of the same name based on the policy:<br/>- `always` : Always overwrite the file.<br/>- `never` : Never overwrite the file. If the destination contains partial files that are older or the same as the source files and resume is enabled, the partial files resume transfer. Partial files with checksums or sizes that differ from the source files are not overwritten.<br/>- `diff` : (default) Overwrite the file if it is different from the source, depending on the compare method (default is size). If the destination is object storage, `diff` has the same effect as always. If resume is not enabled, partial files are overwritten if they are different from the source, otherwise they are skipped. If resume is enabled, only partial files with different sizes or checksums from the source are overwritten; otherwise, files resume.<br/>- `diff+older` : Overwrite the file if it is older and different from the source, depending on the compare method (default is size). If resume is not enabled, partial files are overwritten if they are older and different from the source, otherwise they are skipped. If resume is enabled, only partial files that are different and older than the source are overwritten, otherwise they are resumed.<br/>- `older` : Overwrite the file if its timestamp is older than the source timestamp.<br/>If you set an overwrite policy of `diff` or `diff+older`, difference is determined by the value set for `resume_policy`:<br/>`none` : The source and destination files are always considered different and the destination file is always overwritten<br/>`attributes` : The source and destination files are compared based on file attributes <br/>`sparse_checksum` : The source and destination files are compared based on sparse checksums, (currently file size)<br/>`full_checksum` : The source and destination files are compared based on full checksums<br/>Allowed values: `never`, `always`, `diff`, `older`, `diff+older`.<br/>Default: `diff`.<br/>(`--overwrite={enum}`) |
|
|
5549
|
+
| `overwrite` | `Enum[String]` | Overwrite files at the destination with source files of the same name based on the policy:<br/>- `always` : Always overwrite the file.<br/>- `never` : Never overwrite the file. If the destination contains partial files that are older or the same as the source files and resume is enabled, the partial files resume transfer. Partial files with checksums or sizes that differ from the source files are not overwritten.<br/>- `diff` : (default) Overwrite the file if it is different from the source, depending on the compare method (default is size). If the destination is object storage, `diff` has the same effect as always. If resume is not enabled, partial files are overwritten if they are different from the source, otherwise they are skipped. If resume is enabled, only partial files with different sizes or checksums from the source are overwritten; otherwise, files resume.<br/>- `diff+older` : Overwrite the file if it is older and different from the source, depending on the compare method (default is size). If resume is not enabled, partial files are overwritten if they are older and different from the source, otherwise they are skipped. If resume is enabled, only partial files that are different and older than the source are overwritten, otherwise they are resumed.<br/>- `older` : Overwrite the file if its timestamp is older than the source timestamp.<br/>If you set an overwrite policy of `diff` or `diff+older`, difference is determined by the value set for `resume_policy`:<br/>`none` : The source and destination files are always considered different and the destination file is always overwritten<br/>`attributes` : The source and destination files are compared based on file attributes <br/>`sparse_checksum` : The source and destination files are compared based on sparse checksums, (currently file size)<br/>`full_checksum` : The source and destination files are compared based on full checksums<br/>Allowed values: `never`, `always`, `diff`, `older`, `diff+older`.<br/>Default: `diff`.<br/>(`--overwrite={enum}`) |
|
|
4706
5550
|
| `password` | `String` | Password for local Windows user when transfer user associated with node API user is not the same as the one running `asperanoded`.<br/>Allows impersonating the transfer user and have access to resources (e.g. network shares).<br/>Windows only, node API only.<br/>(N) |
|
|
4707
5551
|
| `paths` | `Array` | Array of path to the source (required) and a path to the destination (optional).<br/>Required. |
|
|
4708
5552
|
| `precalculate_job_size` | `Bool` | Specifies whether to precalculate the job size.<br/>(`--precalculate-job-size / --precalculate-disable`) |
|
|
4709
5553
|
| `preserve_access_time` | `Bool` | Preserve the source-file access timestamps at the destination.<br/>Because source access times are updated by the transfer operation, the timestamp that is preserved is the one just before to the transfer.<br/>(`--preserve-access-time`) |
|
|
4710
|
-
| `preserve_acls` | `String` | Preserve access control lists.<br/>Allowed values: `none`, `native`, `metafile`.<br/>Default: `none`.<br/>(A, T)<br/>(`--preserve-acls={enum}`) |
|
|
5554
|
+
| `preserve_acls` | `Enum[String]` | Preserve access control lists.<br/>Allowed values: `none`, `native`, `metafile`.<br/>Default: `none`.<br/>(A, T)<br/>(`--preserve-acls={enum}`) |
|
|
4711
5555
|
| `preserve_creation_time` | `Bool` | Preserve source-file creation timestamps at the destination.<br/>Only Windows systems retain information about creation time. If the destination is not a Windows computer, this option is ignored.<br/>(`--preserve-creation-time`) |
|
|
4712
|
-
| `preserve_extended_attrs` | `String` | Preserve the extended attributes.<br/>Allowed values: `none`, `native`, `metafile`.<br/>Default: `none`.<br/>(A, T)<br/>(`--preserve-xattrs={enum}`) |
|
|
5556
|
+
| `preserve_extended_attrs` | `Enum[String]` | Preserve the extended attributes.<br/>Allowed values: `none`, `native`, `metafile`.<br/>Default: `none`.<br/>(A, T)<br/>(`--preserve-xattrs={enum}`) |
|
|
4713
5557
|
| `preserve_file_owner_gid` | `Bool` | Preserve the group ID for a file owner.<br/>(A, T)<br/>(`--preserve-file-owner-gid`) |
|
|
4714
5558
|
| `preserve_file_owner_uid` | `Bool` | Preserve the user ID for a file owner.<br/>(A, T)<br/>(`--preserve-file-owner-uid`) |
|
|
4715
5559
|
| `preserve_modification_time` | `Bool` | Set the modification time, the last time a file or directory was modified (written), of a transferred file to the modification of the source file or directory.<br/>Preserve source-file modification timestamps at the destination.<br/>(`--preserve-modification-time`) |
|
|
4716
|
-
| `preserve_remote_acls` | `String` | Preserve remote access control lists.<br/>Allowed values: `none`, `native`, `metafile`.<br/>Default: `none`.<br/>(A, T)<br/>(`--remote-preserve-acls={enum}`) |
|
|
4717
|
-
| `preserve_remote_extended_attrs` | `String` | Preserve remote extended attributes.<br/>Allowed values: `none`, `native`, `metafile`.<br/>Default: `none`.<br/>(A, T)<br/>(`--remote-preserve-xattrs={enum}`) |
|
|
5560
|
+
| `preserve_remote_acls` | `Enum[String]` | Preserve remote access control lists.<br/>Allowed values: `none`, `native`, `metafile`.<br/>Default: `none`.<br/>(A, T)<br/>(`--remote-preserve-acls={enum}`) |
|
|
5561
|
+
| `preserve_remote_extended_attrs` | `Enum[String]` | Preserve remote extended attributes.<br/>Allowed values: `none`, `native`, `metafile`.<br/>Default: `none`.<br/>(A, T)<br/>(`--remote-preserve-xattrs={enum}`) |
|
|
4718
5562
|
| `preserve_source_access_time` | `Bool` | Preserve the time logged for when the source file was accessed.<br/>(A, T)<br/>(`--preserve-source-access-time`) |
|
|
4719
5563
|
| `preserve_times` | `Bool` | Preserve file timestamps.<br/>(A, N, T)<br/>(`-p`) |
|
|
4720
5564
|
| `proxy` | `String` | Specify the address of the Aspera high-speed proxy server.<br/>`dnat(s)://[user[:password]@]server:port`<br/>Default ports for DNAT and DNATS protocols are 9091 and 9092.<br/>Password, if specified here, overrides the value of environment variable `ASPERA_PROXY_PASS`.<br/>(A)<br/>(`--proxy={string}`) |
|
|
4721
|
-
| `
|
|
4722
|
-
| `
|
|
5565
|
+
| `rate_policy` | `Enum[String]` | The transfer rate policy to use when sharing bandwidth. Allowable values:<br/>- `high` : When sharing bandwidth, transfer at twice the rate of a transfer using a fair policy.<br/>- `fair` : (Default) Share bandwidth equally with other traffic.<br/>- `low` : Use only unused bandwidth.<br/>- `fixed` : Transfer at the target rate, regardless of the actual network capacity. Do not share bandwidth. Aspera recommends that you do not use this setting except under special circumstances, otherwise the destination storage can be damaged.<br/>Allowed values: `low`, `fair`, `high`, `fixed`.<br/>(`--policy={enum}`) |
|
|
5566
|
+
| `rate_policy_allowed` | `Enum[String]` | Specifies most aggressive rate policy that is allowed. Returned by node API.<br/>Allowed values: `low`, `fair`, `high`, `fixed`.<br/>(C) |
|
|
4723
5567
|
| `remote_access_key` | `String` | The access key ID of the access key that was used to construct the bearer token that is used to authenticate to the remote node.<br/>(T) |
|
|
4724
5568
|
| `remote_host` | `String` | IP or fully qualified domain name (FQDN) of the remote server.<br/>Required.<br/>(`--host={string}`) |
|
|
4725
5569
|
| `remote_password` | `String` | SSH session password.<br/>(env:`ASPERA_SCP_PASS`) |
|
|
@@ -4729,27 +5573,27 @@ The description gives the supported agents, if not all, and the corresponding `a
|
|
|
4729
5573
|
| `remove_empty_source_dir` | `Bool` | Remove empty source subdirectories and remove the source directory itself, if empty.<br/>(T) |
|
|
4730
5574
|
| `remove_empty_source_directory` | `Bool` | Remove empty source subdirectories and remove the source directory itself, if empty.<br/>(A)<br/>(`--remove-empty-source-directory`) |
|
|
4731
5575
|
| `remove_skipped` | `Bool` | Must also have `remove_after_transfer` set to `true`. Defaults to `false`. If `true`, skipped files will be removed as well.<br/>(A, C, N)<br/>(`--remove-skipped`) |
|
|
4732
|
-
| `resume_policy` | `String` | If a transfer is interrupted or fails to finish, this policy directs the transfer to resume without retransferring the files. Allowable values:<br/>- `none` : Always re-transfer the entire file.<br/>- `attrs` : Compare file attributes and resume if they match, and re-transfer if they do not.<br/>- `sparse_csum` : Compare file attributes and the sparse file checksums; resume if they match, and re-transfer if they do not.<br/>- `full_csum` : Compare file attributes and the full file checksums; resume if they match, and re-transfer if they do not.<br/>Note: transferd uses values: `attributes`, `sparse_checksum`, `full_checksum`.<br/>Allowed values: `none`, `attrs`, `sparse_csum`, `full_csum`.<br/>Default: `faspmgr:none;other:sparse_csum`.<br/>(`-k (conversion){enum}`) |
|
|
5576
|
+
| `resume_policy` | `Enum[String]` | If a transfer is interrupted or fails to finish, this policy directs the transfer to resume without retransferring the files. Allowable values:<br/>- `none` : Always re-transfer the entire file.<br/>- `attrs` : Compare file attributes and resume if they match, and re-transfer if they do not.<br/>- `sparse_csum` : Compare file attributes and the sparse file checksums; resume if they match, and re-transfer if they do not.<br/>- `full_csum` : Compare file attributes and the full file checksums; resume if they match, and re-transfer if they do not.<br/>Note: transferd uses values: `attributes`, `sparse_checksum`, `full_checksum`.<br/>Allowed values: `none`, `attrs`, `sparse_csum`, `full_csum`.<br/>Default: `faspmgr:none;other:sparse_csum`.<br/>(`-k (conversion){enum}`) |
|
|
4733
5577
|
| `retry_duration` | `Integer, String` | Specifies how long to wait before retrying transfer (e.g. `5min`).<br/>(T) |
|
|
4734
5578
|
| `save_before_overwrite` | `Bool` | If a transfer would result in an existing file <filename>.<ext> being overwritten, move that file to <filename>.yyyy.mm.dd.hh.mm.ss.index.<ext> (where index is set to 1 at the beginning of each new second and incremented for each file saved in this manner during the same second) in the same directory before writing the new file.<br/>File attributes are maintained in the renamed file.<br/>(A, N, T)<br/>(`--save-before-overwrite`) |
|
|
4735
5579
|
| `skip_duplicate_check` | `Bool` | Don't check for duplicate files at the destination.<br/>(A, T)<br/>(`--skip-dir-traversal-dupes`) |
|
|
4736
5580
|
| `skip_special_files` | `Bool` | All assets other than files, directories and symbolic links are considered special. A transfer will fail if the user attempts to transfer special assets. If `true`, `ascp` skips special assets and proceeds with the transfer of all other assets.<br/>(A, T)<br/>(`--skip-special-files`) |
|
|
4737
|
-
| `source_root_id` | `String` | The file ID of the source root directory. Required when using Bearer token auth for the source node.<br/>(N, T) |
|
|
4738
5581
|
| `source_root` | `String` | Path to be prepended to each source path.<br/>This is either a conventional path or it can be a URI but only if there is no root defined.<br/>(`--source-prefix64=(conversion){string}`) |
|
|
4739
|
-
| `
|
|
5582
|
+
| `source_root_id` | `String` | The file ID of the source root directory. Required when using Bearer token auth for the source node.<br/>(N, T) |
|
|
4740
5583
|
| `src_base` | `String` | Specify the prefix to be stripped off from each source object.<br/>The remaining portion of the source path is kept intact at the destination.<br/>Special care must be taken when used with cloud storage.<br/>(A, N, T)<br/>(`--src-base64=(conversion){string}`) |
|
|
5584
|
+
| `src_base64` | `String` | The folder name below which the directory structure is preserved (base64 encoded).<br/>(A, T)<br/>(`--src-base64={string}`) |
|
|
4741
5585
|
| `ssh_args` | `Array` | Add arguments to the command-line arguments passed to the external ssh program (implies -SSH). The arguments are inserted before any key file(s) supplied to `ascp` and before the user/host arguments.<br/>(A, T)<br/>(special:`--ssh-arg={array}`) |
|
|
4742
5586
|
| `ssh_port` | `Integer` | Specifies SSH (TCP) port.<br/>Default: `direct:22, other:33001`.<br/>(`-P {integer}`) |
|
|
5587
|
+
| `ssh_private_key` | `String` | Private key used for SSH authentication.<br/>Shall look like: -----BEGIN RSA PRIV4TE KEY-----\nMII...<br/>Note the JSON encoding: \n for newlines.<br/>(A, T)<br/>(env:`ASPERA_SCP_KEY`) |
|
|
4743
5588
|
| `ssh_private_key_passphrase` | `String` | The passphrase associated with the transfer user's SSH private key. Available as of 3.7.2.<br/>(A, T)<br/>(env:`ASPERA_SCP_PASS`) |
|
|
4744
5589
|
| `ssh_private_key_path` | `String` | Path to private key for SSH.<br/>(A, T)<br/>(`-i {string}`) |
|
|
4745
|
-
| `ssh_private_key` | `String` | Private key used for SSH authentication.<br/>Shall look like: -----BEGIN RSA PRIV4TE KEY-----\nMII...<br/>Note the JSON encoding: \n for newlines.<br/>(A, T)<br/>(env:`ASPERA_SCP_KEY`) |
|
|
4746
5590
|
| `sshfp` | `String` | Check it against server SSH host key fingerprint.<br/>(`--check-sshfp={string}`) |
|
|
4747
|
-
| `symlink_policy` | `String` | Handle source side symbolic links. Refer to HSTS manual for more details.<br/>- `follow`: Follow a symbolic link and transfer the contents of the linked file or directory when the link target is in the user's docroot.<br/>- `copy`: Copy only the symbolic link. If a file with the same name exists at the destination, the symbolic link does not replace the file.<br/>- `skip`: Skip-symbolic links. The link or the file to which it points are not transferred.<br/>- `copy+force`: Copy only the symbolic link. If a file with the same name exists at the destination, the symbolic link replaces the file. If the file of the same name at the destination is a symbolic link to a directory, it is not replaced.<br/>Allowed values: `follow`, `copy`, `copy+force`, `skip`.<br/>Default: `follow`.<br/>(`--symbolic-links={enum}`) |
|
|
4748
|
-
| `tags64` | `String` | Base64 string for `tags`.<br/>(A, T)<br/>(`--tags64={string}`) |
|
|
5591
|
+
| `symlink_policy` | `Enum[String]` | Handle source side symbolic links. Refer to HSTS manual for more details.<br/>- `follow`: Follow a symbolic link and transfer the contents of the linked file or directory when the link target is in the user's docroot.<br/>- `copy`: Copy only the symbolic link. If a file with the same name exists at the destination, the symbolic link does not replace the file.<br/>- `skip`: Skip-symbolic links. The link or the file to which it points are not transferred.<br/>- `copy+force`: Copy only the symbolic link. If a file with the same name exists at the destination, the symbolic link replaces the file. If the file of the same name at the destination is a symbolic link to a directory, it is not replaced.<br/>Allowed values: `follow`, `copy`, `copy+force`, `skip`.<br/>Default: `follow`.<br/>(`--symbolic-links={enum}`) |
|
|
4749
5592
|
| `tags` | `Hash` | Metadata for transfer as JSON. Key `aspera` is reserved. Key `aspera.xfer_retry` specifies a "retry timeout" but is not actually used for node API initiated transfers.<br/>(`--tags64=(conversion){object}`) |
|
|
5593
|
+
| `tags64` | `String` | Base64 string for `tags`.<br/>(A, T)<br/>(`--tags64={string}`) |
|
|
5594
|
+
| `target_rate` | `String, Integer` | Pseudo-parameter: desired transfer rate in bps, with an optional unit suffix. Converted to `target_rate_kbps` (rounded down) before the transfer is started, overriding it if both are present. Also applies to `async` (sync). Accepted formats: integer (bps), or integer followed by `k`/`K` (x1000), `m`/`M` (x1000000), `g`/`G` (x1000000000). Examples: `100000000`, `100000k`, `100m`, `1g`. |
|
|
4750
5595
|
| `target_rate_cap_kbps` | `Integer` | Maximum target rate for incoming transfers, in kilobits per second. Returned by upload/download_setup node API.<br/>(C, T) |
|
|
4751
5596
|
| `target_rate_kbps` | `Integer` | Specifies desired speed for the transfer.<br/>(`-l {integer}`) |
|
|
4752
|
-
| `target_rate` | `String, Integer` | Pseudo-parameter: desired transfer rate in bps, with an optional unit suffix. Converted to `target_rate_kbps` (rounded down) before the transfer is started, overriding it if both are present. Also applies to `async` (sync). Accepted formats: integer (bps), or integer followed by `k`/`K` (x1000), `m`/`M` (x1000000), `g`/`G` (x1000000000). Examples: `100000000`, `100000k`, `100m`, `1g`. |
|
|
4753
5597
|
| `title` | `String` | Title of the transfer.<br/>(C, N, T) |
|
|
4754
5598
|
| `token` | `String` | Authorization token. Type is Bearer, Basic or ATM.<br/>(env:`ASPERA_SCP_TOKEN`) |
|
|
4755
5599
|
| `use_ascp4` | `Bool` | Specify version of protocol. `ascp4` will be deprecated.<br/>Default: `false`.<br/>(A, N, T) |
|
|
@@ -5563,7 +6407,7 @@ If the transfer user has no docroot and the transfer does not use a token, you c
|
|
|
5563
6407
|
```text
|
|
5564
6408
|
ascli -h
|
|
5565
6409
|
NAME
|
|
5566
|
-
ascli -- a command line tool for Aspera Applications (v4.
|
|
6410
|
+
ascli -- a command line tool for Aspera Applications (v4.29.0)
|
|
5567
6411
|
|
|
5568
6412
|
SYNOPSIS
|
|
5569
6413
|
ascli [GLOBAL_OPTIONS] <command> [OPTIONS] [ARGS]
|
|
@@ -5574,6 +6418,7 @@ DESCRIPTION
|
|
|
5574
6418
|
execute: ascli conf doc
|
|
5575
6419
|
or visit: https://ibm.biz/ascli-doc
|
|
5576
6420
|
source repo: https://github.com/IBM/aspera-cli
|
|
6421
|
+
AI assistants: ascli config commands, https://ibm.github.io/aspera-cli/llms.txt
|
|
5577
6422
|
|
|
5578
6423
|
ENVIRONMENT VARIABLES
|
|
5579
6424
|
Any option can be set as an environment variable, refer to the manual
|
|
@@ -5619,7 +6464,7 @@ OPTIONS: global
|
|
|
5619
6464
|
-h, --help Show this message
|
|
5620
6465
|
--show-config Display parameters used for the provided action
|
|
5621
6466
|
-v, --version Display version
|
|
5622
|
-
--ui=HASH User interface (dot-notation: mode, command)
|
|
6467
|
+
--ui=HASH User interface (dot-notation: mode, web_auth, command)
|
|
5623
6468
|
--invalid-characters=VALUE Replacement character and invalid filename characters
|
|
5624
6469
|
--log-level=ENUM Log level
|
|
5625
6470
|
--log-format=VALUE Log formatter
|
|
@@ -5628,6 +6473,7 @@ OPTIONS: global
|
|
|
5628
6473
|
--security=HASH Security restrictions (dot-notation: level, allowed_paths)
|
|
5629
6474
|
--lock-port=INT Prevent dual execution of a command, e.g. in cron
|
|
5630
6475
|
--once-only=yes|no Process only new items (some commands)
|
|
6476
|
+
--dry-run=yes|no Do not perform changes, only show what would be done
|
|
5631
6477
|
--log-secrets=yes|no Show passwords in logs
|
|
5632
6478
|
--temp=HASH Temporary files (dot-notation: folder, clean, expiry)
|
|
5633
6479
|
--clean-temp=yes|no Cleanup temporary files on exit (deprecated after 4.27.5: use --temp.clean)
|
|
@@ -5643,6 +6489,7 @@ OPTIONS: global
|
|
|
5643
6489
|
--fpac=VALUE Proxy auto configuration script
|
|
5644
6490
|
--proxy-credentials=LIST HTTP proxy credentials for fpac: user, password
|
|
5645
6491
|
--sql=VALUE SQL suffix appended to sqlite3 queries for admin subcommands (e.g. WHERE clause)
|
|
6492
|
+
--ascp-logs=HASH Ascp: log analysis (dot-notation: period, zero_bytes, mtu, resolve, thresholds, timezone, health_minutes, remote_max_size)
|
|
5646
6493
|
-P, --preset=VALUE Load the named option preset from current config file
|
|
5647
6494
|
--version-check-days=INT Period in days to check new version (zero to disable)
|
|
5648
6495
|
--plugin-folder=VALUE Folder where to find additional plugins
|
|
@@ -5655,9 +6502,6 @@ OPTIONS: global
|
|
|
5655
6502
|
--cache-tokens=yes|no Save and reuse OAuth tokens
|
|
5656
6503
|
--expand-mounts=yes|no Commands: list commands of sub-trees provided by another plugin
|
|
5657
6504
|
-N, --no-default Do not load default configuration for plugin
|
|
5658
|
-
--override=yes|no Wizard: override existing value
|
|
5659
|
-
--default=yes|no Wizard: set as default configuration for specified plugin (also: update)
|
|
5660
|
-
--key-path=VALUE Wizard: path to private key for JWT
|
|
5661
6505
|
--insecure=yes|no HTTP/S: Do not validate any certificate
|
|
5662
6506
|
--ignore-certificate=LIST HTTP/S: Do not validate certificate for these URLs
|
|
5663
6507
|
--warn-insecure=yes|no HTTP/S: Issue a warning if certificate is ignored
|
|
@@ -5689,6 +6533,7 @@ PLUGINS
|
|
|
5689
6533
|
preview Preview
|
|
5690
6534
|
server HSTS Fasp/SSH
|
|
5691
6535
|
shares Shares
|
|
6536
|
+
transferd Transfer Daemon
|
|
5692
6537
|
|
|
5693
6538
|
|
|
5694
6539
|
```
|
|
@@ -5699,25 +6544,6 @@ Bulk creation and deletion of resources are possible using option `bulk` (`yes`,
|
|
|
5699
6544
|
In that case, the operation expects an `Array` of `Hash` instead of a simple `Hash` using the [Extended Value](#extended-value-syntax) syntax.
|
|
5700
6545
|
This option is available only for some resources: if you need it, try and see if the entities you create or delete support this option.
|
|
5701
6546
|
|
|
5702
|
-
### Option: `query`
|
|
5703
|
-
|
|
5704
|
-
The `query` option can generally be used to add URL parameters to commands that list resources.
|
|
5705
|
-
It takes a `Hash`, corresponding to key/value pairs that appear in the query part of the request.
|
|
5706
|
-
|
|
5707
|
-
For example: `--query=@json:'{"p1":"v1","p2":"v2"}'` leads to query: `?p1=v1&p2=v2`.
|
|
5708
|
-
|
|
5709
|
-
If the same parameter needs to be provided several times, then it is also possible to provide an `Array`.
|
|
5710
|
-
|
|
5711
|
-
For example: `--query=@json:'{"p":["v1","v2"]}'` leads to query: `?p=v1&p=v2`.
|
|
5712
|
-
|
|
5713
|
-
If PHP-style arrays are expected in the API, add `[]` to the name of the parameter.
|
|
5714
|
-
|
|
5715
|
-
For example: `--query=@json:'{"p[]":["v1","v2"]}'` leads to query: `?p[]=v1&p[]=v2`.
|
|
5716
|
-
|
|
5717
|
-
> [!TIP]
|
|
5718
|
-
> Use `--query=help` on any `list` command to display the available query parameters and their types, as documented in the API.
|
|
5719
|
-
> For example: `ascli faspex5 admin accounts list --query=help`
|
|
5720
|
-
|
|
5721
6547
|
### Plugins
|
|
5722
6548
|
|
|
5723
6549
|
`ascli` uses a plugin mechanism.
|
|
@@ -5761,7 +6587,6 @@ ascli config plugins create foo .
|
|
|
5761
6587
|
Created ./foo.rb
|
|
5762
6588
|
```
|
|
5763
6589
|
|
|
5764
|
-
|
|
5765
6590
|
```shell
|
|
5766
6591
|
ascli --plugin-folder=. foo
|
|
5767
6592
|
```
|
|
@@ -5834,7 +6659,7 @@ It's up to the program to split arguments:
|
|
|
5834
6659
|
|
|
5835
6660
|
`ascli` is a Ruby program, so Ruby parses the command line (received with `GetCommandLineW`) into arguments and provides them to the Ruby code (`$0` and `ARGV`).
|
|
5836
6661
|
Ruby vaguely follows the Microsoft C/C++ parameter parsing rules.
|
|
5837
|
-
(See `w32_cmdvector` in Ruby source [`win32.c`](https://github.com/ruby/ruby/blob/master/win32/win32.c#L1766)):
|
|
6662
|
+
(See `w32_cmdvector` in Ruby source [`win32.c`](https://github.com/ruby/ruby/blob/master/win32/win32.c#L1766)):
|
|
5838
6663
|
|
|
5839
6664
|
- Space characters: split arguments (space, tab, newline)
|
|
5840
6665
|
- Backslash: `\` escapes a single special character
|
|
@@ -6144,11 +6969,13 @@ To complete the setup, you must have:
|
|
|
6144
6969
|
|
|
6145
6970
|
#### Wizard Invocation
|
|
6146
6971
|
|
|
6147
|
-
The wizard accepts
|
|
6972
|
+
The wizard accepts an optional argument, a `Hash` with keys:
|
|
6148
6973
|
|
|
6149
|
-
-
|
|
6974
|
+
- `url`: The organization name or the full FQDN.
|
|
6150
6975
|
|
|
6151
|
-
-
|
|
6976
|
+
- `plugin`: Specify `aoc` to bypass automatic application detection.
|
|
6977
|
+
|
|
6978
|
+
- `preset`: Name of the preset to create.
|
|
6152
6979
|
|
|
6153
6980
|
If the URL is omitted, the wizard will prompt for it interactively.
|
|
6154
6981
|
|
|
@@ -6165,8 +6992,8 @@ Once saved in the UI, return to the terminal and press Enter.
|
|
|
6165
6992
|
```console
|
|
6166
6993
|
$ ascli config wizard
|
|
6167
6994
|
Using: Aspera on Cloud at https://<ORG_NAME>.ibmaspera.com
|
|
6168
|
-
|
|
6169
|
-
option:
|
|
6995
|
+
Private RSA key, e.g. @file:<path> (leave empty to generate):
|
|
6996
|
+
option: private_key>
|
|
6170
6997
|
Using existing key:
|
|
6171
6998
|
/home/john/.aspera/ascli/<PKEY_NAME>.pem
|
|
6172
6999
|
Please Log in as user john@example.com at: https://<ORG_NAME>.ibmaspera.com
|
|
@@ -6191,12 +7018,12 @@ Saving config file.
|
|
|
6191
7018
|
|
|
6192
7019
|
- **Custom Client Identification**:
|
|
6193
7020
|
By default, `ascli` uses a pre-registered global client ID.
|
|
6194
|
-
To create and use an organization-specific integration,
|
|
7021
|
+
To create and use an organization-specific integration, give the option `--use-generic-client=no` of plugin `aoc` to the wizard command.
|
|
6195
7022
|
|
|
6196
7023
|
- **Direct Plugin Targeting**: To limit detection to the `aoc` plugin and skip discovery, provide both the URL and plugin name:
|
|
6197
7024
|
|
|
6198
7025
|
```shell
|
|
6199
|
-
ascli config wizard
|
|
7026
|
+
ascli config wizard @: url=<ORG_NAME> plugin=aoc
|
|
6200
7027
|
```
|
|
6201
7028
|
|
|
6202
7029
|
#### Verifying the Configuration
|
|
@@ -6262,6 +7089,7 @@ To register with web-based authentication (auth=web):
|
|
|
6262
7089
|
|
|
6263
7090
|
> [!NOTE]
|
|
6264
7091
|
> For web based authentication, `ascli` listens on a local port (for example, specified by the `redirect_uri` parameter, in this example: `12345`), and the browser will provide the OAuth code there.
|
|
7092
|
+
> See [Web login flow](#web-login-flow).
|
|
6265
7093
|
> For `ascli`, HTTP is required, and `12345` is the default port.
|
|
6266
7094
|
> The host of `redirect_uri` shall be loopback: `localhost`, an address of `127.0.0.0/8`, or `[::1]`.
|
|
6267
7095
|
|
|
@@ -6284,7 +7112,7 @@ updated: <AOC_ORG>
|
|
|
6284
7112
|
> [!NOTE]
|
|
6285
7113
|
> In above example, replace `https://<ORG_NAME>.ibmaspera.com` with your actual AoC URL.
|
|
6286
7114
|
|
|
6287
|
-
(This can also be done in one line using the command `config preset
|
|
7115
|
+
(This can also be done in one line using the command `config preset set <AOC_ORG> @: url=...`)
|
|
6288
7116
|
|
|
6289
7117
|
Define this [Option Preset](#option-preset) as default configuration for the `aoc` plugin:
|
|
6290
7118
|
|
|
@@ -6398,7 +7226,7 @@ To activate default use of JWT authentication for `ascli` using the [Option Pres
|
|
|
6398
7226
|
Execute:
|
|
6399
7227
|
|
|
6400
7228
|
```shell
|
|
6401
|
-
ascli config preset
|
|
7229
|
+
ascli config preset set <AOC_ORG> @: auth=jwt private_key=@val:@file:~/.aspera/ascli/<PKEY_NAME> username=someuser@example.com
|
|
6402
7230
|
```
|
|
6403
7231
|
|
|
6404
7232
|
> [!NOTE]
|
|
@@ -6518,7 +7346,7 @@ The following parameters are supported:
|
|
|
6518
7346
|
| other | Native | Other specific parameters depending on resource type. |
|
|
6519
7347
|
|
|
6520
7348
|
> [!NOTE]
|
|
6521
|
-
> Both `max` and `pmax` are processed
|
|
7349
|
+
> Both `max` and `pmax` are processed by `ascli` (see [option `--query`](#option---query-parameters-of-the-api)).
|
|
6522
7350
|
> `ascli` will return all values using paging if not provided.
|
|
6523
7351
|
> `page` and `per_page` are normally added by `ascli` to build successive API calls to get all values if there are more than 1000
|
|
6524
7352
|
> (AoC allows a maximum page size of 1000).
|
|
@@ -6529,7 +7357,7 @@ The following parameters are supported:
|
|
|
6529
7357
|
> For example: `ascli aoc admin user list --query=help`
|
|
6530
7358
|
|
|
6531
7359
|
> [!TIP]
|
|
6532
|
-
>
|
|
7360
|
+
> Options `--out.query` and `--out.select` can also be used to further refine selection, refer to [Filtering results](#filtering-results).
|
|
6533
7361
|
|
|
6534
7362
|
Examples:
|
|
6535
7363
|
|
|
@@ -6785,7 +7613,7 @@ ascli aoc user settings modify <ID> @json:'{"value":"..."}'
|
|
|
6785
7613
|
> - **Application identity**: derived from the `client_id` used during authentication.
|
|
6786
7614
|
>
|
|
6787
7615
|
> This means that settings stored by one client application (for example, the AoC web UI) are not visible to another (for example, `ascli` using a different `client_id`).
|
|
6788
|
-
> By default, `ascli` uses the pre-registered global `client_id` (see `--use-generic-client`).
|
|
7616
|
+
> By default, `ascli` uses the pre-registered global `client_id` (see option `--use-generic-client` of plugin `aoc`).
|
|
6789
7617
|
|
|
6790
7618
|
#### Example: Create a sub access key in a `node`
|
|
6791
7619
|
|
|
@@ -6954,7 +7782,7 @@ In this example, a user has access to a workspace where two shared folders are l
|
|
|
6954
7782
|
First, set up the environment (skip if already done), see [AoC configuration: Using Wizard](#aoc-configuration-using-wizard):
|
|
6955
7783
|
|
|
6956
7784
|
```shell
|
|
6957
|
-
ascli config wizard https://sedemo.ibmaspera.com aoc aoc_sedemo --username=someuser@example.com
|
|
7785
|
+
ascli config wizard @: url=https://sedemo.ibmaspera.com plugin=aoc preset=aoc_sedemo --username=someuser@example.com
|
|
6958
7786
|
```
|
|
6959
7787
|
|
|
6960
7788
|
This creates the option preset `aoc_sedemo` to allow seamless command line access and sets it as default for Aspera on Cloud.
|
|
@@ -7241,7 +8069,7 @@ The `package_folder` option (`Hash`) controls how downloaded packages are organi
|
|
|
7241
8069
|
**Supported Fields**:
|
|
7242
8070
|
|
|
7243
8071
|
| Field | Type | Description |
|
|
7244
|
-
|
|
8072
|
+
| ----- | ------------- | -------------------------------------------------------------------------------- |
|
|
7245
8073
|
| `fld` | `Array[String]` | List of package fields (up to 2) used to build the subfolder name. Field values are joined with `.`.<br/>Example: `["name", "id"]`. |
|
|
7246
8074
|
| `inf` | `Bool` | If `true`, creates a `<ID>.info.json` sidecar file inside the folder containing package metadata.<br/>Default: `false`. |
|
|
7247
8075
|
| `opt` | `Bool` | If `false` (default), all fields in `fld` are always used. If `true`, the first field is used unless the folder already exists.<br/>Default: `false`. |
|
|
@@ -7723,7 +8551,7 @@ For instructions, refer to section `find` for plugin `node`.
|
|
|
7723
8551
|
|
|
7724
8552
|
```shell
|
|
7725
8553
|
admin analytics application_events
|
|
7726
|
-
admin analytics files organization '' <
|
|
8554
|
+
admin analytics files organization '' <ID>
|
|
7727
8555
|
admin analytics transfers organization --query=@json:'{"status":"completed","direction":"receive","limit":2}' --notify-to=my_email_external --notify-template=@ruby:'%Q{From: <%=from_name%> <<%=from_email%>>\nTo: <<%=to%>>\nSubject: <%=ev["files_completed"]%> files received\n\n<%=ev.to_yaml%>}'
|
|
7728
8556
|
admin analytics transfers users --once-only=yes
|
|
7729
8557
|
admin application instance list
|
|
@@ -7731,8 +8559,8 @@ admin application instance list --query.aspera_app_type=files
|
|
|
7731
8559
|
admin application instance list --query.organization_apps=true
|
|
7732
8560
|
admin application membership list
|
|
7733
8561
|
admin application types
|
|
7734
|
-
admin ats access_key create --cloud=aws --region=my_region @json:'{"id":"ak_aws_aoc","name":"my test key AWS","storage":{"type":"aws_s3","bucket":"my_bucket","credentials":{"access_key_id":"
|
|
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
|
|
8562
|
+
admin ats access_key create --cloud=aws --region=my_region @json:'{"id":"ak_aws_aoc","name":"my test key AWS","storage":{"type":"aws_s3","bucket":"my_bucket","credentials":{"access_key_id":"<ACCESS_KEY>","secret_access_key":"<SECRET_KEY>"},"path":"/"}}'
|
|
8563
|
+
admin ats access_key create --cloud=softlayer --region=my_region @: id=ak1ibmcloud secret=<SECRET> 'name="my test key"' storage.type=ibm-s3 storage.bucket=my_bucket storage.credentials.access_key_id=<ACCESS_KEY> storage.credentials.secret_access_key=<SECRET_KEY> storage.path=/
|
|
7736
8564
|
admin ats access_key delete ak1ibmcloud
|
|
7737
8565
|
admin ats access_key list --fields=name,id
|
|
7738
8566
|
admin ats access_key node ak1ibmcloud --secret=<SECRET> browse /
|
|
@@ -7745,10 +8573,10 @@ admin bearer_token --out.level=data --out.secrets=yes
|
|
|
7745
8573
|
admin client list
|
|
7746
8574
|
admin client_access_key list
|
|
7747
8575
|
admin client_registration_token create @json:'{"data":{"name":"test_client_reg1","client_subject_scopes":["alee","aejd"],"client_subject_enabled":true}}'
|
|
7748
|
-
admin client_registration_token delete <
|
|
8576
|
+
admin client_registration_token delete <ID>
|
|
7749
8577
|
admin client_registration_token list
|
|
7750
8578
|
admin configuration_policy list
|
|
7751
|
-
admin configuration_policy show <
|
|
8579
|
+
admin configuration_policy show <ID>
|
|
7752
8580
|
admin contact list
|
|
7753
8581
|
admin dropbox list
|
|
7754
8582
|
admin dropbox_membership list
|
|
@@ -7756,7 +8584,7 @@ admin group list
|
|
|
7756
8584
|
admin group_membership list --fields=ALL --query=@json:'{"page":1,"per_page":50,"embed":"member","inherited":false,"workspace_id":11363,"sort":"name"}'
|
|
7757
8585
|
admin kms_profile list
|
|
7758
8586
|
admin network_policy list
|
|
7759
|
-
admin network_policy show <
|
|
8587
|
+
admin network_policy show <ID>
|
|
7760
8588
|
admin node bearer_token %name:my_node_name user:all
|
|
7761
8589
|
admin node do %name:my_node_name --secret=<AK_SECRET> browse /
|
|
7762
8590
|
admin node do %name:my_node_name --secret=<AK_SECRET> browse /folder_sub --node-api.cache=false
|
|
@@ -7764,8 +8592,8 @@ admin node do %name:my_node_name --secret=<AK_SECRET> delete /folder1
|
|
|
7764
8592
|
admin node do %name:my_node_name --secret=<AK_SECRET> delete /folder_sub
|
|
7765
8593
|
admin node do %name:my_node_name --secret=<AK_SECRET> mkdir /folder1
|
|
7766
8594
|
admin node do %name:my_node_name --secret=<AK_SECRET> mkdir /folder_sub
|
|
7767
|
-
admin node do %name:my_node_name --secret=<AK_SECRET> v3 access_key create @json:'{"id":"
|
|
7768
|
-
admin node do %name:my_node_name --secret=<AK_SECRET> v3 access_key delete
|
|
8595
|
+
admin node do %name:my_node_name --secret=<AK_SECRET> v3 access_key create @json:'{"id":"test-sub-1","storage":{"path":"/folder_sub"}}'
|
|
8596
|
+
admin node do %name:my_node_name --secret=<AK_SECRET> v3 access_key delete test-sub-1
|
|
7769
8597
|
admin node do %name:my_node_name --secret=<AK_SECRET> v3 events
|
|
7770
8598
|
admin node do %name:my_node_name delete test_shared_folder
|
|
7771
8599
|
admin node do %name:my_node_name mkdir test_shared_folder
|
|
@@ -7790,12 +8618,15 @@ admin user preferences %name:my_user_email show
|
|
|
7790
8618
|
admin workspace dropbox %name:my_other_workspace list
|
|
7791
8619
|
admin workspace list
|
|
7792
8620
|
admin workspace shared_folder %name:my_other_workspace list
|
|
7793
|
-
admin workspace shared_folder %name:my_other_workspace member <
|
|
8621
|
+
admin workspace shared_folder %name:my_other_workspace member <ID> list
|
|
8622
|
+
admin workspace shared_folder %name:my_other_workspace node <ID> browse /
|
|
7794
8623
|
admin workspace_membership list
|
|
7795
8624
|
admin workspace_membership list --fields=ALL --query=@json:'{"page":1,"per_page":50,"embed":"member","inherited":false,"workspace_id":11363,"sort":"name"}'
|
|
7796
|
-
automation workflow action <
|
|
8625
|
+
automation workflow action <ID> create @: name=toto
|
|
7797
8626
|
automation workflow create @: name=test_workflow
|
|
7798
|
-
automation workflow delete <
|
|
8627
|
+
automation workflow delete <ID>
|
|
8628
|
+
automation workflow details <ID>
|
|
8629
|
+
automation workflow export <ID>
|
|
7799
8630
|
automation workflow list
|
|
7800
8631
|
automation workflow list --query.show_org_workflows=@val:true
|
|
7801
8632
|
automation workflow list --select.name=test_workflow --fields=id
|
|
@@ -7803,65 +8634,66 @@ bearer_token --out.level=data --out.secrets=yes
|
|
|
7803
8634
|
files bearer /
|
|
7804
8635
|
files bearer_token_node / --cache-tokens=no
|
|
7805
8636
|
files browse /
|
|
7806
|
-
files browse / --url
|
|
7807
|
-
files browse / --url
|
|
7808
|
-
files browse / --url
|
|
8637
|
+
files browse / --url=<PRIVATE_LINK_SHARED_FOLDER>
|
|
8638
|
+
files browse / --url=<PUBLIC_LINK_FOLDER_NO_PASS>
|
|
8639
|
+
files browse / --url=<PUBLIC_LINK_FOLDER_WITH_PASS> --password=<PUBLIC_LINK_FOLDER_PASSWORD>
|
|
7809
8640
|
files browse my_remote_file
|
|
7810
8641
|
files browse my_remote_folder
|
|
7811
8642
|
files browse my_remote_folder/
|
|
7812
|
-
files cat
|
|
7813
|
-
files delete /
|
|
7814
|
-
files download --to-folder=.
|
|
7815
|
-
files download --transfer.agent=connect
|
|
7816
|
-
files download --transfer.agent=desktop
|
|
8643
|
+
files cat test-dst/test_file.bin
|
|
8644
|
+
files delete /test-src
|
|
8645
|
+
files download --to-folder=. test-dst/test_file.bin test-dst/test_file.bin
|
|
8646
|
+
files download --transfer.agent=connect test-dst/test_file.bin
|
|
8647
|
+
files download --transfer.agent=desktop test-dst/test_file.bin
|
|
7817
8648
|
files find /sample_video
|
|
7818
8649
|
files find /sample_video '\.partial$'
|
|
7819
8650
|
files find /sample_video @ruby:'->(f){f["type"].eql?("file")}'
|
|
7820
|
-
files mkdir /
|
|
8651
|
+
files mkdir /test-src
|
|
7821
8652
|
files modify /some_folder @: mount_point=false
|
|
7822
8653
|
files permission my_test_folder list
|
|
7823
|
-
files rename /some_folder
|
|
7824
|
-
files short_link /
|
|
7825
|
-
files short_link /
|
|
7826
|
-
files short_link /
|
|
7827
|
-
files short_link /
|
|
7828
|
-
files show %id:<
|
|
8654
|
+
files rename /some_folder test-dst
|
|
8655
|
+
files short_link /test-dst private create
|
|
8656
|
+
files short_link /test-dst private list
|
|
8657
|
+
files short_link /test-dst public create @: access_levels.0=mkdir access_levels.1=write --fields=id
|
|
8658
|
+
files short_link /test-dst public modify <AOC_SHORT_LINK_PUB_CREATE> @: access_levels=edit
|
|
8659
|
+
files show %id:<ID>
|
|
7829
8660
|
files show /
|
|
7830
|
-
files show
|
|
8661
|
+
files show test-dst/test_file.bin
|
|
7831
8662
|
files sync admin status /data/local_sync
|
|
7832
|
-
files sync pull /
|
|
8663
|
+
files sync pull /test-dst --to-folder=/data/local_sync @json:'{"reset":true,"transport":{"target_rate":my_bps}}'
|
|
7833
8664
|
files thumbnail my_test_folder/video_file.mpg
|
|
7834
8665
|
files thumbnail my_test_folder/video_file.mpg --query.text=true --query.double=true
|
|
7835
|
-
files transfer push /
|
|
7836
|
-
files upload --to-folder=/ test_file.bin --url
|
|
7837
|
-
files upload --to-folder=/
|
|
7838
|
-
files upload --to-folder=/
|
|
8666
|
+
files transfer push /test-src --to-folder=/test-dst test_file.bin
|
|
8667
|
+
files upload --to-folder=/ test_file.bin --url=<PUBLIC_LINK_FOLDER_NO_PASS>
|
|
8668
|
+
files upload --to-folder=/test-src test_file.bin
|
|
8669
|
+
files upload --to-folder=/test-src test_file.bin test_file.bin
|
|
7839
8670
|
files v3 info
|
|
7840
8671
|
gateway @: url=https://localhost:12347/aspera/faspex
|
|
7841
8672
|
organization
|
|
7842
8673
|
organization --format=image --fields=background_image_url --ui=text
|
|
7843
|
-
organization --url
|
|
7844
|
-
packages browse <
|
|
8674
|
+
organization --url=<PUBLIC_LINK_RECV_FROM_AOC_USER>
|
|
8675
|
+
packages browse <ID> /
|
|
7845
8676
|
packages list
|
|
7846
8677
|
packages list --query=@json:'{"dropbox_name":"my_shared_inbox_name","sort":"-received_at","archived":false,"received":true,"has_content":true,"exclude_dropbox_packages":false}'
|
|
7847
|
-
packages receive <
|
|
7848
|
-
packages receive <
|
|
8678
|
+
packages receive <ID> --to-folder=.
|
|
8679
|
+
packages receive <ID> --to-folder=. /
|
|
7849
8680
|
packages receive ALL --once-only=yes --to-folder=. --query.max=5 --lock-port=50101 --package-folder.fld.0=name --package-folder.fld.1=id --package-folder.opt=true
|
|
7850
8681
|
packages receive ALL --once-only=yes --to-folder=. --query.max=5 --lock-port=50101 --query=@json:'{"dropbox_name":"my_shared_inbox_name","archived":false,"received":true,"has_content":true,"exclude_dropbox_packages":false,"include_draft":false}' --ts=@json:'{"resume_policy":"sparse_csum","target_rate_kbps":50000}'
|
|
8682
|
+
packages receive ALL --url=<PUBLIC_LINK_RECV_FROM_AOC_USER> --to-folder=.
|
|
7851
8683
|
packages receive INIT --once-only=yes --query.dropbox_name=my_shared_inbox_name
|
|
7852
8684
|
packages send --workspace=my_workspace_shared_inbox --validate-metadata=yes @json:'{"name":"package title","recipients":["my_shared_inbox_meta"],"metadata":[{"input_type":"single-text","name":"Project Id","values":["123"]},{"input_type":"single-dropdown","name":"Type","values":["Opt2"]},{"input_type":"multiple-checkbox","name":"CheckThose","values":["Check1","Check2"]},{"input_type":"date","name":"Optional Date","values":["2021-01-13T15:02:00.000Z"]}]}' test_file.bin
|
|
7853
8685
|
packages send --workspace=my_workspace_shared_inbox --validate-metadata=yes @json:'{"name":"package title","recipients":["my_shared_inbox_meta"],"metadata":{"Project Id":"456","Type":"Opt2","CheckThose":["Check1","Check2"],"Optional Date":"2021-01-13T15:02:00.000Z"}}' test_file.bin
|
|
7854
8686
|
packages send --workspace=my_workspace_shared_inbox @json:'{"name":"package title","recipients":["my_shared_inbox_name"]}' test_file.bin
|
|
7855
|
-
packages send @: 'name=package title' END test_file.bin --url
|
|
7856
|
-
packages send @: 'name=package title' END test_file.bin --url
|
|
8687
|
+
packages send @: 'name=package title' END test_file.bin --url=<PUBLIC_LINK_SEND_AOC_USER> --password=<PUBLIC_LINK_SEND_USE_PASS>
|
|
8688
|
+
packages send @: 'name=package title' END test_file.bin --url=<PUBLIC_LINK_SEND_SHARED_INBOX>
|
|
7857
8689
|
packages send @: 'name=package title' recipients.0=my_username 'note=some notes' END test_file.bin
|
|
7858
8690
|
packages send @json:'{"name":"package title","recipients":["my_email_external"]}' --new-user-option.package_contact=true test_file.bin
|
|
7859
8691
|
packages shared_inboxes list
|
|
7860
8692
|
packages shared_inboxes short_link public %name:my_shared_inbox_name create --fields=id
|
|
7861
|
-
packages shared_inboxes short_link public %name:my_shared_inbox_name delete <
|
|
8693
|
+
packages shared_inboxes short_link public %name:my_shared_inbox_name delete <AOC_SHARED_INBOX_SHORT_LINK_CREATE>
|
|
7862
8694
|
packages shared_inboxes short_link public %name:my_shared_inbox_name list
|
|
7863
|
-
packages shared_inboxes short_link public %name:my_shared_inbox_name modify <
|
|
7864
|
-
packages shared_inboxes short_link public %name:my_shared_inbox_name show <
|
|
8695
|
+
packages shared_inboxes short_link public %name:my_shared_inbox_name modify <AOC_SHARED_INBOX_SHORT_LINK_CREATE> @: password=<PUBLIC_LINK_FOLDER_PASSWORD>
|
|
8696
|
+
packages shared_inboxes short_link public %name:my_shared_inbox_name show <AOC_SHARED_INBOX_SHORT_LINK_CREATE>
|
|
7865
8697
|
packages shared_inboxes show %name:my_shared_inbox_name
|
|
7866
8698
|
packages show '%name:package title'
|
|
7867
8699
|
remind --username=my_user_email --url=https://aoc.example.com/path
|
|
@@ -7925,7 +8757,7 @@ Then, to register the key by default for the `ats` plugin, create a preset.
|
|
|
7925
8757
|
Execute:
|
|
7926
8758
|
|
|
7927
8759
|
```shell
|
|
7928
|
-
ascli config preset
|
|
8760
|
+
ascli config preset set <PRESET_NAME> @: ibm_api_key=<API_KEY>
|
|
7929
8761
|
```
|
|
7930
8762
|
|
|
7931
8763
|
```shell
|
|
@@ -7941,7 +8773,7 @@ aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee
|
|
|
7941
8773
|
```
|
|
7942
8774
|
|
|
7943
8775
|
```shell
|
|
7944
|
-
ascli config preset
|
|
8776
|
+
ascli config preset set <PRESET_NAME> @: instance=aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee
|
|
7945
8777
|
```
|
|
7946
8778
|
|
|
7947
8779
|
```shell
|
|
@@ -7958,7 +8790,7 @@ ascli ats api_key create --out.secrets=yes
|
|
|
7958
8790
|
```
|
|
7959
8791
|
|
|
7960
8792
|
```shell
|
|
7961
|
-
ascli config preset
|
|
8793
|
+
ascli config preset set <PRESET_NAME> @: ats_key=<ATS_KEY> ats_secret=<ATS_SECRET>
|
|
7962
8794
|
```
|
|
7963
8795
|
|
|
7964
8796
|
### ATS Access key creation parameters
|
|
@@ -8011,8 +8843,8 @@ The parameters provided to ATS for access key creation are the ones of [ATS API]
|
|
|
8011
8843
|
|
|
8012
8844
|
```shell
|
|
8013
8845
|
access_key cluster ak2ibmcloud --secret=<SECRET>
|
|
8014
|
-
access_key create --cloud=aws --region=my_region @json:'{"id":"ak_aws","name":"my test key AWS","storage":{"type":"aws_s3","bucket":"my_bucket","credentials":{"access_key_id":"
|
|
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":"
|
|
8846
|
+
access_key create --cloud=aws --region=my_region @json:'{"id":"ak_aws","name":"my test key AWS","storage":{"type":"aws_s3","bucket":"my_bucket","credentials":{"access_key_id":"<ACCESS_KEY>","secret_access_key":"<SECRET_KEY>"},"path":"/"}}'
|
|
8847
|
+
access_key create --cloud=softlayer --region=my_region @json:'{"id":"ak2ibmcloud","secret":"<SECRET>","name":"my test key","storage":{"type":"ibm-s3","bucket":"my_bucket","credentials":{"access_key_id":"<ACCESS_KEY>","secret_access_key":"<SECRET_KEY>"},"path":"/"}}'
|
|
8016
8848
|
access_key delete ak2ibmcloud
|
|
8017
8849
|
access_key entitlement ak2ibmcloud
|
|
8018
8850
|
access_key list --fields=name,id
|
|
@@ -8059,7 +8891,7 @@ ascli server --url=ssh://hsts.example.com:33001 --username=john --ssh-keys=~/.ss
|
|
|
8059
8891
|
|
|
8060
8892
|
```shell
|
|
8061
8893
|
browse /
|
|
8062
|
-
browse / --password @none: --ssh-options.number_of_password_prompts=0 --ssh-keys=<
|
|
8894
|
+
browse / --password @none: --ssh-options.number_of_password_prompts=0 --ssh-keys=<SERV_KEY_PATH>
|
|
8063
8895
|
browse my_inside_folder/test_file.bin
|
|
8064
8896
|
browse my_upload_folder/target_hot
|
|
8065
8897
|
cp my_inside_folder/test_file.bin my_upload_folder/200KB.2
|
|
@@ -8084,6 +8916,7 @@ sync admin status /data/local_sync
|
|
|
8084
8916
|
sync pull my_inside_folder --to-folder=/data/local_sync @: name=serv_sync_pull_conf
|
|
8085
8917
|
sync pull my_inside_folder --to-folder=/data/local_sync @json:'{"name":"serv_sync_pull_conf","reset":true,"transport":{"target_rate":my_bps}}'
|
|
8086
8918
|
upload 'faux:///test.bin?1k' --to-folder=my_upload_folder
|
|
8919
|
+
upload 'faux:///test.bin?1m' --to-folder=my_upload_folder --ts.target_rate=500m
|
|
8087
8920
|
upload --sources=@ts --transfer.ascp_args=@list:,--file-list,file_list.txt --to-folder=my_inside_folder
|
|
8088
8921
|
upload --sources=@ts --transfer.ascp_args=@list:,--file-pair-list,file_pair_list.txt
|
|
8089
8922
|
upload --sources=@ts --ts=@json:'{"paths":[{"source":"test_file.bin","destination":"my_inside_folder/other_name_4"}]}' --transfer.agent=transferd
|
|
@@ -8169,6 +9002,23 @@ ascli server --ssh-options=@json:'{"use_agent": false}' ...
|
|
|
8169
9002
|
If one of the SSH private keys is passphrase-protected, then option `passphrase` can be used.
|
|
8170
9003
|
It is equivalent to setting both options `ssh_options.passphrase` and `ts.ssh_private_key_passphrase`.
|
|
8171
9004
|
|
|
9005
|
+
### Analyze `ascp` logs of the server
|
|
9006
|
+
|
|
9007
|
+
Command `logs` analyzes the `ascp` log files of the server (`ascp` 4.0 and later), instead of those of the local machine: the files are read over the SSH connection of the plugin (same `url`, `username`, `password` or `ssh_keys`, and `ssh_options`), then analyzed like with [`config ascp logs`](#agent-direct-transfer). It has the same sub-commands (`summary`, `sessions`, `diagnostics`, `health`, `records`, ...) and the same option `ascp_logs`.
|
|
9008
|
+
Paths of the files on the server are mandatory: there is no default location, as it depends on the installation (e.g. a syslog file such as `/var/log/aspera.log` or `/var/log/messages`, or a file of the folder given with `ascp -L`).
|
|
9009
|
+
Files compressed with gzip (rotations) are supported. A folder is not read, give its files.
|
|
9010
|
+
|
|
9011
|
+
```shell
|
|
9012
|
+
ascli server --url=ssh://<SERVER_ADDRESS>:33001 --username=root --ssh-keys=~/.ssh/id_rsa logs summary /var/log/aspera.log
|
|
9013
|
+
ascli server ... logs sessions /var/log/aspera.log /var/log/aspera.log-20261101.gz --select=@json:'{"status":"failed"}'
|
|
9014
|
+
```
|
|
9015
|
+
|
|
9016
|
+
The user must be allowed to read the files (log files are often readable by `root` only), and the server shall provide a shell with `head` (and `stat`).
|
|
9017
|
+
The files are copied to a temporary folder, removed after the analysis.
|
|
9018
|
+
The size of the files is limited (total of 256 MB by default), to avoid reading huge logs in memory: the limit is the key `remote_max_size` (in bytes) of option `ascp_logs`, e.g. `--ascp-logs.remote_max_size=1000000000`.
|
|
9019
|
+
The modification date of each file is kept, as the year of syslog lines is deduced from it.
|
|
9020
|
+
Not available with `--url=local:` and `https`.
|
|
9021
|
+
|
|
8172
9022
|
### Other session channels for `server`
|
|
8173
9023
|
|
|
8174
9024
|
URL schemes `local` and `https` are also supported (mainly for testing purposes).
|
|
@@ -8655,7 +9505,8 @@ ascli node -N --url=https://... --password="Bearer $(cat bearer.txt)" --root-id=
|
|
|
8655
9505
|
```shell
|
|
8656
9506
|
--url=http://localhost:12348 --username=sim --password=<PASSWORD> browse / --fields=path --format=csv --select=@json:'{"basename":"test_file.bin"}'
|
|
8657
9507
|
--url=http://localhost:12348 --username=sim --password=<PASSWORD> transfer list --fields=status
|
|
8658
|
-
--url=https://
|
|
9508
|
+
--url=https://node.example.com:9092 --username=user1 --password=<PASSWORD> --ui=text asperabrowser
|
|
9509
|
+
--url=https://tst.example.com/path --password 'Bearer <ND_BEARER_TOKEN>' --root-id=<ID> access_key do self browse /
|
|
8659
9510
|
access_key create @json:'{"id":"my_username","secret":"<PASSWORD>","storage":{"type":"local","path":"/"}}'
|
|
8660
9511
|
access_key delete my_username
|
|
8661
9512
|
access_key do my_ak_name browse / --secret=<AK_SECRET>
|
|
@@ -8673,15 +9524,14 @@ access_key do my_ak_name node_info / --secret=<AK_SECRET>
|
|
|
8673
9524
|
access_key do my_ak_name rename /tst_nd_ak test_nd_ak2 --secret=<AK_SECRET>
|
|
8674
9525
|
access_key do my_ak_name show %id:1 --secret=<AK_SECRET>
|
|
8675
9526
|
access_key do my_ak_name upload 'faux:///test_nd_ak3?100k' --node-api.standard_ports=false --secret=<AK_SECRET>
|
|
8676
|
-
access_key do self permission %id:<
|
|
9527
|
+
access_key do self permission %id:<ID> create @json:'{"access_type":"user","access_id":"666"}'
|
|
8677
9528
|
access_key do self permission / delete 1
|
|
8678
9529
|
access_key do self permission / modify 1 @: 'access_levels=@list: read list'
|
|
8679
9530
|
access_key do self permission / show 1
|
|
8680
9531
|
access_key list
|
|
8681
|
-
access_key set_bearer_key self @file
|
|
9532
|
+
access_key set_bearer_key self @file:<PRIVATE_KEY_FILE>
|
|
8682
9533
|
access_key show %id:self
|
|
8683
9534
|
api_details
|
|
8684
|
-
asperabrowser
|
|
8685
9535
|
async bandwidth %name:my_sync_session_name
|
|
8686
9536
|
async counters %name:my_sync_session_name
|
|
8687
9537
|
async delete ALL
|
|
@@ -8730,12 +9580,12 @@ sync admin status /data/local_sync
|
|
|
8730
9580
|
sync pull /aspera-test-dir-tiny --to-folder=/data/local_sync @: reset=true
|
|
8731
9581
|
sync pull /aspera-test-dir-tiny --to-folder=/data/local_sync @json:'{"name":"my_sync_session_name","reset":true}'
|
|
8732
9582
|
transfer bandwidth_average
|
|
8733
|
-
transfer cancel <
|
|
9583
|
+
transfer cancel <ID>
|
|
8734
9584
|
transfer list --query.active_only=true
|
|
8735
9585
|
transfer list --query.reset=true --once-only=yes
|
|
8736
|
-
transfer modify <
|
|
9586
|
+
transfer modify <ID> @: target_rate_kbps=10000
|
|
8737
9587
|
transfer sessions
|
|
8738
|
-
transfer show <
|
|
9588
|
+
transfer show <ID>
|
|
8739
9589
|
transport
|
|
8740
9590
|
upload 'faux:///testfile1?1m' --to-folder=my_local_path
|
|
8741
9591
|
upload --to-folder=my_upload_folder --sources=@ts --ts=@json:'{"paths":[{"source":"/aspera-test-dir-small/10MB.2"}],"precalculate_job_size":true}' --transfer.agent=node --transfer.url=https://node.example.com/path --transfer.username=my_username --transfer.password=<PASSWORD>
|
|
@@ -8767,7 +9617,7 @@ Identify the region and the endpoint URL will be `https://otlp-[region]-saas.ins
|
|
|
8767
9617
|
For convenience, those parameters can be provided in a preset, for example, named `otel_default`.
|
|
8768
9618
|
|
|
8769
9619
|
```shell
|
|
8770
|
-
ascli config preset
|
|
9620
|
+
ascli config preset set otel_default @json:'{"url":"https://otlp-orange-saas.instana.io:4318","key":"<KEY>","interval":1.1}'
|
|
8771
9621
|
```
|
|
8772
9622
|
|
|
8773
9623
|
Then it is invoked like this (assuming a default node is configured):
|
|
@@ -8797,13 +9647,13 @@ The emulator starts its own `transferd`, and stops it on exit.
|
|
|
8797
9647
|
It takes an optional `Hash` argument with the following parameters:
|
|
8798
9648
|
|
|
8799
9649
|
| Field | Type | Description |
|
|
8800
|
-
|
|
9650
|
+
| ----------------- | ------- | -------------------------------------------------------------------------------- |
|
|
8801
9651
|
| `cert` | `String` | Path to the TLS certificate file. Accepted formats: PEM (`.pem`) or PKCS12 (`.p12` / `.pfx`).<br/>Example: `/path/to/cert.pem`. |
|
|
8802
9652
|
| `chain` | `String` | Path to the PEM certificate chain file (appended as extra chain certificates).<br/>Example: `/path/to/chain.pem`. |
|
|
8803
9653
|
| `docroot` | `String` | Local folder of the node files. Paths of `/files/browse` and local paths of transfers (sources of `send`, destination of `receive`) are relative to it, and confined in it. Defaults to the current working directory.<br/>Example: `/data/aspera`. |
|
|
8804
9654
|
| `key` | `String` | Path to the PEM private key file, or the PKCS12 passphrase when `cert` is a `.p12`/`.pfx` file.<br/>Example: `/path/to/key.pem`. |
|
|
9655
|
+
| `password` | `String` | Password expected from clients in HTTP Basic authentication, for the above `username`. Generate it with `openssl rand -hex 32`: a weak password is refused (see `password_min_bits`).<br/>Example: `<PASSWORD>`. |
|
|
8805
9656
|
| `password_min_bits` | `Integer` | Minimum estimated strength of `password`, in bits (log2 of the number of guesses to find it). The strength is estimated with gem `zxcvbn` if installed, else with a built-in estimate that detects repeats, sequences, keyboard rows, words and years. `0` disables the check. A random password of 32 bytes (`openssl rand -hex 32`) is far above the default.<br/>Default: `80`. |
|
|
8806
|
-
| `password` | `String` | Password expected from clients in HTTP Basic authentication, for the above `username`. Generate it with `openssl rand -hex 32`: a weak password is refused (see `password_min_bits`).<br/>Example: `my_password`. |
|
|
8807
9657
|
| `retention_sec` | `Integer` | Time in seconds a transfer stays in the list of transfers after it ended (completed, failed or canceled, and no more retried).<br/>Default: `86400`. |
|
|
8808
9658
|
| `url` | `String` | Address and port the emulator listens on. Use `https://` with `cert`/`key` for TLS.<br/>Default: `http://localhost:8080`. |
|
|
8809
9659
|
| `username` | `String` | Username expected from clients in HTTP Basic authentication. Set together with `password`. When not set, requests are accepted without authentication. Mandatory when `url` is not a loopback address (`localhost`, `127.0.0.0/8`, `::1`).<br/>Example: `node_user`. |
|
|
@@ -8822,7 +9672,7 @@ ascli node emulator @json:'{"url":"http://localhost:12348","username":"sim","pas
|
|
|
8822
9672
|
|
|
8823
9673
|
Generate the password with `openssl rand -hex 32`.
|
|
8824
9674
|
A weak password is refused at startup: its strength is estimated in bits, and shall be at least `password_min_bits`.
|
|
8825
|
-
`username` and `password` are mandatory when `url` is not a loopback address (
|
|
9675
|
+
`username` and `password` are mandatory when `url` is not a loopback address (see [Web service](#web-service)): anyone reaching the emulator could send the files of the `docroot` to any host.
|
|
8826
9676
|
|
|
8827
9677
|
Then, in another terminal, use it as a node, for example, to list the files in `/data`:
|
|
8828
9678
|
|
|
@@ -8903,13 +9753,13 @@ Multiple applications detected:
|
|
|
8903
9753
|
product> faspex5
|
|
8904
9754
|
```
|
|
8905
9755
|
|
|
8906
|
-
When Faspex is detected, the wizard asks for
|
|
9756
|
+
When Faspex is detected, the wizard asks for a private key (a value like `@file:<path>`).
|
|
8907
9757
|
If you do not have a private key, leave that field blank, and one will be generated or a previously generated key will be used.
|
|
8908
9758
|
|
|
8909
9759
|
```text
|
|
8910
9760
|
Using: Faspex at https://faspex5.example.com/aspera/faspex
|
|
8911
|
-
|
|
8912
|
-
option:
|
|
9761
|
+
Private RSA key, e.g. @file:<path> (leave empty to generate):
|
|
9762
|
+
option: private_key>
|
|
8913
9763
|
Using existing key:
|
|
8914
9764
|
/Users/someuser/.aspera/ascli/my_key
|
|
8915
9765
|
```
|
|
@@ -9004,7 +9854,7 @@ Typically, users create a preset so they don't have to enter these options each
|
|
|
9004
9854
|
Example:
|
|
9005
9855
|
|
|
9006
9856
|
```shell
|
|
9007
|
-
ascli config preset
|
|
9857
|
+
ascli config preset set <F5_PRESET> @: auth=jwt client_id=<CLIENT_ID> client_secret=<SECRET> username=<USERNAME> private_key=@file:.../path/to/key.pem
|
|
9008
9858
|
|
|
9009
9859
|
ascli config preset set default faspex5 <F5_PRESET>
|
|
9010
9860
|
|
|
@@ -9019,9 +9869,9 @@ For web-based authentication, the administrator must create an **API client** in
|
|
|
9019
9869
|
- Do not Activate JWT
|
|
9020
9870
|
- Set **Redirect URI** to `https://127.0.0.1:8888`
|
|
9021
9871
|
- Click **Create**
|
|
9022
|
-
- Take note of the Client Id
|
|
9872
|
+
- Take note of the Client Id, and of the Client Secret if HTTP basic authentication is enabled on the API client
|
|
9023
9873
|
|
|
9024
|
-
The user will use the following options:
|
|
9874
|
+
The user will use the following options (`client_secret` only if HTTP basic authentication is enabled on the API client):
|
|
9025
9875
|
|
|
9026
9876
|
```text
|
|
9027
9877
|
--auth=web
|
|
@@ -9030,6 +9880,9 @@ The user will use the following options:
|
|
|
9030
9880
|
--redirect-uri=https://127.0.0.1:8888
|
|
9031
9881
|
```
|
|
9032
9882
|
|
|
9883
|
+
`ascli` uses PKCE (RFC 7636, method `S256`): the authorization code can be exchanged for a token only by the `ascli` process that requested it.
|
|
9884
|
+
Faspex checks it since version 5.0.16, earlier versions ignore it.
|
|
9885
|
+
|
|
9033
9886
|
### Faspex 5 public link authentication
|
|
9034
9887
|
|
|
9035
9888
|
If all you have is a public link received by email or other, you can still do authorized actions with it.
|
|
@@ -9052,7 +9905,7 @@ For `boot` method: (will be removed in future)
|
|
|
9052
9905
|
Use this token as password and use `--auth=boot`.
|
|
9053
9906
|
|
|
9054
9907
|
```shell
|
|
9055
|
-
ascli config preset
|
|
9908
|
+
ascli config preset set f5boot @: url=https://localhost/aspera/faspex auth=boot password=<TOKEN>
|
|
9056
9909
|
```
|
|
9057
9910
|
|
|
9058
9911
|
### Tested commands for `faspex5`
|
|
@@ -9102,33 +9955,36 @@ gateway @: url=https://localhost:12346/aspera/faspex
|
|
|
9102
9955
|
health --url=https://f5.example.com/path
|
|
9103
9956
|
invitation list
|
|
9104
9957
|
invitations create @: email_address=aspera.user1+u@gmail.com
|
|
9105
|
-
packages browse --url
|
|
9106
|
-
packages browse <
|
|
9107
|
-
packages delete <
|
|
9958
|
+
packages browse --url=<PUBLIC_LINK_RECV_FR_USER> /
|
|
9959
|
+
packages browse <ID> --query.recursive=true
|
|
9960
|
+
packages delete <ID>
|
|
9108
9961
|
packages list --box=ALL
|
|
9109
9962
|
packages list --box=my_shared_box_name
|
|
9110
9963
|
packages list --box=my_workgroup --group-type=workgroups
|
|
9111
9964
|
packages list --box=outbox --fields=DEF,sender.email,recipients.0.recipient_type
|
|
9112
9965
|
packages list --query=@json:'{"mailbox":"inbox","status":"completed"}'
|
|
9113
|
-
packages receive --box=my_shared_box_name <
|
|
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=.
|
|
9966
|
+
packages receive --box=my_shared_box_name <ID> --to-folder=.
|
|
9967
|
+
packages receive --box=my_workgroup --group-type=workgroups <ID> --to-folder=.
|
|
9968
|
+
packages receive --url=<PUBLIC_LINK_RECV_FR_USER> --to-folder=.
|
|
9969
|
+
packages receive --url=<PUBLIC_LINK_RECV_FR_USER> ALL --to-folder=.
|
|
9970
|
+
packages receive <ID> --to-folder=. --ts.content_protection_password=<PASSWORD>
|
|
9971
|
+
packages receive <ID> <F5_PACK_FIRST_FILE> --to-folder=. --ts.content_protection_password=<PASSWORD>
|
|
9972
|
+
packages receive ALL --once-only=yes --to-folder=.
|
|
9973
|
+
packages receive ALL --once-only=yes --to-folder=. --query.max=5 --ts.content_protection_password=<PASSWORD>
|
|
9120
9974
|
packages receive INIT --once-only=yes
|
|
9121
|
-
packages send --url
|
|
9122
|
-
packages send --url
|
|
9975
|
+
packages send --url=<PUBLIC_LINK_SEND_SHARED_BOX> @json:'{"title":"test title"}' test_file.bin
|
|
9976
|
+
packages send --url=<PUBLIC_LINK_SEND_TO_USER> @json:'{"title":"test title"}' test_file.bin
|
|
9123
9977
|
packages send @: 'title=for shared inbox' recipients.0=my_shared_box_name metadata.Options=Opt1 'metadata.TextInput=example text' END test_file.bin
|
|
9978
|
+
packages send @: 'title=test ear' recipients.0.name=my_username END test_file.bin --ts.content_protection=encrypt --ts.content_protection_password=<PASSWORD>
|
|
9979
|
+
packages send @: 'title=test recipient types' recipients.0=my_username recipient_types.0=user END test_file.bin
|
|
9124
9980
|
packages send @: 'title=test title' recipients.0.name=my_username END test_file.bin --ts.content_protection_password=<PASSWORD>
|
|
9125
9981
|
packages send @json:'{"title":"test title","recipients":["my_workgroup"]}' test_file.bin
|
|
9126
9982
|
packages send @json:'{"title":"test_webhook_ascli","recipients":["my_shared_box_name"]}' 'faux:///test1?1m'
|
|
9127
|
-
packages show --box=my_shared_box_name <
|
|
9128
|
-
packages show --box=my_workgroup --group-type=workgroups <
|
|
9129
|
-
packages show <
|
|
9130
|
-
packages status <
|
|
9131
|
-
packages status <
|
|
9983
|
+
packages show --box=my_shared_box_name <ID>
|
|
9984
|
+
packages show --box=my_workgroup --group-type=workgroups <ID>
|
|
9985
|
+
packages show <ID>
|
|
9986
|
+
packages status <F5_PACK_SEND_SHARED> @list:,failed,completed
|
|
9987
|
+
packages status <ID>
|
|
9132
9988
|
postprocessing @: url=https://localhost:8553/asclihook script_folder=/path/to/scripts cert=.../localhost.p12 key=<PASSWORD>
|
|
9133
9989
|
shared browse %name:my_shared_folder_name
|
|
9134
9990
|
shared list
|
|
@@ -9533,15 +10389,15 @@ ascli faspex5 postprocessing
|
|
|
9533
10389
|
An optional positional parameter can be provided as [Extended Value](#extended-value-syntax) `Hash`:
|
|
9534
10390
|
|
|
9535
10391
|
| Field | Type | Description |
|
|
9536
|
-
|
|
10392
|
+
| --------------------- | --------------------- | -------------------------------------------------------------------------------- |
|
|
9537
10393
|
| `allowed_ips` | `String, Array[String]` | IP address or network (CIDR, e.g. `10.89.0.0/24`), or list of them, allowed to call the listener. Requests from any other source IP are rejected with HTTP 403. When not set, no IP restriction is applied. This parameter or `secret_token` is required when `url` is not a local address. |
|
|
9538
10394
|
| `cert` | `String` | Path to the TLS certificate file. Accepted formats: PEM (`.pem`) or PKCS12 (`.p12` / `.pfx`).<br/>Example: `/path/to/cert.pem`. |
|
|
9539
10395
|
| `chain` | `String` | Path to the PEM certificate chain file (appended as extra chain certificates).<br/>Example: `/path/to/chain.pem`. |
|
|
9540
10396
|
| `fail_on_error` | `Bool` | When `true`, return HTTP 500 if the script exits with a non-zero status code. When `false` (default), the exit code is reported in the response body but HTTP 200 is returned.<br/>Default: `false`. |
|
|
9541
10397
|
| `key` | `String` | Path to the PEM private key file, or the PKCS12 passphrase when `cert` is a `.p12`/`.pfx` file.<br/>Example: `/path/to/key.pem`. |
|
|
9542
10398
|
| `script_folder` | `String` | Folder containing the post-processing scripts. The URL path (after the base path) is appended to this folder to locate the script to execute.<br/>Default: `.`.<br/>Example: `/opt/faspex/scripts`. |
|
|
9543
|
-
| `secret_token_min_bits` | `Integer` | Minimum estimated strength of `secret_token`, in bits (log2 of the number of guesses to find it). The strength is estimated with gem `zxcvbn` if installed, else with a built-in estimate that detects repeats, sequences, keyboard rows, words and years. `0` disables the check. A random token of 32 bytes (`openssl rand -hex 32`) is far above the default.<br/>Default: `80`. |
|
|
9544
10399
|
| `secret_token` | `String` | Shared secret for webhook authentication. When set, every incoming request must include `?token=<value>` in the URL; requests without the correct token are rejected with HTTP 401. Configure the Faspex webhook URL as `http://host:port/path/script.sh?token=<value>`. This parameter or `allowed_ips` is required when `url` is not a local address. Generate it with `openssl rand -hex 32`: a weak token is refused (see `secret_token_min_bits`). |
|
|
10400
|
+
| `secret_token_min_bits` | `Integer` | Minimum estimated strength of `secret_token`, in bits (log2 of the number of guesses to find it). The strength is estimated with gem `zxcvbn` if installed, else with a built-in estimate that detects repeats, sequences, keyboard rows, words and years. `0` disables the check. A random token of 32 bytes (`openssl rand -hex 32`) is far above the default.<br/>Default: `80`. |
|
|
9545
10401
|
| `timeout_seconds` | `Integer` | Maximum time in seconds to wait for the script to complete before killing it.<br/>Default: `60`. |
|
|
9546
10402
|
| `url` | `String` | Address and port the server listens on. Use `https://` with `cert`/`key` for TLS.<br/>Default: `http://localhost:8080`. |
|
|
9547
10403
|
|
|
@@ -9574,8 +10430,8 @@ Instead, one can specify the **IP address of the host** or `host.containers.inte
|
|
|
9574
10430
|
So, `ascli` shall listen on an address reachable from the containers: the IP address of the host, or `0.0.0.0` for all interfaces.
|
|
9575
10431
|
|
|
9576
10432
|
> [!NOTE]
|
|
9577
|
-
> **Security**: by default the listener binds to loopback (`localhost`) and is not reachable from outside the host.
|
|
9578
|
-
> When `url` is not a loopback address
|
|
10433
|
+
> **Security**: by default the listener binds to loopback (`localhost`) and is not reachable from outside the host (see [Web service](#web-service)).
|
|
10434
|
+
> When `url` is not a loopback address, at least one of the following protections is required:
|
|
9579
10435
|
>
|
|
9580
10436
|
> - **`secret_token`**: include the token in the Faspex webhook URL: `http://host:8080/processing/script1.sh?token=<TOKEN>`. Requests without the correct token are rejected with HTTP 401.
|
|
9581
10437
|
> - **`allowed_ips`**: restrict the listener to the known Faspex container IPs or network, e.g. `@json:'{"allowed_ips":["192.168.1.10","10.89.0.0/24"]}'`. Requests from other IPs are rejected with HTTP 403.
|
|
@@ -9608,15 +10464,17 @@ For legacy Faspex client applications that use the `send` API (only) of Faspex v
|
|
|
9608
10464
|
It takes an optional `Hash` argument:
|
|
9609
10465
|
|
|
9610
10466
|
| Field | Type | Description |
|
|
9611
|
-
|
|
10467
|
+
| ----------------- | ------- | -------------------------------------------------------------------------------- |
|
|
9612
10468
|
| `cert` | `String` | Path to the TLS certificate file. Accepted formats: PEM (`.pem`) or PKCS12 (`.p12` / `.pfx`).<br/>Example: `/path/to/cert.pem`. |
|
|
9613
10469
|
| `chain` | `String` | Path to the PEM certificate chain file (appended as extra chain certificates).<br/>Example: `/path/to/chain.pem`. |
|
|
9614
10470
|
| `key` | `String` | Path to the PEM private key file, or the PKCS12 passphrase when `cert` is a `.p12`/`.pfx` file.<br/>Example: `/path/to/key.pem`. |
|
|
10471
|
+
| `password` | `String` | Password expected from clients in HTTP Basic authentication, for the above `username`. Generate it with `openssl rand -hex 32`: a weak password is refused (see `password_min_bits`).<br/>Example: `<PASSWORD>`. |
|
|
9615
10472
|
| `password_min_bits` | `Integer` | Minimum estimated strength of `password`, in bits (log2 of the number of guesses to find it). The strength is estimated with gem `zxcvbn` if installed, else with a built-in estimate that detects repeats, sequences, keyboard rows, words and years. `0` disables the check. A random password of 32 bytes (`openssl rand -hex 32`) is far above the default.<br/>Default: `80`. |
|
|
9616
|
-
| `password` | `String` | Password expected from clients in HTTP Basic authentication, for the above `username`. Generate it with `openssl rand -hex 32`: a weak password is refused (see `password_min_bits`).<br/>Example: `my_password`. |
|
|
9617
10473
|
| `url` | `String` | Address and port the server listens on. Use `https://` with `cert`/`key` for TLS.<br/>Default: `http://localhost:8080`. |
|
|
9618
10474
|
| `username` | `String` | Username expected from clients in HTTP Basic authentication. Set together with `password`. When not set, requests are accepted without authentication. Mandatory when `url` is not a loopback address (`localhost`, `127.0.0.0/8`, `::1`).<br/>Example: `fx4_user`. |
|
|
9619
10475
|
|
|
10476
|
+
For details on `url` and HTTPS (`cert`, `key`, `chain`), see [Web service](#web-service).
|
|
10477
|
+
|
|
9620
10478
|
Example:
|
|
9621
10479
|
|
|
9622
10480
|
```shell
|
|
@@ -9626,7 +10484,7 @@ ascli faspex5 gateway @json:'{"url":"https://localhost:12345/aspera/faspex","use
|
|
|
9626
10484
|
Clients authenticate with HTTP Basic, as on Faspex 4, with the `username` and `password` of the gateway.
|
|
9627
10485
|
Generate the password with `openssl rand -hex 32`.
|
|
9628
10486
|
A weak password is refused at startup: its strength is estimated in bits, and shall be at least `password_min_bits`.
|
|
9629
|
-
`username` and `password` are mandatory when `url` is not a loopback address (
|
|
10487
|
+
`username` and `password` are mandatory when `url` is not a loopback address (see [Web service](#web-service)): anyone reaching the gateway could send packages to anyone, as the Faspex 5 user.
|
|
9630
10488
|
When they are not set, requests are accepted without authentication.
|
|
9631
10489
|
|
|
9632
10490
|
There are many limitations:
|
|
@@ -9704,6 +10562,43 @@ ascli shares admin user all share_permissions %username:john@example.com list --
|
|
|
9704
10562
|
done
|
|
9705
10563
|
```
|
|
9706
10564
|
|
|
10565
|
+
### Authentication of SAML users
|
|
10566
|
+
|
|
10567
|
+
By default, `shares` authenticates with `username` and `password`.
|
|
10568
|
+
A user that has only a SAML identity (no local password) can authenticate with a web browser: `--auth=web`.
|
|
10569
|
+
|
|
10570
|
+
```shell
|
|
10571
|
+
ascli shares --url=https://shares.example.com --auth=web files browse /
|
|
10572
|
+
```
|
|
10573
|
+
|
|
10574
|
+
Option `ui.web_auth` selects how the result of the login is received (see [Web login flow](#web-login-flow)):
|
|
10575
|
+
|
|
10576
|
+
- `port` (default): automatic when the browser runs on the same system as `ascli`.
|
|
10577
|
+
`ascli` listens on a local port (`--redirect-uri`, default: `http://localhost:12345`), opens the SAML login page of Shares (`/auth/saml`) in the browser with this URL in `RelayState`, and receives the OAuth tokens there.
|
|
10578
|
+
The host of `redirect_uri` shall be loopback: `localhost`, an address of `127.0.0.0/8`, or `[::1]`.
|
|
10579
|
+
- `paste`: the browser may run on another system than `ascli` (for example, `ascli` runs on a server accessed with SSH), without tunnel.
|
|
10580
|
+
No local port is opened and `--redirect-uri` is not used.
|
|
10581
|
+
`ascli` generates a random `state` and opens the SAML login page with `RelayState` `aspera://device-code?state=<state>`.
|
|
10582
|
+
After login, Shares displays a code (a long text of letters, digits, `-` and `_`). The user copies it and pastes it in the terminal (nothing is displayed, as the code contains a token).
|
|
10583
|
+
If standard input is not a terminal, the code is read from it.
|
|
10584
|
+
`ascli` checks that the `state` of the code is the one it generated.
|
|
10585
|
+
The code is valid for **15 to 30 minutes** after its display: it is encrypted with a key derived from the `state` and from the current time in slots of 15 minutes (the previous and the next slot are also accepted).
|
|
10586
|
+
So the clocks of the Shares server and of the system that runs `ascli` shall be correct (less than 15 minutes apart), and the code shall be pasted soon after the login, otherwise `ascli` reports an expired code or a wrong clock, and the login shall be done again.
|
|
10587
|
+
The code is also protected against typing errors and modification.
|
|
10588
|
+
|
|
10589
|
+
The token is saved, and renewed with its refresh token: the browser is opened again only if this fails.
|
|
10590
|
+
Option `username` is optional: with it, the token is saved for this user.
|
|
10591
|
+
|
|
10592
|
+
> [!IMPORTANT]
|
|
10593
|
+
> Shares does not have the OAuth authorization code grant: both ways require a specific patch of Shares, which returns the tokens when `RelayState` is a loopback URL (`port`) or `aspera://device-code?state=<state>` (`paste`).
|
|
10594
|
+
> The patch is the file [`docs/shares/zz_saml_cli_relay_state.rb`](shares/zz_saml_cli_relay_state.rb) of the GitHub repository.
|
|
10595
|
+
> It is temporary code, provided until an equivalent function is officially released in Shares.
|
|
10596
|
+
> It modifies no file of Shares: to install it, copy it to `<shares_rails_root>/config/initializers/` on the Shares server and restart Shares; to remove it, delete the file and restart Shares.
|
|
10597
|
+
> With a Shares without the patch, `ascli` reports that no token was received.
|
|
10598
|
+
> This feature works only with this patch: it is not a standard function of Shares, and it has not been validated on a released version of Shares yet.
|
|
10599
|
+
> It may change with the final implementation in Shares: the `RelayState` values, the format of the code (and so its validity and its encryption) and the returned fields can differ, and `ascli` will then be adapted. Do not rely on the current format outside of `ascli`.
|
|
10600
|
+
> The tokens given by Shares go through the browser (in the URL, or in the code): `ascli` immediately exchanges the refresh token for a new token, so that the tokens that were visible are not valid any more.
|
|
10601
|
+
|
|
9707
10602
|
### Tested commands for `shares`
|
|
9708
10603
|
|
|
9709
10604
|
> [!NOTE]
|
|
@@ -9737,7 +10632,7 @@ files download --to-folder=. my_share_folder/test_file.bin my_share_folder/test_
|
|
|
9737
10632
|
files mkdir my_share_folder/new_folder
|
|
9738
10633
|
files sync push /data/local_sync --to-folder=my_share_folder/synctst
|
|
9739
10634
|
files sync push /data/local_sync --to-folder=my_share_folder/synctst @: reset=true
|
|
9740
|
-
files upload 'faux:///
|
|
10635
|
+
files upload 'faux:///test-file?1m' --to-folder=my_share_folder --transfer.agent=httpgw --transfer.url=https://tst.example.com/path --transfer.synchronous=true --transfer.api_version=v1 --transfer.upload_chunk_size=100000
|
|
9741
10636
|
files upload --to-folder=my_share_folder test_file.bin
|
|
9742
10637
|
files upload --to-folder=my_share_folder test_file.bin --transfer.agent=httpgw --transfer.url=https://tst.example.com/path
|
|
9743
10638
|
files upload send_folder --to-folder=my_share_folder --transfer.agent=httpgw --transfer.url=https://tst.example.com/path --transfer.synchronous=true --transfer.api_version=v1 --transfer.upload_chunk_size=100000
|
|
@@ -9767,40 +10662,41 @@ In addition, it is possible to place a single `query` parameter in the request t
|
|
|
9767
10662
|
endpoint list
|
|
9768
10663
|
health
|
|
9769
10664
|
ssh_key list
|
|
9770
|
-
transfer current files <
|
|
10665
|
+
transfer current files <ID>
|
|
9771
10666
|
transfer current list --query.filter='(transfer_name contain aoc)'
|
|
9772
10667
|
transfer current list --query=@json:'{"filter1":"transfer_name","comp1":"contain","val1":"aoc"}'
|
|
9773
|
-
transfer current show <
|
|
10668
|
+
transfer current show <ID>
|
|
9774
10669
|
transfer smart list
|
|
9775
|
-
transfer smart sub
|
|
10670
|
+
transfer smart sub <SMART_ID> @: source.paths.0=my_smart_file source_type=user_selected
|
|
9776
10671
|
```
|
|
9777
10672
|
|
|
9778
10673
|
## Plugin: `orchestrator`: IBM Aspera Orchestrator
|
|
9779
10674
|
|
|
9780
|
-
To write workflow files without the designer, refer to the [
|
|
10675
|
+
To write workflow files without the designer, refer to the [Aspera Orchestrator Development Guide](https://github.com/laurent-martin/aspera-orchestrator-plugins-doc/blob/main/docs/orchestrator-development-guide.md): file format, graph, execution, examples and REST API.
|
|
9781
10676
|
|
|
9782
|
-
Command `workflows development`
|
|
9783
|
-
|
|
10677
|
+
Command `workflows development` gives access to the documentation for workflow development, read from GitHub.
|
|
10678
|
+
Without argument, it lists the documents: the guide (`guide`), the [Action Template Reference](https://github.com/laurent-martin/aspera-orchestrator-plugins-doc/blob/main/docs/action-template-reference.md) (`templates`) and the Plugin Manual (`manual`).
|
|
10679
|
+
After the name of a document: `toc` lists its sections, `full` displays the whole document, and `section <anchor>` displays only one section: the guide and the manual are large, use `toc` first.
|
|
9784
10680
|
It does not require access to Orchestrator.
|
|
9785
10681
|
The [MCP server](#plugin-mcp-model-context-protocol-server) instructs AI assistants to read it before writing or modifying a workflow.
|
|
9786
10682
|
|
|
9787
10683
|
```shell
|
|
9788
|
-
ascli orchestrator workflows development
|
|
9789
|
-
ascli orchestrator workflows development templates customruby
|
|
10684
|
+
ascli orchestrator workflows development guide toc
|
|
10685
|
+
ascli orchestrator workflows development templates section customruby
|
|
9790
10686
|
```
|
|
9791
10687
|
|
|
9792
|
-
|
|
10688
|
+
Commands `plugins spec` display the specifications of action plugins, read from GitHub: [plugins.yml](https://github.com/laurent-martin/aspera-orchestrator-plugins-doc/blob/main/docs/plugins.yml).
|
|
9793
10689
|
For each plugin: template attributes (label, allowed values, defaults), and inputs and outputs of its steps, with the template settings they depend on.
|
|
9794
|
-
The fields are described in section [Plugin specifications](https://github.com/laurent-martin/aspera-orchestrator-plugins-doc/blob/main/docs/
|
|
9795
|
-
|
|
9796
|
-
|
|
10690
|
+
The fields are described in section [Plugin specifications](https://github.com/laurent-martin/aspera-orchestrator-plugins-doc/blob/main/docs/orchestrator-development-guide.md#plugin-specifications) of the guide.
|
|
10691
|
+
`toc` lists the plugins, with the anchor of their section in the Plugin Manual (`manual_anchor`, for `workflows development manual section`).
|
|
10692
|
+
`show` with a plugin name (class name, case insensitive) displays its specification, or one section: `attributes`, `inputs` or `outputs`.
|
|
9797
10693
|
It does not require access to Orchestrator.
|
|
9798
10694
|
Option `plugin_specs` gives another URL or path of the file, for example for another version of Orchestrator.
|
|
9799
10695
|
|
|
9800
10696
|
```shell
|
|
9801
|
-
ascli orchestrator plugins spec --select=@json:'{"category":"Triggers"}'
|
|
9802
|
-
ascli orchestrator plugins spec AmazonS3Operation --format=yaml
|
|
9803
|
-
ascli orchestrator plugins spec ascpclient inputs
|
|
10697
|
+
ascli orchestrator plugins spec toc --select=@json:'{"category":"Triggers"}'
|
|
10698
|
+
ascli orchestrator plugins spec show AmazonS3Operation --format=yaml
|
|
10699
|
+
ascli orchestrator plugins spec show ascpclient inputs
|
|
9804
10700
|
```
|
|
9805
10701
|
|
|
9806
10702
|
### Authentication
|
|
@@ -9811,9 +10707,9 @@ The Orchestrator plugin supports different credentials and authentication styles
|
|
|
9811
10707
|
- `--auth_style=token` (default): Exchanges credentials for a JWT Bearer token via `/api/login`.
|
|
9812
10708
|
- `--auth_style=basic`: Standard HTTP Basic Authentication.
|
|
9813
10709
|
- `--auth_style=query`: Passes credentials in URL query parameters (`?login=...&password=...`).
|
|
9814
|
-
- **API Key** (`--apikey`):
|
|
10710
|
+
- **Username / API Key** (`--username` and `--apikey`): the API key is the one of the user, so the user name is required.
|
|
9815
10711
|
- `--auth_style=token` (default): Exchanges the API key for a JWT Bearer token via `/api/login`.
|
|
9816
|
-
- `--auth_style=query`: Passes the API key in URL query
|
|
10712
|
+
- `--auth_style=query`: Passes the API key in URL query parameters (`?login=...&api_key=...`).
|
|
9817
10713
|
|
|
9818
10714
|
### Start a workflow
|
|
9819
10715
|
|
|
@@ -9900,7 +10796,7 @@ An issue has these fields:
|
|
|
9900
10796
|
|
|
9901
10797
|
Checked: format of the file (YAML, number of elements, plain format layout), attributes, `error_free`, action template keys, XML of the graph, `Start`, `End`, `Fail` and `Error` nodes, unique step names, step template, prerequisites, `Synch_factor`, steps that have no output or no prerequisite, references to outputs and parameters.
|
|
9902
10798
|
|
|
9903
|
-
With the specifications of plugins (see `plugins spec`), it also checks action templates and the inputs of steps, for the settings of each template:
|
|
10799
|
+
With the specifications of plugins (see `plugins spec show`), it also checks action templates and the inputs of steps, for the settings of each template:
|
|
9904
10800
|
|
|
9905
10801
|
- plugin class name, attributes of the template, and their values (type, allowed values),
|
|
9906
10802
|
- required inputs not mapped (`step.input_missing`),
|
|
@@ -9946,39 +10842,45 @@ Orchestrator does not refuse an incomplete resolution: `workflows import_with_co
|
|
|
9946
10842
|
```shell
|
|
9947
10843
|
--auth_style=query workflow list
|
|
9948
10844
|
--auth_style=token workflow list
|
|
10845
|
+
alerts list
|
|
9949
10846
|
health
|
|
9950
10847
|
info
|
|
9951
10848
|
journal files journal --query=@json:'{"details":"false"}'
|
|
9952
10849
|
monitors list node
|
|
9953
10850
|
monitors snapshot
|
|
9954
10851
|
plugins list
|
|
9955
|
-
plugins spec --
|
|
9956
|
-
plugins spec
|
|
9957
|
-
plugins spec
|
|
10852
|
+
plugins spec show AmazonS3Operation --format=yaml
|
|
10853
|
+
plugins spec show ascpclient inputs
|
|
10854
|
+
plugins spec toc --select=@json:'{"category":"Triggers"}'
|
|
10855
|
+
portlets list
|
|
9958
10856
|
processes
|
|
9959
10857
|
queues list
|
|
10858
|
+
queues stats
|
|
10859
|
+
tasks list
|
|
9960
10860
|
workflow check_import orch_wf_check.yml
|
|
9961
|
-
workflow details
|
|
9962
|
-
workflow export
|
|
9963
|
-
workflow inputs
|
|
10861
|
+
workflow details <WORKFLOW_ID>
|
|
10862
|
+
workflow export <WORKFLOW_ID>
|
|
10863
|
+
workflow inputs <WORKFLOW_ID>
|
|
9964
10864
|
workflow list
|
|
9965
|
-
workflow outputs
|
|
9966
|
-
workflow start
|
|
9967
|
-
workflow start
|
|
9968
|
-
workflow start
|
|
10865
|
+
workflow outputs <WORKFLOW_ID>
|
|
10866
|
+
workflow start <SLEEP_WORKFLOW_ID> --fields=work_order.id
|
|
10867
|
+
workflow start <WORKFLOW_ID> @: 'Param=world !'
|
|
10868
|
+
workflow start <WORKFLOW_ID> @: 'Param=world !' END @: step=ResultStep variable=Complete_status_message
|
|
10869
|
+
workflow status <WORKFLOW_ID>
|
|
9969
10870
|
workflow status ALL
|
|
9970
|
-
workflow
|
|
9971
|
-
workflow workorders
|
|
9972
|
-
|
|
9973
|
-
workflows development
|
|
9974
|
-
|
|
9975
|
-
workorder
|
|
9976
|
-
workorder
|
|
9977
|
-
workorder
|
|
9978
|
-
|
|
9979
|
-
|
|
9980
|
-
|
|
9981
|
-
|
|
10871
|
+
workflow workorders <WORKFLOW_ID>
|
|
10872
|
+
workflow workorders <WORKFLOW_ID> --fields=id --query.max_results=1
|
|
10873
|
+
workflows development guide toc
|
|
10874
|
+
workflows development templates section customruby
|
|
10875
|
+
workorder cancel <ID>
|
|
10876
|
+
workorder output <ID>
|
|
10877
|
+
workorder reset <ID>
|
|
10878
|
+
workorder status <ID>
|
|
10879
|
+
workorders stats
|
|
10880
|
+
workorders worksteps <ORCH_WF_START_SLEEP> --select.status='In Progress' --fields=id
|
|
10881
|
+
worksteps cancel <ID>
|
|
10882
|
+
worksteps stats
|
|
10883
|
+
worksteps status <ID>
|
|
9982
10884
|
```
|
|
9983
10885
|
|
|
9984
10886
|
## Plugin: `cos`: IBM Cloud Object Storage
|
|
@@ -10010,7 +10912,7 @@ If you already have these parameters, provide the following options to `ascli`:
|
|
|
10010
10912
|
Example: Create a Default Configuration
|
|
10011
10913
|
|
|
10012
10914
|
```shell
|
|
10013
|
-
ascli config preset
|
|
10915
|
+
ascli config preset set <COS_PRESET_NAME> @: bucket=mybucket endpoint=https://s3.us-east.cloud-object-storage.appdomain.cloud apikey=<API_KEY> crn=<CRN>
|
|
10014
10916
|
ascli config preset set default cos <COS_PRESET_NAME>
|
|
10015
10917
|
```
|
|
10016
10918
|
|
|
@@ -10080,7 +10982,7 @@ The required options for this method are:
|
|
|
10080
10982
|
Example: Create a Default Configuration
|
|
10081
10983
|
|
|
10082
10984
|
```shell
|
|
10083
|
-
ascli config preset
|
|
10985
|
+
ascli config preset set <COS_PRESET_NAME> @: bucket=mybucket service_credentials=@val:@json:@file:~/service_creds.json region=us-south
|
|
10084
10986
|
ascli config preset set default cos <COS_PRESET_NAME>
|
|
10085
10987
|
```
|
|
10086
10988
|
|
|
@@ -10104,8 +11006,8 @@ ascli cos node upload 'faux:///sample1G?1g'
|
|
|
10104
11006
|
|
|
10105
11007
|
```shell
|
|
10106
11008
|
node download test_file.bin --to-folder=.
|
|
10107
|
-
node info --bucket=my_bucket --endpoint=my_endpoint --apikey
|
|
10108
|
-
node info --bucket=my_bucket --region=my_region --service-credentials=@json:@file
|
|
11009
|
+
node info --bucket=my_bucket --endpoint=my_endpoint --apikey=<API_KEY> --crn=<RESOURCE_INSTANCE_ID>
|
|
11010
|
+
node info --bucket=my_bucket --region=my_region --service-credentials=@json:@file:<COS_SVC_CRED_FILE>
|
|
10109
11011
|
node info --log-level=trace2
|
|
10110
11012
|
node upload test_file.bin
|
|
10111
11013
|
```
|
|
@@ -10122,6 +11024,47 @@ health
|
|
|
10122
11024
|
info
|
|
10123
11025
|
```
|
|
10124
11026
|
|
|
11027
|
+
## Plugin: `transferd`: Transfer Daemon
|
|
11028
|
+
|
|
11029
|
+
Plugin `transferd` installs the IBM Aspera Transfer Daemon (`transferd`, which includes `ascp`) and runs it as a system service.
|
|
11030
|
+
See [Installing `ascp` through `transferd`](#installing-ascp-through-transferd) and [Transfer Daemon as a system service](#transfer-daemon-as-a-system-service).
|
|
11031
|
+
|
|
11032
|
+
The plugin also has client commands for a running daemon (for example one installed with `transferd service install`):
|
|
11033
|
+
|
|
11034
|
+
| Command | Action |
|
|
11035
|
+
|---------------------------------|---------------------------------------------------------------------|
|
|
11036
|
+
| `info` | Version of the API and information on the instance of the daemon. |
|
|
11037
|
+
| `transfers show <transfer_id>` | Status of a transfer: the daemon keeps it for some time after its end. |
|
|
11038
|
+
| `transfers cancel <transfer_id>`| Stop a transfer. |
|
|
11039
|
+
|
|
11040
|
+
They use the options `url` (mandatory, endpoint of the daemon, e.g. `127.0.0.1:55002`), `api_key` (if the daemon enables `authentication`) and `ca_file` (if the daemon enables `tls`).
|
|
11041
|
+
If a key is not given, it is taken from the same key of the option `--transfer`, when its agent is `transferd` (e.g. a preset used for transfers).
|
|
11042
|
+
The options of the plugin have priority.
|
|
11043
|
+
The daemon has no call to list the transfers.
|
|
11044
|
+
These commands require the gem `grpc`: it is loaded only when one of them runs, so that the other commands do not need it.
|
|
11045
|
+
If it is missing: `gem install grpc`.
|
|
11046
|
+
|
|
11047
|
+
```bash
|
|
11048
|
+
ascli transferd info --url=127.0.0.1:55002 --api-key=@vault:transferd.api_key
|
|
11049
|
+
```
|
|
11050
|
+
|
|
11051
|
+
> [!NOTE]
|
|
11052
|
+
> Commands `config transferd ...` and `config ascp install` are deprecated aliases of `transferd ...` and `transferd install`.
|
|
11053
|
+
|
|
11054
|
+
### Tested commands for `transferd`
|
|
11055
|
+
|
|
11056
|
+
> [!NOTE]
|
|
11057
|
+
> Add `ascli transferd` in front of the following commands:
|
|
11058
|
+
|
|
11059
|
+
```shell
|
|
11060
|
+
install
|
|
11061
|
+
install --sdk-folder=sdk_test_dir
|
|
11062
|
+
install 1.1.3
|
|
11063
|
+
list
|
|
11064
|
+
service configure --dry-run=yes @json:'{"service":{"user":"aspweb"},"config":{"port":55002}}'
|
|
11065
|
+
service spec
|
|
11066
|
+
```
|
|
11067
|
+
|
|
10125
11068
|
## Plugin: `faspio`: Faspio Gateway
|
|
10126
11069
|
|
|
10127
11070
|
IBM Aspera faspio Gateway is a high-performance proxy that bridges traditional TCP/UDP applications with the Aspera FASP protocol, enabling secure, ultra-fast transfers over any network, even with high latency or packet loss.
|
|
@@ -10135,7 +11078,7 @@ Using `ascli`, you can remotely create and manage bridges on faspio Gateway, sim
|
|
|
10135
11078
|
|
|
10136
11079
|
```shell
|
|
10137
11080
|
bridges create @json:'{"name":"test1","local":{"protocol":"tcp","tls_enabled":false,"port":"3000","bind_address":"127.0.0.1"},"forward":{"protocol":"fasp","tls_enabled":false,"port":"3994","bind_address":"127.0.0.1","host":["10.0.0.1"]}}'
|
|
10138
|
-
bridges delete --bulk=yes @json:<
|
|
11081
|
+
bridges delete --bulk=yes @json:<FASPIO_BCLEAN_LIST>
|
|
10139
11082
|
bridges list
|
|
10140
11083
|
bridges show 1
|
|
10141
11084
|
health
|
|
@@ -10338,7 +11281,7 @@ For example:
|
|
|
10338
11281
|
```shell
|
|
10339
11282
|
su -s /bin/bash - xfer
|
|
10340
11283
|
|
|
10341
|
-
ascli config preset
|
|
11284
|
+
ascli config preset set <PREVIEW_PRESET_NAME> @: url=https://localhost:9092 username=<ACCESS_KEY> password=<SECRET> skip_types=office lock_port=12346
|
|
10342
11285
|
|
|
10343
11286
|
ascli config preset set default preview <PREVIEW_PRESET_NAME>
|
|
10344
11287
|
```
|
|
@@ -10359,7 +11302,7 @@ This shall list the contents of the storage root of the access key.
|
|
|
10359
11302
|
When generating preview files, the following options can be modified on command line (or in a preset):
|
|
10360
11303
|
|
|
10361
11304
|
| Field | Type | Description |
|
|
10362
|
-
|
|
11305
|
+
| ------------------- | ------------ | -------------------------------------------------------------------------------- |
|
|
10363
11306
|
| `blend_fps` | `Integer` | MP4 video preview (`blend`): frames per second.<br/>Default: `15`. |
|
|
10364
11307
|
| `blend_keyframes` | `Integer` | MP4 video preview (`blend`): number of key frames.<br/>Default: `30`. |
|
|
10365
11308
|
| `blend_pauseframes` | `Integer` | MP4 video preview (`blend`): number of pause frames (repetitions of each key frame).<br/>Default: `3`. |
|
|
@@ -10367,17 +11310,17 @@ When generating preview files, the following options can be modified on command
|
|
|
10367
11310
|
| `clips_count` | `Integer` | MP4 video preview (`clips`): number of clips.<br/>Default: `5`. |
|
|
10368
11311
|
| `clips_length` | `Integer` | Video: length (in seconds) of each clip of MP4 video preview (`clips`), and of `animated` PNG thumbnail.<br/>Default: `5`. |
|
|
10369
11312
|
| `max_size` | `Integer` | Maximum size (in bytes) of a preview file: a warning is logged if exceeded.<br/>Default: `16777216`. |
|
|
10370
|
-
| `office_conversion` | `String` | PNG thumbnail of office document: conversion tool.<br/>Allowed values: `soffice`, `unoconv`.<br/>Default: `soffice`. |
|
|
11313
|
+
| `office_conversion` | `Enum[String]` | PNG thumbnail of office document: conversion tool.<br/>Allowed values: `soffice`, `unoconv`.<br/>Default: `soffice`. |
|
|
11314
|
+
| `reencode_ffmpeg` | `Hash` | MP4 video preview (`reencode`): `ffmpeg` options replacing the default ones.<br/>Default: `{}`. |
|
|
10371
11315
|
| `reencode_ffmpeg.in` | `Array` | Input options. |
|
|
10372
11316
|
| `reencode_ffmpeg.out` | `Array` | Output options. |
|
|
10373
|
-
| `reencode_ffmpeg` | `Hash` | MP4 video preview (`reencode`): `ffmpeg` options replacing the default ones.<br/>Default: `{}`. |
|
|
10374
11317
|
| `thumb_img_size` | `Integer` | PNG thumbnail of image, PDF, office document or text: size (in pixels).<br/>Default: `800`. |
|
|
10375
11318
|
| `thumb_text_font` | `String` | PNG thumbnail of text: font name, as listed by `magick identify -list font`.<br/>Default: `Courier`. |
|
|
10376
11319
|
| `thumb_vid_fraction` | `Number` | PNG thumbnail of video (`fixed`): position of the snapshot, as a fraction of the video duration.<br/>Default: `0.1`. |
|
|
10377
11320
|
| `thumb_vid_scale` | `String` | PNG thumbnail of video: frame size, as `ffmpeg` scale filter argument.<br/>Default: `-1:min(ih,100)`. |
|
|
10378
11321
|
| `video_codec` | `String` | MP4 video preview (`reencode`): `ffmpeg` video codec, e.g. `libx264`, `h264_videotoolbox`, `h264_nvenc`. Default: first available H.264 encoder. |
|
|
10379
|
-
| `video_conversion` | `String` | MP4 video preview: generation method. `reencode`: re-encode the beginning of the video, `blend`: key frames with transitions, `clips`: concatenation of short clips.<br/>Allowed values: `reencode`, `blend`, `clips`.<br/>Default: `reencode`. |
|
|
10380
|
-
| `video_png_conv` | `String` | PNG thumbnail of video: generation method. `fixed`: single frame, `animated`: animated PNG.<br/>Allowed values: `fixed`, `animated`.<br/>Default: `fixed`. |
|
|
11322
|
+
| `video_conversion` | `Enum[String]` | MP4 video preview: generation method. `reencode`: re-encode the beginning of the video, `blend`: key frames with transitions, `clips`: concatenation of short clips.<br/>Allowed values: `reencode`, `blend`, `clips`.<br/>Default: `reencode`. |
|
|
11323
|
+
| `video_png_conv` | `Enum[String]` | PNG thumbnail of video: generation method. `fixed`: single frame, `animated`: animated PNG.<br/>Allowed values: `fixed`, `animated`.<br/>Default: `fixed`. |
|
|
10381
11324
|
| `video_scale` | `String` | MP4 video preview: frame size, as `ffmpeg` scale filter argument.<br/>Default: `min(iw,360):-2`. |
|
|
10382
11325
|
| `video_start_sec` | `Integer` | Video: start offset (in seconds) of MP4 video preview and of `animated` PNG thumbnail.<br/>Default: `10`. |
|
|
10383
11326
|
|
|
@@ -10539,10 +11482,6 @@ trevents --once-only=yes --skip-types=office --log-level=info
|
|
|
10539
11482
|
|
|
10540
11483
|
## Plugin: `mcp`: Model Context Protocol server
|
|
10541
11484
|
|
|
10542
|
-
> [!WARNING]
|
|
10543
|
-
> This plugin is **experimental**.
|
|
10544
|
-
> The interface, options, and behavior may change in future releases without notice.
|
|
10545
|
-
|
|
10546
11485
|
The `mcp` plugin starts a [Model Context Protocol (MCP)](https://modelcontextprotocol.io/) server that exposes `ascli` to AI assistants and LLM-based tools.
|
|
10547
11486
|
The server registers a single tool, `execute_ascli_command`, which executes any `ascli` command in-process and returns the result as text.
|
|
10548
11487
|
|
|
@@ -10613,6 +11552,8 @@ Keys of a transport are refused with the other transport.
|
|
|
10613
11552
|
> [!NOTE]
|
|
10614
11553
|
> `port` and `bind` are deprecated: use `url`, for example, `url=http://0.0.0.0:8080` instead of `port=8080 bind=0.0.0.0`.
|
|
10615
11554
|
|
|
11555
|
+
For the addresses the server listens on, and HTTPS, see [Web service](#web-service).
|
|
11556
|
+
|
|
10616
11557
|
### Security
|
|
10617
11558
|
|
|
10618
11559
|
> [!WARNING]
|
|
@@ -10623,7 +11564,7 @@ With the `http` transport:
|
|
|
10623
11564
|
|
|
10624
11565
|
- With `oauth`, the consent page asks for `auth_token` as access code, else anyone reaching the server could approve its own client.
|
|
10625
11566
|
It shows where the authorization is sent (origin of `redirect_uri`): allow only if it is the expected AI client, for example `http://127.0.0.1:<port>`.
|
|
10626
|
-
- For local-only deployments (hosts of `url` and `public_url` are loopback
|
|
11567
|
+
- For local-only deployments (hosts of `url` and `public_url` are loopback, see [Web service](#web-service)), `auth_token` and `oauth` are optional but recommended: on a host shared with other users, they can also reach the server.
|
|
10627
11568
|
Without `auth_token`, the consent page only asks to click **Allow**.
|
|
10628
11569
|
- `auth_token` and `oauth` can coexist: a request is accepted if it carries a valid static token **or** a valid OAuth access token.
|
|
10629
11570
|
- A weak `auth_token` is refused at startup (see `auth_token_min_bits`): generate it with `openssl rand -hex 32`.
|
|
@@ -10636,9 +11577,12 @@ With both transports:
|
|
|
10636
11577
|
- Extended value `@stdin:` is refused.
|
|
10637
11578
|
- `@secret:` is entered by the user on a web page, see [Secrets entered in a web page](#secrets-entered-in-a-web-page).
|
|
10638
11579
|
- Secrets are hidden in responses, also a value shorter than 8 characters as a word in a text (for example, a short password in an error message).
|
|
10639
|
-
- The [Security Level](#security-level) is `high` by default: `@ruby:`, `@file
|
|
11580
|
+
- The [Security Level](#security-level) is `high` by default: `@ruby:`, `@file:` (also in the parameters of stores of option `vault`), `@uri:`, and `@env:` are refused, and a secret must be the whole value: hidden in results, it cannot be processed by another extended value.
|
|
10640
11581
|
It applies to commands sent by the client, and to presets, because the client can modify presets.
|
|
10641
11582
|
Commands sent by the client cannot change option `security`.
|
|
11583
|
+
Features that execute code, such as option `notify_template` or command `config plugins create`, plugins, and writing to a file chosen by the client (option `out.file`), are refused, see [Security Level](#security-level).
|
|
11584
|
+
Files can be written (for example by `config download`, or by a transfer that receives files) only in `writable_paths`, none by default: without it, the client cannot download files.
|
|
11585
|
+
It applies to files written on the system that runs the server: not to a transfer with agent `node` (`--transfer=node`), which writes on the node.
|
|
10642
11586
|
|
|
10643
11587
|
To use another level, set option `security` when starting the server, for example:
|
|
10644
11588
|
|
|
@@ -10646,12 +11590,20 @@ To use another level, set option `security` when starting the server, for exampl
|
|
|
10646
11590
|
ascli mcp server --security.level=medium --security.allowed_paths.0=$HOME/.aspera/ascli/my_private_key
|
|
10647
11591
|
```
|
|
10648
11592
|
|
|
11593
|
+
To let the client download files in a folder, keep the level `high` and give the folder:
|
|
11594
|
+
|
|
11595
|
+
```shell
|
|
11596
|
+
ascli mcp server --security.writable_paths.0=$HOME/Downloads/ascli
|
|
11597
|
+
```
|
|
11598
|
+
|
|
10649
11599
|
> [!NOTE]
|
|
10650
11600
|
> A level set by option also applies to the parameters of the `server` command: for example, `auth_token=@env:MCP_TOKEN` requires level `low`.
|
|
10651
11601
|
> Without option `security`, the parameters of the `server` command are not restricted.
|
|
10652
11602
|
>
|
|
10653
11603
|
> A preset created by `aoc wizard` or `faspex5 wizard` reads the private key with `@file:`.
|
|
10654
11604
|
> With level `high`, either store the key in the preset (`ascli config preset set <AOC_ORG> private_key @file:<PATH>`, without `@val:`), or use level `medium` with the key in `allowed_paths`.
|
|
11605
|
+
>
|
|
11606
|
+
> In the same way, a secret of a vault read from a file (for example, `token` of HashiCorp Vault: `@file:<path>`) requires level `medium` with the file in `allowed_paths`.
|
|
10655
11607
|
|
|
10656
11608
|
### HTTP endpoints
|
|
10657
11609
|
|
|
@@ -10873,7 +11825,7 @@ For [**IBM Bob**](https://bob.ibm.com/docs/ide/configuration/mcp/mcp-in-bob), ad
|
|
|
10873
11825
|
}
|
|
10874
11826
|
```
|
|
10875
11827
|
|
|
10876
|
-
|
|
11828
|
+
Most other clients (Claude Desktop, Cursor, and so on) use the same `mcpServers` format, VS Code uses `servers` (see below).
|
|
10877
11829
|
|
|
10878
11830
|
##### Claude Desktop `stdio`
|
|
10879
11831
|
|
|
@@ -10893,6 +11845,47 @@ Place this section in `mcpServers`:
|
|
|
10893
11845
|
}
|
|
10894
11846
|
```
|
|
10895
11847
|
|
|
11848
|
+
##### Claude Code `stdio`
|
|
11849
|
+
|
|
11850
|
+
For [**Claude Code**](https://code.claude.com/docs/en/mcp), register the server with the command line (option `--scope user` for all projects):
|
|
11851
|
+
|
|
11852
|
+
```shell
|
|
11853
|
+
claude mcp add ascli -- ascli mcp server
|
|
11854
|
+
```
|
|
11855
|
+
|
|
11856
|
+
In a shell, Claude Code can also execute `ascli` directly: install the agent skill instead (see [Leveraging AI Assistance](#leveraging-ai-assistance)).
|
|
11857
|
+
|
|
11858
|
+
##### VS Code `stdio`
|
|
11859
|
+
|
|
11860
|
+
For **VS Code** (GitHub Copilot agent mode), add to `.vscode/mcp.json` in your workspace (or run command **MCP: Add Server**):
|
|
11861
|
+
|
|
11862
|
+
```json
|
|
11863
|
+
{
|
|
11864
|
+
"servers": {
|
|
11865
|
+
"ascli": {
|
|
11866
|
+
"type": "stdio",
|
|
11867
|
+
"command": "ascli",
|
|
11868
|
+
"args": ["mcp", "server"]
|
|
11869
|
+
}
|
|
11870
|
+
}
|
|
11871
|
+
}
|
|
11872
|
+
```
|
|
11873
|
+
|
|
11874
|
+
##### Cursor `stdio`
|
|
11875
|
+
|
|
11876
|
+
For **Cursor**, add to `.cursor/mcp.json` in your project (or `~/.cursor/mcp.json` for global configuration):
|
|
11877
|
+
|
|
11878
|
+
```json
|
|
11879
|
+
{
|
|
11880
|
+
"mcpServers": {
|
|
11881
|
+
"ascli": {
|
|
11882
|
+
"command": "ascli",
|
|
11883
|
+
"args": ["mcp", "server"]
|
|
11884
|
+
}
|
|
11885
|
+
}
|
|
11886
|
+
}
|
|
11887
|
+
```
|
|
11888
|
+
|
|
10896
11889
|
##### Development mode for `stdio`
|
|
10897
11890
|
|
|
10898
11891
|
If the `ascli` gem is not installed and you are running directly from the source tree, Ruby will not find the `lib/` directory automatically.
|
|
@@ -11131,10 +12124,10 @@ ascli config sync spec
|
|
|
11131
12124
|
> The options listed in the **Description** column correspond to the equivalent parameters used by the low-level `async` command.
|
|
11132
12125
|
|
|
11133
12126
|
| Field | Type | Description |
|
|
11134
|
-
|
|
12127
|
+
| ---------------------------------------- | ------------- | -------------------------------------------------------------------------------- |
|
|
11135
12128
|
| `ascp_dir` | `String` | Directory containing ascp executable to use. |
|
|
11136
12129
|
| `assume_no_mods` | `Bool` | Assume that the directory structure has not been modified.<br/>Default: `false`.<br/>(`--assume-no-mods`) |
|
|
11137
|
-
| `checksum` | `String` | Use the specified checksum type. Default is none on cloud storage.<br/>Allowed values: `sha1`, `md5`, `sha1_sparse`, `md5_sparse`, `none`.<br/>Default: `sha1_sparse`.<br/>(`--checksum={enum}`)(-k) |
|
|
12130
|
+
| `checksum` | `Enum[String]` | Use the specified checksum type. Default is none on cloud storage.<br/>Allowed values: `sha1`, `md5`, `sha1_sparse`, `md5_sparse`, `none`.<br/>Default: `sha1_sparse`.<br/>(`--checksum={enum}`)(-k) |
|
|
11138
12131
|
| `clean_excluded` | `Bool` | Removes any existing entries in the snapshot database for excluded paths<br/>Default: `false`.<br/>(`--clean-excluded`) |
|
|
11139
12132
|
| `cookie` | `String` | User-defined identification string.<br/>(`--cookie={string}`) |
|
|
11140
12133
|
| `cooloff_max_seconds` | `Integer` | Wait up to the specified time for a file to stop changing before skipping synchronization of the file. 0 for disabled<br/>Default: `0`.<br/>(`--cooloff-max={integer}`) |
|
|
@@ -11143,19 +12136,20 @@ ascli config sync spec
|
|
|
11143
12136
|
| `db_cache_size` | `Integer` | Specify DB cache size.<br/>Default: `16000`. |
|
|
11144
12137
|
| `db_journal_off` | `Bool` | Turn off DB journal.<br/>Default: `false`. |
|
|
11145
12138
|
| `db_sync_on` | `Bool` | Enable synchronous write in DB.<br/>Default: `false`. |
|
|
11146
|
-
| `dedup` | `String` | Take the specified action when async detects duplicate files on the source.<br/>Allowed values: `copy`, `inode`, `hardlink`, `none`.<br/>Default: `none`.<br/>(`--dedup={enum}`) |
|
|
12139
|
+
| `dedup` | `Enum[String]` | Take the specified action when async detects duplicate files on the source.<br/>Allowed values: `copy`, `inode`, `hardlink`, `none`.<br/>Default: `none`.<br/>(`--dedup={enum}`) |
|
|
11147
12140
|
| `delete_before` | `Bool` | Schedule deletes before transfers.<br/>Default: `false`.<br/>(`--delete-before`) |
|
|
11148
12141
|
| `delete_delay` | `Bool` | Delay actual deletes until the end of the synchronization.<br/>Default: `false`.<br/>(`--delete-delay`) |
|
|
11149
|
-
| `direction` | `String` | The direction of replication relative to the local.<br/>Allowed values: `bidi`, `pull`, `push`.<br/>Default: `push`.<br/>(`--direction={enum}`)(-K) |
|
|
12142
|
+
| `direction` | `Enum[String]` | The direction of replication relative to the local.<br/>Allowed values: `bidi`, `pull`, `push`.<br/>Default: `push`.<br/>(`--direction={enum}`)(-K) |
|
|
12143
|
+
| `exclude_dirs_older_than` | `Hash` | Don't scan directories with a recursive modified time older than absolute or async start time - relative_seconds |
|
|
11150
12144
|
| `exclude_dirs_older_than.absolute` | `String` | UTC timestamp. Empty value for disabled. |
|
|
11151
12145
|
| `exclude_dirs_older_than.relative_seconds` | `Integer` | Relative to async start time. `-1` for disabled.<br/>Default: `-1`. |
|
|
11152
|
-
| `exclude_dirs_older_than` | `Hash` | Don't scan directories with a recursive modified time older than absolute or async start time - relative_seconds |
|
|
11153
|
-
| `filters[].rule` | `String` | The rule for the filter.<br/>Required.<br/>Allowed values: `include`, `exclude`, `include_from`, `exclude_from`. |
|
|
11154
|
-
| `filters[].value` | `String` | On include or exclude, the filter's pattern. On include_from or exclude_from, the path containing filter specifications<br/>Required. |
|
|
11155
12146
|
| `filters` | `Array[Hash]` | The filters allow to further specify which files have to be excluded and included from the transfer list. Each filter is defined by a rule and a value. Order of filters matters |
|
|
12147
|
+
| `filters[].rule` | `Enum[String]` | The rule for the filter.<br/>Required.<br/>Allowed values: `include`, `exclude`, `include_from`, `exclude_from`. |
|
|
12148
|
+
| `filters[].value` | `String` | On include or exclude, the filter's pattern. On include_from or exclude_from, the path containing filter specifications<br/>Required. |
|
|
11156
12149
|
| `ignore_delete` | `Bool` | Do not copy removals to the peer.<br/>Default: `false`.<br/>(`--ignore-delete`) |
|
|
11157
12150
|
| `ignore_mode` | `Bool` | Source files that have had their mode changed after the initial transfer will not update the destination file mode.<br/>Default: `false`.<br/>(`--ignore-mode`) |
|
|
11158
12151
|
| `ignore_remote_host_sync_name` | `Bool` | Do not check that the remote host being used for the current transfer matches the host used when the local database was created<br/>Default: `false`. |
|
|
12152
|
+
| `local` | `Hash` | Required. |
|
|
11159
12153
|
| `local.pass` | `String` | Authenticate the local async with the specified password. |
|
|
11160
12154
|
| `local.path` | `String` | The directory to be synchronized on the local host.<br/>Required.<br/>(`--local-dir={string}`)(-d) |
|
|
11161
12155
|
| `local_apply_docroot` | `Bool` | Prepend the docroot to the directory on the local host.<br/>Default: `false`.<br/>(`--apply-local-docroot`) |
|
|
@@ -11167,26 +12161,25 @@ ascli config sync spec
|
|
|
11167
12161
|
| `local_keep_dir` | `String` | Move deleted files into the specified directory on the local host.<br/>(`--keep-dir-local={string}`) |
|
|
11168
12162
|
| `local_mount_signature` | `String` | Verify that the file system is mounted by the existence of this file on the local host.<br/>(`--local-mount-signature={string}`) |
|
|
11169
12163
|
| `local_move_cache_timeout_seconds` | `Integer` | Delay in seconds before aborting moving a file from local cache to final destination. `-1` for disabled.<br/>Default: `-1`.<br/>(`--local-move-cache-timeout={integer}`) |
|
|
11170
|
-
| `local_preserve_acls` | `String` | Preserve access control lists on the local host.<br/>Allowed values: `native`, `metafile`, `none`.<br/>Default: `none`.<br/>(`--preserve-acls={enum}`) |
|
|
11171
|
-
| `local_preserve_xattrs` | `String` | Preserve extended attributes on the local.<br/>Allowed values: `native`, `metafile`, `none`.<br/>Default: `none`.<br/>(`--preserve-xattrs={enum}`) |
|
|
12164
|
+
| `local_preserve_acls` | `Enum[String]` | Preserve access control lists on the local host.<br/>Allowed values: `native`, `metafile`, `none`.<br/>Default: `none`.<br/>(`--preserve-acls={enum}`) |
|
|
12165
|
+
| `local_preserve_xattrs` | `Enum[String]` | Preserve extended attributes on the local.<br/>Allowed values: `native`, `metafile`, `none`.<br/>Default: `none`.<br/>(`--preserve-xattrs={enum}`) |
|
|
11172
12166
|
| `local_scan_interval_milliseconds` | `Integer` | Enable periodic scans on the local host during a continuous sync. `-1` for disabled. On the command line, the value is a duration, e.g. `1h 30m`, `2s500ms`, `5:30`, `1d 02:00:00.250`. A plain number is in seconds. Stored in milliseconds.<br/>Default: `-1`.<br/>(`--scan-interval={integer}`) |
|
|
11173
12167
|
| `local_scan_threads` | `Integer` | Number of directory scanning threads on the local host. Value must be between 1 and 99<br/>Default: `1`.<br/>(`--scan-threads={integer}`) |
|
|
11174
12168
|
| `local_stat_cache_size` | `Integer` | Set stat cache size on the local host. 0 for disabled.<br/>Default: `0`. |
|
|
11175
|
-
| `
|
|
11176
|
-
| `log.level` | `String` | Use the specified log level.<br/>Allowed values: `log`, `dbg1`, `dbg2`.<br/>Default: `log`.<br/>(special:`-D`) |
|
|
12169
|
+
| `log` | `Hash` | |
|
|
12170
|
+
| `log.level` | `Enum[String]` | Use the specified log level.<br/>Allowed values: `log`, `dbg1`, `dbg2`.<br/>Default: `log`.<br/>(special:`-D`) |
|
|
11177
12171
|
| `log.local_dir` | `String` | Use the specified logging directory on the local host.<br/>(`--alt-logdir={string}`)(-L) |
|
|
11178
12172
|
| `log.remote_dir` | `String` | Use the specified logging directory on the remote host.<br/>(`--remote-logdir={string}`)(-R) |
|
|
11179
|
-
| `log` | `Hash` | |
|
|
11180
12173
|
| `manifest_path` | `String` | A directory path where ascp will create manifest TEXT files (passed to ascp as --file-manifest-path) |
|
|
11181
12174
|
| `mirror` | `Bool` | Force the pulling side to be exactly like the pushing side, removing files on the destination that don't exist on the source and resending source files that don't have an exact match on the destination. Cannot be used in bi-directional mode.<br/>Default: `false`.<br/>(`--mirror`) |
|
|
11182
|
-
| `mode` | `String` | Specify whether async runs continuously or not. In `one_time` mode, async stops after the first full synchronization. `continuous` supported only if the source is Windows or Linux.<br/>Allowed values: `one_time`, `continuous`.<br/>Default: `one_time`.<br/>(special:`--continuous`)(-C) |
|
|
12175
|
+
| `mode` | `Enum[String]` | Specify whether async runs continuously or not. In `one_time` mode, async stops after the first full synchronization. `continuous` supported only if the source is Windows or Linux.<br/>Allowed values: `one_time`, `continuous`.<br/>Default: `one_time`.<br/>(special:`--continuous`)(-C) |
|
|
11183
12176
|
| `monitor_buffer_size` | `Integer` | Bytes to allocate for the change monitor buffer. Applies to any Windows machine on either side. `-1` to use the computed value.<br/>Default: `-1`. |
|
|
11184
12177
|
| `name` | `String` | Name of the synchronization pair.<br/>Required.<br/>(`--name={string}`)(-N) |
|
|
11185
12178
|
| `no_log` | `String` | Suppress log messages for ITEM. The only currently supported ITEM is 'stats', which suppresses both STATS and PROG log messages.<br/>(`--no-log={string}`) |
|
|
11186
12179
|
| `no_preserve_root_attrs` | `Bool` | Disable the preservation of attributes on the Sync root.<br/>Default: `false`.<br/>(`--no-preserve-root-attrs`) |
|
|
11187
12180
|
| `no_scan` | `Bool` | Skip initial scanning.<br/>Default: `false`.<br/>(`--no-scan`) |
|
|
11188
12181
|
| `notifications_sharing_retry_max` | `Integer` | Retry processing filesystem notifications up to the specified maximum number after a sharing violation.<br/>Default: `3`. |
|
|
11189
|
-
| `overwrite` | `String` | Overwrite files according to the specified policy. Default is determined by the direction: `conflict` for `bidi`, otherwise `always`.<br/>Allowed values: `always`, `older`, `conflict`.<br/>(`--overwrite={enum}`)(-o) |
|
|
12182
|
+
| `overwrite` | `Enum[String]` | Overwrite files according to the specified policy. Default is determined by the direction: `conflict` for `bidi`, otherwise `always`.<br/>Allowed values: `always`, `older`, `conflict`.<br/>(`--overwrite={enum}`)(-o) |
|
|
11190
12183
|
| `pending_max` | `Integer` | Allow the maximum number of files that are pending transfer to be no more than the specified number.<br/>Default: `2000`.<br/>(`--pending-max={integer}`) |
|
|
11191
12184
|
| `preserve_access_time` | `Bool` | Preserve file access time from the source to the destination.<br/>Default: `false`.<br/>(`--preserve-access-time`) |
|
|
11192
12185
|
| `preserve_creation_time` | `Bool` | Preserve file creation time from the source to the destination.<br/>Default: `false`.<br/>(`--preserve-creation-time`) |
|
|
@@ -11197,21 +12190,22 @@ ascli config sync spec
|
|
|
11197
12190
|
| `preserve_object_metadata` | `Bool` | Preserve object metadata from the source to the destination.<br/>Default: `false`.<br/>(`--preserve-object-metadata`) |
|
|
11198
12191
|
| `preserve_uid` | `Bool` | Preserve the file owner's UID.<br/>Default: `false`.<br/>(`--preserve-uid`)(-u) |
|
|
11199
12192
|
| `quiet` | `Bool` | Disable progress display.<br/>Default: `true`.<br/>(`--quiet`)(-q) |
|
|
11200
|
-
| `remote
|
|
12193
|
+
| `remote` | `Hash` | Required. |
|
|
12194
|
+
| `remote.connect_mode` | `Enum[String]` | Define how to connect to the remote.<br/>Allowed values: `ssh`, `ws`.<br/>Default: `ssh`.<br/>(special:`--ws-connect`) |
|
|
11201
12195
|
| `remote.fingerprint` | `String` | Check it against server SSH host key fingerprint. |
|
|
11202
12196
|
| `remote.host` | `String` | Use the specified host name or address of the remote host.<br/>Required.<br/>(`--host={string}`) |
|
|
11203
12197
|
| `remote.pass` | `String` | Authenticate the transfer with the specified password.<br/>(`--pass={string}`)(-w) |
|
|
11204
12198
|
| `remote.path` | `String` | Synchronize the specified directory on the remote host.<br/>Required.<br/>(`--remote-dir={string}`)(-r) |
|
|
11205
12199
|
| `remote.port` | `Integer` | Use the specified TCP port for SSH. Used when connect_mode is `ssh`<br/>Default: `22`.<br/>(`--tcp-port={integer}`)(-P) |
|
|
11206
12200
|
| `remote.private_key_paths` | `Array[String]` | Authenticate with the specified SSH private key file.<br/>(`--private-key-path={array}`)(-i) |
|
|
12201
|
+
| `remote.proxy` | `Hash` | Specify the address of the Aspera high-speed proxy server.<br/>(special:`--proxy={object}`) |
|
|
11207
12202
|
| `remote.proxy.host` | `String` | Use the specified host name or address of the proxy. |
|
|
11208
12203
|
| `remote.proxy.pass` | `String` | Authenticate to the proxy with the specified password. |
|
|
11209
12204
|
| `remote.proxy.port` | `Integer` | Use the specified port. Default is 9091 for dnat, 9092 for dnats. |
|
|
11210
|
-
| `remote.proxy.protocol` | `String` | The protocol to be used.<br/>Allowed values: `none`, `dnat`, `dnats`.<br/>Default: `none`. |
|
|
12205
|
+
| `remote.proxy.protocol` | `Enum[String]` | The protocol to be used.<br/>Allowed values: `none`, `dnat`, `dnats`.<br/>Default: `none`. |
|
|
11211
12206
|
| `remote.proxy.user` | `String` | Authenticate to the proxy with the specified username. |
|
|
11212
|
-
| `remote.proxy` | `Hash` | Specify the address of the Aspera high-speed proxy server.<br/>(special:`--proxy={object}`) |
|
|
11213
|
-
| `remote.token_node_user` | `String` | Node API user identity associated with the token. Required for node user bearer tokens |
|
|
11214
12207
|
| `remote.token` | `String` | Token string passed to server's authentication service. |
|
|
12208
|
+
| `remote.token_node_user` | `String` | Node API user identity associated with the token. Required for node user bearer tokens |
|
|
11215
12209
|
| `remote.user` | `String` | Authenticate the transfer with the specified username.<br/>Required.<br/>(`--user={string}`) |
|
|
11216
12210
|
| `remote.ws_port` | `Integer` | Use the specified port for Websocket. Used when connect_mode is `ws`.<br/>Default: `9093`. |
|
|
11217
12211
|
| `remote_checksum_threads` | `Integer` | Maximum number of threads to do checksum on the remote host. Value must be between 1 and 99<br/>Default: `4`.<br/>(`--remote-checksum-threads={integer}`) |
|
|
@@ -11222,46 +12216,45 @@ ascli config sync spec
|
|
|
11222
12216
|
| `remote_keep_dir` | `String` | Move deleted files into the specified directory on the remote host.<br/>(`--keep-dir-remote={string}`) |
|
|
11223
12217
|
| `remote_mount_signature` | `String` | Verify that the file system is mounted by the existence of this file on the remote host.<br/>(`--remote-mount-signature={string}`) |
|
|
11224
12218
|
| `remote_move_cache_timeout_seconds` | `Integer` | Delay in seconds before aborting moving a file from remote cache to final destination. `-1` for disabled.<br/>Default: `-1`.<br/>(`--remote-move-cache-timeout={integer}`) |
|
|
11225
|
-
| `remote_preserve_acls` | `String` | Preserve access control lists on the remote host. If not specified, the default behavior is to use the same storage mode as specified by `preserve_acls`.<br/>Allowed values: `native`, `metafile`, `none`.<br/>(`--remote-preserve-acls={enum}`) |
|
|
11226
|
-
| `remote_preserve_xattrs` | `String` | Preserve extended attributes on the remote host. If not specified, the default behavior is to use the same storage mode as specified by `preserve_xattrs`.<br/>Allowed values: `native`, `metafile`, `none`.<br/>(`--remote-preserve-xattrs={enum}`) |
|
|
12219
|
+
| `remote_preserve_acls` | `Enum[String]` | Preserve access control lists on the remote host. If not specified, the default behavior is to use the same storage mode as specified by `preserve_acls`.<br/>Allowed values: `native`, `metafile`, `none`.<br/>(`--remote-preserve-acls={enum}`) |
|
|
12220
|
+
| `remote_preserve_xattrs` | `Enum[String]` | Preserve extended attributes on the remote host. If not specified, the default behavior is to use the same storage mode as specified by `preserve_xattrs`.<br/>Allowed values: `native`, `metafile`, `none`.<br/>(`--remote-preserve-xattrs={enum}`) |
|
|
11227
12221
|
| `remote_scan_interval_milliseconds` | `Integer` | Enable periodic scans on the remote host. `-1` for disabled. On the command line, the value is a duration, e.g. `1h 30m`, `2s500ms`, `5:30`, `1d 02:00:00.250`. A plain number is in seconds. Stored in milliseconds.<br/>Default: `-1`.<br/>(special:`--remote-scan-interval={integer}`) |
|
|
11228
12222
|
| `remote_scan_threads` | `Integer` | Number of directory scanning threads on the remote host. Value must be between 1 and 99.<br/>Default: `1`.<br/>(`--remote-scan-threads={integer}`) |
|
|
11229
12223
|
| `remote_stat_cache_size` | `Integer` | Set stat cache size on the remote host. 0 for disabled.<br/>Default: `0`. |
|
|
11230
|
-
| `remote` | `Hash` | Required. |
|
|
11231
12224
|
| `remove_after_transfer` | `Bool` | Remove source files after they are successfully synchronized.<br/>Default: `false`.<br/>(`--remove-after-transfer`) |
|
|
11232
12225
|
| `reset` | `Bool` | Clear the snapshot database and rescan the synchronized directories and files to create a fresh snapshot<br/>Default: `false`.<br/>(`--reset`)(-x) |
|
|
12226
|
+
| `resume` | `Hash` | Partial transfers may exist if communication disruptions caused the underlying ascp processes to terminate early. Note that transfer resumption can only happen if the `reset` option is disabled. If an async session starts with `reset` enabled and resume enabled, transfers interrupted during that session will be resumable, but only if async is then restarted with 'reset' disabled. |
|
|
11233
12227
|
| `resume.enabled` | `Bool` | Enable the possibility of resuming individual file transfers between async sessions.<br/>Default: `false`. |
|
|
11234
12228
|
| `resume.max_age` | `Integer` | Sets the age limit in days for temporary files that will be preserved on cleanup (usually at async's start and stop) for potential transfer resume. Temp files older than the given value will be removed regardless of whether they might be resumable.<br/>Default: `5`.<br/>(`--resume-age-days={integer}`) |
|
|
11235
12229
|
| `resume.min_size` | `Integer` | This field specifies the minimum size of files that will be allowed to resume.<br/>Default: `1048576`.<br/>(`--support-resume={integer}`) |
|
|
11236
12230
|
| `resume_scan` | `Bool` | Resume the scan from where the previous execution left off.<br/>Default: `false`.<br/>(`--resume-scan`) |
|
|
11237
|
-
| `resume` | `Hash` | Partial transfers may exist if communication disruptions caused the underlying ascp processes to terminate early. Note that transfer resumption can only happen if the `reset` option is disabled. If an async session starts with `reset` enabled and resume enabled, transfers interrupted during that session will be resumable, but only if async is then restarted with 'reset' disabled. |
|
|
11238
12231
|
| `scan_dir_rename` | `Bool` | Enable the detection of renamed directories and files compared to the previous scan, based on matching inodes<br/>Default: `false`.<br/>(`--scan-dir-rename`) |
|
|
11239
12232
|
| `scan_file_rename` | `Bool` | Enable the detection of renamed files compared to the previous scan, based on matching inodes.<br/>Default: `false`.<br/>(`--scan-file-rename`) |
|
|
11240
|
-
| `scan_intensity` | `String` | Scan at the set intensity. `vlow` minimizes system activity. `vhigh` maximizes system activity by continuously scanning files without rest.<br/>Allowed values: `vlow`, `low`, `medium`, `high`, `vhigh`.<br/>Default: `medium`.<br/>(`--scan-intensity={enum}`)(-H) |
|
|
12233
|
+
| `scan_intensity` | `Enum[String]` | Scan at the set intensity. `vlow` minimizes system activity. `vhigh` maximizes system activity by continuously scanning files without rest.<br/>Allowed values: `vlow`, `low`, `medium`, `high`, `vhigh`.<br/>Default: `medium`.<br/>(`--scan-intensity={enum}`)(-H) |
|
|
11241
12234
|
| `sharing_retry_max` | `Integer` | Retry synchronizations up to the specified maximum number after a sharing violation.<br/>Default: `3`.<br/>(`--sharing-retry-max={integer}`) |
|
|
11242
12235
|
| `store_metadata_records` | `Bool` | Store the acls or xattrs in the snapshot database.<br/>Default: `false`.<br/>(`--store-metadata-records`) |
|
|
11243
|
-
| `symbolic_links` | `String` | Handle symbolic links with the specified method. Default is `skip` on windows, `copy` otherwise.<br/>Allowed values: `copy`, `skip`, `follow`.<br/>(`--symbolic-links={enum}`)(-n) |
|
|
12236
|
+
| `symbolic_links` | `Enum[String]` | Handle symbolic links with the specified method. Default is `skip` on windows, `copy` otherwise.<br/>Allowed values: `copy`, `skip`, `follow`.<br/>(`--symbolic-links={enum}`)(-n) |
|
|
11244
12237
|
| `tags` | `Hash` | User-defined metadata tags.<br/>(special:`--tags64={object}`) |
|
|
12238
|
+
| `transfer_threads` | `Array[Hash]` | Use the specified number of dedicated transfer threads to process files smaller or equal to the specified size<br/>(special:`--transfer-threads={array}`) |
|
|
11245
12239
|
| `transfer_threads[].size` | `Integer` | Upper limit. `-1` for infinity.<br/>Default: `-1`. |
|
|
11246
12240
|
| `transfer_threads[].threads` | `Integer` | The number of threads.<br/>Required. |
|
|
11247
|
-
| `
|
|
11248
|
-
| `transport.cipher` | `String` | Specify encryption algorithm for file data.<br/>Allowed values: `none`, `aes128`, `aes192`, `aes256`, `aes128cfb`, `aes192cfb`, `aes256cfb`, `aes128gcm`, `aes192gcm`, `aes256gcm`.<br/>Default: `aes128`.<br/>(`--cipher={enum}`)(-c) |
|
|
11249
|
-
| `transport.compression` | `String` | Compress a file before transfer using the specified MODE.<br/>Allowed values: `none`, `zlib`.<br/>Default: `none`.<br/>(`--compression={enum}`) |
|
|
12241
|
+
| `transport` | `Hash` | |
|
|
12242
|
+
| `transport.cipher` | `Enum[String]` | Specify encryption algorithm for file data.<br/>Allowed values: `none`, `aes128`, `aes192`, `aes256`, `aes128cfb`, `aes192cfb`, `aes256cfb`, `aes128gcm`, `aes192gcm`, `aes256gcm`.<br/>Default: `aes128`.<br/>(`--cipher={enum}`)(-c) |
|
|
12243
|
+
| `transport.compression` | `Enum[String]` | Compress a file before transfer using the specified MODE.<br/>Allowed values: `none`, `zlib`.<br/>Default: `none`.<br/>(`--compression={enum}`) |
|
|
11250
12244
|
| `transport.datagram_size` | `Integer` | Specify the datagram size (MTU) for FASP. By default it uses the detected path MTU.<br/>(`--datagram-size={integer}`)(-Z) |
|
|
11251
12245
|
| `transport.min_rate` | `Integer` | Attempt to transfer no slower than the specified rate (in bps).<br/>Default: `0`.<br/>(`--min-rate={integer}`)(-m) |
|
|
11252
|
-
| `transport.rate_policy` | `String` | Defines how `ascp` will manage the bandwidth.<br/>Allowed values: `fair`, `fixed`, `high`, `low`.<br/>Default: `fair`.<br/>(`--rate-policy={enum}`)(-a) |
|
|
12246
|
+
| `transport.rate_policy` | `Enum[String]` | Defines how `ascp` will manage the bandwidth.<br/>Allowed values: `fair`, `fixed`, `high`, `low`.<br/>Default: `fair`.<br/>(`--rate-policy={enum}`)(-a) |
|
|
11253
12247
|
| `transport.raw_options` | `Array[String]` | Pass arbitrary arguments to `ascp`.<br/>(special:`--raw-options={array}`) |
|
|
11254
12248
|
| `transport.read_block_size` | `Integer` | Use the specified block size (in bytes) for reading. Default is determined by `aspera.conf`.<br/>(`--read-block-size={integer}`)(-g) |
|
|
11255
12249
|
| `transport.rexmsg_size` | `Integer` | Use the specified size (in bytes) for a retransmission request. Default is determined by `aspera.conf`.<br/>(`--rexmsg-size={integer}`)(-X) |
|
|
11256
12250
|
| `transport.target_rate` | `Integer` | Transfer no faster than the specified rate (in bps). A string with suffix `k`, `m` or `g` is converted to bps by `ascli` (e.g. `100m`).<br/>Default: `10000000`.<br/>(`--target-rate={integer}`)(-l) |
|
|
11257
12251
|
| `transport.udp_port` | `Integer` | Use the specified UDP port for FASP data transfer.<br/>Default: `33001`.<br/>(`--udp-port={integer}`)(-O) |
|
|
11258
12252
|
| `transport.write_block_size` | `Integer` | Use the specified block size (in bytes) for writing. Default is determined by `aspera.conf`.<br/>(`--write-block-size={integer}`)(-G) |
|
|
11259
|
-
| `
|
|
11260
|
-
| `watchd.datastore` | `String` | Specify the type of datastore, `none` for disabled.<br/>Allowed values: `none`, `redis`, `scalekv`.<br/>Default: `none`. |
|
|
12253
|
+
| `watchd` | `Hash` | When connection is configured, `asperawatchd` is used to detect the changes on the source directory.<br/>(special:`--watchd={object}`) |
|
|
12254
|
+
| `watchd.datastore` | `Enum[String]` | Specify the type of datastore, `none` for disabled.<br/>Allowed values: `none`, `redis`, `scalekv`.<br/>Default: `none`. |
|
|
11261
12255
|
| `watchd.domain` | `String` | Specify the domain. Default is the current username. |
|
|
11262
12256
|
| `watchd.host` | `String` | Use the specified host name or address to connect to the datastore. |
|
|
11263
12257
|
| `watchd.port` | `Integer` | Use the specified port.<br/>Default: `31415`. |
|
|
11264
|
-
| `watchd` | `Hash` | When connection is configured, `asperawatchd` is used to detect the changes on the source directory.<br/>(special:`--watchd={object}`) |
|
|
11265
12258
|
| `write_gid` | `String` | Try to write files as the specified group.<br/>(`--write-gid={string}`) |
|
|
11266
12259
|
| `write_uid` | `String` | Try to write files as the specified user.<br/>(`--write-uid={string}`) |
|
|
11267
12260
|
|
|
@@ -11338,16 +12331,16 @@ ascli ... sync admin file_info <FOLDER> --sql="WHERE state=20 ORDER BY f_meta_pa
|
|
|
11338
12331
|
**`sync_snapmeta_table`** - one row per session, written at start and updated at stop:
|
|
11339
12332
|
|
|
11340
12333
|
| Field | Type | Description |
|
|
11341
|
-
|
|
12334
|
+
| ----------------------- | ------------ | -------------------------------------------------------------------------------- |
|
|
11342
12335
|
| `ascp_sids` | `String` | Last known FASP (ascp) session IDs. |
|
|
11343
12336
|
| `byte_peerxfer` | `Integer` | Number of bytes transferred by the peer. |
|
|
11344
12337
|
| `byte_synced` | `Integer` | Number of bytes successfully synchronized. |
|
|
11345
12338
|
| `byte_xferres` | `Integer` | Number of bytes for which transfer was resumed. |
|
|
11346
|
-
| `checksum` | `String` | Checksum algorithm.<br/>Allowed values: `sha1`, `md5`, `sha1_sparse`, `md5_sparse`, `none`. |
|
|
12339
|
+
| `checksum` | `Enum[String]` | Checksum algorithm.<br/>Allowed values: `sha1`, `md5`, `sha1_sparse`, `md5_sparse`, `none`. |
|
|
11347
12340
|
| `cip_true_val` | `Integer` | Candidate-in-progress counter true value (internal). |
|
|
11348
|
-
| `condition` | `String` | Last known session condition.<br/>Allowed values: `running`, `stopped`. |
|
|
12341
|
+
| `condition` | `Enum[String]` | Last known session condition.<br/>Allowed values: `running`, `stopped`. |
|
|
11349
12342
|
| `dbversion` | `String` | Database schema version. |
|
|
11350
|
-
| `direction` | `String` | Sync direction.<br/>Allowed values: `push`, `pull`, `bidi`. |
|
|
12343
|
+
| `direction` | `Enum[String]` | Sync direction.<br/>Allowed values: `push`, `pull`, `bidi`. |
|
|
11351
12344
|
| `exclude_dirs_older_than` | `Integer` | Exclude directories with modification time older than this epoch value (0 = disabled). |
|
|
11352
12345
|
| `file_peerxfer` | `Integer` | Number of files transferred by the peer. |
|
|
11353
12346
|
| `file_synced` | `Integer` | Number of files successfully synchronized. |
|
|
@@ -11371,7 +12364,7 @@ ascli ... sync admin file_info <FOLDER> --sql="WHERE state=20 ORDER BY f_meta_pa
|
|
|
11371
12364
|
**`sync_snap_counters_table`** - one row, updated live during a session:
|
|
11372
12365
|
|
|
11373
12366
|
| Field | Type | Description |
|
|
11374
|
-
|
|
12367
|
+
| ------------------------ | ------- | ------------------------------------------------ |
|
|
11375
12368
|
| `conflict` | `Integer` | Number of paths in the `Conflict` state. |
|
|
11376
12369
|
| `error` | `Integer` | Number of paths in the `Error` state. |
|
|
11377
12370
|
| `files_conflict` | `Integer` | Number of files in the `Conflict` state. |
|
|
@@ -11387,7 +12380,7 @@ ascli ... sync admin file_info <FOLDER> --sql="WHERE state=20 ORDER BY f_meta_pa
|
|
|
11387
12380
|
**`sync_snapdb_table`** - one row per tracked file or directory:
|
|
11388
12381
|
|
|
11389
12382
|
| Field | Type | Description |
|
|
11390
|
-
|
|
12383
|
+
| ---------------------- | ------- | -------------------------------------------------------------------------------- |
|
|
11391
12384
|
| `c_cont_csum` | `String` | Current content — checksum. |
|
|
11392
12385
|
| `c_cont_mtime` | `Integer` | Current content — modification time (epoch). |
|
|
11393
12386
|
| `c_cont_size` | `Integer` | Current content — file size in bytes. |
|
|
@@ -11405,8 +12398,8 @@ ascli ... sync admin file_info <FOLDER> --sql="WHERE state=20 ORDER BY f_meta_pa
|
|
|
11405
12398
|
| `c_meta_path` | `String` | Current metadata — file path as known to the snapshot. |
|
|
11406
12399
|
| `c_meta_type` | `Integer` | Current metadata — file type (file, directory, …). |
|
|
11407
12400
|
| `c_meta_uid` | `Integer` | Current metadata — user ID (Unix). |
|
|
11408
|
-
| `c_meta_xattrs_cksum` | `String` | Current metadata — checksum of extended attributes. |
|
|
11409
12401
|
| `c_meta_xattrs` | `Integer` | Current metadata — extended attributes (not used). |
|
|
12402
|
+
| `c_meta_xattrs_cksum` | `String` | Current metadata — checksum of extended attributes. |
|
|
11410
12403
|
| `candidate_in_prog` | `Integer` | Set to 1 when this record is currently in the candidate transfer list. |
|
|
11411
12404
|
| `commit_version` | `Integer` | Local commit version for this entry. |
|
|
11412
12405
|
| `f_cont_csum` | `String` | Filesystem content — checksum. |
|
|
@@ -11426,8 +12419,8 @@ ascli ... sync admin file_info <FOLDER> --sql="WHERE state=20 ORDER BY f_meta_pa
|
|
|
11426
12419
|
| `f_meta_path` | `String` | Filesystem metadata — file path as seen on disk (displayed by `file_info`). |
|
|
11427
12420
|
| `f_meta_type` | `Integer` | Filesystem metadata — file type. |
|
|
11428
12421
|
| `f_meta_uid` | `Integer` | Filesystem metadata — user ID (Unix). |
|
|
11429
|
-
| `f_meta_xattrs_cksum` | `String` | Filesystem metadata — checksum of extended attributes. |
|
|
11430
12422
|
| `f_meta_xattrs` | `Integer` | Filesystem metadata — extended attributes (not used). |
|
|
12423
|
+
| `f_meta_xattrs_cksum` | `String` | Filesystem metadata — checksum of extended attributes. |
|
|
11431
12424
|
| `message` | `String` | Error or status message associated with this entry. |
|
|
11432
12425
|
| `meta_lastreq_no` | `Integer` | Sequence number of the last metadata request sent. |
|
|
11433
12426
|
| `meta_lastresp_no` | `Integer` | Sequence number of the last metadata response received. |
|
|
@@ -11588,11 +12581,11 @@ To do so, set up the SMTP configuration with option `smtp`.
|
|
|
11588
12581
|
The `smtp` option is a `Hash` ([Extended Value](#extended-value-syntax)) with the following fields:
|
|
11589
12582
|
|
|
11590
12583
|
| Field | Type | Description |
|
|
11591
|
-
|
|
12584
|
+
| ---------- | ------- | -------------------------------------------------------------------------------- |
|
|
11592
12585
|
| `domain` | `String` | Email domain of the user. Defaults to the domain part of `server`.<br/>Example: `gmail.com`. |
|
|
11593
12586
|
| `from_email` | `String` | Sender address (used in `From:` header and as reply-to). Defaults to `username` when defined.<br/>Example: `johnny@example.com`. |
|
|
11594
12587
|
| `from_name` | `String` | Display name of the sender. Defaults to the local-part of `from_email`.<br/>Example: `John Wayne`. |
|
|
11595
|
-
| `password` | `String` | Password for the above `username`.<br/>Example:
|
|
12588
|
+
| `password` | `String` | Password for the above `username`.<br/>Example: `<PASSWORD>`. |
|
|
11596
12589
|
| `port` | `Integer` | Port for the SMTP service.<br/>Defaults: `587` (TLS), `465` (SSL), `25` (plain).<br/>Example: `587`. |
|
|
11597
12590
|
| `server` | `String` | SMTP server address.<br/>Required.<br/>Example: `smtp.gmail.com`. |
|
|
11598
12591
|
| `ssl` | `Bool` | Enable `TLS/SSL` (port 465).<br/>Default: `false`. |
|
|
@@ -11610,14 +12603,13 @@ ascli config preset set smtp_google password <PASSWORD>
|
|
|
11610
12603
|
or
|
|
11611
12604
|
|
|
11612
12605
|
```shell
|
|
11613
|
-
ascli config preset
|
|
12606
|
+
ascli config preset set smtp_google @json:'{"server":"smtp.google.com","username":"john@gmail.com","password":"<PASSWORD>"}'
|
|
11614
12607
|
```
|
|
11615
12608
|
|
|
11616
12609
|
or
|
|
11617
12610
|
|
|
11618
|
-
|
|
11619
12611
|
```shell
|
|
11620
|
-
ascli config preset
|
|
12612
|
+
ascli config preset set smtp_google @: server=smtp.google.com username=john@gmail.com password=<PASSWORD>
|
|
11621
12613
|
```
|
|
11622
12614
|
|
|
11623
12615
|
Set this configuration as global default, for instance:
|
|
@@ -11821,28 +12813,26 @@ This also requires Ruby header files.
|
|
|
11821
12813
|
If Ruby was installed as a Linux package, then also install the Ruby development package:
|
|
11822
12814
|
`ruby-dev` or `ruby-devel`, depending on distribution.
|
|
11823
12815
|
|
|
11824
|
-
### Private key type: `ed25519`
|
|
11825
|
-
|
|
11826
|
-
There are a few aspects concerning ED25519 keys.
|
|
12816
|
+
### Private key type: `ed25519`
|
|
11827
12817
|
|
|
11828
|
-
|
|
11829
|
-
|
|
11830
|
-
If you want to use `ed25519` keys, then install the required gems:
|
|
12818
|
+
Keys of type `ed25519` and keys in the OpenSSH format are supported by `net-ssh` using the Ruby `openssl` gem (>= 3.2.0): the `ed25519` gem is not needed.
|
|
12819
|
+
Only OpenSSH private keys protected by a passphrase require the `bcrypt_pbkdf` gem, which requires compilation of native code:
|
|
11831
12820
|
|
|
11832
12821
|
```shell
|
|
11833
|
-
gem install
|
|
12822
|
+
gem install bcrypt_pbkdf
|
|
11834
12823
|
```
|
|
11835
12824
|
|
|
11836
|
-
|
|
12825
|
+
If the gem is missing, then loading such a key fails with an error mentioning `bcrypt_pbkdf`.
|
|
12826
|
+
|
|
12827
|
+
If the OpenSSL backend does not support Ed25519, then the following message is displayed:
|
|
11837
12828
|
|
|
11838
12829
|
```text
|
|
11839
12830
|
OpenSSH keys only supported if ED25519 is available (NotImplementedError)
|
|
11840
|
-
net-ssh requires
|
|
11841
|
-
* ed25519 (>= 1.2, < 2.0)
|
|
11842
|
-
* bcrypt_pbkdf (>= 1.0, < 2.0)
|
|
11843
|
-
See https://github.com/net-ssh/net-ssh/issues/565 for more information
|
|
12831
|
+
net-ssh requires openssl >= 3.2.0 and a crypto backend with Ed25519 enabled for ed25519 support.
|
|
11844
12832
|
```
|
|
11845
12833
|
|
|
12834
|
+
To ignore the `ed25519` keys of the default identities (`~/.ssh/id_ed25519`), set env var `ASCLI_ENABLE_ED25519` to `false`.
|
|
12835
|
+
|
|
11846
12836
|
In addition, if **JRuby** is used, host keys of type: `ecdsa-sha2` and `ecdh-sha2` are also deactivated by default.
|
|
11847
12837
|
To activate, set env var `ASCLI_ENABLE_ECDSHA2` to `true`.
|
|
11848
12838
|
|
|
@@ -11878,7 +12868,7 @@ This happens on Linux x86 if you try to install `transferd` on a Linux version t
|
|
|
11878
12868
|
Workaround: Install an older version of `transferd`:
|
|
11879
12869
|
|
|
11880
12870
|
```shell
|
|
11881
|
-
ascli
|
|
12871
|
+
ascli transferd install 1.1.2
|
|
11882
12872
|
```
|
|
11883
12873
|
|
|
11884
12874
|
See [Single file executable](#single-file-executable).
|
|
@@ -11919,11 +12909,45 @@ Another possibility is to add this option: `--transfer=@json:'{"ascp_args":["--p
|
|
|
11919
12909
|
> If one relies on `--lock-port` when using containers to avoid parallel transfers in a cron job, this may be the cause, as `lock_port` does not lock across containers.
|
|
11920
12910
|
> Use `flock` instead.
|
|
11921
12911
|
|
|
12912
|
+
## Security and Trust
|
|
12913
|
+
|
|
12914
|
+
This section is for security and compliance reviewers who evaluate `ascli` before its use in an organization.
|
|
12915
|
+
It summarizes how `ascli` protects credentials, communications and the system that runs it, and how the project is developed and released.
|
|
12916
|
+
The detailed reasoning is in the [Security Assurance Case](ASSURANCE_CASE.md).
|
|
12917
|
+
|
|
12918
|
+
### Protection by area
|
|
12919
|
+
|
|
12920
|
+
| Area | How `ascli` protects it | Details |
|
|
12921
|
+
| ---- | ------------------------ | ------- |
|
|
12922
|
+
| Credentials | Secret values are hidden in logs, results and error messages. Secrets can be kept in a vault instead of the configuration file: encrypted file, HashiCorp Vault, Keeper, 1Password, macOS keychain, Linux Secret Service. The configuration folder is readable only by the current user. | [Secret Vault](#secret-vault) |
|
|
12923
|
+
| Communications | API calls use HTTPS, and the certificate of the server is verified by default (disabled only with `--insecure=yes`). | [SSL CA certificate bundle](#configuring-the-ssl-ca-certificate-bundle) |
|
|
12924
|
+
| File transfers | Transfers use the IBM Aspera transfer engine (`ascp`), with the encryption in transit and at rest defined by the server and the transfer specification. | [Transfer Specification](#transfer-specification) |
|
|
12925
|
+
| Execution by a client that is not fully trusted (AI assistant, program that builds commands) | A security level restricts what commands can do: reading local files, executing code, writing files. The MCP server uses level `high` by default, and the client cannot change it. | [Security Level](#security-level) |
|
|
12926
|
+
| AI assistants (MCP server) | The AI client cannot execute code, cannot write files outside the folders that the user allows, and never sees secrets. Over HTTP, a token is mandatory when the server is not on the loopback address, and OAuth 2.0 with PKCE is supported. | [MCP server security](#security) |
|
|
12927
|
+
| Local web servers (login, MCP over HTTP) | They listen on the loopback address by default, with authentication and protection against cross-site requests. | [Web service](#web-service) |
|
|
12928
|
+
| Usage data | `ascli` sends no usage data (no telemetry). It connects to the servers given in commands and presets, and to public IBM and GitHub locations only for the commands that download from them (for example `transferd install`, development guides). Every 7 days by default, it checks RubyGems for a new version (option `version_check_days`, `0` to disable). | [Configuration](#plugin-config-configuration) |
|
|
12929
|
+
|
|
12930
|
+
### Supply chain
|
|
12931
|
+
|
|
12932
|
+
- The gem is signed: its signature can be verified at installation, see [Verifying gem installation signature](#verifying-gem-installation-signature).
|
|
12933
|
+
- Publishing the gem on RubyGems requires multi-factor authentication.
|
|
12934
|
+
- Release packages (gem, single executable, portable packages, container image) are built by GitHub Actions from the repository.
|
|
12935
|
+
- Dependencies are gems, updated with Renovate.
|
|
12936
|
+
- The source code is analyzed by CodeQL and RuboCop in continuous integration, and tested by unit and integration tests, including tests of the security levels (coverage is shown in the README badge).
|
|
12937
|
+
|
|
12938
|
+
### Project practices
|
|
12939
|
+
|
|
12940
|
+
- Open source, Apache 2.0 license, developed in the [IBM GitHub organization](https://github.com/IBM/aspera-cli).
|
|
12941
|
+
- [OpenSSF Best Practices](https://www.bestpractices.dev/projects/5861): silver badge.
|
|
12942
|
+
- Vulnerabilities are reported and handled as described in [SECURITY.md](../SECURITY.md).
|
|
12943
|
+
- Roles, decisions and continuity of the project: [GOVERNANCE.md](../GOVERNANCE.md).
|
|
12944
|
+
- Structure of the code: [ARCHITECTURE.md](ARCHITECTURE.md).
|
|
12945
|
+
|
|
11922
12946
|
## About
|
|
11923
12947
|
|
|
11924
12948
|
### Hootput, the mascot
|
|
11925
12949
|
|
|
11926
|
-

|
|
12950
|
+

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