Revision 2bd23362

b/docs/conf.py
54 54
from sys import path, stderr
55 55
import os
56 56

  
57

  
58
SITE_PACKAGES_PATH = os.path.expanduser(
59
    '~/src/kamaki/docsenv/lib/python2.7/site-packages')
60

  
57 61
try:
58 62
    from objpool.http import PooledHTTPConnection
59 63
    PooledHTTPConnection
60 64
except ImportError:
61
    stderr.write("`objpool` package is required to build kamaki docs.\n")
65
    path.insert(0, SITE_PACKAGES_PATH)
66
    try:
67
        from objpool.http import PooledHTTPConnection
68
        PooledHTTPConnection
69
    except ImportError:
70
        stderr.write("`objpool` package is required to build kamaki docs.\n")
71
        exit(1)
62 72

  
63 73
try:
64 74
    from progress.bar import ShadyBar
65 75
    ShadyBar
66 76
except ImportError:
67
    stderr.write("`progress` package is required to build kamaki docs.\n")
77
    path.insert(0, SITE_PACKAGES_PATH)
78
    try:
79
        from progress.bar import ShadyBar
80
        ShadyBar
81
    except ImportError:
82
        stderr.write("`progress` package is required to build kamaki docs.\n")
83
        exit(1)
68 84

  
69 85
path.insert(0, os.path.join(os.path.abspath(os.path.dirname(__file__)), '..'))
70 86

  
b/docs/installation.rst
90 90

  
91 91
    $ sudo apt-get install python-mock=1.0.1
92 92

  
93
.. hint:: To activate functional tests in kamaki. enable the preconfigured
93
.. hint:: To activate functional tests in kamaki enable the preconfigured
94 94
    *livetest* command group:
95 95

  
96 96
    .. code-block:: console
......
98 98
        $ kamaki config set livetest_cli livetest
99 99

  
100 100

  
101
Install astakosclient (optional)
102
""""""""""""""""""""""""""""""""
103

  
104
A seperate project called
105
`astakosclient <https://pypi.python.org/pypi/astakosclient>`_ can be used for
106
advanced user and service management.
107

  
108
.. code-block:: console
109

  
110
    $ apt-get install python-astakosclient
111

  
112
.. hint:: To activate astakosclient commands in kamaki, enable the
113
    preconfigured *astakos* command group:
114

  
115
    .. code-block:: console
116

  
117
        $ kamaki config set astakos_cli astakos
118

  
119 101
.. _installing-from-pypi-ref:
120 102

  
121 103
Installing from pypi
......
136 118
Setup a virtual enviroment (optional)
137 119
"""""""""""""""""""""""""""""""""""""
138 120

  
139
With virtualenv users can setup kamaki and Synnefo services in a sandbox
121
Use virtualenv to setup kamaki and Synnefo services in a sandbox
140 122
environment.
141 123

  
142 124
.. code-block:: console
......
187 169

  
188 170
        $ kamaki config set livetest_cli livetest
