asperalm 0.6.7 → 0.6.8

Sign up to get free protection for your applications and to get access to all the features.
checksums.yaml CHANGED
@@ -1,7 +1,7 @@
1
1
  ---
2
2
  SHA1:
3
- metadata.gz: 579212fc85d1bdee36113902f91953cb4447c2f7
4
- data.tar.gz: dbf502e290423bb22c98668cb107dbeb9ff71a5f
3
+ metadata.gz: e3bda3529a8808ff718df6a33a92196f463d234b
4
+ data.tar.gz: db0f87502e67bf8d99582898c7e42a263ade41f6
5
5
  SHA512:
6
- metadata.gz: 5c3b1faebeaeeeb5d9c7416168dfd842b92df96605f97569456ddb173891ac015d3a949207d469f29aee9556df4e64a87281a1ad5a25d76edf97770add739dd1
7
- data.tar.gz: 55ea0431d8756ee89309435c55fd76c5b9f601edf1cb1c67aeb4caf015c3f1825dbaf9395cb0b9ab26cd8f3ef058631eb7b4dc04eacc27528367c4b01232c283
6
+ metadata.gz: b8e9c2e2f1057dc451c85e6713c9726bcece2052e7b58001228a446e4df947635d14184b968bff861f596b8ac1ce01b9322d7bb02436c3f7166be82d9111647a
7
+ data.tar.gz: 4d099ac09460fc03406c0a89859292c5b79193fb4d48e993119754a6ef7ed2db6a26ee718412605b32e621e4a3863c8fa552e1fad027159484f2d3b4bf67ad42
data/README.md CHANGED
@@ -1,6 +1,6 @@
1
1
  # Asperalm - Laurent's Aspera Command Line Interface and Ruby Library
2
2
 
3
- Version : 0.6.7
3
+ Version : 0.6.8
4
4
 
5
5
 
6
6
  _Laurent/2016-2018_
@@ -22,7 +22,7 @@ This manual addresses three parts:
22
22
 
23
23
  * `aslmcli` tool
24
24
  * `asession` tool
25
- * `Asperalm` ruby library
25
+ * `Asperalm` ruby module
26
26
 
27
27
  In examples, command line operations (starting with `$`) are shown using a standard shell: `bash`.
28
28
 
@@ -37,22 +37,31 @@ $ aslmcli --version
37
37
  x.y.z
38
38
  ```
39
39
 
40
- Then, follow the section relative to the product you want to access (Files, Faspex, ...).
40
+ Then, follow the section relative to the product you want to inbteract with: Files, Faspex, ...
41
41
 
42
42
  Detailed generic information on configuration can be found in section: [Tool: `aslmcli`](#aslmcli).
43
43
 
44
44
  # <a name="installation"></a>Installation
45
45
 
46
- ## Pre-requisite : Ruby
46
+ In order to use the tool or the gem, it is necessary to install those components:
47
47
 
48
- As a ruby gem and ruby based tool, a ruby interpreter is required. It is also required to have privilege to install gems.
48
+ * ruby
49
+ * asperalm
50
+ * fasp
49
51
 
50
- Requires Ruby 2.4+, should work with 2.0+.
52
+ The following sections provide information on the installation.
53
+
54
+ ## Ruby
55
+
56
+ A ruby interpreter is required to run the tool or to use the gem. It is also required to have privilege to install gems.
57
+
58
+ Ruby 2.4+ is prefered, but it should also work with 2.0+.
51
59
 
52
60
  Refer to the following sections for specific operating systems.
53
61
 
54
- ### MacOS X
55
- Ruby comes pre-installed on MacOSx. Nevertheless, installing new gems require admin privilege (sudo) and the version is not up to date.
62
+ ### macOS
63
+
64
+ Ruby comes pre-installed on macOS. Nevertheless, installion of new gems on pre-installed ruby requires admin privilege (sudo) and the version is not the latest.
56
65
 
57
66
  It is better to install "homebrew", from here: [https://brew.sh/](https://brew.sh/), and then install Ruby:
58
67
 
@@ -61,22 +70,26 @@ $ brew install ruby
61
70
  ```
62
71
 
63
72
  ### Windows
