root / docs / usage.rst @ 76769d2f
History | View | Annotate | Download (22.6 kB)
1 |
Usage |
---|---|
2 |
===== |
3 |
|
4 |
Kamaki features commands of the form:: |
5 |
|
6 |
[kamaki] <object> <action> [identifier(s)] <non-positional arguments> |
7 |
e.g., |
8 |
kamaki user info --username=user@example.com |
9 |
|
10 |
A detailed list of the command specifications can be found in |
11 |
`Commands <commands.html>`_ section. |
12 |
|
13 |
All commands can run either from the host shell or through the kamaki |
14 |
interactive shell: |
15 |
|
16 |
.. code-block:: console |
17 |
|
18 |
# Run from host shell |
19 |
$ kamaki user info |
20 |
... RESULTS ... |
21 |
|
22 |
# Run from kamaki interactive shell |
23 |
$ kamaki-shell |
24 |
[kamaki]: user info |
25 |
... RESULTS ... |
26 |
|
27 |
In the later, the term "one-command" will be user to refer to running kamaki |
28 |
commands from host shell, while the term "shell" will refer to the kamaki's own |
29 |
interactive shell |
30 |
|
31 |
.. note:: This section refers to the kamaki CLI. Developers and people who write |
32 |
scripts, should rather use the the |
33 |
`Clients lib <developers/code.html#the-clients-api>`_ instead of the kamaki |
34 |
CLI. |
35 |
|
36 |
Quick Setup |
37 |
----------- |
38 |
|
39 |
Kamaki interfaces rely on a list of configuration options. Check the |
40 |
`Setup <setup.html>`_ guide for a full list. |
41 |
|
42 |
As rule of the thump, it is enough to set a cloud authentication URL and TOKEN: |
43 |
|
44 |
.. code-block:: console |
45 |
:emphasize-lines: 1 |
46 |
|
47 |
Example 1.1: Set authentication URL, user token for cloud alias "default" |
48 |
|
49 |
$ kamaki config set cloud.default.url <authentication URL> |
50 |
$ kamaki config set cloud.default.token myt0k3n== |
51 |
|
52 |
.. note:: The term *default* can be replaced by any arbitary term chosen by |
53 |
the user. |
54 |
|
55 |
Shell vs one-command |
56 |
-------------------- |
57 |
|
58 |
Kamaki users can access Synnefo services through either the kamaki shell or the |
59 |
one-command interface. Both systems feature identical responses and error |
60 |
messages, since they rely on the same internal command and library API |
61 |
implementation. However, there are some minor differences. |
62 |
|
63 |
In favor of interactive shell: |
64 |
|
65 |
* shorter commands (context switching) |
66 |
* tab completion for commands (if supported by host shell) |
67 |
* kamaki-specific history with ↑ or ↓ keys (if supported by host shell) |
68 |
* re-run old commands with /history |
69 |
|
70 |
In favor of one-command: |
71 |
|
72 |
* users take advantage of host shell features (pipelines, redirection, etc.) |
73 |
* can be used in shell scripts |
74 |
|
75 |
Run as shell |
76 |
^^^^^^^^^^^^ |
77 |
To use kamaki as a shell, run: |
78 |
|
79 |
.. code-block:: console |
80 |
:emphasize-lines: 1 |
81 |
|
82 |
Example 2.2.1: Run kamaki shell |
83 |
|
84 |
$ kamaki-shell |
85 |
|
86 |
* with any kind of '-' prefixed arguments, except '-h', '--help', '-V', |
87 |
'- - version'. |
88 |
|
89 |
.. code-block:: console |
90 |
:emphasize-lines: 1 |
91 |
|
92 |
Example 2.2.2: Run kamaki shell with custom configuration file |
93 |
|
94 |
$ kamaki-shell -c myconfig.file |
95 |
|
96 |
Example 2.2.3: Run kamaki shell so as to use a specific cloud |
97 |
|
98 |
$ kamaki-shell --cloud=my_demo_cloud |
99 |
|
100 |
Example 2.2.4: Run kamaki shell with verbosity (shows HTTP requests) |
101 |
|
102 |
$ kamaki-shell -v |
103 |
|
104 |
.. note:: Valid arguments can be combined e.g., it is ok to run a shell with |
105 |
verbosity and a specific cloud:: |
106 |
|
107 |
$ kamaki-shell -v --cloud=my_demo_cloud |
108 |
|
109 |
Run as one-command |
110 |
^^^^^^^^^^^^^^^^^^ |
111 |
To use kamaki as an one-command tool, run: |
112 |
|
113 |
* with the '-h' or '--help' arguments (help for kamaki one-command) |
114 |
|
115 |
.. code-block:: console |
116 |
:emphasize-lines: 1 |
117 |
|
118 |
Example 2.3.1: Kamaki help |
119 |
|
120 |
$kamaki -h |
121 |
|
122 |
* with one or more command parameters (object and, maybe, action): |
123 |
|
124 |
.. code-block:: console |
125 |
:emphasize-lines: 1 |
126 |
|
127 |
Example 2.3.2: List servers managed by user |
128 |
|
129 |
$ kamaki server list |
130 |
|
131 |
One-command interface |
132 |
--------------------- |
133 |
|
134 |
Using help |
135 |
^^^^^^^^^^ |
136 |
|
137 |
Kamaki help provides information on commands (description, syntax). |
138 |
|
139 |
To see the command groups (objects), use -h or --help (example 1.3.1). The |
140 |
following examples demonstrate the help messages of kamaki, in the context of a |
141 |
command group (server) and of a command in that group (list). |
142 |
|
143 |
.. code-block:: console |
144 |
:emphasize-lines: 1 |
145 |
|
146 |
Example 3.1.1: kamaki help shows available parameters and command groups |
147 |
|
148 |
|
149 |
$ kamaki -h |
150 |
usage: kamaki <cmd_group> [<cmd_subbroup> ...] <cmd> |
151 |
[-v] [-s] [-V] [-d] [-c CONFIG] [-o OPTIONS] [--cloud CLOUD] [-h] |
152 |
|
153 |
optional arguments: |
154 |
-v, --verbose More info at response |
155 |
-s, --silent Do not output anything |
156 |
-V, --version Print current version |
157 |
-d, --debug Include debug output |
158 |
-c CONFIG, --config CONFIG |
159 |
Path to configuration file |
160 |
-o OPTIONS, --options OPTIONS |
161 |
Override a config value |
162 |
--cloud CLOUD Chose a cloud to connect to |
163 |
-h, --help Show help message |
164 |
|
165 |
Options: |
166 |
- - - - |
167 |
resource: Astakos/Account API commands for resources |
168 |
group: Pithos+/Storage user groups |
169 |
network: Networking API network commands |
170 |
subnet: Networking API network commands |
171 |
ip: Networking API floatingip commands |
172 |
image: Cyclades/Plankton API image commands |
173 |
imagecompute: Cyclades/Compute API image commands |
174 |
quota: Astakos/Account API commands for quotas |
175 |
sharer: Pithos+/Storage sharers |
176 |
project: Astakos project API commands |
177 |
user: Astakos/Identity API commands |
178 |
file: Pithos+/Storage object level API commands |
179 |
container: Pithos+/Storage container level API commands |
180 |
flavor: Cyclades/Compute API flavor commands |
181 |
server: Cyclades/Compute API server commands |
182 |
config: Kamaki configurations |
183 |
port: Networking API network commands |
184 |
history: Kamaki command history |
185 |
kamaki-shell: An interactive command line shell |
186 |
|
187 |
.. code-block:: console |
188 |
:emphasize-lines: 1,2 |
189 |
|
190 |
Example 3.1.2: Cyclades help contains all first-level commands of Cyclades |
191 |
command group |
192 |
|
193 |
$ kamaki server -h |
194 |
usage: kamaki server <...> [-v] [-s] [-V] [-d] [-c CONFIG] |
195 |
[-o OPTIONS] [--cloud CLOUD] [-h] |
196 |
|
197 |
optional arguments: |
198 |
-v, --verbose More info at response |
199 |
-s, --silent Do not output anything |
200 |
-V, --version Print current version |
201 |
-d, --debug Include debug output |
202 |
-c CONFIG, --config CONFIG |
203 |
Path to configuration file |
204 |
-o OPTIONS, --options OPTIONS |
205 |
Override a config value |
206 |
--cloud CLOUD Chose a cloud to connect to |
207 |
-h, --help Show help message |
208 |
|
209 |
Options: |
210 |
- - - - |
211 |
info: Detailed information on a Virtual Machine |
212 |
modify: Modify attributes of a virtual server |
213 |
create: Create a server (aka Virtual Machine) |
214 |
list: List virtual servers accessible by user |
215 |
reboot: Reboot a virtual server |
216 |
start: Start an existing virtual server |
217 |
shutdown: Shutdown an active virtual server |
218 |
delete: Delete a virtual server |
219 |
|
220 |
.. code-block:: console |
221 |
:emphasize-lines: 1,2 |
222 |
|
223 |
Example 3.1.3: Help for command "server list" with syntax, description and |
224 |
available user options |
225 |
|
226 |
$ kamaki server list -h |
227 |
usage: kamaki server list [-v] [-s] [-V] [-d] [-c CONFIG] [-o OPTIONS] |
228 |
[--cloud CLOUD] [-h] [--since SINCE] [--enumerate] |
229 |
[-l] [--more] [-n LIMIT] [-j] |
230 |
|
231 |
List Virtual Machines accessible by user |
232 |
|
233 |
optional arguments: |
234 |
-v, --verbose More info at response |
235 |
-s, --silent Do not output anything |
236 |
-V, --version Print current version |
237 |
-d, --debug Include debug output |
238 |
-c CONFIG, --config CONFIG |
239 |
Path to config file |
240 |
-o OPTIONS, --options OPTIONS |
241 |
Override a config value |
242 |
--cloud CLOUD Chose a cloud to connect to |
243 |
-h, --help Show help message |
244 |
--status STATUS filter by status (ACTIVE, STOPPED, REBOOT, ERROR, |
245 |
etc.) |
246 |
--enumerate Enumerate results |
247 |
--name-suffix NAME_SUFF |
248 |
filter by name suffix (case insensitive) |
249 |
--image-id IMAGE_ID filter by image id |
250 |
--metadata META filter by metadata key=values |
251 |
-j, --json show headers in json |
252 |
--id ID filter by id |
253 |
--user-id USER_ID filter by user id |
254 |
--id-like ID_LIKE print only if id contains this (case insensitive) |
255 |
--id-suffix ID_SUFF filter by id suffix (case insensitive) |
256 |
--since SINCE show only items since date (' d/m/Y H:M:S ') |
257 |
-l, --details show detailed output |
258 |
--name NAME filter by name |
259 |
--more output results in pages (-n to set items per page, |
260 |
default 10) |
261 |
--name-prefix NAME_PREF |
262 |
filter by name prefix (case insensitive) |
263 |
-n LIMIT, --number LIMIT |
264 |
limit number of listed virtual servers |
265 |
--id-prefix ID_PREF filter by id prefix (case insensitive) |
266 |
--user-name USER_NAME |
267 |
filter by user name |
268 |
--name-like NAME_LIKE |
269 |
print only if name contains this (case insensitive) |
270 |
--metadata-like META_LIKE |
271 |
print only if in key=value, the value is part of |
272 |
actual value |
273 |
--flavor-id FLAVOR_ID |
274 |
filter by flavor id |
275 |
|
276 |
Details: |
277 |
Use filtering arguments (e.g., --name-like) to manage long server lists |
278 |
|
279 |
.. _using-history-ref: |
280 |
|
281 |
Using history |
282 |
^^^^^^^^^^^^^ |
283 |
|
284 |
Kamaki command history is stored in '${HOME}/.kamaki.history' by default). To |
285 |
set a custom history file path users must set the history.file config option |
286 |
(more on config options `here <setup.html#editing-options>`_). |
287 |
|
288 |
Every command is appended at the end of that file. In order to see how to use |
289 |
history, use the kamaki help system: |
290 |
|
291 |
.. code-block:: console |
292 |
:emphasize-lines: 1 |
293 |
|
294 |
Example 3.2.1: Available history options |
295 |
|
296 |
$ kamaki history -h |
297 |
Options: |
298 |
- - - - |
299 |
clean: Clean up history (permanent) |
300 |
run : Run previously executed command(s) |
301 |
show : Show intersession command history |
302 |
|
303 |
|
304 |
Example 3.2.2: Clean up everything, run a kamaki command, show full and filtered history |
305 |
|
306 |
$ kamaki history clean |
307 |
$ kamaki server list |
308 |
... |
309 |
$ kamaki history show |
310 |
1. kamaki server list |
311 |
2. kamaki history show |
312 |
$ kamaki history show --match server |
313 |
1. kamaki server list |
314 |
3. kamaki history show --match server |
315 |
|
316 |
Debug and logging |
317 |
^^^^^^^^^^^^^^^^^ |
318 |
|
319 |
Debug |
320 |
""""" |
321 |
|
322 |
When in debug mode, kamaki outputs some useful debug information (stack trace |
323 |
and http logs). Kamaki in debug mode cancels the suppression of warning |
324 |
messages too. |
325 |
|
326 |
To run kamaki in debug mode use the -d or --debug option. |
327 |
|
328 |
|
329 |
Verbose |
330 |
""""""" |
331 |
|
332 |
Most kamaki commands are translated into http requests. Kamaki clients API |
333 |
translates command semantics to REST and handles the response. Users who need |
334 |
to have access to these commands can use the verbose mode that outputs the |
335 |
HTTP Request and Response details along with the (possibly modified) regular |
336 |
command output. |
337 |
|
338 |
To run kamaki in verbose mode use the *-v/- - verbose* argument, it goes with |
339 |
everything. |
340 |
|
341 |
Verbose mode outputs the request and response mode, address and |
342 |
headers as well as the size of the data block, if any. Sensitive information |
343 |
(x-auth-token header and data body) are omitted by default,. Users who need |
344 |
this information may enable it through the log_token and log_data configuration |
345 |
options |
346 |
|
347 |
.. tip:: Use the -o argument to include http data in the output: |
348 |
|
349 |
.. code-block:: console |
350 |
|
351 |
$ kamaki server list -v -o log_data=on |
352 |
|
353 |
|
354 |
Logging |
355 |
""""""" |
356 |
|
357 |
Kamaki logs in a file specified by the *log_file* option which defaults to |
358 |
*${HOME}/.kamaki.log*. This configuration option can be modified:: |
359 |
|
360 |
kamaki config set log_file /new/log/file/path |
361 |
|
362 |
Kamaki logs http request and response information, namely the method, URL, |
363 |
headers and data size. Sensitive information (data and token header) are |
364 |
omitted by default. There are some configuration options that can switch them |
365 |
on, though: |
366 |
|
367 |
* HTTP data blocks are not logged by default |
368 |
to enable logging the full http bodies, set log_data to `on`:: |
369 |
|
370 |
kamaki config set log_data on |
371 |
|
372 |
to disable it, set it to `off`:: |
373 |
|
374 |
kamaki config set log_data off |
375 |
|
376 |
or delete it:: |
377 |
|
378 |
kamaki config delete log_data |
379 |
|
380 |
* X-Auth-Token header is not logged by default |
381 |
to enable logging the X-Auth-Token header, set log_token to `on`:: |
382 |
|
383 |
kamaki config set log_token on |
384 |
|
385 |
to disable it, set it to `off`:: |
386 |
|
387 |
kamaki config set log_token off |
388 |
|
389 |
or delete it:: |
390 |
|
391 |
kamaki config delete log_token |
392 |
|
393 |
* The information (pid, name, date) of the processes that handle http requests |
394 |
is not logged by default, because if they are, logs are difficult to read. |
395 |
Still, they are useful for resolving race condition problems, so to enable |
396 |
logging proccess information:: |
397 |
|
398 |
kamaki config set log_pid on |
399 |
|
400 |
to disable it, set if to off:: |
401 |
|
402 |
kamaki config set log_pid off |
403 |
|
404 |
or delete it:: |
405 |
|
406 |
kamaki config delete log_pid |
407 |
|
408 |
One-command features |
409 |
^^^^^^^^^^^^^^^^^^^^ |
410 |
|
411 |
.. code-block:: console |
412 |
:emphasize-lines: 1 |
413 |
|
414 |
Example 3.4.1: List the trash container contents, containing c1_ |
415 |
|
416 |
$ kamaki file list -v -o log_token=on |
417 |
... |
418 |
X-Auth-Token: s0m3-3x4mp1e-70k3n |
419 |
... |
420 |
|
421 |
The -o argument can be used to temporarily override various (set or unset) |
422 |
options. In one command, all -o option sets are forgotten just after the |
423 |
command has been completed, and the previous settings are restored (the |
424 |
configuration file is not modified). |
425 |
|
426 |
For security reasons, all commands hide the authentication token from outputs |
427 |
and the logs. In example 3.4.1 the token is not hided, because of the |
428 |
*log_token=on* config option. |
429 |
|
430 |
.. warning:: Complimentary output i.e., http logs and informative messages are |
431 |
printed to standard error stream |
432 |
|
433 |
Interactive shell |
434 |
----------------- |
435 |
|
436 |
Command Contexts |
437 |
^^^^^^^^^^^^^^^^ |
438 |
|
439 |
The command namespaces in kamaki interactive shell are called **contexts**. |
440 |
|
441 |
Each command group is also a context where the users can **enter** by typing |
442 |
the group name. If the context switch is successful, the kamaki shell prompt |
443 |
changes to present the new context ("*file*" in example 4.1.1). |
444 |
|
445 |
.. code-block:: console |
446 |
:emphasize-lines: 1 |
447 |
|
448 |
Example 4.1.1: Start kamaki and switch to file context |
449 |
|
450 |
|
451 |
$ kamaki |
452 |
[kamaki]: file |
453 |
[file]: |
454 |
|
455 |
Type **exit** (alternatively **ctrl-D** in (X)nix systems or **ctrl-Z** in |
456 |
Windows) to exit a context and return to the context of origin. If already at |
457 |
the top context (kamaki), an exit is equivalent to exiting the program. |
458 |
|
459 |
.. code-block:: console |
460 |
:emphasize-lines: 1 |
461 |
|
462 |
Example 4.1.2: Exit file context and then exit kamaki |
463 |
|
464 |
[file]: exit |
465 |
[kamaki]: exit |
466 |
$ |
467 |
|
468 |
A user might **browse** through different contexts during one session. |
469 |
|
470 |
.. code-block:: console |
471 |
:emphasize-lines: 1 |
472 |
|
473 |
Example 4.1.3: Execute list command in different contexts |
474 |
|
475 |
$ kamaki |
476 |
[kamaki]: config |
477 |
[config]: list |
478 |
... (configuration options listing) ... |
479 |
[config]: exit |
480 |
[kamaki]: file |
481 |
[file]: list |
482 |
... (file listing) ... |
483 |
[file]: exit |
484 |
[kamaki]: server |
485 |
[server]: list |
486 |
... (servers listing) ... |
487 |
[server]: exit |
488 |
[kamaki]: |
489 |
|
490 |
Users can avoid switching between contexts: all commands can run from the |
491 |
**top context** e.g., examples 4.1.3 and 4.1.4 are equivalent. |
492 |
|
493 |
.. code-block:: console |
494 |
:emphasize-lines: 1 |
495 |
|
496 |
Example 4.1.4: Execute different "list" commands from top context |
497 |
|
498 |
[kamaki]: config list |
499 |
... (configuration options listing) ... |
500 |
[kamaki]: file list |
501 |
... (file listing) ... |
502 |
[kamaki]: server list |
503 |
... (servers listing) ... |
504 |
[kamaki]: |
505 |
|
506 |
While in a context, other contexts are accessible by using a **/** as shown in |
507 |
the following example: |
508 |
|
509 |
.. code-block:: console |
510 |
|
511 |
Example 4.1.5: Execute different "list" commands from the config context |
512 |
|
513 |
[kamaki]: config |
514 |
[config]: list |
515 |
... (configuration option listing) ... |
516 |
[config]: /file list |
517 |
... (file listing) ... |
518 |
[config]: /server list |
519 |
... (servers listing) ... |
520 |
[config]: |
521 |
|
522 |
Using Help |
523 |
^^^^^^^^^^ |
524 |
|
525 |
There are two help mechanisms: a context-level and a command-level. |
526 |
|
527 |
**Context-level help** lists the available commands in a context and can also |
528 |
offer a short description for each command. |
529 |
|
530 |
Context-level help syntax:: |
531 |
|
532 |
* Show available commands in current context * |
533 |
[context]: help |
534 |
... |
535 |
[context]: ? |
536 |
... |
537 |
|
538 |
* Show help for command cmd * |
539 |
[context]: help cmd |
540 |
... |
541 |
[context]: ?cmd |
542 |
... |
543 |
|
544 |
The context-level help results may change from context to context |
545 |
|
546 |
.. code-block:: console |
547 |
:emphasize-lines: 1 |
548 |
|
549 |
Example 4.2.1: Get available commands and then get help in a context |
550 |
|
551 |
[kamaki]: help |
552 |
|
553 |
kamaki commands: |
554 |
================ |
555 |
user config flavor history image network server file ... |
556 |
|
557 |
interactive shell commands: |
558 |
=========================== |
559 |
exit help shell |
560 |
|
561 |
[kamaki]: ?config |
562 |
Configuration commands (config -h for more options) |
563 |
|
564 |
[kamaki]: config |
565 |
|
566 |
[config]: ? |
567 |
|
568 |
config commands: |
569 |
================ |
570 |
delete get list set |
571 |
|
572 |
interactive shell commands: |
573 |
=========================== |
574 |
exit help shell |
575 |
|
576 |
[config]: help set |
577 |
Set a configuration option (set -h for more options) |
578 |
|
579 |
In context-level, there is a distinction between kamaki-commands and |
580 |
interactive shell commands. The former are available in one-command mode and |
581 |
are the main functionality of kamaki, while the later are used to manage the |
582 |
kamaki-shell. |
583 |
|
584 |
**Command-level help** prints the syntax, arguments and description of a |
585 |
specific (terminal) command |
586 |
|
587 |
Command-level help syntax:: |
588 |
|
589 |
* Get help for command cmd1 cmd2 ... cmdN * |
590 |
[context]: cmd1 cmd2 ... cmdN -h |
591 |
<syntax> |
592 |
|
593 |
<description> |
594 |
|
595 |
<arguments and possible extensions> |
596 |
|
597 |
Command-level help mechanism is exactly the same as the one used in |
598 |
one-command mode. For example, it is invoked by using the -h or --help |
599 |
parameter at any point. |
600 |
|
601 |
.. code-block:: console |
602 |
:emphasize-lines: 1 |
603 |
|
604 |
Example 4.2.2: Get command-level help for config and config-set |
605 |
|
606 |
|
607 |
[kamaki]: config --help |
608 |
config: Configuration commands |
609 |
delete: Delete a configuration option (and use the default value) |
610 |
get : Show a configuration option |
611 |
list : List configuration options |
612 |
set : Set a configuration option |
613 |
|
614 |
[kamaki]: config |
615 |
|
616 |
[config]: set -h |
617 |
usage: set <option> <value> [-v] [-d] [-h] [-i] [--config CONFIG] [-s] |
618 |
|
619 |
Set a configuration option |
620 |
|
621 |
optional arguments: |
622 |
-v, --verbose More info at response |
623 |
-d, --debug Include debug output |
624 |
-h, --help Show help message |
625 |
-i, --include Include protocol headers in the output |
626 |
--config CONFIG Path to configuration file |
627 |
-s, --silent Do not output anything |
628 |
|
629 |
There are many ways of producing a help message, as shown in example 4.2.3 |
630 |
|
631 |
.. code-block:: console |
632 |
:emphasize-lines: 1 |
633 |
|
634 |
Example 4.2.3: Equivalent calls of command-level help for config-set |
635 |
|
636 |
|
637 |
[config]: set -h |
638 |
[config]: set --help |
639 |
[kamaki]: config set -h |
640 |
[kamaki]: config set --help |
641 |
[file]: /config set -h |
642 |
[server]: /config set --help |
643 |
|
644 |
History modes |
645 |
^^^^^^^^^^^^^ |
646 |
|
647 |
There are two history modes: session and permanent. Session history keeps |
648 |
record of all actions in a kamaki shell session, while permanent history |
649 |
appends all commands to an accessible history file. |
650 |
|
651 |
Session history is only available in interactive shell mode. Users can iterate |
652 |
through past commands in the same session with the ↑ and ↓ keys. Session |
653 |
history is not stored, although commands are recorded through the permanent |
654 |
history mechanism. |
655 |
|
656 |
Permanent history is implemented as a command group and is common to both the |
657 |
one-command and shell interfaces. In specific, every command is appended in a |
658 |
history file (configured as `history_file` in settings, see |
659 |
`setup section <setup.html>`_ for details). Commands executed in one-command |
660 |
mode are mixed with the ones run in kamaki shell (also see |
661 |
:ref:`using-history-ref` section on this guide). |
662 |
|
663 |
Scripting |
664 |
^^^^^^^^^ |
665 |
|
666 |
The history-run feature allows the sequential run of previous command |
667 |
executions in kamaki shell. |
668 |
|
669 |
The following sequence copies and downloads a file from *mycontainer1* , |
670 |
uploads it to *mycontainer2* , then undo the proccess and repeats it with |
671 |
history-run |
672 |
|
673 |
.. code-block:: console |
674 |
:emphasize-lines: 1,12,19,32 |
675 |
|
676 |
* Download mycontainer1:myfile and upload it to mycontainer2:myfile * |
677 |
[kamaki]: file |
678 |
[file]: copy /mycontainer1/somefile /mycontainer1/myfile |
679 |
[file]: download /mycontainer1/myfile mylocalfile |
680 |
... |
681 |
Download completed |
682 |
[file]: upload mylocalfile /mycontainer2/myfile -f |
683 |
... |
684 |
Upload completed |
685 |
|
686 |
* undo the process * |
687 |
[file]: !rm mylocalfile |
688 |
[file]: delete /mycontainer1/myfile |
689 |
[file]: delete /mycontainer2/myfile |
690 |
|
691 |
* check history entries * |
692 |
[file]: exit |
693 |
[kamaki]: history |
694 |
[history]: show |
695 |
1. file |
696 |
2. file copy /mycontainer1/somefile /mycontainer1/myfile |
697 |
3. file download /mycontainer1/myfile mylocalfile |
698 |
4. file upload mylocalfile /mycontainer2/myfile -f |
699 |
5. file delete /mycontainer1/myfile |
700 |
6. file delete /mycontainer2/myfile |
701 |
7. history |
702 |
8. history show |
703 |
|
704 |
*repeat the process * |
705 |
[history]: run 2-4 |
706 |
<file copy /mycontainer1/somefile /mycontainer1/myfile> |
707 |
<file download /mycontainer1/myfile mylocalfile> |
708 |
Download completed |
709 |
<file upload mylocalfile /mycontainer2/myfile> |
710 |
Upload completed |
711 |
|
712 |
The suggested best practice for scripting is python scripts that import the |
713 |
`kamaki.clients` library. Another option is host shell scripting (e.g., bash) |
714 |
with kamaki one-command. Still, the history-run functionality might prove handy |
715 |
in many occasions. |
716 |
|
717 |
OS Shell integration |
718 |
^^^^^^^^^^^^^^^^^^^^ |
719 |
|
720 |
Kamaki shell features the ability to execute OS-shell commands from any |
721 |
context. This can be achieved by typing *!* or *shell*:: |
722 |
|
723 |
[kamaki_context]: !<OS shell command> |
724 |
... OS shell command output ... |
725 |
|
726 |
[kamaki_context]: shell <OS shell command> |
727 |
... OS shell command output ... |
728 |
|
729 |
.. code-block:: console |
730 |
:emphasize-lines: 1 |
731 |
|
732 |
Example 4.7.1: Run unix-style shell commands from kamaki shell |
733 |
|
734 |
|
735 |
[kamaki]: !ls -al |
736 |
total 16 |
737 |
drwxrwxr-x 2 username username 4096 Nov 27 16:47 . |
738 |
drwxrwxr-x 7 username username 4096 Nov 27 16:47 .. |
739 |
-rw-rw-r-- 1 username username 8063 Jun 28 14:48 kamaki-logo.png |
740 |
|
741 |
[kamaki]: shell cp kamaki-logo.png logo-copy.png |
742 |
|
743 |
[kamaki]: shell ls -al |
744 |
total 24 |
745 |
drwxrwxr-x 2 username username 4096 Nov 27 16:47 . |
746 |
drwxrwxr-x 7 username username 4096 Nov 27 16:47 .. |
747 |
-rw-rw-r-- 1 username username 8063 Jun 28 14:48 kamaki-logo.png |
748 |
-rw-rw-r-- 1 username username 8063 Jun 28 14:48 logo-copy.png |
749 |
|
750 |
|
751 |
Kamaki shell commits command strings to the outside shell and prints the |
752 |
results, without interacting with it. After a command is finished, kamaki shell |
753 |
returns to its initial state, which involves the current directory, as shown in |
754 |
example 4.8.2 |
755 |
|
756 |
.. code-block:: console |
757 |
:emphasize-lines: 1 |
758 |
|
759 |
Example 4.8.2: Attempt (and fail) to change working directory |
760 |
|
761 |
|
762 |
[kamaki]: !pwd |
763 |
/home/username |
764 |
|
765 |
[kamaki]: !cd .. |
766 |
|
767 |
[kamaki]: shell pwd |
768 |
/home/username |