189 171

  
190
Install astakosclient
191
"""""""""""""""""""""
192

  
193
A seperate project called
194
`astakosclient <https://pypi.python.org/pypi/astakosclient>`_ can be used for
195
advanced user and service management.
196

  
197
.. code-block:: console
198

  
199
    $ pip install astakosclient
200

  
201
.. hint:: To activate astakosclient commands in kamaki, enable the
202
    preconfigured *astakos* command group:
203

  
204
    .. code-block:: console
205

  
206
        $ kamaki config set astakos_cli astakos
207 172

  
208 173
Mac OS X
209 174
--------
210 175

  
211
Kamaki can be installed on Mac OS X systems from source, by following the steps
176
Kamaki can be installed on Mac OS X systems, by following the steps
212 177
at :ref:`installing-from-pypi-ref`.
213 178

  
214 179
Windows
......
226 191

  
227 192
* Setuptools (`Official versions and workarounds <http://pypi.python.org/pypi/setuptools>`_)
228 193

  
229
Users who have already set up and wokring python and setuptools (e.g., for
194
Users who have already set up python and setuptools (e.g., for
230 195
another project) may skip Python and / or setuptools installation.
231 196

  
232 197
Install Python
......
264 229
`python org page <http://pypi.python.org/pypi/setuptools>`_, the setuptools
265 230
installer doesn't currently work on 64bit machines.
266 231

  
267
* Users with 32-bit operating systems should download and run the graphic
232
* Users with 32-bit platforms should download and run the graphic
268 233
    installer
269 234

  
270
* Users with 64-bit machines should download the
235
* Users with 64-bit platforms should download the
271 236
    `ez_setup.py <http://peak.telecommunity.com/dist/ez_setup.py>`_ script and
272 237
    install it from a command shell. In the following example, the script was
273 238
    downloaded at C:\\Downloads::
b/docs/setup.rst
8 8
Quick Setup
9 9
-----------
10 10

  
11
Existing kamaki users should consult the
12
`migration guide <#migrating-from-kamaki-0-8-x-to-0-9>`_ first.
11
.. warning:: Users of kamaki 0.8.X or older should consult the
12
    `migration guide <#migrating-from-kamaki-0-8-x-to-0-9-or-better>`_ first.
13 13

  
14 14
Kamaki has to be configured for a specific Synnefo deployment, with an
15 15
authentication url and user token pair. Users should also pick an alias to name
16
the cloud configuration. This can be any single word, e.g., "default", "mycloud"
17
or whatever suits kamaki users.
16
the cloud configuration. This can be any single word, e.g., "default",
17
"mycloud"or whatever suits the user.
18 18

  
19 19
.. code-block:: console
20 20

  
......
31 31
Since version 0.14, Synnefo supports a single authentication URL for retrieving
32 32
all API endpoints. This URL is retrieved from the Synnefo Web UI and should be
33 33
set as the cloud URL for kamaki. All service-specific URLs are retrieved and
34
handled automatically by kamaki, through this URL. Users of Synnefo clouds
35
>=0.14 are advised against using any service-specific URLs.
34
handled automatically. Users of Synnefo clouds >=0.14 are advised against using
35
any service-specific URLs.
36 36

  
37
Migrating from kamaki 0.8.X to 0.9
38
----------------------------------
37
Migrating from kamaki 0.8.X to 0.9 or better
38
--------------------------------------------
39 39

  
40 40
This section refers to running installations of kamaki version <= 0.8.X. To
41 41
check the current kamaki version:
......
46 46

  
47 47
Existing kamaki users should convert their configuration files to v9. To do
48 48
that, kamaki 0.9 can inspect the configuration file and suggests a list of
49
config file transformations, which are performed automatically (after users'
50
permission). This mechanism is invoked when an API-related kamaki command is
51
fired. On example 2.1 we suggest using the `user authenticate` command to fire
52
the kamaki config file conversion mechanism.
49
config file transformations, which are performed automatically after users'
50
permission. This mechanism is invoked when an API-related kamaki command is
51
fired. On example 2.1 we suggest using the `user authenticate` command to start
52
the conversion mechanism for the configuration file.
53 53

  
54 54
.. code-block:: console
55 55
    :emphasize-lines: 1
......
78 78
    Overwrite file /home/exampleuser/.kamakirc ? [Y, y]
79 79

  
80 80
At this point, we should examine the kamaki output. Most options are renamed to
81
be understood by the new kamaki.
81
match the latest configuration file version specifications.
82 82

  
83 83
Let's take a look at the discarded options:
84 84

  
......
89 89
    meaningless and therefore omitted.
90 90

  
91 91
* `global.data_log` option has never been a valid kamaki config option.
92
    In this example, the user accidentally misspelled the term `log_data`
93
    (which is a valid kamaki config option) as `data_log`. To fix this, the
94
    user should set the correct option after the conversion is complete
95
    (Example 2.2).
92
    In this scenario, the user wanted to set the `log_data` option, but he or
93
    she typed `data_log` instead. To fix this, the user should manually set the
94
    correct option after the conversion is complete (Example 2.2).
96 95

  
97
Users should press *y* when they are ready. Kamaki has now modified the default
98
config file to conform with kamaki config file v3. Now users should rescue
99
unrescued information (if any).
96
Users should press *y* when they are ready, which will cause the default config
97
file to be modified so that it conforms with the latest version.
100 98

  
101 99
.. code-block:: console
102 100
    :emphasize-lines: 1
......
121 119

  
122 120
The following refers to users of multiple Synnefo and/or Open Stack
123 121
deployments. In the following, a Synnefo or Open Stack cloud deployment will
124
frequently be called as a **cloud**.
122
be called **a cloud**.
125 123

  
126
Kamaki supports accessing multiple clouds from the same kamaki setup. Before
127
kamaki 0.9, this was possible only by using multiple config files. Since 0.9,
128
kamaki supports multiple clouds in the same configuration.
129

  
130
Each cloud corresponds to a Synnefo (or Open Stack) cloud deployment.
131
Since Synnefo version 0.14, each deployment offers a single point of
132
authentication, as an **authentication URL** and **token** pair. Users can
133
retrieve this information through the cloud UI.
124
Multiple clouds can be configured and manager in a single  kamaki setup, since
125
version 0.9. Each cloud corresponds to a Synnefo (or Open Stack) cloud
126
deployment, with each deployment offering a single point of authentication (an
127
**authentication URL** and **token** pair). Users can retrieve this information
128
through the cloud UI.
134 129

  
135 130
Once a user has retrieved one URL/token pair per cloud, it is time to assign a
136
name to each cloud and let kamaki know about them.
131
name to each cloud and configure kamaki accordingly.
137 132

  
138 133
For example, let the user have access to two clouds with the following authentication information ::
139 134

  
......
146 141
    authentication token: my73571ng70k3n==
147 142

  
148 143
.. note:: the cloud alias is arbitrary and decided by the user. It is just a
149
    name to call a cloud setup in the kamaki context.
144
    reference label for the cloud setup in the kamaki context.
150 145

  
151 146
The user should let kamaki know about these setups:
152 147

  
......
164 159

  
165 160
.. code-block:: console
166 161

  
167
    $ kamaki config getcloud
162
    $ kamaki config get cloud
168 163
     cloud.default.url = https://example.com/astakos.identity/v2.0/
169
     cloud.default.url = myd3f4u1770k3n==
164
     cloud.default.token = myd3f4u1770k3n==
170 165
     cloud.devel.url = https://devel.example.com/astakos/identity/v2.0/
171 166
     cloud.devel.token = myd3v3170k3n==
172 167
     cloud.testing.url = https://testing.example.com/astakos/identity/v2.0/
......
214 209
        name       :  Default User
215 210
    $
216 211

  
217
In interactive cell, the cloud is picked when invoking the shell, with
212
In interactive cell, the cloud can be picked when invoking the shell, with
218 213
the **- - cloud** option.
219 214

  
215
.. code-block:: console
216

  
217
    $ kamaki --cloud=devel
218
    kamaki v0.10 - Interactive Shell
219

  
220
    /exit       terminate kamaki
221
    exit or ^D  exit context
222
    ? or help   available commands
223
    ?command    help on command
224
    !<command>  execute OS shell command
225

  
226
    Session user is Devel User
227
    (uuid: 725d5de4-1bab-45ac-9e98-38a60a8c543c)
228
    [kamaki]: 
229

  
230

  
220 231
Optional features
221 232
-----------------
222 233

  
......
233 244
    * Allow unit tests to run on kamaki.clients package
234 245
    * Needs mock version 1.X or better
235 246

  
236
* astakosclient
237
    * For advanced users mostly
238
    * Allows the use of a full astakos command line client
239

  
240 247
Any of the above features can be installed at any time before or after kamaki
241 248
installation.
242 249

  
......
247 254

  
248 255
* kamaki-related (global)
249 256
    interface settings and constants of the kamaki internal mechanism, e.g.,
250
    colors in the output, maximum threads per connection, custom logging or
251
    history files, etc.
257
    terminal colors, maximum threads per connection, custom logging, history
258
    file path, etc.
252 259

  
253 260
* cloud-related
254 261
    information needed to connect and use one or more clouds. There are some
......
284 291
Modifying options at runtime
285 292
^^^^^^^^^^^^^^^^^^^^^^^^^^^^
286 293

  
287
All kamaki commands can be used with the -o option in order to override configuration options at runtime. For example::
294
All kamaki commands can be used with the -o option in order to override configuration options at runtime. For example:
288 295

  
289 296
.. code-block:: console
290 297

  
......
293 300
will invoke *kamaki file list* with the specified options, but the initial
294 301
global.pithos_container values will not be modified.
295 302

  
303

  
296 304
Editing options
297 305
^^^^^^^^^^^^^^^
298 306

  
299 307
Kamaki config command allows users to see and manage all configuration options.
300 308

  
301 309
* kamaki config list
302
    lists all configuration options currently used by a Kamaki installation
310
    lists all configuration options of a kamaki setup
303 311

  
304 312
* kamaki config get <group.option>
305 313
    show the value of a specific configuration option. Options must be of the
306
    form *group.option*. The term *option* is equivalent to *global.option*
314
    form *group.option*. A single *option* is equivalent to *global.option*,
315
    with the exception of the term *cloud* (see bellow)
307 316

  
308 317
* kamaki config set <group.option> <value>
309
    set the group.option to value. If no group is given, the defaults to
318
    set the group.option to value. If no group is given, it defaults to
310 319
    *global*.
311 320

  
312 321
* kamaki config delete <group.option>
313
    delete a configuration option. If no group is given, the defaults to
322
    delete a configuration option. If no group is given, it defaults to
314 323
    *global*
315 324

  
316 325
The above commands cause option values to be permanently stored in the Kamaki configuration file.
......
341 350
        delete the <option> and its value from the cloud cloud aliased as
342 351
        <cloud alias>
343 352

  
344
.. note:: To see if a default cloud is configured, get the default_cloud value
353
To see if a default cloud is configured, get the default_cloud value
345 354

  
346 355
    .. code-block:: console
347 356

  
348 357
        $ kamaki config get default_cloud
349 358

  
359
If no default_cloud value is set, the first cloud alias is picked as default.
360
To pick a cloud alias as default:
361

  
362
    .. code-block:: console
363

  
364
        $ kamaki config set default_cloud <cloud alias>
365

  
366

  
350 367
Editing the configuration file
351 368
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
352 369

  
353 370
The configuration file is a simple text file that can be created by the user.
354 371

  
355
.. note:: users of kamaki < 0.9 can use kamaki 0.9.X to automatically convert
356
    their old configuration files to the new config file version (>= 3.0). To
357
    do this, follow `these instructions <#migrating-from-kamaki-0-8-x-to-0-9>`_
372
.. note:: users of kamaki < 0.9 can use the latest versions to automatically
373
    convert their old configuration files to the new configuration file(s).
374
    See `these instructions <#migrating-from-kamaki-0-8-x-to-0-9-or-better>`_
375
    for more.
358 376

  
359 377
A simple way to create the configuration file is to set a configuration option
360 378
using the kamaki config command. For example:
......
378 396
    url =
379 397
    token =
380 398

  
381
A bunch of configuration options are created and set to their default options,
382
except the log_file option which is set to whatever the specified value.
383

  
384
The [cloud "default"] section is special and is used to configure the default
385
cloud cloud. Kamaki will not be able to run without setting the url and token
386
values to that section.
399
In this scenario, a bunch of configuration options are created and set to their
400
default options, except the log_file option which is set to whatever the
401
specified value.
387 402

  
388
More clouds can be created  on the side of the default cloud, e.g., using the
389
examples at the `multiple clouds guide <#multiple-clouds>`_ ::
390

  
391
    [cloud "devel"]
392
    url = https://devel.example.com/astakos/identity/v2.0/
393
    token = myd3v3170k3n==
394

  
395
    [cloud "testing"]
396
    url = https://testing.example.com/astakos/identity/v2.0/
397
    token = my73571ng70k3n==
403
The *[cloud "default"]* section is special and is used to configure the default
404
cloud. Kamaki will not be able to do anything useful without proper url and
405
token values set in the cloud section.
398 406

  
399 407
Available options
400 408
^^^^^^^^^^^^^^^^^
401 409

  
402
The [global] group is treated by kamaki as a generic group for kamaki-related
410
The [*global*] group is treated by kamaki as a generic group for kamaki
403 411
settings, namely command cli specifications, the thread limit, console colors,
404 412
history and log files, log detail options and pithos-specific options.
405 413

  
......
416 424
    allow kamaki to log http data (by default, it logs only method, URL and
417 425
    headers)
418 426

  
427
* global.log_pid <on|off>
428
    attach the process name and id that produces each log line. Useful for
429
    resolving race condition problems.
430

  
419 431
* global.file_cli <UI command specifications for file>
420 432
    a special package that is used to load storage commands to kamaki UIs.
421 433
    Don't touch this unless if you know what you are doing.
......
447 459
Additional features
448 460
^^^^^^^^^^^^^^^^^^^
449 461

  
450
The livetest suite
451
""""""""""""""""""
462
Functional tests
463
""""""""""""""""
452 464

  
453
Kamaki contains a live test suite for the kamaki.clients API, where "live"
454
means that the tests are performed against active services that up and running.
455
The live test package is named "livetest", it is accessible as kamaki.clients.
456
livetest and it is designed to check the actual relation between kamaki and
457
synnefo services.
465
Kamaki contains a set of functional tests for *kamaki.clients*, called
466
"livetest". The term "live" means that the tests are performed against an
467
on-line functional cloud deployment. The package is accessible as
468
*kamaki.clients.livetest* .
458 469

  
459
The livetest suite can be activated with the following option on the configuration file::
470
The livetest commands can be activated by setting the following option in the
471
configuration file::
460 472

  
461 473
    [global]
