root / docs / usage.rst @ 82cc4b8f
History | View | Annotate | Download (26.2 kB)
1 | 8f489707 | Stavros Sachtouris | Usage |
---|---|---|---|
2 | 8f489707 | Stavros Sachtouris | ===== |
3 | 8f489707 | Stavros Sachtouris | |
4 | 904091dd | Stavros Sachtouris | Kamaki offers command line interfaces that implement specific command |
5 | 904091dd | Stavros Sachtouris | specifications. A detailed list of the command specifications can be found in |
6 | 904091dd | Stavros Sachtouris | `Commands <commands.html>`_ section. This guide covers the generic usage of |
7 | 904091dd | Stavros Sachtouris | both interfaces. |
8 | f23a5cdb | Stavros Sachtouris | |
9 | 904091dd | Stavros Sachtouris | What's more, kamaki offers a clients API that allows the development of |
10 | 904091dd | Stavros Sachtouris | external applications for synnefo. The clients API is listed in the |
11 | 904091dd | Stavros Sachtouris | `Clients lib <developers/code.html#the-clients-api>`_ section. |
12 | f23a5cdb | Stavros Sachtouris | |
13 | 961e6040 | Stavros Sachtouris | Quick Setup |
14 | 961e6040 | Stavros Sachtouris | ----------- |
15 | f23a5cdb | Stavros Sachtouris | |
16 | 904091dd | Stavros Sachtouris | Kamaki interfaces rely on a list of configuration options. A detailed guide for |
17 | 904091dd | Stavros Sachtouris | setting up kamaki can be found in the `Setup <setup.html>`_ section. |
18 | f23a5cdb | Stavros Sachtouris | |
19 | 904091dd | Stavros Sachtouris | As rule of the thump, it is enough to set the authentication URL and user token |
20 | 904091dd | Stavros Sachtouris | for the cloud kamaki should communicate with by default: |
21 | f23a5cdb | Stavros Sachtouris | |
22 | f23a5cdb | Stavros Sachtouris | .. code-block:: console |
23 | f3446cf0 | Stavros Sachtouris | :emphasize-lines: 1 |
24 | f23a5cdb | Stavros Sachtouris | |
25 | fa382f9e | Stavros Sachtouris | Example 1.1: Set authentication URL, user token and cloud alias "default" |
26 | f23a5cdb | Stavros Sachtouris | |
27 | fa382f9e | Stavros Sachtouris | $ kamaki config set cloud.default.url <authentication URL> |
28 | fa382f9e | Stavros Sachtouris | $ kamaki config set cloud.default.token myt0k3n== |
29 | fa382f9e | Stavros Sachtouris | |
30 | fa382f9e | Stavros Sachtouris | .. note:: The term *default* can be replaced by any arbitary term chosen by |
31 | fa382f9e | Stavros Sachtouris | the user. This term will serve as a cloud alias for kamaki users, and can |
32 | fa382f9e | Stavros Sachtouris | be easily modified. |
33 | f3446cf0 | Stavros Sachtouris | |
34 | a6370d73 | Stavros Sachtouris | Shell vs one-command |
35 | 7536c9bf | Stavros Sachtouris | -------------------- |
36 | 904091dd | Stavros Sachtouris | Kamaki users can access synnefo services through either the interactive shell |
37 | 904091dd | Stavros Sachtouris | or the one-command behaviors. In practice, both systems rely on the same |
38 | 904091dd | Stavros Sachtouris | command set implementations and API clients, with identical responses and error |
39 | 904091dd | Stavros Sachtouris | messages. Still, there are some differences. |
40 | 7536c9bf | Stavros Sachtouris | |
41 | a6370d73 | Stavros Sachtouris | In favor of interactive shell behavior: |
42 | a6370d73 | Stavros Sachtouris | |
43 | fa382f9e | Stavros Sachtouris | * tab completion for commands (if supported by host command line shell) |
44 | fa382f9e | Stavros Sachtouris | * session history with ↑ or ↓ keys (if supported by host command line shell) |
45 | 7536c9bf | Stavros Sachtouris | * shorter commands with command context switching |
46 | 79b4f177 | Stavros Sachtouris | * re-run old commands with /history |
47 | a6370d73 | Stavros Sachtouris | |
48 | a6370d73 | Stavros Sachtouris | In favor of one-command behavior: |
49 | a6370d73 | Stavros Sachtouris | |
50 | a6370d73 | Stavros Sachtouris | * can be used along with advanced shell features (pipelines, redirection, etc.) |
51 | a6370d73 | Stavros Sachtouris | * can be used in shell scripts |
52 | a6370d73 | Stavros Sachtouris | * prints debug and verbose messages if needed |
53 | a6370d73 | Stavros Sachtouris | |
54 | f23a5cdb | Stavros Sachtouris | Run as shell |
55 | 7536c9bf | Stavros Sachtouris | ^^^^^^^^^^^^ |
56 | a6370d73 | Stavros Sachtouris | To use kamaki as a shell, run: |
57 | f23a5cdb | Stavros Sachtouris | |
58 | f23a5cdb | Stavros Sachtouris | * without any parameters or arguments |
59 | f23a5cdb | Stavros Sachtouris | |
60 | f23a5cdb | Stavros Sachtouris | .. code-block:: console |
61 | f3446cf0 | Stavros Sachtouris | :emphasize-lines: 1 |
62 | f23a5cdb | Stavros Sachtouris | |
63 | f3446cf0 | Stavros Sachtouris | Example 2.2.1: Run kamaki shell |
64 | f23a5cdb | Stavros Sachtouris | |
65 | f3446cf0 | Stavros Sachtouris | $ kamaki |
66 | f23a5cdb | Stavros Sachtouris | |
67 | f23a5cdb | Stavros Sachtouris | * with any kind of '-' prefixed arguments, except '-h', '--help'. |
68 | f23a5cdb | Stavros Sachtouris | |
69 | f23a5cdb | Stavros Sachtouris | .. code-block:: console |
70 | f3446cf0 | Stavros Sachtouris | :emphasize-lines: 1 |
71 | f23a5cdb | Stavros Sachtouris | |
72 | f3446cf0 | Stavros Sachtouris | Example 2.2.2: Run kamaki shell with custom configuration file |
73 | f23a5cdb | Stavros Sachtouris | |
74 | fa382f9e | Stavros Sachtouris | $ kamaki -c myconfig.file |
75 | f23a5cdb | Stavros Sachtouris | |
76 | f23a5cdb | Stavros Sachtouris | |
77 | f23a5cdb | Stavros Sachtouris | Run as one-command |
78 | 7536c9bf | Stavros Sachtouris | ^^^^^^^^^^^^^^^^^^ |
79 | a6370d73 | Stavros Sachtouris | To use kamaki as an one-command tool, run: |
80 | f23a5cdb | Stavros Sachtouris | |
81 | f23a5cdb | Stavros Sachtouris | * with the '-h' or '--help' arguments (help for kamaki one-command) |
82 | f23a5cdb | Stavros Sachtouris | |
83 | f23a5cdb | Stavros Sachtouris | .. code-block:: console |
84 | f3446cf0 | Stavros Sachtouris | :emphasize-lines: 1 |
85 | f23a5cdb | Stavros Sachtouris | |
86 | a6370d73 | Stavros Sachtouris | Example 2.3.1: Kamaki help |
87 | f23a5cdb | Stavros Sachtouris | |
88 | f3446cf0 | Stavros Sachtouris | $kamaki -h |
89 | f3446cf0 | Stavros Sachtouris | |
90 | f23a5cdb | Stavros Sachtouris | * with one or more command parameters: |
91 | f23a5cdb | Stavros Sachtouris | |
92 | f23a5cdb | Stavros Sachtouris | .. code-block:: console |
93 | f3446cf0 | Stavros Sachtouris | :emphasize-lines: 1 |
94 | f23a5cdb | Stavros Sachtouris | |
95 | a6370d73 | Stavros Sachtouris | Example 2.3.2: List VMs managed by user |
96 | f23a5cdb | Stavros Sachtouris | |
97 | f3446cf0 | Stavros Sachtouris | $ kamaki server list |
98 | f3446cf0 | Stavros Sachtouris | |
99 | 457cb69b | Stavros Sachtouris | One-command interface |
100 | 7536c9bf | Stavros Sachtouris | --------------------- |
101 | a6370d73 | Stavros Sachtouris | |
102 | a6370d73 | Stavros Sachtouris | Using help |
103 | 7536c9bf | Stavros Sachtouris | ^^^^^^^^^^ |
104 | a6370d73 | Stavros Sachtouris | |
105 | 904091dd | Stavros Sachtouris | Kamaki help is used to list available commands with description, syntax and |
106 | 904091dd | Stavros Sachtouris | corresponding optional arguments. |
107 | a6370d73 | Stavros Sachtouris | |
108 | 904091dd | Stavros Sachtouris | To see the command groups, use -h or --help like in example 1.3.1. In the same |
109 | 904091dd | Stavros Sachtouris | way, help information for command groups and commands is printed. In the |
110 | 904091dd | Stavros Sachtouris | following examples, the help messages of kamaki, of a command group (server) |
111 | 904091dd | Stavros Sachtouris | and of a command in that group (list) are shown. |
112 | a6370d73 | Stavros Sachtouris | |
113 | a6370d73 | Stavros Sachtouris | .. code-block:: console |
114 | f3446cf0 | Stavros Sachtouris | :emphasize-lines: 1 |
115 | f3446cf0 | Stavros Sachtouris | |
116 | 2151584b | Stavros Sachtouris | Example 3.1.1: kamaki help shows available parameters and command groups |
117 | f3446cf0 | Stavros Sachtouris | |
118 | a6370d73 | Stavros Sachtouris | |
119 | a6370d73 | Stavros Sachtouris | $ kamaki -h |
120 | f3446cf0 | Stavros Sachtouris | usage: kamaki <cmd_group> [<cmd_subbroup> ...] <cmd> |
121 | 904091dd | Stavros Sachtouris | [-v] [-s] [-V] [-d] [-i] [-c CONFIG] [-o OPTIONS] [--cloud CLOUD] [-h] |
122 | a6370d73 | Stavros Sachtouris | |
123 | a6370d73 | Stavros Sachtouris | optional arguments: |
124 | a6370d73 | Stavros Sachtouris | -v, --verbose More info at response |
125 | a6370d73 | Stavros Sachtouris | -s, --silent Do not output anything |
126 | a6370d73 | Stavros Sachtouris | -V, --version Print current version |
127 | a6370d73 | Stavros Sachtouris | -d, --debug Include debug output |
128 | a6370d73 | Stavros Sachtouris | -i, --include Include protocol headers in the output |
129 | 904091dd | Stavros Sachtouris | -c CONFIG, --config CONFIG |
130 | 904091dd | Stavros Sachtouris | Path to configuration file |
131 | a6370d73 | Stavros Sachtouris | -o OPTIONS, --options OPTIONS |
132 | a6370d73 | Stavros Sachtouris | Override a config value |
133 | fa382f9e | Stavros Sachtouris | --cloud CLOUD Chose a cloud to connect to |
134 | a6370d73 | Stavros Sachtouris | -h, --help Show help message |
135 | a6370d73 | Stavros Sachtouris | |
136 | a6370d73 | Stavros Sachtouris | Options: |
137 | a6370d73 | Stavros Sachtouris | - - - - |
138 | fa382f9e | Stavros Sachtouris | config : Kamaki configurations |
139 | fa382f9e | Stavros Sachtouris | file : Pithos+/Storage API commands |
140 | fa382f9e | Stavros Sachtouris | flavor : Cyclades/Compute API flavor commands |
141 | fa382f9e | Stavros Sachtouris | history: Kamaki command history |
142 | fa382f9e | Stavros Sachtouris | image : Cyclades/Plankton API image commands |
143 | 904091dd | Stavros Sachtouris | image compute: Cyclades/Compute API image commands |
144 | fa382f9e | Stavros Sachtouris | network: Cyclades/Compute API network commands |
145 | fa382f9e | Stavros Sachtouris | server : Cyclades/Compute API server commands |
146 | fa382f9e | Stavros Sachtouris | user : Astakos API commands |
147 | a6370d73 | Stavros Sachtouris | |
148 | f3446cf0 | Stavros Sachtouris | .. code-block:: console |
149 | 904091dd | Stavros Sachtouris | :emphasize-lines: 1,2 |
150 | a6370d73 | Stavros Sachtouris | |
151 | 904091dd | Stavros Sachtouris | Example 3.1.2: Cyclades help contains all first-level commands of Cyclades |
152 | 904091dd | Stavros Sachtouris | command group |
153 | a6370d73 | Stavros Sachtouris | |
154 | e9e547ed | Stavros Sachtouris | $ kamaki server -h |
155 | 904091dd | Stavros Sachtouris | usage: kamaki server <...> [-v] [-s] [-V] [-d] [-i] [-c CONFIG] |
156 | 904091dd | Stavros Sachtouris | [-o OPTIONS] [--cloud CLOUD] [-h] |
157 | a6370d73 | Stavros Sachtouris | |
158 | a6370d73 | Stavros Sachtouris | optional arguments: |
159 | a6370d73 | Stavros Sachtouris | -v, --verbose More info at response |
160 | a6370d73 | Stavros Sachtouris | -s, --silent Do not output anything |
161 | a6370d73 | Stavros Sachtouris | -V, --version Print current version |
162 | a6370d73 | Stavros Sachtouris | -d, --debug Include debug output |
163 | a6370d73 | Stavros Sachtouris | -i, --include Include protocol headers in the output |
164 | 904091dd | Stavros Sachtouris | -c CONFIG, --config CONFIG |
165 | 904091dd | Stavros Sachtouris | Path to configuration file |
166 | a6370d73 | Stavros Sachtouris | -o OPTIONS, --options OPTIONS |
167 | a6370d73 | Stavros Sachtouris | Override a config value |
168 | fa382f9e | Stavros Sachtouris | --cloud CLOUD Chose a cloud to connect to |
169 | a6370d73 | Stavros Sachtouris | -h, --help Show help message |
170 | a6370d73 | Stavros Sachtouris | |
171 | a6370d73 | Stavros Sachtouris | Options: |
172 | a6370d73 | Stavros Sachtouris | - - - - |
173 | 904091dd | Stavros Sachtouris | addr : List the addresses of all network interfaces on a server (VM) |
174 | 904091dd | Stavros Sachtouris | console : Get a VNC console to access an existing server (VM) |
175 | 904091dd | Stavros Sachtouris | create : Create a server (aka Virtual Machine) |
176 | 904091dd | Stavros Sachtouris | delete : Delete a server (VM) |
177 | 904091dd | Stavros Sachtouris | firewall: Manage server (VM) firewall profiles for public networks |
178 | 8be50626 | Stavros Sachtouris | ip : Manage floating IPs for the servers |
179 | 904091dd | Stavros Sachtouris | info : Detailed information on a Virtual Machine |
180 | 904091dd | Stavros Sachtouris | list : List Virtual Machines accessible by user |
181 | 904091dd | Stavros Sachtouris | metadata: Manage Server metadata (key:value pairs of server attributes) |
182 | 904091dd | Stavros Sachtouris | reboot : Reboot a server (VM) |
183 | 904091dd | Stavros Sachtouris | rename : Set/update a server (VM) name |
184 | 904091dd | Stavros Sachtouris | shutdown: Shutdown an active server (VM) |
185 | 904091dd | Stavros Sachtouris | start : Start an existing server (VM) |
186 | 904091dd | Stavros Sachtouris | stats : Get server (VM) statistics |
187 | fc7c3c4c | Stavros Sachtouris | resize : Set a different flavor for an existing server |
188 | a6370d73 | Stavros Sachtouris | wait : Wait for server to finish [BUILD, STOPPED, REBOOT, ACTIVE] |
189 | a6370d73 | Stavros Sachtouris | |
190 | f3446cf0 | Stavros Sachtouris | .. code-block:: console |
191 | 904091dd | Stavros Sachtouris | :emphasize-lines: 1,2 |
192 | a6370d73 | Stavros Sachtouris | |
193 | 904091dd | Stavros Sachtouris | Example 3.1.3: Help for command "server list" with syntax, description and |
194 | 904091dd | Stavros Sachtouris | available user options |
195 | a6370d73 | Stavros Sachtouris | |
196 | a6370d73 | Stavros Sachtouris | $ kamaki server list -h |
197 | 904091dd | Stavros Sachtouris | usage: kamaki server list [-v] [-s] [-V] [-d] [-i] [-c CONFIG] [-o OPTIONS] |
198 | 904091dd | Stavros Sachtouris | [--cloud CLOUD] [-h] [--since SINCE] [--enumerate] |
199 | 904091dd | Stavros Sachtouris | [-l] [--more] [-n LIMIT] [-j] |
200 | a6370d73 | Stavros Sachtouris | |
201 | 904091dd | Stavros Sachtouris | List Virtual Machines accessible by user |
202 | 904091dd | Stavros Sachtouris | User Authentication: |
203 | 904091dd | Stavros Sachtouris | * to check authentication: /user authenticate |
204 | fa382f9e | Stavros Sachtouris | * to set authentication token: /config set cloud.default.token <token> |
205 | a6370d73 | Stavros Sachtouris | |
206 | a6370d73 | Stavros Sachtouris | optional arguments: |
207 | 904091dd | Stavros Sachtouris | -v, --verbose More info at response |
208 | 904091dd | Stavros Sachtouris | -s, --silent Do not output anything |
209 | 904091dd | Stavros Sachtouris | -V, --version Print current version |
210 | 904091dd | Stavros Sachtouris | -d, --debug Include debug output |
211 | 904091dd | Stavros Sachtouris | -i, --include Include raw connection data in the output |
212 | 904091dd | Stavros Sachtouris | -c CONFIG, --config CONFIG |
213 | 904091dd | Stavros Sachtouris | Path to configuration file |
214 | 904091dd | Stavros Sachtouris | -o OPTIONS, --options OPTIONS |
215 | 904091dd | Stavros Sachtouris | Override a config value |
216 | fa382f9e | Stavros Sachtouris | --cloud CLOUD Chose a cloud to connect to |
217 | 904091dd | Stavros Sachtouris | -h, --help Show help message |
218 | 904091dd | Stavros Sachtouris | --since SINCE show only items since date (' d/m/Y H:M:S ') |
219 | 904091dd | Stavros Sachtouris | --enumerate Enumerate results |
220 | 904091dd | Stavros Sachtouris | -l, --details show detailed output |
221 | 904091dd | Stavros Sachtouris | --more output results in pages (-n to set items per page, |
222 | 904091dd | Stavros Sachtouris | default 10) |
223 | 904091dd | Stavros Sachtouris | -n LIMIT, --number LIMIT |
224 | 904091dd | Stavros Sachtouris | limit number of listed VMs |
225 | 904091dd | Stavros Sachtouris | -j, --json show headers in json |
226 | a6370d73 | Stavros Sachtouris | |
227 | e5d1d5c2 | Stavros Sachtouris | .. _using-history-ref: |
228 | e5d1d5c2 | Stavros Sachtouris | |
229 | a6370d73 | Stavros Sachtouris | Using history |
230 | 7536c9bf | Stavros Sachtouris | ^^^^^^^^^^^^^ |
231 | a6370d73 | Stavros Sachtouris | |
232 | a6370d73 | Stavros Sachtouris | Kamaki command history is stored in a file at user home (".kamaki.history" by default). To set a custom history file path users must set the history.file config option (see `available config options <setup.html#editing-options>`_). |
233 | a6370d73 | Stavros Sachtouris | |
234 | a6370d73 | Stavros Sachtouris | Every syntactically correct command is appended at the end of that file. In order to see how to use history, use the kamaki help system: |
235 | a6370d73 | Stavros Sachtouris | |
236 | a6370d73 | Stavros Sachtouris | .. code-block:: console |
237 | f3446cf0 | Stavros Sachtouris | :emphasize-lines: 1 |
238 | f3446cf0 | Stavros Sachtouris | |
239 | 2151584b | Stavros Sachtouris | Example 3.2.1: Available history options |
240 | f3446cf0 | Stavros Sachtouris | |
241 | a6370d73 | Stavros Sachtouris | |
242 | a6370d73 | Stavros Sachtouris | $ kamaki history -h |
243 | 79b4f177 | Stavros Sachtouris | Options: |
244 | 79b4f177 | Stavros Sachtouris | - - - - |
245 | 79b4f177 | Stavros Sachtouris | clean: Clean up history (permanent) |
246 | 79b4f177 | Stavros Sachtouris | run : Run previously executed command(s) |
247 | 79b4f177 | Stavros Sachtouris | show : Show intersession command history |
248 | a6370d73 | Stavros Sachtouris | |
249 | a6370d73 | Stavros Sachtouris | The following example showcases how to use history in kamaki |
250 | a6370d73 | Stavros Sachtouris | |
251 | a6370d73 | Stavros Sachtouris | .. code-block:: console |
252 | f3446cf0 | Stavros Sachtouris | :emphasize-lines: 1 |
253 | f3446cf0 | Stavros Sachtouris | |
254 | 2151584b | Stavros Sachtouris | Example 3.2.2: Clean up everything, run a kamaki command, show full and filtered history |
255 | f3446cf0 | Stavros Sachtouris | |
256 | a6370d73 | Stavros Sachtouris | |
257 | e5d1d5c2 | Stavros Sachtouris | $ kamaki history clean |
258 | a6370d73 | Stavros Sachtouris | $ kamaki server list |
259 | a6370d73 | Stavros Sachtouris | ... |
260 | a6370d73 | Stavros Sachtouris | $ kamaki history show |
261 | a6370d73 | Stavros Sachtouris | 1. kamaki server list |
262 | a6370d73 | Stavros Sachtouris | 2. kamaki history show |
263 | a6370d73 | Stavros Sachtouris | $ kamaki history show --match server |
264 | a6370d73 | Stavros Sachtouris | 1. kamaki server list |
265 | a6370d73 | Stavros Sachtouris | 3. kamaki history show --match server |
266 | a6370d73 | Stavros Sachtouris | |
267 | 904091dd | Stavros Sachtouris | Debug and logging |
268 | 904091dd | Stavros Sachtouris | ^^^^^^^^^^^^^^^^^ |
269 | 904091dd | Stavros Sachtouris | |
270 | a6370d73 | Stavros Sachtouris | Debug |
271 | 904091dd | Stavros Sachtouris | """"" |
272 | 904091dd | Stavros Sachtouris | |
273 | 904091dd | Stavros Sachtouris | In case of errors, kamaki in debug mode shows useful debug information, like |
274 | 904091dd | Stavros Sachtouris | the stack trace. Kamaki in debug mode cancels suppression of warning messages. |
275 | 904091dd | Stavros Sachtouris | |
276 | 904091dd | Stavros Sachtouris | To run kamaki in debug mode use the -d or --debug option (can be combined with |
277 | 904091dd | Stavros Sachtouris | any other parameters or options) |
278 | 904091dd | Stavros Sachtouris | |
279 | 904091dd | Stavros Sachtouris | Logging |
280 | 904091dd | Stavros Sachtouris | """"""" |
281 | 904091dd | Stavros Sachtouris | |
282 | 904091dd | Stavros Sachtouris | Kamaki keeps its logs in a file specified as global.log_file and its value |
283 | 904091dd | Stavros Sachtouris | defaults to ${HOME}/.kamaki.log . This value may change with a config setting:: |
284 | 904091dd | Stavros Sachtouris | |
285 | 904091dd | Stavros Sachtouris | kamaki config set log_file /new/log/file/path |
286 | 904091dd | Stavros Sachtouris | |
287 | 904091dd | Stavros Sachtouris | Kamaki logs mostly the http connection requests and responses, including http |
288 | 904091dd | Stavros Sachtouris | methods, urls, parameters and headers. There is some special handling in two |
289 | 904091dd | Stavros Sachtouris | cases: |
290 | 904091dd | Stavros Sachtouris | |
291 | 904091dd | Stavros Sachtouris | * HTTP bodies are not logged by default |
292 | 904091dd | Stavros Sachtouris | to enable logging the full http bodies, set log_data to `on`:: |
293 | 904091dd | Stavros Sachtouris | |
294 | 904091dd | Stavros Sachtouris | kamaki config set log_data on |
295 | 904091dd | Stavros Sachtouris | |
296 | 904091dd | Stavros Sachtouris | to disable it, set it to `off`:: |
297 | 904091dd | Stavros Sachtouris | |
298 | 904091dd | Stavros Sachtouris | kamaki config set log_data off |
299 | 904091dd | Stavros Sachtouris | |
300 | 904091dd | Stavros Sachtouris | or delete it:: |
301 | 904091dd | Stavros Sachtouris | |
302 | 904091dd | Stavros Sachtouris | kamaki config delete log_data |
303 | 904091dd | Stavros Sachtouris | |
304 | 904091dd | Stavros Sachtouris | * X-Auth-Token header is not logged by default |
305 | 904091dd | Stavros Sachtouris | to enable logging the X-Auth-Token header, set log_token to `on`:: |
306 | 904091dd | Stavros Sachtouris | |
307 | 904091dd | Stavros Sachtouris | kamaki config set log_token on |
308 | 904091dd | Stavros Sachtouris | |
309 | 904091dd | Stavros Sachtouris | to disable it, set it to `off`:: |
310 | 904091dd | Stavros Sachtouris | |
311 | 904091dd | Stavros Sachtouris | kamaki config set log_token off |
312 | a6370d73 | Stavros Sachtouris | |
313 | 904091dd | Stavros Sachtouris | or delete it:: |
314 | a6370d73 | Stavros Sachtouris | |
315 | 904091dd | Stavros Sachtouris | kamaki config delete log_token |
316 | a6370d73 | Stavros Sachtouris | |
317 | 79b4f177 | Stavros Sachtouris | Verbose and Include |
318 | 79b4f177 | Stavros Sachtouris | """"""""""""""""""" |
319 | a6370d73 | Stavros Sachtouris | |
320 | 904091dd | Stavros Sachtouris | Most kamaki commands are translated into http requests. Kamaki clients API |
321 | 904091dd | Stavros Sachtouris | translated the semantics to REST and handles the response. Users who need to |
322 | 904091dd | Stavros Sachtouris | have access to these commands can use the verbose mode that presents the HTTP |
323 | 904091dd | Stavros Sachtouris | Request details as well as the full server response. |
324 | a6370d73 | Stavros Sachtouris | |
325 | a6370d73 | Stavros Sachtouris | To run kamaki in verbose mode use the -v or --verbose option |
326 | a6370d73 | Stavros Sachtouris | |
327 | 904091dd | Stavros Sachtouris | Be default, kamaki in verbose mode prints down only the headers and the address |
328 | 904091dd | Stavros Sachtouris | information, thus hiding the data body of the request or response. To see the |
329 | 904091dd | Stavros Sachtouris | data body, the -i option can be used. |
330 | 79b4f177 | Stavros Sachtouris | |
331 | f3446cf0 | Stavros Sachtouris | One-command features |
332 | 7536c9bf | Stavros Sachtouris | ^^^^^^^^^^^^^^^^^^^^ |
333 | a6370d73 | Stavros Sachtouris | |
334 | a6370d73 | Stavros Sachtouris | Kamaki commands can be used along with advanced shell features. |
335 | a6370d73 | Stavros Sachtouris | |
336 | a6370d73 | Stavros Sachtouris | .. code-block:: console |
337 | f3446cf0 | Stavros Sachtouris | :emphasize-lines: 1 |
338 | f3446cf0 | Stavros Sachtouris | |
339 | 904091dd | Stavros Sachtouris | Example 3.4.1: List the trash container contents, containing c1_ |
340 | f3446cf0 | Stavros Sachtouris | |
341 | a6370d73 | Stavros Sachtouris | |
342 | fa382f9e | Stavros Sachtouris | $ kamaki file list -o cloud.default.pithos_container=trash| grep c1_ |
343 | 904091dd | Stavros Sachtouris | c1_1370859409.0 20KB |
344 | 904091dd | Stavros Sachtouris | c1_1370859414.0 9MB |
345 | 904091dd | Stavros Sachtouris | c1_1370859409.1 110B |
346 | a6370d73 | Stavros Sachtouris | |
347 | 904091dd | Stavros Sachtouris | The -o argument can be used to temporarily override various (set or unset) |
348 | 904091dd | Stavros Sachtouris | options. In one command, all -o option sets are forgotten just after the |
349 | 904091dd | Stavros Sachtouris | command has been completed, and the previous settings are restored (the |
350 | 904091dd | Stavros Sachtouris | configuration file is not modified). |
351 | a6370d73 | Stavros Sachtouris | |
352 | 904091dd | Stavros Sachtouris | The file-list command in example 3.4.1 runs with an explicitly provided |
353 | 904091dd | Stavros Sachtouris | pithos_account, which temporarily overrides the one probably provided in the |
354 | 904091dd | Stavros Sachtouris | configuration file (it works even if the user has not set the optional |
355 | 904091dd | Stavros Sachtouris | pithos_account config option). |
356 | 457cb69b | Stavros Sachtouris | |
357 | 457cb69b | Stavros Sachtouris | Interactive shell |
358 | 7536c9bf | Stavros Sachtouris | ----------------- |
359 | f23a5cdb | Stavros Sachtouris | |
360 | f3446cf0 | Stavros Sachtouris | Command Contexts |
361 | 7536c9bf | Stavros Sachtouris | ^^^^^^^^^^^^^^^^ |
362 | f3446cf0 | Stavros Sachtouris | |
363 | 904091dd | Stavros Sachtouris | The kamaki interactive shell implements the notion of command contexts. Each |
364 | 904091dd | Stavros Sachtouris | command group is also a context where the users can **enter** by typing the |
365 | 904091dd | Stavros Sachtouris | group name. If the context switch is successful, the kamaki shell prompt |
366 | 904091dd | Stavros Sachtouris | changes to present the new context ("file" in example 4.1.1). |
367 | f3446cf0 | Stavros Sachtouris | |
368 | f3446cf0 | Stavros Sachtouris | .. code-block:: console |
369 | f3446cf0 | Stavros Sachtouris | :emphasize-lines: 1 |
370 | f3446cf0 | Stavros Sachtouris | |
371 | 0ea31480 | Stavros Sachtouris | Example 4.1.1: Enter file commands context / group |
372 | f3446cf0 | Stavros Sachtouris | |
373 | f3446cf0 | Stavros Sachtouris | |
374 | f3446cf0 | Stavros Sachtouris | $ kamaki |
375 | 0ea31480 | Stavros Sachtouris | [kamaki]: file |
376 | 0ea31480 | Stavros Sachtouris | [file]: |
377 | f3446cf0 | Stavros Sachtouris | |
378 | 904091dd | Stavros Sachtouris | Type **exit** (alternatively **ctrl-D** in (X)nix systems or **ctrl-Z** in |
379 | 904091dd | Stavros Sachtouris | Windows) to exit a context and return to the context of origin. If already at |
380 | 904091dd | Stavros Sachtouris | the top context (kamaki), an exit is equivalent to exiting the program. |
381 | f3446cf0 | Stavros Sachtouris | |
382 | f3446cf0 | Stavros Sachtouris | .. code-block:: console |
383 | f3446cf0 | Stavros Sachtouris | :emphasize-lines: 1 |
384 | f3446cf0 | Stavros Sachtouris | |
385 | 0ea31480 | Stavros Sachtouris | Example 4.1.2: Exit file context and then exit kamaki |
386 | f3446cf0 | Stavros Sachtouris | |
387 | 0ea31480 | Stavros Sachtouris | [file]: exit |
388 | f3446cf0 | Stavros Sachtouris | [kamaki]: exit |
389 | f3446cf0 | Stavros Sachtouris | $ |
390 | f3446cf0 | Stavros Sachtouris | |
391 | f3446cf0 | Stavros Sachtouris | A user might **browse** through different contexts during one session. |
392 | f3446cf0 | Stavros Sachtouris | |
393 | f3446cf0 | Stavros Sachtouris | .. code-block:: console |
394 | f3446cf0 | Stavros Sachtouris | :emphasize-lines: 1 |
395 | f3446cf0 | Stavros Sachtouris | |
396 | 2151584b | Stavros Sachtouris | Example 4.1.3: Execute list command in different contexts |
397 | f3446cf0 | Stavros Sachtouris | |
398 | f3446cf0 | Stavros Sachtouris | $ kamaki |
399 | 79b4f177 | Stavros Sachtouris | [kamaki]: config |
400 | 79b4f177 | Stavros Sachtouris | [config]: list |
401 | f3446cf0 | Stavros Sachtouris | ... (configuration options listing) ... |
402 | 79b4f177 | Stavros Sachtouris | [config]: exit |
403 | 0ea31480 | Stavros Sachtouris | [kamaki]: file |
404 | 0ea31480 | Stavros Sachtouris | [file]: list |
405 | f3446cf0 | Stavros Sachtouris | ... (storage containers listing) ... |
406 | 0ea31480 | Stavros Sachtouris | [file]: exit |
407 | 79b4f177 | Stavros Sachtouris | [kamaki]: server |
408 | 79b4f177 | Stavros Sachtouris | [server]: list |
409 | f3446cf0 | Stavros Sachtouris | ... (VMs listing) ... |
410 | f3446cf0 | Stavros Sachtouris | [server]: exit |
411 | f3446cf0 | Stavros Sachtouris | [kamaki]: |
412 | f3446cf0 | Stavros Sachtouris | |
413 | 904091dd | Stavros Sachtouris | Users have the option to avoid switching between contexts: all commands can run |
414 | 904091dd | Stavros Sachtouris | from the **top context**. As a result, examples 4.1.3 and 4.1.4 are equivalent. |
415 | f3446cf0 | Stavros Sachtouris | |
416 | f3446cf0 | Stavros Sachtouris | .. code-block:: console |
417 | f3446cf0 | Stavros Sachtouris | :emphasize-lines: 1 |
418 | f3446cf0 | Stavros Sachtouris | |
419 | 2151584b | Stavros Sachtouris | Example 4.1.4: Execute different "list" commands from top context |
420 | f3446cf0 | Stavros Sachtouris | |
421 | f3446cf0 | Stavros Sachtouris | |
422 | 79b4f177 | Stavros Sachtouris | [kamaki]: config list |
423 | f3446cf0 | Stavros Sachtouris | ... (configuration options listing) ... |
424 | 0ea31480 | Stavros Sachtouris | [kamaki]: file list |
425 | f3446cf0 | Stavros Sachtouris | ... (storage container listing) ... |
426 | 79b4f177 | Stavros Sachtouris | [kamaki]: server list |
427 | f3446cf0 | Stavros Sachtouris | ... (VMs listing) ... |
428 | f3446cf0 | Stavros Sachtouris | [kamaki]: |
429 | f3446cf0 | Stavros Sachtouris | |
430 | 7536c9bf | Stavros Sachtouris | Using Help |
431 | 7536c9bf | Stavros Sachtouris | ^^^^^^^^^^ |
432 | f3446cf0 | Stavros Sachtouris | |
433 | f3446cf0 | Stavros Sachtouris | There are two help mechanisms: a context-level and a command-level. |
434 | f3446cf0 | Stavros Sachtouris | |
435 | 904091dd | Stavros Sachtouris | **Context-level help** lists the available commands in a context and can also |
436 | 904091dd | Stavros Sachtouris | offer a short description for each command. |
437 | f3446cf0 | Stavros Sachtouris | |
438 | f3446cf0 | Stavros Sachtouris | Context-level help syntax:: |
439 | f3446cf0 | Stavros Sachtouris | |
440 | f3446cf0 | Stavros Sachtouris | * Show available commands in current context * |
441 | 79b4f177 | Stavros Sachtouris | [context]: help |
442 | 79b4f177 | Stavros Sachtouris | [context]: ? |
443 | f3446cf0 | Stavros Sachtouris | |
444 | f3446cf0 | Stavros Sachtouris | * Show help for command cmd * |
445 | 79b4f177 | Stavros Sachtouris | [context]: help cmd |
446 | 79b4f177 | Stavros Sachtouris | [context]: ?cmd |
447 | f3446cf0 | Stavros Sachtouris | |
448 | 904091dd | Stavros Sachtouris | The context-level help results may change from context to context |
449 | f3446cf0 | Stavros Sachtouris | |
450 | f3446cf0 | Stavros Sachtouris | .. code-block:: console |
451 | f3446cf0 | Stavros Sachtouris | :emphasize-lines: 1 |
452 | f3446cf0 | Stavros Sachtouris | |
453 | 904091dd | Stavros Sachtouris | Example 4.2.1: Get available commands and then get help in a context |
454 | f3446cf0 | Stavros Sachtouris | |
455 | f3446cf0 | Stavros Sachtouris | |
456 | 79b4f177 | Stavros Sachtouris | [kamaki]: help |
457 | f3446cf0 | Stavros Sachtouris | |
458 | f3446cf0 | Stavros Sachtouris | kamaki commands: |
459 | f3446cf0 | Stavros Sachtouris | ================ |
460 | 0ea31480 | Stavros Sachtouris | user config flavor history image network server file |
461 | f3446cf0 | Stavros Sachtouris | |
462 | f3446cf0 | Stavros Sachtouris | interactive shell commands: |
463 | f3446cf0 | Stavros Sachtouris | =========================== |
464 | f3446cf0 | Stavros Sachtouris | exit help shell |
465 | f3446cf0 | Stavros Sachtouris | |
466 | 79b4f177 | Stavros Sachtouris | [kamaki]: ?config |
467 | f3446cf0 | Stavros Sachtouris | Configuration commands (config -h for more options) |
468 | f3446cf0 | Stavros Sachtouris | |
469 | 79b4f177 | Stavros Sachtouris | [kamaki]: config |
470 | f3446cf0 | Stavros Sachtouris | |
471 | 79b4f177 | Stavros Sachtouris | [config]: ? |
472 | f3446cf0 | Stavros Sachtouris | |
473 | f3446cf0 | Stavros Sachtouris | config commands: |
474 | f3446cf0 | Stavros Sachtouris | ================ |
475 | f3446cf0 | Stavros Sachtouris | delete get list set |
476 | f3446cf0 | Stavros Sachtouris | |
477 | f3446cf0 | Stavros Sachtouris | interactive shell commands: |
478 | f3446cf0 | Stavros Sachtouris | =========================== |
479 | f3446cf0 | Stavros Sachtouris | exit help shell |
480 | f3446cf0 | Stavros Sachtouris | |
481 | 79b4f177 | Stavros Sachtouris | [config]: help set |
482 | f3446cf0 | Stavros Sachtouris | Set a configuration option (set -h for more options) |
483 | f3446cf0 | Stavros Sachtouris | |
484 | 904091dd | Stavros Sachtouris | In context-level, there is a distinction between kamaki-commands and |
485 | 904091dd | Stavros Sachtouris | interactive shell commands. The former are available in one-command mode and |
486 | 904091dd | Stavros Sachtouris | are related to the cloud client setup and use, while the later are |
487 | 904091dd | Stavros Sachtouris | context-shell functions. |
488 | f3446cf0 | Stavros Sachtouris | |
489 | 904091dd | Stavros Sachtouris | **Command-level help** prints the syntax, arguments and description of a |
490 | 904091dd | Stavros Sachtouris | specific (terminal) command |
491 | f3446cf0 | Stavros Sachtouris | |
492 | f3446cf0 | Stavros Sachtouris | Command-level help syntax:: |
493 | f3446cf0 | Stavros Sachtouris | |
494 | f3446cf0 | Stavros Sachtouris | * Get help for command cmd1 cmd2 ... cmdN * |
495 | 79b4f177 | Stavros Sachtouris | [context]: cmd1 cmd2 ... cmdN -h |
496 | f3446cf0 | Stavros Sachtouris | <syntax> |
497 | f3446cf0 | Stavros Sachtouris | |
498 | f3446cf0 | Stavros Sachtouris | <description> |
499 | f3446cf0 | Stavros Sachtouris | |
500 | 7536c9bf | Stavros Sachtouris | <arguments and possible extensions> |
501 | f3446cf0 | Stavros Sachtouris | |
502 | 904091dd | Stavros Sachtouris | Command-level help mechanism is exactly the same as the one used in |
503 | 904091dd | Stavros Sachtouris | one-command mode. For example, it is invoked by using the -h or --help |
504 | 904091dd | Stavros Sachtouris | parameter at any point. |
505 | f3446cf0 | Stavros Sachtouris | |
506 | f3446cf0 | Stavros Sachtouris | .. code-block:: console |
507 | f3446cf0 | Stavros Sachtouris | :emphasize-lines: 1 |
508 | f3446cf0 | Stavros Sachtouris | |
509 | 2151584b | Stavros Sachtouris | Example 4.2.2: Get command-level help for config and config-set |
510 | f3446cf0 | Stavros Sachtouris | |
511 | f3446cf0 | Stavros Sachtouris | |
512 | 79b4f177 | Stavros Sachtouris | [kamaki]: config --help |
513 | f3446cf0 | Stavros Sachtouris | config: Configuration commands |
514 | f3446cf0 | Stavros Sachtouris | delete: Delete a configuration option (and use the default value) |
515 | f3446cf0 | Stavros Sachtouris | get : Show a configuration option |
516 | f3446cf0 | Stavros Sachtouris | list : List configuration options |
517 | f3446cf0 | Stavros Sachtouris | set : Set a configuration option |
518 | f3446cf0 | Stavros Sachtouris | |
519 | 79b4f177 | Stavros Sachtouris | [kamaki]: config |
520 | f3446cf0 | Stavros Sachtouris | |
521 | 79b4f177 | Stavros Sachtouris | [config]: set -h |
522 | f3446cf0 | Stavros Sachtouris | usage: set <option> <value> [-v] [-d] [-h] [-i] [--config CONFIG] [-s] |
523 | f3446cf0 | Stavros Sachtouris | |
524 | f3446cf0 | Stavros Sachtouris | Set a configuration option |
525 | f3446cf0 | Stavros Sachtouris | |
526 | f3446cf0 | Stavros Sachtouris | optional arguments: |
527 | f3446cf0 | Stavros Sachtouris | -v, --verbose More info at response |
528 | f3446cf0 | Stavros Sachtouris | -d, --debug Include debug output |
529 | f3446cf0 | Stavros Sachtouris | -h, --help Show help message |
530 | f3446cf0 | Stavros Sachtouris | -i, --include Include protocol headers in the output |
531 | f3446cf0 | Stavros Sachtouris | --config CONFIG Path to configuration file |
532 | f3446cf0 | Stavros Sachtouris | -s, --silent Do not output anything |
533 | f3446cf0 | Stavros Sachtouris | |
534 | 2151584b | Stavros Sachtouris | There are many ways of producing a help message, as shown in example 4.2.3 |
535 | f3446cf0 | Stavros Sachtouris | |
536 | f3446cf0 | Stavros Sachtouris | .. code-block:: console |
537 | f3446cf0 | Stavros Sachtouris | :emphasize-lines: 1 |
538 | f3446cf0 | Stavros Sachtouris | |
539 | 2151584b | Stavros Sachtouris | Example 4.2.3: Equivalent calls of command-level help for config-set |
540 | f3446cf0 | Stavros Sachtouris | |
541 | f3446cf0 | Stavros Sachtouris | |
542 | 79b4f177 | Stavros Sachtouris | [config]: set -h |
543 | 79b4f177 | Stavros Sachtouris | [config]: set --help |
544 | 79b4f177 | Stavros Sachtouris | [kamaki]: config set -h |
545 | 79b4f177 | Stavros Sachtouris | [kamaki]: config set --help |
546 | 0ea31480 | Stavros Sachtouris | [file]: /config set -h |
547 | 79b4f177 | Stavros Sachtouris | [server]: /config set --help |
548 | f3446cf0 | Stavros Sachtouris | |
549 | e5d1d5c2 | Stavros Sachtouris | .. _accessing-top-level-commands-ref: |
550 | e5d1d5c2 | Stavros Sachtouris | |
551 | f3446cf0 | Stavros Sachtouris | Accessing top-level commands |
552 | 7536c9bf | Stavros Sachtouris | ^^^^^^^^^^^^^^^^^^^^^^^^^^^^ |
553 | f3446cf0 | Stavros Sachtouris | |
554 | 904091dd | Stavros Sachtouris | When working in a context, it is often useful to access other contexts or |
555 | 904091dd | Stavros Sachtouris | top-level commands. Kamaki offers access to top-level commands by using the |
556 | 904091dd | Stavros Sachtouris | `/` prefix, as shown bellow:: |
557 | f3446cf0 | Stavros Sachtouris | |
558 | f3446cf0 | Stavros Sachtouris | * access a command "anothercontext cmd1 cmd2 ... cmdN" |
559 | 79b4f177 | Stavros Sachtouris | [context]: /anothercontext cmd1 cmd2 ... cmdN |
560 | f3446cf0 | Stavros Sachtouris | |
561 | 904091dd | Stavros Sachtouris | An example (4.3.1) that showcases how top-level access improves user experience |
562 | 904091dd | Stavros Sachtouris | is the creation of a VM. A VM is created with the command server-create. This |
563 | 904091dd | Stavros Sachtouris | command is called with three parameters: |
564 | f3446cf0 | Stavros Sachtouris | |
565 | f3446cf0 | Stavros Sachtouris | * the name of the new VM |
566 | f3446cf0 | Stavros Sachtouris | * the flavor id |
567 | f3446cf0 | Stavros Sachtouris | * the image id |
568 | f3446cf0 | Stavros Sachtouris | |
569 | 904091dd | Stavros Sachtouris | It is often the case that a user who works in the context command, needs to |
570 | 904091dd | Stavros Sachtouris | create a new VM, but hasn't selected a flavor or an image id, or cannot recall |
571 | 904091dd | Stavros Sachtouris | the id of that flavor or image. Therefore, it is necessary to list all |
572 | 904091dd | Stavros Sachtouris | available flavors (flavor-list) or images (image-compute-list). Both commands |
573 | 904091dd | Stavros Sachtouris | belong to different contexts. |
574 | f3446cf0 | Stavros Sachtouris | |
575 | f3446cf0 | Stavros Sachtouris | .. code-block:: console |
576 | f3446cf0 | Stavros Sachtouris | :emphasize-lines: 1 |
577 | f3446cf0 | Stavros Sachtouris | |
578 | 2151584b | Stavros Sachtouris | Example 4.3.1: Create a VM from server context |
579 | f3446cf0 | Stavros Sachtouris | |
580 | 79b4f177 | Stavros Sachtouris | [server]: create -h |
581 | f3446cf0 | Stavros Sachtouris | create <name> <flavor id> <image id> ... |
582 | f3446cf0 | Stavros Sachtouris | ... |
583 | f3446cf0 | Stavros Sachtouris | |
584 | 79b4f177 | Stavros Sachtouris | [server]: /flavor list |
585 | f3446cf0 | Stavros Sachtouris | ... |
586 | e3a1d743 | Stavros Sachtouris | 43 AFLAVOR |
587 | f3446cf0 | Stavros Sachtouris | SNF:disk_template: drbd |
588 | f3446cf0 | Stavros Sachtouris | cpu : 4 |
589 | f3446cf0 | Stavros Sachtouris | disk : 10 |
590 | f3446cf0 | Stavros Sachtouris | ram : 2048 |
591 | f3446cf0 | Stavros Sachtouris | |
592 | 573be34f | Stavros Sachtouris | [server]: /image compute list |
593 | f3446cf0 | Stavros Sachtouris | 1580deb4-edb3-7a246c4c0528 (Ubuntu Desktop) |
594 | f3446cf0 | Stavros Sachtouris | 18a82962-43eb-8f8880af89d7 (Windows 7) |
595 | f3446cf0 | Stavros Sachtouris | 531aa018-9a40-a4bfe6a0caff (Windows XP) |
596 | f3446cf0 | Stavros Sachtouris | 6aa6eafd-dccb-67fe2bdde87e (Debian Desktop) |
597 | f3446cf0 | Stavros Sachtouris | |
598 | 79b4f177 | Stavros Sachtouris | [server]: create 'my debian' 43 6aa6eafd-dccb-67fe2bdde87e |
599 | f3446cf0 | Stavros Sachtouris | ... |
600 | f3446cf0 | Stavros Sachtouris | |
601 | 904091dd | Stavros Sachtouris | An other example (4.3.2) showcases how to acquire and modify configuration |
602 | 904091dd | Stavros Sachtouris | settings from a different context. In this scenario, the user token expires at |
603 | 904091dd | Stavros Sachtouris | server side while the user is working. When that happens, the system responds |
604 | 904091dd | Stavros Sachtouris | with an *(401) UNAUTHORIZED* message. The user can acquire a new token (valid |
605 | 904091dd | Stavros Sachtouris | for the Astakos identity manager of preference) which has to be set to kamaki. |
606 | f3446cf0 | Stavros Sachtouris | |
607 | f3446cf0 | Stavros Sachtouris | .. code-block:: console |
608 | f3446cf0 | Stavros Sachtouris | :emphasize-lines: 1 |
609 | f3446cf0 | Stavros Sachtouris | |
610 | 0ea31480 | Stavros Sachtouris | Example 4.3.2: Set a new token from file context |
611 | f3446cf0 | Stavros Sachtouris | |
612 | f3446cf0 | Stavros Sachtouris | |
613 | 0ea31480 | Stavros Sachtouris | [file]: list |
614 | f3446cf0 | Stavros Sachtouris | (401) UNAUTHORIZED Access denied |
615 | f3446cf0 | Stavros Sachtouris | |
616 | 0ea31480 | Stavros Sachtouris | [file]: /user authenticate |
617 | f3446cf0 | Stavros Sachtouris | (401) UNAUTHORIZED Invalid X-Auth-Token |
618 | f3446cf0 | Stavros Sachtouris | |
619 | fa382f9e | Stavros Sachtouris | [file]: /config get cloud.default.token |
620 | f3446cf0 | Stavros Sachtouris | my3xp1r3dt0k3n== |
621 | f3446cf0 | Stavros Sachtouris | |
622 | fa382f9e | Stavros Sachtouris | [file]: /config set cloud.default.token myfr35ht0k3n== |
623 | f3446cf0 | Stavros Sachtouris | |
624 | fa382f9e | Stavros Sachtouris | [file]: /config get cloud.default |
625 | fa382f9e | Stavros Sachtouris | cloud.default.url = https://astakos.example.com/astakos/identity/2.0/ |
626 | fa382f9e | Stavros Sachtouris | cloud.default.token = myfr35ht0k3n== |
627 | f3446cf0 | Stavros Sachtouris | |
628 | 0ea31480 | Stavros Sachtouris | [file]: list |
629 | f3446cf0 | Stavros Sachtouris | 1. pithos (10MB, 2 objects) |
630 | f3446cf0 | Stavros Sachtouris | 2. trash (0B, 0 objects) |
631 | f3446cf0 | Stavros Sachtouris | |
632 | 904091dd | Stavros Sachtouris | .. note:: The error messages on this example where shortened for clarity. |
633 | fa382f9e | Stavros Sachtouris | Actual kamaki error messages are more helpful and descriptive. |
634 | e3a1d743 | Stavros Sachtouris | |
635 | 904091dd | Stavros Sachtouris | The following example compares some equivalent calls that run |
636 | 904091dd | Stavros Sachtouris | *user-authenticate* after a *file-list* 401 failure. |
637 | f3446cf0 | Stavros Sachtouris | |
638 | f3446cf0 | Stavros Sachtouris | .. code-block:: console |
639 | e5d1d5c2 | Stavros Sachtouris | :emphasize-lines: 1,3,10,17,26 |
640 | f3446cf0 | Stavros Sachtouris | |
641 | 904091dd | Stavros Sachtouris | Example 4.3.3: Equivalent user-authenticate calls after a file-list 401 |
642 | f3446cf0 | Stavros Sachtouris | |
643 | 7de017e5 | Stavros Sachtouris | * without kamaki interactive shell * |
644 | 0ea31480 | Stavros Sachtouris | $ kamaki file list |
645 | f3446cf0 | Stavros Sachtouris | (401) UNAUTHORIZED Access denied |
646 | 0ea31480 | Stavros Sachtouris | $ kamaki user authenticate |
647 | f3446cf0 | Stavros Sachtouris | ... |
648 | f3446cf0 | Stavros Sachtouris | $ |
649 | f3446cf0 | Stavros Sachtouris | |
650 | f3446cf0 | Stavros Sachtouris | * from top-level context * |
651 | 0ea31480 | Stavros Sachtouris | [kamaki]: file list |
652 | f3446cf0 | Stavros Sachtouris | (401) UNAUTHORIZED Access denied |
653 | 0ea31480 | Stavros Sachtouris | [kamaki]: user authenticate |
654 | f3446cf0 | Stavros Sachtouris | ... |
655 | f3446cf0 | Stavros Sachtouris | [kamaki] |
656 | f3446cf0 | Stavros Sachtouris | |
657 | f3446cf0 | Stavros Sachtouris | * maximum typing * |
658 | 0ea31480 | Stavros Sachtouris | [file]: list |
659 | f3446cf0 | Stavros Sachtouris | (401) UNAUTHORIZED Access denied |
660 | 0ea31480 | Stavros Sachtouris | [file]: exit |
661 | 0ea31480 | Stavros Sachtouris | [kamaki]: user |
662 | 0ea31480 | Stavros Sachtouris | [user]: authenticate |
663 | f3446cf0 | Stavros Sachtouris | ... |
664 | 0ea31480 | Stavros Sachtouris | [user]: |
665 | f3446cf0 | Stavros Sachtouris | |
666 | f3446cf0 | Stavros Sachtouris | * minimum typing * |
667 | 0ea31480 | Stavros Sachtouris | [file]: list |
668 | f3446cf0 | Stavros Sachtouris | (401) UNAUTHORIZED Access denied |
669 | 0ea31480 | Stavros Sachtouris | [file]: /user authenticate |
670 | f3446cf0 | Stavros Sachtouris | ... |
671 | 0ea31480 | Stavros Sachtouris | [file]: |
672 | f3446cf0 | Stavros Sachtouris | |
673 | e5d1d5c2 | Stavros Sachtouris | .. hint:: To exit kamaki shell while in a context, try */exit* |
674 | e5d1d5c2 | Stavros Sachtouris | |
675 | 7536c9bf | Stavros Sachtouris | Using config |
676 | 7536c9bf | Stavros Sachtouris | ^^^^^^^^^^^^ |
677 | f3446cf0 | Stavros Sachtouris | |
678 | fa382f9e | Stavros Sachtouris | The configuration mechanism of kamaki is detailed in the |
679 | 904091dd | Stavros Sachtouris | `setup section <setup.html>`_ and it is common for both interaction modes. In |
680 | 904091dd | Stavros Sachtouris | specific, the configuration mechanism is implemented as a command group, namely |
681 | 904091dd | Stavros Sachtouris | `config`. Using the config commands is as straightforward as any other kamaki |
682 | 904091dd | Stavros Sachtouris | commands. |
683 | e5d1d5c2 | Stavros Sachtouris | |
684 | 904091dd | Stavros Sachtouris | It is often useful to set, delete or update a value. This can be managed either |
685 | 904091dd | Stavros Sachtouris | inside the config context or from any command context by using the / prefix. |
686 | 79b4f177 | Stavros Sachtouris | |
687 | 904091dd | Stavros Sachtouris | .. Note:: config updates in kamaki shell persist even after the session is over |
688 | e5d1d5c2 | Stavros Sachtouris | |
689 | 904091dd | Stavros Sachtouris | All setting changes affect the physical kamaki config file. The config file is |
690 | 904091dd | Stavros Sachtouris | created automatically at callers' home firectory the first time a config option |
691 | 904091dd | Stavros Sachtouris | is set, and lives there as *.kamakirc* . It can be edited with any text editor |
692 | 904091dd | Stavros Sachtouris | or managed with kamaki config commands. |
693 | e5d1d5c2 | Stavros Sachtouris | |
694 | 904091dd | Stavros Sachtouris | In example 4.4.1 the user is going to work with only one storage container. The |
695 | 904091dd | Stavros Sachtouris | file commands use the container:path syntax, but if the user sets a container |
696 | 904091dd | Stavros Sachtouris | name as default, the container name can be omitted. This is possible by setting |
697 | 904091dd | Stavros Sachtouris | a *file.container* setting. |
698 | e5d1d5c2 | Stavros Sachtouris | |
699 | e5d1d5c2 | Stavros Sachtouris | .. code-block:: console |
700 | e5d1d5c2 | Stavros Sachtouris | :emphasize-lines: 1 |
701 | e5d1d5c2 | Stavros Sachtouris | |
702 | fa382f9e | Stavros Sachtouris | Example 4.4.1: Set default storage container (cloud: default) |
703 | e5d1d5c2 | Stavros Sachtouris | |
704 | e5d1d5c2 | Stavros Sachtouris | |
705 | 0ea31480 | Stavros Sachtouris | [file]: list |
706 | e5d1d5c2 | Stavros Sachtouris | 1. mycontainer (32MB, 2 objects) |
707 | e5d1d5c2 | Stavros Sachtouris | 2. pithos (0B, 0 objects) |
708 | e5d1d5c2 | Stavros Sachtouris | 3. trash (2MB, 1 objects) |
709 | e5d1d5c2 | Stavros Sachtouris | |
710 | 0ea31480 | Stavros Sachtouris | [file]: list mycontainer |
711 | e5d1d5c2 | Stavros Sachtouris | 1. D mydir/ |
712 | e5d1d5c2 | Stavros Sachtouris | 2. 20M mydir/rndm_local.file |
713 | e5d1d5c2 | Stavros Sachtouris | |
714 | fa382f9e | Stavros Sachtouris | [file]: /config set cloud.default.pithos_container mycontainer |
715 | e5d1d5c2 | Stavros Sachtouris | |
716 | 0ea31480 | Stavros Sachtouris | [file]: list |
717 | e5d1d5c2 | Stavros Sachtouris | 1. D mydir/ |
718 | e5d1d5c2 | Stavros Sachtouris | 2. 20M mydir/rndm_local.file |
719 | e5d1d5c2 | Stavros Sachtouris | |
720 | 904091dd | Stavros Sachtouris | After a while, the user needs to work with multiple containers, therefore a |
721 | 904091dd | Stavros Sachtouris | default container is no longer needed. The *pithos_container* setting can be |
722 | 904091dd | Stavros Sachtouris | deleted, as shown in example 4.4.2 |
723 | e5d1d5c2 | Stavros Sachtouris | |
724 | e5d1d5c2 | Stavros Sachtouris | .. code-block:: console |
725 | e5d1d5c2 | Stavros Sachtouris | :emphasize-lines: 1 |
726 | e5d1d5c2 | Stavros Sachtouris | |
727 | fa382f9e | Stavros Sachtouris | Example 4.4.2: Delete a setting option (cloud: default) |
728 | e5d1d5c2 | Stavros Sachtouris | |
729 | e5d1d5c2 | Stavros Sachtouris | |
730 | fa382f9e | Stavros Sachtouris | [file]: /config delete cloud.default.pithos_container |
731 | e5d1d5c2 | Stavros Sachtouris | |
732 | 0ea31480 | Stavros Sachtouris | [file]: list |
733 | e5d1d5c2 | Stavros Sachtouris | 1. mycontainer (32MB, 2 objects) |
734 | e5d1d5c2 | Stavros Sachtouris | 2. pithos (0B, 0 objects) |
735 | e5d1d5c2 | Stavros Sachtouris | 3. trash (2MB, 1 objects) |
736 | e5d1d5c2 | Stavros Sachtouris | |
737 | 7536c9bf | Stavros Sachtouris | Using history |
738 | 7536c9bf | Stavros Sachtouris | ^^^^^^^^^^^^^ |
739 | f3446cf0 | Stavros Sachtouris | |
740 | 904091dd | Stavros Sachtouris | There are two history modes: session and permanent. Session history keeps |
741 | 904091dd | Stavros Sachtouris | record of all actions in a kamaki shell session, while permanent history |
742 | 904091dd | Stavros Sachtouris | appends all commands to an accessible history file. |
743 | e5d1d5c2 | Stavros Sachtouris | |
744 | 904091dd | Stavros Sachtouris | Session history is only available in interactive shell mode. Users can iterate |
745 | 904091dd | Stavros Sachtouris | through past commands in the same session with the ↑ and ↓ keys. Session |
746 | 904091dd | Stavros Sachtouris | history is not stored, although syntactically correct commands are recorded |
747 | 904091dd | Stavros Sachtouris | through the permanent history mechanism. |
748 | e5d1d5c2 | Stavros Sachtouris | |
749 | 904091dd | Stavros Sachtouris | Permanent history is implemented as a command group and is common to both the |
750 | 904091dd | Stavros Sachtouris | one-command and shell interfaces. In specific, every syntactically correct |
751 | 904091dd | Stavros Sachtouris | command is appended in a history file (configured as `history_file` in |
752 | 904091dd | Stavros Sachtouris | settings, see `setup section <setup.html>`_ for details). Commands executed in |
753 | 904091dd | Stavros Sachtouris | one-command mode are mixed with the ones run in kamaki shell (also |
754 | 904091dd | Stavros Sachtouris | see :ref:`using-history-ref` section on this guide). |
755 | e5d1d5c2 | Stavros Sachtouris | |
756 | ee9f8245 | Stavros Sachtouris | Scripting |
757 | ee9f8245 | Stavros Sachtouris | ^^^^^^^^^ |
758 | ee9f8245 | Stavros Sachtouris | |
759 | 904091dd | Stavros Sachtouris | The history-run feature allows the sequential run of previous command |
760 | 904091dd | Stavros Sachtouris | executions in kamaki shell. |
761 | ee9f8245 | Stavros Sachtouris | |
762 | 904091dd | Stavros Sachtouris | The following sequence copies and downloads a file from *mycontainer1* , |
763 | 904091dd | Stavros Sachtouris | uploads it to *mycontainer2* , then undo the proccess and repeats it with |
764 | 904091dd | Stavros Sachtouris | history-run |
765 | ee9f8245 | Stavros Sachtouris | |
766 | ee9f8245 | Stavros Sachtouris | .. code-block:: console |
767 | ee9f8245 | Stavros Sachtouris | :emphasize-lines: 1,12,19,32 |
768 | ee9f8245 | Stavros Sachtouris | |
769 | ee9f8245 | Stavros Sachtouris | * Download mycontainer1:myfile and upload it to mycontainer2:myfile |
770 | 0ea31480 | Stavros Sachtouris | [kamaki]: file |
771 | 0ea31480 | Stavros Sachtouris | [file]: copy mycontainer1:somefile mycontainer1:myfile |
772 | 0ea31480 | Stavros Sachtouris | [file]: download mycontainer1:myfile mylocalfile |
773 | ee9f8245 | Stavros Sachtouris | Download completed |
774 | 0ea31480 | Stavros Sachtouris | [file]: upload mylocalfile mycontainer2:myfile |
775 | ee9f8245 | Stavros Sachtouris | Upload completed |
776 | ee9f8245 | Stavros Sachtouris | |
777 | ee9f8245 | Stavros Sachtouris | * undo the process * |
778 | 0ea31480 | Stavros Sachtouris | [file]: !rm mylocalfile |
779 | 0ea31480 | Stavros Sachtouris | [file]: delete mycontainer1:myfile |
780 | 0ea31480 | Stavros Sachtouris | [file]: delete mycontainer2:myfile |
781 | ee9f8245 | Stavros Sachtouris | |
782 | ee9f8245 | Stavros Sachtouris | * check history entries * |
783 | 0ea31480 | Stavros Sachtouris | [file]: exit |
784 | ee9f8245 | Stavros Sachtouris | [kamaki]: history |
785 | ee9f8245 | Stavros Sachtouris | [history]: show |
786 | 0ea31480 | Stavros Sachtouris | 1. file |
787 | 0ea31480 | Stavros Sachtouris | 2. file copy mycontainer1:somefile mycontainer1:myfile |
788 | 0ea31480 | Stavros Sachtouris | 3. file download mycontainer1:myfile mylocalfile |
789 | 0ea31480 | Stavros Sachtouris | 4. file upload mylocalfile mycontainer2:myfile |
790 | 0ea31480 | Stavros Sachtouris | 5. file delete mycontainer1:myfile |
791 | 0ea31480 | Stavros Sachtouris | 6. file delete mycontainer2:myfile |
792 | 79b4f177 | Stavros Sachtouris | 7. history |
793 | 79b4f177 | Stavros Sachtouris | 8. history show |
794 | ee9f8245 | Stavros Sachtouris | |
795 | ee9f8245 | Stavros Sachtouris | *repeat the process * |
796 | 68ab0942 | Stavros Sachtouris | [history]: run 2-4 |
797 | 0ea31480 | Stavros Sachtouris | <file copy mycontainer1:somefile mycontainer1:myfile> |
798 | 0ea31480 | Stavros Sachtouris | <file download mycontainer1:myfile mylocalfile> |
799 | ee9f8245 | Stavros Sachtouris | Download completed |
800 | 0ea31480 | Stavros Sachtouris | <file upload mylocalfile mycontainer2:myfile> |
801 | ee9f8245 | Stavros Sachtouris | Upload completed |
802 | ee9f8245 | Stavros Sachtouris | |
803 | 904091dd | Stavros Sachtouris | For powerfull scripting, users are advised to take advantage of their os shell |
804 | 904091dd | Stavros Sachtouris | scripting capabilities and combine them with kamaki one-command. Still, the |
805 | 904091dd | Stavros Sachtouris | history-run functionality might prove handy in many occasions. |
806 | ee9f8245 | Stavros Sachtouris | |
807 | f3446cf0 | Stavros Sachtouris | Tab completion |
808 | 7536c9bf | Stavros Sachtouris | ^^^^^^^^^^^^^^ |
809 | b8e90894 | Stavros Sachtouris | |
810 | 904091dd | Stavros Sachtouris | Kamaki shell features tab completion for the first level of command terms of |
811 | 904091dd | Stavros Sachtouris | the current context. Tab completion pool changes dynamically when the context |
812 | 904091dd | Stavros Sachtouris | is switched. Currently, tab completion is not supported when / is used |
813 | 904091dd | Stavros Sachtouris | (see :ref:`accessing-top-level-commands-ref` ). |
814 | e5d1d5c2 | Stavros Sachtouris | |
815 | f3446cf0 | Stavros Sachtouris | OS Shell integration |
816 | 7536c9bf | Stavros Sachtouris | ^^^^^^^^^^^^^^^^^^^^ |
817 | b8e90894 | Stavros Sachtouris | |
818 | 904091dd | Stavros Sachtouris | Kamaki shell features the ability to execute OS-shell commands from any |
819 | 904091dd | Stavros Sachtouris | context. This can be achieved by typing *!* or *shell*:: |
820 | e5d1d5c2 | Stavros Sachtouris | |
821 | 79b4f177 | Stavros Sachtouris | [kamaki_context]: !<OS shell command> |
822 | e5d1d5c2 | Stavros Sachtouris | ... OS shell command output ... |
823 | e5d1d5c2 | Stavros Sachtouris | |
824 | 79b4f177 | Stavros Sachtouris | [kamaki_context]: shell <OS shell command> |
825 | e5d1d5c2 | Stavros Sachtouris | ... OS shell command output ... |
826 | e5d1d5c2 | Stavros Sachtouris | |
827 | e5d1d5c2 | Stavros Sachtouris | .. code-block:: console |
828 | e5d1d5c2 | Stavros Sachtouris | :emphasize-lines: 1 |
829 | e5d1d5c2 | Stavros Sachtouris | |
830 | 2151584b | Stavros Sachtouris | Example 4.7.1: Run unix-style shell commands from kamaki shell |
831 | e5d1d5c2 | Stavros Sachtouris | |
832 | e5d1d5c2 | Stavros Sachtouris | |
833 | 79b4f177 | Stavros Sachtouris | [kamaki]: !ls -al |
834 | e5d1d5c2 | Stavros Sachtouris | total 16 |
835 | 59cadffb | Stavros Sachtouris | drwxrwxr-x 2 username username 4096 Nov 27 16:47 . |
836 | 59cadffb | Stavros Sachtouris | drwxrwxr-x 7 username username 4096 Nov 27 16:47 .. |
837 | 59cadffb | Stavros Sachtouris | -rw-rw-r-- 1 username username 8063 Jun 28 14:48 kamaki-logo.png |
838 | e5d1d5c2 | Stavros Sachtouris | |
839 | 79b4f177 | Stavros Sachtouris | [kamaki]: shell cp kamaki-logo.png logo-copy.png |
840 | e5d1d5c2 | Stavros Sachtouris | |
841 | 79b4f177 | Stavros Sachtouris | [kamaki]: shell ls -al |
842 | e5d1d5c2 | Stavros Sachtouris | total 24 |
843 | 59cadffb | Stavros Sachtouris | drwxrwxr-x 2 username username 4096 Nov 27 16:47 . |
844 | 59cadffb | Stavros Sachtouris | drwxrwxr-x 7 username username 4096 Nov 27 16:47 .. |
845 | 59cadffb | Stavros Sachtouris | -rw-rw-r-- 1 username username 8063 Jun 28 14:48 kamaki-logo.png |
846 | 59cadffb | Stavros Sachtouris | -rw-rw-r-- 1 username username 8063 Jun 28 14:48 logo-copy.png |
847 | e5d1d5c2 | Stavros Sachtouris | |
848 | e5d1d5c2 | Stavros Sachtouris | |
849 | 904091dd | Stavros Sachtouris | Kamaki shell commits command strings to the outside shell and prints the |
850 | 904091dd | Stavros Sachtouris | results, without interacting with it. After a command is finished, kamaki shell |
851 | 904091dd | Stavros Sachtouris | returns to its initial state, which involves the current directory, as show in |
852 | 904091dd | Stavros Sachtouris | example 4.8.2 |
853 | e5d1d5c2 | Stavros Sachtouris | |
854 | e5d1d5c2 | Stavros Sachtouris | .. code-block:: console |
855 | e5d1d5c2 | Stavros Sachtouris | :emphasize-lines: 1 |
856 | e5d1d5c2 | Stavros Sachtouris | |
857 | ee9f8245 | Stavros Sachtouris | Example 4.8.2: Attempt (and fail) to change working directory |
858 | e5d1d5c2 | Stavros Sachtouris | |
859 | e5d1d5c2 | Stavros Sachtouris | |
860 | 79b4f177 | Stavros Sachtouris | [kamaki]: !pwd |
861 | e5d1d5c2 | Stavros Sachtouris | /home/username |
862 | e5d1d5c2 | Stavros Sachtouris | |
863 | 79b4f177 | Stavros Sachtouris | [kamaki]: !cd .. |
864 | e5d1d5c2 | Stavros Sachtouris | |
865 | 79b4f177 | Stavros Sachtouris | [kamaki]: shell pwd |
866 | e5d1d5c2 | Stavros Sachtouris | /home/username |