64
- On windows you can get it from here: [https://rubyinstaller.org/](https://rubyinstaller.org/) .
73
+
74
+ On windows you can get it from here: [https://rubyinstaller.org/](https://rubyinstaller.org/).
65
75
 
66
76
  ### Linux
77
+
67
78
  ```bash
68
79
  $ yum install ruby rubygems
69
80
  ```
81
+
70
82
  Note that Ruby 2+ is required, if you have an older Linux (e.g. CentOS 6), you should install "rvm" [https://rvm.io/](https://rvm.io/) and install and use a newer Ruby.
71
83
 
72
- ## Gem Installation
84
+ ## `asperalm` gem
85
+
73
86
  Once you have ruby and rights to install gems: Install the gem and its dependencies:
74
87
 
75
88
  ```bash
76
89
  $ gem install asperalm
77
90
  ```
78
91
 
79
- ## FASP Installation
92
+ ## FASP
80
93
 
81
94
  For any FASP based file transfer, the FASP protocol and a valid license
82
95
  is required (e.g. if the server side is "connect" enabled, one can use
@@ -87,12 +100,13 @@ the connect client license).
87
100
  Aspera Connect Client can be installed
88
101
  by visiting the page: [http://downloads.asperasoft.com/connect2/](http://downloads.asperasoft.com/connect2/)
89
102
 
90
- It is also possible to use the `ascp` binary from Aspera CLI, or any other transfer product.
103
+ It is also possible to use the `ascp` binary from Aspera CLI, or any other transfer product (High Speed Transfer Server, etc...).
91
104
 
92
105
  The connect client can be downloaded on command line using `aslmcli`,
93
106
  see section: [Client](client).
94
107
 
95
108
 
109
+
96
110
  # <a name="aslmcli"></a>Tool: `aslmcli`
97
111
 
98
112
  The `asperalm` Gem provides a Ruby language based command line interface (CLI) which interacts with (mostly APIs using REST calls) Aspera Products:
@@ -112,7 +126,7 @@ The CLI tool that provides the following features:
112
126
  * Supports most Aspera server products (on-premise and SaaS)
113
127
  * Command options can be provided on command line, in configuration file, in env var, in files (products URL, credentials or any option)
114
128
  * Commands, Option values and Parameters can be provided in short format (must be unique)
115
- * FASP transfer agent can be: FaspManager (local ascp), or Connect Client, or a transfer node
129
+ * FASP [transfer agent](#agents) can be: FaspManager (local ascp), or Connect Client, or a transfer node
116
130
  * Transfer parameters can be altered by modification of transferspec, this includes requiring multi-session transfer on nodes
117
131
  * Allows transfers from products to products, essentially at node level
118
132
  * Supports FaspStream creation (using Node API)
@@ -129,22 +143,27 @@ $ aslmcli -h
129
143
 
130
144
  Refer to sections: [Usage](#usage) and [Sample Commands](commands).
131
145
 
146
+ Not all `aslmcli` features are fully documented here, the user may explore commands on the command line.
147
+
148
+
132
149
  ## Commands, Arguments and Options
133
150
 
134
151
  Commands, Options and Arguments are normally provided on command line, i.e. `aslmcli command --option-name=VAL1 VAL2` takes "VAL1" as the value for
135
152
  option `option_name`, and "VAL2" as the value for first argument of command: `command`.
136
153
 
137
- Options are command line arguments starting with a `-`, other arguments are considered as Commands and Arguments. (Note that some options are mandatory). Most options take a value, but a limited number of them are without values.
154
+ Options are command line arguments starting with a `-` (Note that some options are mandatory). Other command line arguments are considered as Commands and Arguments. Most options take a value, but a limited number of them are without values.
138
155
 
139
- The special option "--" stops option processing, so following values are taken as arguments, even the ones starting with a `-`.
156
+ The special option "--" stops option processing, so following values are taken as arguments, including the ones starting with a `-`.
140
157
 
141
- The value of options and arguments use the extended syntax, refer to: [Extended Value](#extended).
158
+ The value of options and arguments can be either a plain text or be provided using the [Extended Value Syntax](#extended).
159
+
160
+ When the value of a command, option or argument is constrained by a fixed list of values, it is possible to use the first letters of the value only, provided that it uniquely identifies a value. For example `aslmcli conf ov` is the same as `aslmcli config overview`.
142
161
 
143
162
  ## Interactive Input
144
163
 
145
164
  Some options and parameters are mandatory and other optional. By default, the tool will ask for missing mandatory options or parameters for interactive execution.
146
165
 
147
- The behaviuor can be controlled with:
166
+ The behaviour can be controlled with:
148
167
 
149
168
  * --interactive=&lt;yes|no&gt; (default=yes if STDIN is a terminal, else no)
150
169
  * yes : missing parameters/options are asked to the user
@@ -152,18 +171,22 @@ The behaviuor can be controlled with:
152
171
  * --ask-options=&lt;yes|no&gt; (default=no)
153
172
  * optional parameters/options are asked to user
154
173
 
155
- ## <a name="extended"></a>Extended Value
174
+ ## <a name="extended"></a>Extended Value Syntax
175
+
176
+ Usually, values are specified by a simple string. But sometime it is required to read a value from a file, or decode it, or have a value more complex than a string (e.g. a structure (hash table)).
156
177
 
157
- The value of options and arguments can optionally use an extended syntax using the following special prefixes:
178
+ The value of options and arguments can optionally use the following special prefixes:
158
179
 
159
- * @val:VALUE , prevents further special prefix processing, e.g. `--username=@val:laurent`, here the same as `--username=laurent`.
180
+ * @val:VALUE , prevents further special prefix processing, e.g. `--username=@val:laurent` sets the option `username` to value `laurent`.
160
181
  * @file:PATH , read value from a file (prefix "~/" is replaced with $HOME), e.g. --key=@file:$HOME/.ssh/mykey
161
182
  * @env:ENVVAR , read from a named env var, e.g.--password=@env:MYPASSVAR
162
183
 
184
+ TODO: @csvfile : read a csv file and create an array of hash, whose keys are on first line, and values in following lines.
185
+
163
186
  In addition it is possible to decode some values by prefixing :
164
187
 
165
188
  * @base64: to decode base64 encoded string
166
- * @json: to decode JSON values
189
+ * @json: to decode JSON values (convenient to provide complex structures)
167
190
  * @zlib: to uncompress data
168
191
  * @ruby: to execute ruby code, for instance read values from files.
169
192
 
@@ -188,48 +211,52 @@ Some options have default values (defined in the tool). All options can be defin
188
211
  configuration file (see [Configuration file](#configfile)).
189
212
  Options values can be displays for a given command by providing the `--show-config` option.
190
213
 
191
- ## <a name="native"></a>Native Value
214
+ ## <a name="native"></a>Structured Value
215
+
216
+ Some options and parameters expect a _Structured Value_, i.e. a value more complex than a simple string. This is usually a Hash table or an Array, which could also contain sub structures.
217
+
218
+ A _Structured Value_ requires the use of
192
219
 
193
- A native value is a value whose type is differemt from "String". For instance, a hash table.
220
+ For instance, a [_transfer-spec_](#_transferspec_) is expected to be a _Structured Value_.
194
221
 
195
- A few commands and options expect _native values_, for instance `transfer specifications` are expected to be a Hash table, so a _native value_.
222
+ A convenient way to specify a _Structured Value_ is to use the `@json:` modifier, and describe the value in JSON format. Note that the `@ruby:` modifier can also be used.
196
223
 
197
- A convenient way to specify a _native value_ is to use the `@json:` modifier, and describe the value in JSON format. Note that the `@ruby:` modifier can also be used.
224
+ It is also possible to provide a _Structured Value_ in a file using `@json:@file:<path>`
198
225
 
199
226
  ## <a name="configfile"></a>Configuration file
200
227
 
201
228
  `aslmcli` keeps configuration and cache files in folder `$HOME/.aspera/aslmcli`.
202
229
 
203
- The use of the configuration file is not mandatory, but one is created by default on first use.
204
- All options can be set on command line, or in the configuratin file, or by env vars.
230
+ A default configuration file is created on first use, but there is no mandatory information required in this file. It is mainly used to define pre-sets of command options.
231
+
232
+ All options can be set on command line, or by env vars, or in the configuratin file.
205
233
  A configuration file provides a way to define default values, especially
206
234
  for authentication parameters, thus avoiding to always have to specify those parameters on the command line.
207
235
 
208
236
  The default configuration file is: `$HOME/.aspera/aslmcli/config.yaml`
209
237
  (this can be overriden with option `--config-file=path`).
210
238
 
211
- It is composed of "parameter groups" containing "parameters".
212
- (The first level is an associative array whose values are associative arrays or parameters).
239
+ It is composed of _option presets_ containing pre-sets for options.
213
240
 
214
- ### Creation and Modification of _parameter groups_
241
+ ### Creation and Modification of _option presets_
215
242
 
216
243
  The configuration file can be modified using the following commands:
217
244
 
218
245
  ```
219
- aslmcli config id <parameter group> set|delete|show|initialize|update
246
+ aslmcli config id <option preset> set|delete|show|initialize|update
220
247
  ```
221
248
 
222
- The command `update` allows the easy creation of parameter group by simply providing the options in their command line format, e.g. :
249
+ The command `update` allows the easy creation of option preset by simply providing the options in their command line format, e.g. :
223
250
 
224
251
  ```
225
252
  aslmcli config id node_to_node update --url=https://10.25.0.4:9092 --username=node_user --password=node_pass --ts=@json:'{"precalculate_job_size":true}' --transfer=node --transfer-node=@json:'{"url":"https://10.25.0.8:9092","username":"node_user2","password":"node_pass2"}'
226
253
  ```
227
254
 
228
- * This creates a _parameter group_ `node_to_node` with all provided options.
255
+ * This creates a _option preset_ `node_to_node` with all provided options.
229
256
 
230
- The command `set` allows setting individual options in a _parameter group_.
257
+ The command `set` allows setting individual options in a _option preset_.
231
258
 
232
- The command `initialize`, like `update` allows to set several parameters at once, but it deletes an existing configuration instead of updating it, and expects a _native value_.
259
+ The command `initialize`, like `update` allows to set several parameters at once, but it deletes an existing configuration instead of updating it, and expects a _[Structured Value](#native)_.
233
260
 
234
261
  A good practice is to not manually edit this file and use modification commands.
235
262
  If necessary, the configuration file can be edited (or simply consulted) with:
@@ -247,17 +274,6 @@ $ aslmcli config over
247
274
 
248
275
  ### Format
249
276
 
250
- Configuation is organized in _parameter group_s, like in `.ini` files. Each group has a name contains option name-value pairs.
251
-
252
- Two _parameter groups_ are reserved:
253
-
254
- * `config` is reserved for the global parameters of the `aslmcli` tool.
255
- It contains a special parameter: "version" showing the CLI
256
- version used to create this file. It is used to check compatibility.
257
- * `default` is reserved to define the default parameter group name used for plugins.
258
-
259
- The user may create as many _parameter groups_ as needed. For instance, a particular _parameter group_ can be created for a particular application instance and contain URL and credentials.
260
-
261
277
  The configuration file is a hash in a YAML file. Example:
262
278
 
263
279
  ```yaml
@@ -273,22 +289,34 @@ myfaspparams:
273
289
  ```
274
290
  * The configuration was created with CLI version 0.3.7
275
291
  * the log level is set to `debug`
276
- * the default parameter group to load for plugin "faspex" is : myfaspparams
277
- * the parameter group "myfaspparams" defines some parameters: the URL and credentials
292
+ * the default option preset to load for plugin "faspex" is : myfaspparams
293
+ * the option preset "myfaspparams" defines some parameters: the URL and credentials
294
+
295
+ Configuation is organized in _option presets_, like in `.ini` files. Each group has a name contains option name-value pairs.
296
+
297
+ Two _option presets_ are reserved:
298
+
299
+ * `config` is reserved for the global parameters of the `aslmcli` tool.
300
+ It contains a special parameter: "version" showing the CLI
301
+ version used to create this file. It is used to check compatibility.
302
+ * `default` is reserved to define the default option preset name used for plugins.
303
+
304
+ The user may create as many _option presets_ as needed. For instance, a particular _option preset_ can be created for a particular application instance and contain URL and credentials.
305
+
278
306
 
279
- Values in the configuration also follow the extended syntax, refer to section: [Extended Value](#extended).
307
+ Values in the configuration also follow the [Extended Value Syntax](#extended).
280
308
 
281
- Note: if the user wants to specify an extended syntax in the configuration file, using the update command, the user shall use the `@val:` prefix. Example:
309
+ Note: if the user wants to use the [Extended Value Syntax](#extended) inside the configuration file, using the `config id update` command, the user shall use the `@val:` prefix. Example:
282
310
 
283
311
  ```bash
284
- $ aslmcli config id files_myorg set private_key @val:@file:"$HOME/.aspera/aslmcli/filesapikey"
312
+ $ aslmcli config id my_files_org set private_key @val:@file:"$HOME/.aspera/aslmcli/filesapikey"
285
313
  ```
286
314
 
287
- This creates the file:
315
+ This creates the _option preset_:
288
316
 
289
317
  ```
290
318
  ...
291
- files_myorg:
319
+ my_files_org:
292
320
  private_key: @file:"/Users/laurent/.aspera/aslmcli/filesapikey"
293
321
  ...
294
322
  ```
@@ -297,15 +325,15 @@ So, the key file will be read only at execution time, but not be embedded in the
297
325
 
298
326
  Options are loaded using this algorithm:
299
327
 
300
- * if option '--load-params=xxxx' is specified (or -Pxxxx), this reads the parameter group specified from the configuration file.
328
+ * if option '--load-params=xxxx' is specified (or -Pxxxx), this reads the option preset specified from the configuration file.
301
329
  * else if option --no-default is specified, then dont load default
302
- * else it looks for the name of the default parameter group in section "default" and loads it
330
+ * else it looks for the name of the default option preset in section "default" and loads it
303
331
  * environment variables are evaluated
304
332
  * command line options are evaluated
305
333
 
306
334
  Parameters are evaluated in the order of command line.
307
335
 
308
- To avoid loading the default parameter group for a plugin, just specify a non existing configuration: `-Pnone`
336
+ To avoid loading the default option preset for a plugin, just specify a non existing configuration: `-Pnone`
309
337
 
310
338
  On command line, words in parameter names are separated by a dash, in configuration file, separator
311
339
  is an underscore. E.g. --transfer-name on command line gives transfer_node in configuration file.
@@ -334,17 +362,17 @@ This can also be provisioned in a config file:
334
362
  6$ aslmcli shares repo browse /
335
363
  ```
336
364
 
337
- The three first commands build a parameter group.
365
+ The three first commands build a option preset.
338
366
  Note that this can also be done with one single command:
339
367
 
340
368
  ```bash
341
369
  $ aslmcli config id shares06 init @json:'{"url":"https://10.25.0.6","username":"john","password":"4sp3ra"}'
342
370
  ```
343
371
 
344
- The fourth command defines this parameter group as the default parameter group for the
372
+ The fourth command defines this option preset as the default option preset for the
345
373
  specified application ("shares"). The 5th command dumps the configuration file.
346
- Alternative parameter groups can be used with option "-P&lt;parameter group&gt;"
347
- (or --load-params=&lt;parameter group&gt;)
374
+ Alternative option presets can be used with option "-P&lt;option preset&gt;"
375
+ (or --load-params=&lt;option preset&gt;)
348
376
 
349
377
  Eventually, the last command shows a call to the shares application using default parameters.
350
378
 
@@ -381,7 +409,7 @@ exact content or HTTP requests and responses.
381
409
 
382
410
  In order to get traces of execution, use argument : `--log-level=debug`
383
411
 
384
- ## Graphical Interactions: Browser and Text Editor
412
+ ## <a name="graphical"></a>Graphical Interactions: Browser and Text Editor
385
413
 
386
414
  Some actions may require the use of a graphical tool:
387
415
 
@@ -397,46 +425,17 @@ a text editor for file edition.
397
425
  * `--gui-mode=text` forces a text environment, the URL or file path to open is displayed on
398
426
  terminal.
399
427
 
400
- ## Key Pairs
428
+ ## <a name="agents"></a>Transfer Agents
401
429
 
402
- In order to use JWT for Aspera Files API client authentication,
403
- a private/public key pair must be generated (without passphrase, TODO: add passphrase protection).
404
-
405
- * using the CLI:
430
+ Some of the actions on Aspera Applications lead to file transfers (upload and download) using the FASP protocol (`ascp`).
406
431
 
407
- ```bash
408
- $ aslmcli config genkey ~/.aspera/aslmcli/filesapikey
409
- ```
432
+ This transfer can be done using on of the 3 following methods:
410
433
 
411
- * `ssh-keygen`:
434
+ * `direct` for a local execution of `ascp`
435
+ * `connect` to make use of a local Connect Client
436
+ * `node` to make use of a _remote_ Aspera Transfer Node.
412
437
 
413
- ```bash
414
- $ ssh-keygen -t rsa -f ~/.aspera/aslmcli/filesapikey -N ''
415
- ```
416
-
417
- * `openssl`
418
-
419
- (on some openssl implementation (mac) there is option: -nodes (no DES))
420
-
421
- ```bash
422
- $ APIKEY=~/.aspera/aslmcli/filesapikey
423
- $ openssl genrsa -passout pass:dummypassword -out ${APIKEY}.protected 2048
424
- $ openssl rsa -passin pass:dummypassword -in ${APIKEY}.protected -out ${APIKEY}
425
- $ openssl rsa -pubout -in ${APIKEY} -out ${APIKEY}.pub
426
- $ rm -f ${APIKEY}.protected
427
- ```
428
-
429
- ## FASP Transfer Agents
430
-
431
- The CLI provides access to Aspera Applications functions through REST APIs, it also
432
- allows FASP based transfers (upload and download).
433
-
434
- Any FASP parameter can be set by changing parameters in the associated "transfer spec".
435
- The CLI standadizes on the use of "transfer spec" and does not support directly ascp options.
436
- It is nevertheless possible to add ascp options (for fasp manager only, but not node api or connect)
437
- using the special transfer spec parameter: `EX_ascp_args`.
438
-
439
- Three Transfer agents are currently supported to start transfers :
438
+ `aslmcli` standadizes on the use of a [_transfer-spec_](#_transferspec_) instead of _raw_ ascp options to provide parameters for a transfer session, as a common method for those three Transfer Agents.
440
439
 
441
440
  ### FASPManager API based (command line)
442
441
 
@@ -444,7 +443,7 @@ By default the CLI will use the Aspera Connect Client FASP part, in this case
444
443
  it requires the installation of the Aspera Connect Client to be
445
444
  able to execute FASP based transfers. The CLI will try to automatically locate the
446
445
  Aspera Protocol (`ascp`). This is option: `--transfer=ascp`. Note that parameters
447
- are always provided with a "transfer spec".
446
+ are always provided with a [_transfer-spec_](#_transferspec_).
448
447
 
449
448
  ### Aspera Connect Client GUI
450
449
 
@@ -462,48 +461,38 @@ in the configuration file, then this node is used by default else the parameter
462
461
  three keys: url, username and password, corresponding to the URL of the node API
463
462
  and associated credentials (node user or access key).
464
463
 
465
- The `--transfer-node` parameter can directly specify a pre-configured parameter group :
464
+ The `--transfer-node` parameter can directly specify a pre-configured option preset :
466
465
  `--transfer-node=@param:<psetname>` or specified using the option syntax :
467
466
  `--transfer-node=@json:'{"url":"https://...","username":"theuser","password":"thepass"}'`
468
467
 
469
- ## Transfer Specification
468
+ ## <a name="transferspec"></a>Transfer Specification
470
469
 
471
- The "Transfer spec" specifies FASP protocol session startup parameters.
470
+ Some commands lead to file transfer (upload/download), all parameters necessary for this transfer
471
+ is described in a _transfer-spec_ (Transfer Specification), such as:
472
472
 
473
- ### Destination folder for transfers
473
+ * server address
474
+ * transfer user name
475
+ * credentials
476
+ * file list
477
+ * etc...
474
478
 
475
- Use parameter --to-folder=_dst_path_ to set destination folder on download or upload.
476
- By default destination is "." for downloads, and "/" for uploads.
477
- Note that it is equivalent to setting "destination_root" in transfer spec
478
- using option --ts=@json:'{"destination_root":"_dst_path_"}'
479
+ `aslmcli` builds a default _transfer-spec_ internally, so it is not necessary to provide additional parameters on the command line for this transfer.
479
480
 
480
- ### Examples
481
+ If needed, it is possible to modify or add any of the supported _transfer-spec_ parameter using the `ts` option. The `ts` option accepts a [Structured Value](#native) containing one or several _transfer-spec_ parameters.
481
482
 
482
- Transfer parameters are contained in a "transfer spec", an associative array.
483
- Changing a transfer spec is done by providing parameters in a JSON syntax.
484
- For instance to override the FASP SSH port to a specific TCP port:
483
+ It is possible to specify ascp options when the `transfer` option is set to `direct` using the special [_transfer-spec_](#_transferspec_) parameter: `EX_ascp_args`. Example: `--ts=@json:'{"EX_ascp_args":["-l","100m"]}'`.
485
484
 
486
- ```
487
- --ts=@json:'{"ssh_port":12345}'
488
- ```
485
+ The use of a _transfer-spec_ instead of `ascp` parameters has the advantage of:
489
486
 
490
- To force http fallback mode:
491
-
492
- ```
493
- --ts=@json:'{"http_fallback":"force"}'
494
- ```
495
-
496
- In Node based transfers, Multi-session is available, simply add `--ts=@json:'{...}'`:
497
-
498
- ```bash
499
- --ts=@json:'{"multi_session":10,"multi_session_threshold":1,"target_rate_kbps":500000,"checksum_type":"none","cookie":"custom:aslmcli:Laurent:My Transfer"}'
500
- ```
487
+ * common to all [Transfer Agent](#agents)
488
+ * not dependant on command line limitations (special characters...)
501
489
 
490
+ A [_transfer-spec_](#_transferspec_) is a Hash table, so it is described on the command line with the [Extended Value Syntax](#extended). Keys are described in section [Transfer Parameters](#transferparams).
502
491
 
503
- ### Parameter list
492
+ ### <a name="transferparams">Transfer Parameters
504
493
 
505
- All standard transfer spec parameter can be overloaded. To display parameter,
506
- run in debug mode (--log-level=debug). Transfer spec can also be saved/overridden in
494
+ All standard [_transfer-spec_](#_transferspec_) parameter can be overloaded. To display parameter,
495
+ run in debug mode (--log-level=debug). [_transfer-spec_](#_transferspec_) can also be saved/overridden in
507
496
  the config file.
508
497
 
509
498
  (UNDER CONSTRUCTION <a href="https://developer.asperasoft.com/web/node/ops-transfers">ref</a>)
@@ -583,6 +572,42 @@ table, th, td {border: 1px solid black;}
583
572
  <tr><td>EX_http_transfer_jpeg</td><td>0</td><td>integer</td><td class="yes">Y</td><td class="no">N</td><td class="no">N</td><td>-j</td><td>HTTP transfers as JPEG file</td></tr>
584
573
  </table>
585
574
 
575
+ ### Destination folder for transfers
576
+
577
+ The destination folder is set by `aslmcli` by default to:
578
+
579
+ * `.` for downloads
580
+ * `/` for uploads
581
+
582
+ It is specified by the [_transfer-spec_](#_transferspec_) parameter `destination_root`. As such, it can be modified with option: `--ts=@json:'{"destination_root":"<path>"}'`.
583
+ The option `to_folder` provides a convenient way to change this parameter: `--to-folder=<path>` and is equivalent.
584
+
585
+ ### Examples
586
+
587
+ * Change target rate
588
+
589
+ ```bash
590
+ --ts=@json:'{"target_rate_kbps":500000}'
591
+ ```
592
+
593
+ * Override the FASP SSH port to a specific TCP port:
594
+
595
+ ```bash
596
+ --ts=@json:'{"ssh_port":12345}'
597
+ ```
598
+
599
+ * Force http fallback mode:
600
+
601
+ ```bash
602
+ --ts=@json:'{"http_fallback":"force"}'
603
+ ```
604
+
605
+ * Use multi-session transfer (when agent=node)
606
+
607
+ ```bash
608
+ --ts=@json:'{"multi_session":10,"multi_session_threshold":1}'
609
+ ```
610
+
586
611
  ## Exclusive execution
587
612
 
588
613
  If it is required to run a command as a single instance, it is possible to protect with parameter: `--lock-port=nnnn`.
@@ -698,7 +723,7 @@ aslmcli shares2 userinfo
698
723
  ```bash
699
724
  $ aslmcli -h
700
725
  NAME
701
- aslmcli -- a command line tool for Aspera Applications (v0.6.7)
726
+ aslmcli -- a command line tool for Aspera Applications (v0.6.8)
702
727
 
703
728
  --interactive=ENUM use interactive input of missing params: yes, no
704
729
  --ask-options=ENUM ask even optional options: yes, no
@@ -876,6 +901,7 @@ SUBCOMMANDS: package, repository, faspexgw, admin
876
901
  OPTIONS:
877
902
  --download-mode=ENUM download mode: fasp, node_http
878
903
  -t, --authTYPE type of authentication: basic, web, jwt, url_token
904
+ --bulk=ENUM download mode: no, yes
879
905
  --url=VALUE URL of application, e.g. http://org.asperafiles.com
880
906
  --username=VALUE username to log in
881
907
  --password=VALUE user's password
@@ -885,7 +911,7 @@ OPTIONS:
885
911
  --title=VALUE package title
886
912
  --note=VALUE package note
887
913
  --secret=VALUE access key secret for node
888
- --query=VALUE for json query
914
+ --query=VALUE list filter (extended value: encode_www_form)
889
915
 
890
916
  --interactive=ENUM use interactive input of missing params: yes, no
891
917
  --ask-options=ENUM ask even optional options: yes, no
@@ -911,7 +937,7 @@ Note that actions and parameter values can be written in short form.
911
937
 
912
938
  ## General: Application URL and Authentication
913
939
 
914
- Aspera legacy applications (Aspera Node, Faspex, Shares, Console, Orchestrator, Server) use simple username/password authentication, usually using HTTP Basic Authentication.
940
+ REST APIs of Aspera legacy applications (Aspera Node, Faspex, Shares, Console, Orchestrator, Server) use simple username/password authentication: HTTP Basic Authentication.
915
941
 
916
942
  Those are using options:
917
943
 
@@ -921,66 +947,133 @@ Those are using options:
921
947
 
922
948
  Those can be provided using command line, parameter set, env var, see section above.
923
949
 
924
- Aspera Files relies on Oauth, refer to the `Files` section.
950
+ Aspera Files relies on Oauth, refer to the [Aspera Files](#files) section.
925
951
 
926
- ## Aspera Files
952
+ ## <a name="files"></a>Aspera Files
927
953
 
928
- Aspera Files supports a more powerful and secure authentication mechanism: Oauth.
929
- HTTP Basic authentication is not supported (deprecated).
954
+ ### OAuth Authentication Preparation
930
955
 
931
- With OAuth, the application (aslmcli) must be identified, and a valid Aspera Files
932
- user must be used to access Aspera Files. Then a "Bearer" token is used for
933
- HTTP authentication.
956
+ Aspera Files requires the use of Oauth authentication. HTTP Basic authentication is not supported, instead a "Bearer" token is used to authenticate REST calls.
934
957
 
935
- The application using the Files API (aslmcli) must be declared in the Files GUI
936
- (see https://aspera.asperafiles.com/helpcenter/admin/organization/registering-an-api-client ).
937
- By declaring the application, a `client_id` and `client_secret` are generated:
958
+ Bearer token are valid for a period of time, so `aslmcli` saves generated tokens in its configuration folder, and regenrate them when they have expired.
938
959
 
939
- <img src="docs/Auth1.png" alt="Files-admin-organization-apiclient-clientdetails"/>
960
+ Several types of OAuth authentication are supported:
940
961
 
941
- It is possible to use the Aspera Files API to register such application. Anyway the user will need web browser to authenticate (generate a bearer token):
942
- `aslmcli` will either display the URL to be entered in a local browser, or open
943
- a browser directly (various options are proposed).
962
+ * JSON Web Token (JWT) : authentication is secured by a private key (recommended)
963
+ * Web based authentication : authentication is made by user in a browser
964
+ * URL Token : external users authentication with url tokens
944
965
 
945
- It is also possible to enable browser-less authentication by using JWT, in this
946
- case a private/public key pair is required (see section: Generating a key pair),
947
- the public key is provided to Aspera Files:
966
+ The authentication method is controled by option `auth`.
948
967
 
949
- <img src="docs/Auth2.png" alt="Files-admin-organization-apiclient-authoptions"/>
968
+ For all above methods, OAuth requires that the external client (`aslmcli`) is declared in Files using the admin interface.
969
+ (see [https://aspera.asperafiles.com/helpcenter/admin/organization/registering-an-api-client](https://aspera.asperafiles.com/helpcenter/admin/organization/registering-an-api-client) ).
950
970
 
951
- Upon successful authentication, auth token are saved (cache) in local files, and
952
- can be used subsequently. Expired token can be refreshed.
971
+ Go to Admin View-Organization-API Clients-Create, and fill the API client creation form (here JWT):
972
+
973
+ * Client Name: aslmcli
974
+ * Redirect URIs: `http://local.connectme.us:12345`
975
+ * Origins: localhost
976
+ * Enable JWT Grant Type
977
+ * Client can retrieve tokens for: All Users
978
+ * Allowed keys: User and Global
979
+ * Public Key: paste from the contents of the generated public key (PEM format, here file ~/.aspera/aslmcli/filesapikey.pub in next section)
980
+ * Enable admin tokens
981
+
982
+ <img src="docs/Auth3.png" alt="Files-admin-organization-apiclient-create"/>
983
+
984
+ It is convenient to save several of those parameters in `aslmcli` configuration file, in order to not have to enter then for every command, so start with the creation of an option preset, lets call it: `my_files_org`.
985
+
986
+ Option preset can be created:
987
+
988
+ * interactively:
989
+
990
+ ```bash
991
+ $ aslmcli config id my_files_org ask url client_id client_secret
992
+ ```
993
+ * or one parameter at a time:
953
994
 
954
- Aspera Files APIs does not support Basic HTTP authentication (see section "Authentication").
955
- Using the CLI with Aspera Files will require the generation of a "Bearer token", this is can
956
- be done by authentication with a web interface (see section "Graphical interactions").
995
+ ```bash
996
+ $ aslmcli config id my_files_org set url https://myorg.asperafiles.com
997
+ $ aslmcli config id my_files_org set client_id MyClIeNtKeY
998
+ $ aslmcli config id my_files_org set client_secret MyClIeNtSeCrEtMyClIeNtSeCrEt
999
+ ```
957
1000
 
958
- A more convenient way to use the CLI with Aspera Files, a possibility is to do the following
959
- (JWT auth):
1001
+ To define this option preset as default for the Files application, execute:
1002
+ ```bash
1003
+ $ aslmcli config id default set files my_files_org
1004
+ ```
960
1005
 
961
- * Create a private/public key pair, as specified in section: "Key Pairs"
1006
+ ### JWT
962
1007
 
963
- * Register a new application in the Aspera Files Admin GUI (refer to section "Authentication").
964
- Here, use the contents of this file (generated in step 2) for public key:
965
- `$HOME/.aspera/aslmcli/filesapikey.pub`
1008
+ If JWT is the chosen method, specify the authentication method:
966
1009
 
967
- * set your Aspera Files default parameters:
1010
+ ```bash
1011
+ $ aslmcli config id my_files_org set auth jwt
1012
+ ```
1013
+
1014
+ In order to use JWT for Aspera Files API client authentication,
1015
+ a private/public key pair must be generated (without passphrase)
1016
+ (TODO: add passphrase protection as option).
1017
+ This can be done using any of the following method:
1018
+
1019
+ * using the CLI:
968
1020
 
969
1021
  ```bash
970
- $ aslmcli config id default set files files_myorg
971
- $ aslmcli config id files_myorg set url https://myorg.asperafiles.com
972
- $ aslmcli config id files_myorg set client_id MyClIeNtKeY
973
- $ aslmcli config id files_myorg set client_secret MyClIeNtSeCrEtMyClIeNtSeCrEt
974
- $ aslmcli config id files_myorg set username user@example.com
975
- $ aslmcli config id files_myorg set private_key @val:@file:"$HOME/.aspera/aslmcli/filesapikey"
1022
+ $ aslmcli config genkey ~/.aspera/aslmcli/filesapikey
1023
+ ```
1024
+
1025
+ * `ssh-keygen`:
1026
+
1027
+ ```bash
1028
+ $ ssh-keygen -t rsa -f ~/.aspera/aslmcli/filesapikey -N ''
1029
+ ```
1030
+
1031
+ * `openssl`
1032
+
1033
+ (on some openssl implementation (mac) there is option: -nodes (no DES))
1034
+
1035
+ ```bash
1036
+ $ APIKEY=~/.aspera/aslmcli/filesapikey
1037
+ $ openssl genrsa -passout pass:dummypassword -out ${APIKEY}.protected 2048
1038
+ $ openssl rsa -passin pass:dummypassword -in ${APIKEY}.protected -out ${APIKEY}
1039
+ $ openssl rsa -pubout -in ${APIKEY} -out ${APIKEY}.pub
1040
+ $ rm -f ${APIKEY}.protected
1041
+ ```
1042
+
1043
+ To save the location of the private key in the option preset, execute:
1044
+
1045
+ ```bash
1046
+ $ aslmcli config id my_files_org set private_key @val:@file:~/.aspera/aslmcli/filesapikey
976
1047
  ```
977
1048
 
978
1049
  Note: the private key argument represents the actual PEM string. In order to read the content from a file, use the @file: prefix. But if the @file: argument is used as is, it will read the file and set in the config file. So to keep the "@file" tag in the configuration file, the @val: prefix is added.
979
1050
 
980
- * CLI is ready to use:
1051
+ The JWT "subject", i.e. the Aspera Files user identifier (email) is provided with:
1052
+
1053
+ ```bash
1054
+ $ aslmcli config id my_files_org set username user@example.com
1055
+ ```
1056
+
1057
+ ### Web
1058
+
1059
+ (do not follow if JWT was selected).
1060
+ It is also possible to use a web browser based method to generate Bearer token, like done
1061
+ when using a web browser to access the Aspera Files application. In that case, no private key is needed, but the user us required to login using a URL (refer to [this section](#graphical)) when Bearer token have expired, making this method not suitable for use in automated scripts.
1062
+
1063
+ Upon successful authentication, auth token are saved (cache) in local files, and
1064
+ can be used subsequently. Expired token are refreshed if possible (without user further authentication).
1065
+
1066
+ The redirection URI shall be provided (keep this value):
1067
+
1068
+ ```bash
1069
+ $ aslmcli config id my_files_org set redirect_uri http://local.connectme.us:12345
1070
+ ```
1071
+
1072
+ ### Example
981
1073
 
982
1074
  ```bash
983
1075
  $ aslmcli files repo browse /
1076
+ Current Workspace: My Org (default)
984
1077
  :..............................:........:................:...........:......................:..............:
985
1078
  : name : type : recursive_size : size : modified_time : access_level :
986
1079
  :..............................:........:................:...........:......................:..............:
@@ -995,14 +1088,58 @@ $ aslmcli files repo browse /
995
1088
 
996
1089
  ### Administration
997
1090
 
998
- It is possible to create, update, delete any entity of Files (users, group, nodes, workspace, etc...) using the `admin resource` command. Even Bulk creation is possible: `bulk_create` expects a file whose format is one extended value per line.
1091
+ The `admin` command allows several administrative tasks (and require admin privilege).
1092
+
1093
+ It allows actions (create, update, delete) on "resources": users, group, nodes, workspace, etc... with the `admin resource` command.
1094
+
1095
+ Bulk operations are possible using option `bulk` (yes,no(default)): currently: create only. In that case, the operation expects an Array of Hash instead of a simple Hash using the [Extended Value Syntax](#extended).
1096
+
1097
+ #### Example
1098
+
1099
+ * Bulk creation
1100
+
1101
+ ```bash
1102
+ aslmcli files admin res user create --bulk=yes @json:'[{"email":"dummyuser1@example.com"},{"email":"dummyuser2@example.com"}]'
1103
+ :.......:.........:
1104
+ : id : status :
1105
+ :.......:.........:
1106
+ : 98398 : created :
1107
+ : 98399 : created :
1108
+ :.......:.........:
1109
+ ```
1110
+
1111
+ * Find with filter and delete
1112
+
1113
+ ```bash
1114
+ $ aslmcli files admin res user list --query='@json:{"q":"dummyuser"}' --fields=id,email
1115
+ :.......:........................:
1116
+ : id : email :
1117
+ :.......:........................:
1118
+ : 98398 : dummyuser1@example.com :
1119
+ : 98399 : dummyuser2@example.com :
1120
+ :.......:........................:
1121
+ $ thelist=$(echo $(aslmcli files admin res user list --query='@json:{"q":"dummyuser"}' --fields=id,email --field=id --format=csv)|tr ' ' ,)
1122
+ $ echo $thelist
1123
+ 98398,98399
1124
+ $ aslmcli files admin res user id @json:[$thelist] delete --bulk=yes
1125
+ :.......:.........:
1126
+ : id : status :
1127
+ :.......:.........:
1128
+ : 98398 : deleted :
1129
+ : 98399 : deleted :
1130
+ :.......:.........:
1131
+ ```
999
1132
 
1000
1133
  ## Aspera Node (Transfer Server)
1001
1134
 
1135
+ ### Simple Operations
1136
+
1137
+ It is possible to browse and transfer and various operations.
1138
+
1002
1139
  ### FASP Stream
1003
1140
  It is possible to start a FASPStream session using the node API:
1004
1141
 
1005
- Use the "node stream create" command, then arguments are provided as a "transfer spec".
1142
+ Use the "node stream create" command, then arguments are provided as a [_transfer-spec_](#_transferspec_).
1006
1143
 
1007
1144
  ```bash
1008
1145
  ./bin/aslmcli node stream create --ts=@json:'{"direction":"send","source":"udp://233.3.3.4:3000?loopback=1&ttl=2","destination":"udp://233.3.3.3:3001/","remote_host":"localhost","remote_user":"stream","remote_password":"XXXX"}' --load-params=stream
@@ -1107,7 +1244,7 @@ $ aslmcli server browse /aspera-test-dir-large
1107
1244
  $ aslmcli server download /aspera-test-dir-large/200MB
1108
1245
  ```
1109
1246
 
1110
- This creates a parameter group "aspera_demo_server" and set it as default for application "server"
1247
+ This creates a option preset "aspera_demo_server" and set it as default for application "server"
1111
1248
 
1112
1249
 
1113
1250
  ## IBM Aspera Faspex
@@ -1138,13 +1275,15 @@ The node configuration name is "my_faspex_node" here.
1138
1275
 
1139
1276
  ## Aspera Transfer Service
1140
1277
 
1278
+ Aka Aspera Files, Aspera on Cloud...
1279
+
1141
1280
  ### First time use
1142
1281
 
1143
1282
  Using the ATS requires an "Aspera ID" (https://id.asperasoft.com/) and have a subscription associated to it.
1144
1283
 
1145
1284
  On first execution, the user is asked to login to Aspera ID using a web browser. This creates an "ats_id" identifier (stored in a cache file).
1146
1285
 
1147
- When only one ats_id is created, it is taken by default. Else it shall be specified with --ats-id or using a parameter group.
1286
+ When only one ats_id is created, it is taken by default. Else it shall be specified with --ats-id or using a option preset.
1148
1287
 
1149
1288
  Note: APIs are described here: [https://ts.asperasoft.com/ats-guide/getting-started-guide/# guide_transfers_create_ak](https://ts.asperasoft.com/ats-guide/getting-started-guide/# guide_transfers_create_ak)
1150
1289
 
@@ -1183,7 +1322,9 @@ delete all my access keys:
1183
1322
  for k in $(aslmcli ats access_key list --field=id --format=csv);do aslmcli ats access_key id $k delete;done
1184
1323
  ```
1185
1324
 
1186
- ## Preview: Generation of previews for Aspera Files
1325
+ ## Preview
1326
+
1327
+ The preview plugin provides generation of previews for Aspera Files.
1187
1328
 
1188
1329
  The tool requires the following external tools:
1189
1330
 
@@ -1206,7 +1347,7 @@ This is related to:
1206
1347
 
1207
1348
  ### Configuration
1208
1349
 
1209
- Like any aslmcli commands, parameters can be passed on command line or using a configuration parameter group. Example using a parameter group:
1350
+ Like any aslmcli commands, parameters can be passed on command line or using a configuration option preset. Example using a option preset:
1210
1351
 
1211
1352
  ```
1212
1353
  $ aslmcli config id default set preview my_files_access_key
@@ -1335,7 +1476,7 @@ service xvfb start
1335
1476
  This gem comes with a second executable tool providing a simplified standardized interface to start a FASP
1336
1477
  session: ```asession```.
1337
1478
 
1338
- It aims at simplifying the startup of a FASP session from a programmatic stand point as formating a transfer spec is:
1479
+ It aims at simplifying the startup of a FASP session from a programmatic stand point as formating a [_transfer-spec_](#_transferspec_) is:
1339
1480
 
1340
1481
  * common to Aspera Node API (HTTP POST /ops/transfer)
1341
1482
  * common to Aspera Connect API (browser javascript startTransfer)
@@ -1343,9 +1484,9 @@ It aims at simplifying the startup of a FASP session from a programmatic stand p
1343
1484
 
1344
1485
  This makes it easy to integrate with any language provided that one can spawn a sub process, write to its STDIN, read from STDOUT, generate and parse JSON.
1345
1486
 
1346
- The tool expect one single argument: a transfer spec (see [Transfer spec](#transfer-spec)) hash value using the extended argument syntax ( see [Option and Argument values](#option-and-argument-values)).
1487
+ The tool expect one single argument: a [_transfer-spec_](#_transferspec_).
1347
1488
 
1348
- If not argument is provided, it assumes a value of: `@json:@stdin`, i.e. a JSON formated transfer spec on stdin.
1489
+ If not argument is provided, it assumes a value of: `@json:@stdin`, i.e. a JSON formated [_transfer-spec_](#_transferspec_) on stdin.
1349
1490
 
1350
1491
  Note that if JSON is the format, one has to specify `@json:` to tell the tool to decode the hash using JSON.
1351
1492
 
@@ -1408,7 +1549,7 @@ So, it evolved into `aslmcli`:
1408
1549
 
1409
1550
  * portable: works on platforms supporting `ruby` (and `ascp`)
1410
1551
  * easy to install with the `gem` utility
1411
- * supports transfers with multiple agents, that&apos;s why transfer parameters moved from ascp command line to transfer specification (more reliable , more standard)
1552
+ * supports transfers with multiple [Transfer Agents](#agents), that&apos;s why transfer parameters moved from ascp command line to [_transfer-spec_](#_transferspec_) (more reliable , more standard)
1412
1553
  * `ruby` is consistent with other Aspera products
1413
1554
 
1414
1555
 
@@ -22,7 +22,7 @@ module Asperalm
22
22
  singleton_class.send(:alias_method, :tool, :instance)
23
23
  def self.version;return @@TOOL_VERSION;end
24
24
  private
25
- @@TOOL_VERSION='0.6.7'
25
+ @@TOOL_VERSION='0.6.8'
26
26
  # first level command for the main tool
27
27
  @@MAIN_PLUGIN_NAME_STR='config'
28
28
  # name of application, also foldername where config is stored
@@ -518,7 +518,7 @@ module Asperalm
518
518
  case action
519
519
  when :id
520
520
  config_name=@options.get_next_argument('config name')
521
- action=@options.get_next_argument('action',[:set,:delete,:initialize,:show,:update])
521
+ action=@options.get_next_argument('action',[:set,:delete,:initialize,:show,:update,:ask])
522
522
  case action
523
523
  when :show
524
524
  raise "no such config: #{config_name}" unless @loaded_configs.has_key?(config_name)
@@ -541,7 +541,7 @@ module Asperalm
541
541
  write_config_file
542
542
  return Main.result_status("updated: #{config_name}->#{param_name} to #{param_value}")
543
543
  when :initialize
544
- config_value=@options.get_next_argument('config value')
544
+ config_value=@options.get_next_argument('extended value (Hash)')
545
545
  if @loaded_configs.has_key?(config_name)
546
546
  Log.log.warn("configuration already exists: #{config_name}, overwriting")
547
547
  end
@@ -556,6 +556,15 @@ module Asperalm
556
556
  @loaded_configs[config_name].merge!(theopts)
557
557
  write_config_file
558
558
  return Main.result_status("updated: #{config_name}")
559
+ when :ask
560
+ @options.use_interactive=:yes
561
+ @loaded_configs[config_name]||={}
562
+ @options.get_next_argument('option names',:multiple).each do |optionname|
563
+ option_value=@options.get_interactive(:option,optionname)
564
+ @loaded_configs[config_name][optionname]=option_value
565
+ end
566
+ write_config_file
567
+ return Main.result_status("updated: #{config_name}")
559
568
  end
560
569
  when :documentation
561
570
  OpenApplication.instance.uri(@@HELP_URL)
@@ -154,7 +154,7 @@ module Asperalm
154
154
  Log.log.debug("set_argv:commands/args=#{@unprocessed_arguments},options=#{@unprocessed_options}".red)
155
155
  end
156
156
 
157
- def get_interactive(descr,expected=:single)
157
+ def get_interactive(type,descr,expected=:single)
158
158
  if !@use_interactive.eql?(:yes)
159
159
  if expected.is_a?(Array)
160
160
  raise self.class.cli_bad_arg("missing: #{descr}",expected)
@@ -167,16 +167,16 @@ module Asperalm
167
167
  result=[]
168
168
  puts " (one per line, end with empty line)"
169
169
  loop do
170
- print "#{descr}> "
170
+ print "#{type}: #{descr}> "
171
171
  entry=STDIN.gets.chomp
172
172
  break if entry.empty?
173
173
  result.push(self.class.get_extended_value(descr,entry))
174
174
  end
175
175
  when :single
176
- print "#{descr}> "
176
+ print "#{type}: #{descr}> "
177
177
  result=self.class.get_extended_value(descr,STDIN.gets.chomp)
178
178
  else # one fixed
179
- print "#{expected.join(' ')}\n#{descr}> "
179
+ print "#{expected.join(' ')}\n#{type}: #{descr}> "
180
180
  result=self.class.get_from_list(STDIN.gets.chomp,descr,expected)
181
181
  end
182
182
  end
@@ -186,7 +186,7 @@ module Asperalm
186
186
  # or :single for a single unconstrained value
187
187
  def get_next_argument(descr,expected=:single,is_type=:mandatory)
188
188
  if is_type.eql?(:mandatory) and @unprocessed_arguments.empty?
189
- result=get_interactive(descr,expected)
189
+ result=get_interactive(:argument,descr,expected)
190
190
  else # there are values
191
191
  case expected
192
192
  when :single
@@ -255,7 +255,7 @@ module Asperalm
255
255
  if @options_symbol_list.has_key?(option_symbol)
256
256
  expected=@options_symbol_list[option_symbol]
257
257
  end
258
- result=get_interactive(option_symbol.to_s,expected)
258
+ result=get_interactive(:option,option_symbol.to_s,expected)
259
259
  set_option(option_symbol,result)
260
260
  end
261
261
  end
@@ -13,8 +13,10 @@ module Asperalm
13
13
 
14
14
  def declare_options
15
15
  Main.tool.options.set_option(:download_mode,:fasp)
16
+ Main.tool.options.set_option(:bulk,:no)
16
17
  Main.tool.options.add_opt_list(:download_mode,[:fasp, :node_http ],"download mode")
17
18
  Main.tool.options.add_opt_list(:auth,Oauth.auth_types,"type of authentication",'-tTYPE')
19
+ Main.tool.options.add_opt_list(:bulk,[:no,:yes],"download mode")
18
20
  Main.tool.options.add_opt_simple(:url,"URL of application, e.g. http://org.asperafiles.com")
19
21
  Main.tool.options.add_opt_simple(:username,"username to log in")
20
22
  Main.tool.options.add_opt_simple(:password,"user's password")
@@ -24,7 +26,7 @@ module Asperalm
24
26
  Main.tool.options.add_opt_simple(:title,"package title")
25
27
  Main.tool.options.add_opt_simple(:note,"package note")
26
28
  Main.tool.options.add_opt_simple(:secret,"access key secret for node")
27
- Main.tool.options.add_opt_simple(:query,"for json query")
29
+ Main.tool.options.add_opt_simple(:query,"list filter (extended value: encode_www_form)")
28
30
  end
29
31
 
30
32
  # returns a node API for access key
@@ -116,13 +118,13 @@ module Asperalm
116
118
  node_info,file_id = find_nodeinfo_and_fileid(home_node_id,fileid,"")
117
119
  node_api=get_files_node_api(node_info,FilesApi::SCOPE_NODE_USER)
118
120
  items=node_api.read("files/#{file_id}")[:data]
119
- return {:data=>items,:type=>:key_val_list}
121
+ return {:type=>:key_val_list,:data=>items}
120
122
  when :browse
121
123
  thepath=Main.tool.options.get_next_argument("path")
122
124
  node_info,file_id = find_nodeinfo_and_fileid(home_node_id,home_file_id,thepath)
123
125
  node_api=get_files_node_api(node_info,FilesApi::SCOPE_NODE_USER)
124
126
  items=node_api.read("files/#{file_id}/files")[:data]
125
- return {:data=>items,:type=>:hash_array,:fields=>['name','type','recursive_size','size','modified_time','access_level']}
127
+ return {:type=>:hash_array,:data=>items,:fields=>['name','type','recursive_size','size','modified_time','access_level']}
126
128
  when :upload
127
129
  filelist = Main.tool.options.get_next_argument("file list",:multiple)
128
130
  Log.log.debug("file list=#{filelist}")
@@ -234,6 +236,19 @@ module Asperalm
234
236
  return @workspace_id == self_data['default_workspace_id']
235
237
  end
236
238
 
239
+ def do_bulk_operation(params,success,&do_action)
240
+ params=[params] if Main.tool.options.get_option(:bulk).eql?(:no)
241
+ raise "expecting Array" unless params.is_a?(Array)
242
+ result=[]
243
+ params.each do |p|
244
+ # todo: manage exception and display status by default
245
+ one=do_action.call(p)
246
+ one['status']=success
247
+ result.push(one)
248
+ end
249
+ return {:type=>:hash_array,:data=>result,:fields=>['id','status']}
250
+ end
251
+
237
252
  def execute_action
238
253
  use_default_ws=init_apis_is_default_ws
239
254
  command=Main.tool.options.get_next_argument('command',action_list)
@@ -285,7 +300,7 @@ module Asperalm
285
300
  when :list
286
301
  # list all packages ('page'=>1,'per_page'=>10,)'sort'=>'-sent_at',
287
302
  packages=@api_files_user.read("packages",{'archived'=>false,'exclude_dropbox_packages'=>true,'has_content'=>true,'received'=>true,'workspace_id'=>@workspace_id})[:data]
288
- return {:data=>packages,:fields=>['id','name','bytes_transferred'],:type=>:hash_array}
303
+ return {:type=>:hash_array,:data=>packages,:fields=>['id','name','bytes_transferred']}
289
304
  end
290
305
  when :repository
291
306
  return execute_node_action(@workspace_data['home_node_id'],@workspace_data['home_file_id'])
@@ -298,7 +313,7 @@ module Asperalm
298
313
  when :search_nodes
299
314
  ak=Main.tool.options.get_next_argument('access_key')
300
315
  nodes=@api_files_admin.read("search_nodes",{'q'=>'access_key:"'+ak+'"'})[:data]
301
- return {:data=>nodes,:type=>:other_struct}
316
+ return {:type=>:other_struct,:data=>nodes}
302
317
  when :events
303
318
  # page=1&per_page=10&q=type:(file_upload+OR+file_delete+OR+file_download+OR+file_rename+OR+folder_create+OR+folder_delete+OR+folder_share+OR+folder_share_via_public_link)&sort=-date
304
319
  #events=@api_files_admin.read('events',{'q'=>'type:(file_upload OR file_download)'})[:data]
@@ -314,7 +329,7 @@ module Asperalm
314
329
  # iteration_token=nnn
315
330
  # active_only=true|false
316
331
  events=api_node.read("ops/transfers",{'count'=>100,'filter'=>'summary','active_only'=>'true'})[:data]
317
- return {:data=>events,:fields=>['id','status'],:type=>:hash_array}
332
+ return {:type=>:hash_array,:data=>events,:fields=>['id','status']}
318
333
  #transfers=api_node.make_request_ex({:operation=>'GET',:subpath=>'ops/transfers',:args=>{'count'=>25,'filter'=>'id'}})
319
334
  #transfers=api_node.read("events") # after_time=2016-05-01T23:53:09Z
320
335
  when :set_client_key
@@ -331,18 +346,11 @@ module Asperalm
331
346
  command=Main.tool.options.get_next_argument('command',operations)
332
347
  case command
333
348
  when :create
334
- params=Main.tool.options.get_next_argument("creation data (native hash)")
335
- resp=@api_files_admin.create(resource_class_path,params)
336
- return {:data=>resp[:data],:type => :other_struct}
337
- when :bulk_create
338
- bulk_file_path=Main.tool.options.get_next_argument("creation data in file (one native hash per line)")
339
- result=[]
340
- File.open(bulk_file_path, "r").each_line do |line|
341
- params=Cli::Manager.get_extended_value("creation data (native hash)",line.chomp)
342
- puts "[#{line}]"
343
- result.push(@api_files_admin.create(resource_class_path,params)[:data])
349
+ list_or_one=Main.tool.options.get_next_argument("creation data (Hash)")
350
+ return do_bulk_operation(list_or_one,'created')do|params|
351
+ raise "expecting Hash" unless params.is_a?(Hash)
352
+ @api_files_admin.create(resource_class_path,params)[:data]
344
353
  end
345
- return {:type => :hash_array,:data=>result}
346
354
  when :list
347
355
  default_fields=['id','name']
348
356
  case resource
@@ -351,12 +359,8 @@ module Asperalm
351
359
  when :contact; default_fields=["email","name","source_id","source_type"]
352
360
  end
353
361
  query=Main.tool.options.get_option(:query,:optional)
354
- args=nil
355
- if !query.nil?
356
- args={'json_query'=>query}
357
- end
358
- Log.log.debug("#{args}".bg_red)
359
- return {:data=>@api_files_admin.read(resource_class_path,args)[:data],:fields=>default_fields,:type=>:hash_array}
362
+ Log.log.debug("#{query}".bg_red)
363
+ return {:type=>:hash_array,:data=>@api_files_admin.read(resource_class_path,query)[:data],:fields=>default_fields}
360
364
  when :id
361
365
  #raise RuntimeError, "unexpected resource type: #{resource}, only 'node' for actions" if !resource.eql?(:node)
362
366
  res_id=Main.tool.options.get_next_argument('resource id')
@@ -375,8 +379,10 @@ module Asperalm
375
379
  @api_files_admin.update(resource_id_path,changes)
376
380
  return Main.result_status('deleted')
377
381
  when :delete
378
- @api_files_admin.delete(resource_id_path)
379
- return Main.result_status('deleted')
382
+ return do_bulk_operation(res_id,'deleted')do|one_id|
383
+ @api_files_admin.delete("#{resource_class_path}/#{one_id.to_s}")
384
+ {'id'=>one_id}
385
+ end
380
386
  when :do
381
387
  res_data=@api_files_admin.read(resource_id_path)[:data]
382
388
  api_node=get_files_node_api(res_data)
@@ -389,7 +395,7 @@ module Asperalm
389
395
  end
390
396
  end #op_or_id
391
397
  when :usage_reports
392
- return {:data=>@api_files_admin.read("usage_reports",{:workspace_id=>@workspace_id})[:data],:type=>:hash_array}
398
+ return {:type=>:hash_array,:data=>@api_files_admin.read("usage_reports",{:workspace_id=>@workspace_id})[:data]}
393
399
  end
394
400
  else
395
401
  raise RuntimeError, "unexpected value: #{command}"
metadata CHANGED
@@ -1,14 +1,14 @@
1
1
  --- !ruby/object:Gem::Specification
2
2
  name: asperalm
3
3
  version: !ruby/object:Gem::Version
4
- version: 0.6.7
4
+ version: 0.6.8
5
5
  platform: ruby
6
6
  authors:
7
7
  - Laurent Martin
8
8
  autorequire:
9
9
  bindir: bin
10
10
  cert_chain: []
11
- date: 2018-03-20 00:00:00.000000000 Z
11
+ date: 2018-03-23 00:00:00.000000000 Z
12
12
  dependencies:
13
13
  - !ruby/object:Gem::Dependency
14
14
  name: xml-simple