462 474
    livetest_cli=livetest
463 475

  
464 476
or with this kamaki command::
465 477

  
466
    kamaki config set livetest_cli livetest
478
    $ kamaki config set livetest_cli livetest
467 479

  
468
In most tests, livetest will run as long as the default cloud is configured
469
correctly. Some commands, though, need some extra settings related to the cloud
470
the test is performed against, or the example files used in kamaki.
480
In most cases, it is enough to have the default cloud configured correctly.
481
Some commands, though, require some extra settings specific to actual contents
482
of the cloud or the example files used in kamaki.
471 483

  
472 484
Here is a list of settings needed:
473 485

  
......
477 489
* for astakos client::
478 490
    * livetest.astakos_details = <A file with an authentication output>
479 491
        To create this file, pipeline the output of an authentication command
480
        with the -j option for raw jason output
492
        with the -j option for raw json output
481 493

  
482 494
        .. code-block:: console
483 495

  
484 496
            $ kamaki user authenticate -j > astakos.details
485 497

  
486
    * livetest.astakos_name = <The exact "real" name of testing user>
498
    * livetest.astakos_name = <The exact "real" name of the testing user>
487 499
    * livetest.astakos_id = <The valid unique user id of the testing user>
488 500

  
489 501
* for image client:
490
    * livetest.image_details = <A file with the image's metadata>
502
    * livetest.image_details = <A file with the image metadata>
491 503
        To create this file, pipeline the output of an image metadata command
492
        with the -j option for raw jason output
504
        with the -j option for raw json output
493 505

  
494 506
        .. code-block:: console
495 507

  
......
501 513
* for flavors (part of the compute client):
502 514
    * livetest.flavor_details = <A file with the flavor details>
503 515
        To create this file, pipeline the output of a flavor info command
504
        with the -j option for raw jason output
516
        with the -j option for raw json output
505 517

  
506 518
        .. code-block:: console
507 519

  
......
512 524

  
513 525
    $ kamaki livetest all
514 526

  
515
a specific test (e.g., astakos)::
527
a specific test (e.g., pithos scenario)::
528

  
529
    $ kamaki livetest pithos
516 530

  
517
    $ kamaki livetest astakos
531
or a specific method from a service (e.g., create_server @ cyclades)::
518 532

  
519
or a specific method from a service (e.g., astakos authenticate)::
533
    $ kamaki livetest cyclades create_server
520 534

  
521
    $ kamaki livetest astakos authenticate
522 535

  
523 536
The unit testing system
524 537
"""""""""""""""""""""""
525 538

  
526 539
Kamaki container a set of finegrained unit tests for the kamaki.clients
527 540
package. This set is not used when kamaki is running. Instead, it is aimed to
528
developers who debug or extent the kamaki clients library. For more
529
information, check the
541
developers who debug or extent kamaki. For more information, check the
530 542
`Going Agile <developers/extending-clients-api.html#going-agile>`_ entry at the
531 543
`developers section <developers/extending-clients-api.html>`_.
b/docs/usage.rst
6 6
`Commands <commands.html>`_ section. This guide covers the generic usage of
7 7
both interfaces.
8 8

  
9
What's more, kamaki offers a clients API that allows the development of
10
external applications for Synnefo. The clients API is listed in the
9
What's more, kamaki offers a clients library for the development of external
10
client applications for Synnefo. The clients library API is detailed in the
11 11
`Clients lib <developers/code.html#the-clients-api>`_ section.
12 12

  
13 13
Quick Setup
......
34 34
Shell vs one-command
35 35
--------------------
36 36
Kamaki users can access Synnefo services through either the interactive shell
37
or the one-command behaviors. In practice, both systems rely on the same
37
or the one-command interface. In practice, both systems rely on the same
38 38
command set implementations and API clients, with identical responses and error
39 39
messages. Still, there are some differences.
40 40

  
41
In favor of interactive shell behavior:
41
In favor of interactive shell:
42 42

  
43 43
* tab completion for commands (if supported by the user's shell)
44 44
* session history with ↑ or ↓ keys (if supported by the user's shell)
45 45
* shorter commands with command context switching
46 46
* re-run old commands with /history
47 47

  
48
In favor of one-command behavior:
48
In favor of one-command:
49 49

  
50 50
* can be used along with advanced shell features (pipelines, redirection, etc.)
51 51
* can be used in shell scripts
......
64 64

  
65 65
    $ kamaki
66 66

  
67
* with any kind of '-' prefixed arguments, except '-h', '--help'.
67
* with any kind of '-' prefixed arguments, except '-h', '--help', '-V',
68
    '- - version'.
68 69

  
69 70
.. code-block:: console
70 71
    :emphasize-lines: 1
......
92 93
.. code-block:: console
93 94
    :emphasize-lines: 1
94 95

  
95
    Example 2.3.2: List VMs managed by user
96
    Example 2.3.2: List servers managed by user
96 97

  
97 98
    $ kamaki server list
98 99

  
......
170 171

  
171 172
    Options:
172 173
     - - - -
173
    addr    :  List the addresses of all network interfaces on a server (VM)
174
    console :  Get a VNC console to access an existing server (VM)
174
    addr    :  List the addresses of all network interfaces on a server (server)
175
    console :  Get a VNC console to access an existing server (server)
175 176
    create  :  Create a server (aka Virtual Machine)
176
    delete  :  Delete a server (VM)
177
    firewall:  Manage server (VM) firewall profiles for public networks
177
    delete  :  Delete a server (server)
178
    firewall:  Manage server (server) firewall profiles for public networks
178 179
    ip      :  Manage floating IPs for the servers
179 180
    info    :  Detailed information on a Virtual Machine
180 181
    list    :  List Virtual Machines accessible by user
181 182
    metadata:  Manage Server metadata (key:value pairs of server attributes)
182
    reboot  :  Reboot a server (VM)
183
    rename  :  Set/update a server (VM) name
184
    shutdown:  Shutdown an active server (VM)
185
    start   :  Start an existing server (VM)
186
    stats   :  Get server (VM) statistics
183
    reboot  :  Reboot a server (server)
184
    rename  :  Set/update a server (server) name
185
    shutdown:  Shutdown an active server (server)
186
    start   :  Start an existing server (server)
187
    stats   :  Get server (server) statistics
187 188
    resize  :  Set a different flavor for an existing server
188 189
    wait    :  Wait for server to finish [BUILD, STOPPED, REBOOT, ACTIVE]
189 190

  
......
221 222
    --more                output results in pages (-n to set items per page,
222 223
                          default 10)
223 224
    -n LIMIT, --number LIMIT
224
                          limit number of listed VMs
225
                          limit number of listed servers
225 226
    -j, --json            show headers in json
226 227

  
227 228
.. _using-history-ref:
......
406 407
    [file]: exit
407 408
    [kamaki]: server
408 409
    [server]: list
409
    ... (VMs listing) ...
410
    ... (servers listing) ...
410 411
    [server]: exit
411 412
    [kamaki]:
412 413

  
......
424 425
    [kamaki]: file list
425 426
    ... (storage container listing) ...
426 427
    [kamaki]: server list
427
    ... (VMs listing) ...
428
    ... (servers listing) ...
428 429
    [kamaki]:
429 430

  
430 431
Using Help
......
559 560
    [context]: /anothercontext cmd1 cmd2 ... cmdN
560 561

  
561 562
An example (4.3.1) that showcases how top-level access improves user experience
562
is the creation of a VM. A VM is created with the command server-create. This
563
is the creation of a server. A server is created with the command server-create. This
563 564
command is called with three parameters:
564 565

  
565
* the name of the new VM
566
* the name of the new server
566 567
* the flavor id
567 568
* the image id
568 569

  
569 570
It is often the case that a user who works in the context command, needs to
570
create a new VM, but hasn't selected a flavor or an image id, or cannot recall
571
create a new server, but hasn't selected a flavor or an image id, or cannot recall
571 572
the id of that flavor or image. Therefore, it is necessary to list all
572 573
available flavors (flavor-list) or images (image-compute-list). Both commands
573 574
belong to different contexts.
......
575 576
.. code-block:: console
576 577
    :emphasize-lines: 1
577 578

  
578
    Example 4.3.1: Create a VM from server context
579
    Example 4.3.1: Create a server from server context
579 580

  
580 581
    [server]: create -h
581 582
    create <name> <flavor id> <image id> ...
b/kamaki/cli/commands/cyclades.py
59 59
    \n* to set authentication token: /config set cloud.<cloud>.token <token>'
60 60

  
61 61
howto_personality = [
62
    'Defines a file to be injected to VMs file system.',
62
    'Defines a file to be injected to virtual servers file system.',
63 63
    'syntax:  PATH,[SERVER_PATH,[OWNER,[GROUP,[MODE]]]]',
64 64
    '  PATH: local file to be injected (relative or absolute)',
65 65
    '  SERVER_PATH: destination location inside server Image',
66
    '  OWNER: VMs user id of the remote destination file',
67
    '  GROUP: VMs group id or name of the destination file',
66
    '  OWNER: virtual servers user id of the remote destination file',
67
    '  GROUP: virtual servers group id or name of the destination file',
68 68
    '  MODEL: permition in octal (e.g. 0777 or o+rwx)']
69 69

  
70 70

  
......
146 146
        since=DateArgument(
147 147
            'show only items since date (\' d/m/Y H:M:S \')',
148 148
            '--since'),
149
        limit=IntArgument('limit number of listed VMs', ('-n', '--number')),
149
        limit=IntArgument(
150
            'limit number of listed virtual servers', ('-n', '--number')),
150 151
        more=FlagArgument(
151 152
            'output results in pages (-n to set items per page, default 10)',
152 153
            '--more'),
......
346 347

  
347 348
@command(server_cmds)
348 349
class server_rename(_init_cyclades, _optional_output_cmd):
349
    """Set/update a server (VM) name
350
    VM names are not unique, therefore multiple servers may share the same name
350
    """Set/update a virtual server name
351
    virtual server names are not unique, therefore multiple servers may share
352
    the same name
351 353
    """
352 354

  
353 355
    @errors.generic.all
......
364 366

  
365 367
@command(server_cmds)
366 368
class server_delete(_init_cyclades, _optional_output_cmd, _server_wait):
367
    """Delete a server (VM)"""
369
    """Delete a virtual server"""
368 370

  
369 371
    arguments = dict(
370 372
        wait=FlagArgument('Wait server to be destroyed', ('-w', '--wait'))
......
392 394

  
393 395
@command(server_cmds)
394 396
class server_reboot(_init_cyclades, _optional_output_cmd, _server_wait):
395
    """Reboot a server (VM)"""
397
    """Reboot a virtual server"""
396 398

  
397 399
    arguments = dict(
398 400
        hard=FlagArgument(
......
434 436

  
435 437
@command(server_cmds)
436 438
class server_start(_init_cyclades, _optional_output_cmd, _server_wait):
437
    """Start an existing server (VM)"""
439
    """Start an existing virtual server"""
438 440

  
439 441
    arguments = dict(
440 442
        wait=FlagArgument('Wait server to be destroyed', ('-w', '--wait'))
......
464 466

  
465 467
@command(server_cmds)
466 468
class server_shutdown(_init_cyclades, _optional_output_cmd, _server_wait):
467
    """Shutdown an active server (VM)"""
469
    """Shutdown an active virtual server"""
468 470

  
469 471
    arguments = dict(
470 472
        wait=FlagArgument('Wait server to be destroyed', ('-w', '--wait'))
......
494 496

  
495 497
@command(server_cmds)
496 498
class server_console(_init_cyclades, _optional_json):
497
    """Get a VNC console to access an existing server (VM)
499
    """Get a VNC console to access an existing virtual server
498 500
    Console connection information provided (at least):
499 501
    - host: (url or address) a VNC host
500
    - port: (int) the gateway to enter VM on host
502
    - port: (int) the gateway to enter virtual server on host
501 503
    - password: for VNC authorization
502 504
    """
503 505

  
......
535 537

  
536 538
@command(server_cmds)
537 539
class server_firewall(_init_cyclades):
538
    """Manage server (VM) firewall profiles for public networks"""
540
    """Manage virtual server firewall profiles for public networks"""
539 541

  
540 542

  
541 543
@command(server_cmds)
542 544
class server_firewall_set(_init_cyclades, _optional_output_cmd):
543
    """Set the server (VM) firewall profile on VMs public network
545
    """Set the firewall profile on virtual server public network
544 546
    Values for profile:
545 547
    - DISABLED: Shutdown firewall
546 548
    - ENABLED: Firewall in normal mode
......
562 564

  
563 565
@command(server_cmds)
564 566
class server_firewall_get(_init_cyclades):
565
    """Get the server (VM) firewall profile for its public network"""
567
    """Get the firewall profile for a virtual servers' public network"""
566 568

  
567 569
    @errors.generic.all
568 570
    @errors.cyclades.connection
......
577 579

  
578 580
@command(server_cmds)
579 581
class server_addr(_init_cyclades, _optional_json):
580
    """List the addresses of all network interfaces on a server (VM)"""
582
    """List the addresses of all network interfaces on a virtual server"""
581 583

  
582 584
    arguments = dict(
583 585
        enum=FlagArgument('Enumerate results', '--enumerate')
......
620 622

  
621 623
@command(server_cmds)
622 624
class server_metadata_set(_init_cyclades, _optional_json):
623
    """Set / update server(VM) metadata
625
    """Set / update virtual server metadata
624 626
    Metadata should be given in key/value pairs in key=value format
625 627
    For example: /server metadata set <server id> key1=value1 key2=value2
626 628
    Old, unreferenced metadata will remain intact
......
655 657

  
656 658
@command(server_cmds)
657 659
class server_metadata_delete(_init_cyclades, _optional_output_cmd):
658
    """Delete server (VM) metadata"""
660
    """Delete virtual server metadata"""
659 661

  
660 662
    @errors.generic.all
661 663
    @errors.cyclades.connection
......
672 674

  
673 675
@command(server_cmds)
674 676
class server_stats(_init_cyclades, _optional_json):
675
    """Get server (VM) statistics"""
677
    """Get virtual server statistics"""
676 678

  
677 679
    @errors.generic.all
678 680
    @errors.cyclades.connection
b/kamaki/cli/commands/errors.py
239 239
                elif network_id or ce.status == 421:
240 240
                    msg = 'Network with id %s is in use' % network_id,
241 241
                    raiseCLIError(ce, msg, details=[
242
                        'Disconnect all nics/VMs of this network first',
242
                        'Disconnect all nics/servers of this network first',
243 243
                        '* to get nics: /network info %s' % network_id,
244 244
                        '.  (under "attachments" section)',
245 245
                        '* to disconnect: /network disconnect <nic id>'])
......
274 274
                server_id = int(server_id)
275 275
                return foo(self, *args, **kwargs)
276 276
            except ValueError as ve:
277
                msg = 'Invalid server(VM) id %s' % server_id,
277
                msg = 'Invalid virtual server id %s' % server_id,
278 278
                details = ['id must be a positive integer'],
279 279
                raiseCLIError(ve, msg, details=details, importance=1)
280 280
            except ClientError as ce:
......
284 284
                ) or (
285 285
                    ce.status == 400 and 'not found' in err_msg
286 286
                ):
287
                    msg = 'server(VM) with id %s not found' % server_id,
287
                    msg = 'virtual server with id %s not found' % server_id,
288 288
                    raiseCLIError(ce, msg, details=[
289
                        '* to get existing VM ids: /server list',
290
                        '* to get VM details: /server info <VM id>'])
289
                        '* to get ids of all servers: /server list',
290
                        '* to get server details: /server info <server id>'])
291 291
                raise
292 292
        return _raise
293 293

  
......
321 321
                    'network interface' in ('%s' % ce).lower()
322 322
                ):
323 323
                    server_id = kwargs.get('server_id', '<no server>')
324
                    err_msg = 'No nic %s on server(VM) with id %s' % (
324
                    err_msg = 'No nic %s on virtual server with id %s' % (
325 325
                        nic_id,
326 326
                        server_id)
327 327
                    raiseCLIError(ce, err_msg, details=[
328
                        '* check server(VM) with id %s: /server info %s' % (
328
                        '* check v. server with id %s: /server info %s' % (
329 329
                            server_id,
330 330
                            server_id),
331
                        '* list nics for server(VM) with id %s:' % server_id,
331
                        '* list nics for v. server with id %s:' % server_id,
332 332
                        '      /server addr %s' % server_id])
333 333
                raise
334 334
        return _raise
......
357 357
                if key and ce.status == 404 and (
358 358
                    'metadata' in ('%s' % ce).lower()
359 359
                ):
360
                        raiseCLIError(ce, 'No VM metadata with key %s' % key)
360
                        raiseCLIError(
361
                            ce, 'No v. server metadata with key %s' % key)
361 362
                raise
362 363
        return _raise
363 364

  
b/kamaki/clients/compute/__init__.py
121 121

  
122 122
        :param flavor_id: integer id denoting a preset hardware configuration
123 123

  
124
        :param image_id: (str) id denoting the OS image to run on the VM
124
        :param image_id: (str) id of the image of the virtual server
125 125

  
126 126
        :param metadata: (dict) vm metadata
127 127

  
128 128
        :param personality: a list of (file path, file contents) tuples,
129
            describing files to be injected into VM upon creation.
129
            describing files to be injected into virtual server upon creation
130 130

  
131
        :returns: a dict with the new VMs details
131
        :returns: a dict with the new virtual server details
132 132

  
133 133
        :raises ClientError: wraps request errors
134 134
        """
......
152 152

  
153 153
    def update_server_name(self, server_id, new_name):
154 154
        """Update the name of the server as reported by the API (does not
155
            modify the hostname used inside the VM)
155
            modify the hostname used inside the virtual server)
156 156

  
157 157
        :param server_id: integer (str or int)
158 158

  
b/kamaki/clients/cyclades/__init__.py
50 50

  
51 51
        :param flavor_id: integer id denoting a preset hardware configuration
52 52

  
53
        :param image_id: (str) id denoting the OS image to run on the VM
53
        :param image_id: (str) id denoting the OS image to run on virt. server
54 54

  
55 55
        :param metadata: (dict) vm metadata updated by os/users image metadata
56 56

  
57 57
        :param personality: a list of (file path, file contents) tuples,
58
            describing files to be injected into VM upon creation.
58
            describing files to be injected into virtual server upon creation
59 59

  
60
        :returns: a dict with the new VMs details
60
        :returns: a dict with the new virtual server details
61 61

  
62 62
        :raises ClientError: wraps request errors
63 63
        """
......
99 99
        """
100 100
        :param server_id: integer (str or int)
101 101

  
102
        :returns: (dict) info to set a VNC connection to VM
102
        :returns: (dict) info to set a VNC connection to virtual server
103 103
        """
104 104
        req = {'console': {'type': 'vnc'}}
105 105
        r = self.servers_action_post(server_id, json_data=req, success=200)
b/kamaki/clients/livetest/__init__.py
37 37
from sys import stdout
38 38

  
39 39
from kamaki.cli.config import Config
40
from kamaki.cli.utils import spiner
41 40

  
42 41

  
43 42
def _add_value(foo, value):
......
102 101
            wait_cb = wait_gen
103 102
        except Exception:
104 103
            stdout.write('%s:' % msg)
105
            (wait_bar, wait_cb) = (None, spiner)
104
            (wait_bar, wait_cb) = None, None
106 105
        return (wait_bar, wait_cb)
107 106

  
108 107
    def _safe_progress_bar_finish(self, progress_bar):

Also available in: Unified diff