Commit f6822a26 authored by Stavros Sachtouris's avatar Stavros Sachtouris
Browse files

Take care of the documentation (except developers)

parent 2bd23362
......@@ -450,7 +450,7 @@ Showcase: Upload and download a file
.. warning:: The container:object/path syntax does not function if the
container and / or the object path contain one or more : characters. To use
containers and objects with : use the --container and --dst-container
arguments, e.g. to copy test.py object from grnet:dev container to
grnet:deploy ::
arguments, e.g. to copy test.py object from example:dev container to
example:deploy ::
$ kamaki file copy --container=grnet:dev test.py --dst-container=grnet:deploy
$ kamaki file copy --container=example:dev test.py --dst-container=example:deploy
Configuration
=============
Since kamaki 0.9, the format of the configuration file has changed. In this
scenario, we have an old configuration file at ${HOME}/.kamakirc that we need
to convert. We also create a new one from scratch. In both cases, we have to
set up one or more clouds in a single configuration and we also examine a case
of multiple configurations.
The following refers to the configuration version 0.9 or better. There is also
information on how to convert from older configuration files.
In this scenario, we start with an old configuration file at
*${HOME}/.kamakirc* that we need to convert. We also create a new one from scratch. In both cases, the second step is the same: set up one or more clouds
in a single configuration. Then we examine a case of multiple configuration
files.
Convert old configuration file
------------------------------
......@@ -45,7 +47,7 @@ Now, let kamaki do the conversion
. image.url = https://cyclades.example.com/plankton
. store.account = OldForgotenAccountName
. Kamaki is ready to convert the config file
. Create (overwrite) file .kamakirc.okeanos ? [y/N]
. Create (overwrite) file .kamakirc ? [y/N]
.
<y is pressed>
.
......@@ -138,7 +140,7 @@ Check that the file is created, everything is set up correctly and working
Failed or incomplete cloud configurations
-----------------------------------------
Now let kamaki use the default configuration ( ${HOME}/.kamakirc ). Let the old
Now let kamaki use the default configuration (*${HOME}/.kamakirc*). Let the old
token be `my0ld70k3n==` and let it be invalid.
Check for clouds and attempt to authenticate
......@@ -172,7 +174,7 @@ Set the URL from the previous example and attempt authentication
. | UNAUTHORIZED unauthorized (Invalid token)
$
After some searching at the deployments UI, you found out that the URL/token
After some searching at the deployments UI, you find out that the URL/token
pair you need is::
URL: https://accounts.deploymentexample.com/identity/v2.0
......@@ -208,7 +210,7 @@ We now have two configurations::
URL: https://accounts.example.com/identity/v2.0/
TOKEN: myt35t70k3n==
As we can see, the default configuration handles only one cloud, aliased as
Obviously the default configuration handles only one cloud, aliased as
"default". We will add the second cloud as well.
.. code-block:: console
......@@ -228,7 +230,7 @@ Check all clouds
. cloud.mytest.token = myt35t70k3n==
$
Check if kamaki knows one of the clouds to be the default
Check if kamaki is confused (is there a default cloud setup?)
.. code-block:: console
......@@ -298,10 +300,10 @@ the default cloud.
Multiple configurations
-----------------------
In the following example, a user wants to experiment with upload and download
for different number of threads. The plan is to contuct a set of tests with 3
threads at most and another one with 5. All experiments will be run against the
same Synnefo cloud (the "mytest" cloud from the previous example).
In the following example, we experiment with the higher number of threads when
uploading and downloading. The plan is to contact a set of tests with 3 threads
at most and another one with 5. All experiments will be run against the same
Synnefo cloud (the "mytest" cloud from the previous example).
Let's create the 3-threaded configuration first
......
......@@ -14,8 +14,13 @@ The image location format at user level::
pithos:debian_base3.diskdump
The crussial element in an image location is the container (e.g. `pithos`) and
the image object path (e.g. `debian_base3.diskdump`).
.. note:: The image API requires the image location in the form
*pithos://<user uuid>/<container>/<object path>*
The translation between
the two formats is handled internally by kamaki. The latest format is still
acceptable by kamaki due to backward compatibility but it is going to be deprecated from kamaki 0.12 and on.
Register an image
......@@ -64,8 +69,7 @@ with the **\- -upload-image-file** argument. This single operation will upload
the image file and then register it as an image, and is equivalent to manually
calling **/file upload** and **/image register**.
In other words, the example that follows is equivalent to calling the two
operations above.
In other words, the preceding and following command sequences are equivalent.
.. code-block:: console
......@@ -168,11 +172,10 @@ The image will be registered again, but with some custom properties::
OS: Linux
user: someuser
These properties can be added freely by the user, and they have no significance
for the image server, but they could be used to help using the image more
efficiently.
These properties can be added freely by the user, and they are not required by
the image server, but they can be used by many applications.
Attempt to register with properties
Attempt to register an image with custom properties
.. code-block:: console
......@@ -180,7 +183,8 @@ Attempt to register with properties
Metadata file pithos:debian_base3.diskdump.meta already exists
[kamaki]:
It's true that the metafile is already there, but we can override it (**-f**)
It's true that a metafile with this name is already there, but we can override
it (**-f**)
.. code-block:: console
......@@ -199,7 +203,7 @@ Download the meta file of the image (it was uploaded recently)
Done
[kamaki]:
The metadata file can be edited. Let's edit the file, by adding properties::
The metadata file can be edited. Let's edit the file to add these properties::
OS: Linux
user: root
......@@ -272,7 +276,7 @@ Let's rename the image:
[kamaki]: image meta set 7h1rd-1m4g3-1d --name='Changed Name'
[kamaki]:
If we, now, get the image metadata, we will see that the name is changed:
A look at the image metadata reveals that the name is changed:
.. code-block:: console
......@@ -305,18 +309,18 @@ id, owner, location, checksum and dates. E.g., to publish and unpublish:
[kamaki]: image meta set 7h1rd-1m4g3-1d --unpublish
[kamaki]:
The first call published the image (set is-public to True) and also restored
the name to "Debian Base Gama". The second one unpublished the image (set
The first call publishes the image (set is-public to True) and also restores
the name to "Debian Base Gama". The second one unpublishes the image (set
is-public to False).
To delete metadata, use the image meta delete method:
To delete metadata, use the image meta delete method. For example, the
following will set the value of *status* to an empty string:
.. code-block:: console
[kamaki]: image meta delete 7h1rd-1m4g3-1d status
[kamaki]:
will empty the value of "status".
These operations can be used for properties with the same semantics:
......@@ -370,12 +374,12 @@ Although the image was unregistered and reregistered, the image id, that is
produced automatically at the server side, was the same. This is due to the
fact that image ids are 1 to 1 related to image objects uploaded to Pithos+
**An explicit name overrides the metafile**
**An explicit image name overrides the metafile**
Each image needs a name and this is given as the first argument of the
`register` command. This name overrides the name in the metafile.
**Reregistration is not update, but an override**
**Reregistration is not an update, but an override**
The property `user: root` won over `user: someuser`, because it was set last.
Actually, all properties were replaced by the new ones, when the image was
......@@ -560,7 +564,7 @@ Let's use the script (enriched with a separator message) to batch-register the
images (all images will be named after their relative paths).
Also, let the registered images be public (accessible to all users for creating
VMs) by adding the **--public** flag argument when calling `image register`.
VMs) by adding the **- - public** flag argument when calling `image register`.
.. code-block:: console
......
......@@ -9,20 +9,21 @@ The examples of this section run in a kamaki interactive shell.
.. code-block:: console
$ kamaki
kamaki v0.9 - Interactive Shell
.
kamaki v0.10 - Interactive Shell
/exit terminate kamaki
exit or ^D exit context
? or help available commands
?command help on command
!<command> execute OS shell command
.
Session user is Tyler Durden <uuid: th3y-4r3-7h3-54m3-p3r50n>
[kamaki]:
Simple listing
--------------
List configuration options, whether in the file or in memory
List configuration options, whether in the file or from defaults list
.. code-block:: console
......@@ -78,7 +79,7 @@ List networks
[kamaki]: network list
1 public_network
42 my_private)network
42 my_private_network
[kamaki]:
List flavors
......@@ -96,15 +97,15 @@ List images from Image API and from Compute APIs
[kamaki]: image list
f1r57-1m4g3-1d Debian Base Alpha
.container_format: bare
.disk_format: diskdump
.size: 474066944
.status: available
container_format: bare
disk_format: diskdump
size: 474066944
status: available
53c0nd-1m4g3-1d Beta Debian Base
.container_format: bare
.disk_format: diskdump
.size: 474066944
.status: available
container_format: bare
disk_format: diskdump
size: 474066944
status: available
[kamaki]: image compute list
f1r57-1m4g3-1d Debian Base Alpha
53c0nd-1m4g3-1d Beta Debian Base
......@@ -130,15 +131,15 @@ List pithos containers with details
count: 3
modified: 2013-06-17T12:35:11.613124+00:00
policy:
. quota: 0
. versioning: auto
quota: 0
versioning: auto
trash
bytes: 0 (0B)
count: 0
modified: 2013-06-06T14:24:23.675891+00:00
policy:
. quota: 0
. versioning: auto
quota: 0
versioning: auto
[file]:
Create some more pithos container to experiment with
......@@ -191,7 +192,7 @@ List contents of container `pithos`
type: plan-text/unicode
uuid: 0493f1d9-9410-4f4b-a81f-fe42f9cefa70
version: 1085
.
video
by: s0m3-u53r-1d
bytes: 0
......@@ -201,7 +202,7 @@ List contents of container `pithos`
type: application/directory
uuid: 80e719f5-9d68-4333-9846-9943972ef1fd
version: 1086
.
video/tk1.mpg
by: s0m3-u53r-1d
bytes: 11000000 (11ΜΒB)
......@@ -211,7 +212,7 @@ List contents of container `pithos`
type: video/mpeg
uuid: b0b46b39-c59a-4adc-a386-6a169cb9f8a5
version: 1079
.
video/tk2.mpg
by: s0m3-u53r-1d
bytes: 12000000 (12MB)
......@@ -221,7 +222,7 @@ List contents of container `pithos`
type: video/mpeg
uuid: 12a81309-db3c-4e30-ae9a-4ac2b8289def
version: 1081
.
video/tk3.mpg
by: s0m3-u53r-1d
bytes: 13000000 (13MB)
......@@ -247,7 +248,7 @@ List only objects starting with "video" and exit "file" context
type: video/mpeg
uuid: b0b46b39-c59a-4adc-a386-6a169cb9f8a5
version: 1079
.
video/tk2.mpg
by: s0m3-u53r-1d
bytes: 12000000 (12MB)
......@@ -257,7 +258,7 @@ List only objects starting with "video" and exit "file" context
type: video/mpeg
uuid: 12a81309-db3c-4e30-ae9a-4ac2b8289def
version: 1081
.
video/tk3.mpg
by: s0m3-u53r-1d
bytes: 13000000 (13MB)
......@@ -358,7 +359,7 @@ Server details (first two only)
OS-EXT-IPS:type: fixed
addr: 192.168.12.4
version: 4
. . . . . . .
OS-EXT-IPS:type: fixed
addr: 2001:648:2ffc:1222:a800:2ff:fee3:49f1
version: 6
......@@ -383,7 +384,7 @@ Server details (first two only)
links:
href: https://example.com/compute/v2.0/flavors/1
rel: bookmark
. . . . . . .
href: https://example.com/compute/v2.0/flavors/1
rel: self
hostId:
......@@ -392,17 +393,17 @@ Server details (first two only)
links:
href: https://example.com/compute/v2.0/images/f1r57-1m4g3-1d
rel: bookmark
. . . . . . .
href: https://example.com/compute/v2.0/images/f1r57-1m4g3-1d
rel: self
. . . . . . .
href: https:/example.com/image/v1.0/images/f1r57-1m4g3-1d
rel: alternate
key_name: None
links:
href: https://example.com/compute/v2.0/servers/4201
rel: bookmark
. . . . . . .
href: https://example.com/compute/v2.0/servers/4201
rel: self
metadata:
......@@ -424,7 +425,7 @@ Server details (first two only)
OS-EXT-IPS:type: fixed
addr: 192.168.12.4
version: 4
. . . . . . .
OS-EXT-IPS:type: fixed
addr: 2002:648:2ffc:1222:a800:2ff:fee3:49f1
version: 6
......@@ -449,7 +450,7 @@ Server details (first two only)
links:
href: https://example.com/compute/v2.0/flavors/2
rel: bookmark
. . . . . . .
href: https://example.com/compute/v2.0/flavors/2
rel: self
hostId:
......@@ -458,17 +459,17 @@ Server details (first two only)
links:
href: https://example.com/compute/v2.0/images/53c0nd-1m4g3-1d
rel: bookmark
. . . . . . .
href: https://example.com/compute/v2.0/images/53c0nd-1m4g3-1d
rel: self
. . . . . . .
href: https:/example.com/image/v1.0/images/53c0nd-1m4g3-1d
rel: alternate
key_name: None
links:
href: https://example.com/compute/v2.0/servers/4202
rel: bookmark
. . . . . . .
href: https://example.com/compute/v2.0/servers/4202
rel: self
metadata:
......@@ -556,10 +557,10 @@ Detailed listing
links:
href: https://example.com/cyclades/compute/v2.0/images/f1r57-1m4g3-1d
rel: bookmark
. . . . . . .
href: https://example.com/cyclades/compute/v2.0/images/f1r57-1m4g3-1d
rel: self
. . . . . . .
href: https://example.com/cyclades/image/v1.0/images/f1r57-1m4g3-1d
rel: alternate
metadata:
......@@ -581,10 +582,10 @@ Detailed listing
links:
href: https://example.com/cyclades/compute/v2.0/images/53c0nd-1m4g3-1d
rel: bookmark
. . . . . . .
href: https://example.com/cyclades/compute/v2.0/images/53c0nd-1m4g3-1d
rel: self
. . . . . . .
href: https://example.com/cyclades/image/v1.0/images/53c0nd-1m4g3-1d
rel: alternate
metadata:
......
......@@ -3,8 +3,8 @@ Networks
Users can create private networks between Virtual Machines.
In the following we assume that there are two active VMs (ids 141 and 142)
connected to one public network with id 1 (default set up).
In the following we assume that there are two active virtual servers (ids 141
and 142) connected to one public network with id 1 (default set up).
.. code-block:: console
......@@ -24,8 +24,8 @@ connected to one public network with id 1 (default set up).
network_id: 1
$
.. note:: In Synnefo, each VM connects to a network through a NIC. The id of a
nic is nic-<server id>-<increment> by convention.
.. note:: In Synnefo, each virtual server connects to a network through a nic.
The id of a nic is *nic-<server id>-<increment>* by convention.
Let's load kamaki for networks and have a look at the current network state. We
expect to find at least one public network (id: 1)
......@@ -71,15 +71,16 @@ The new network will be named 'My Private Net'
user_id: s0m3-u53r-1d
[network]:
Let's create two more networks, one for VM 141 and one for Vm 142
Let's create two more networks, one for virtual server 141 and one for virtual
server 142
.. code-block:: console
[network]: create 'For VM 141'
[network]: create 'For virtual server 141'
...
id: 4
...
[network]: create 'For VM 142'
[network]: create 'For virtual server 142'
...
id: 5
...
......@@ -88,7 +89,8 @@ Let's create two more networks, one for VM 141 and one for Vm 142
Connect and disconnect
----------------------
To make a points, the networks should be connected to their respecting VMs
To make a point, the networks should be connected to their respecting virtual
servers
.. code-block:: console
......@@ -97,7 +99,7 @@ To make a points, the networks should be connected to their respecting VMs
[network]:
Now, let's check the current network state. We expect to see the servers
connected to netowkrd with ids 4 and 5, but not 3.
connected to networks with ids 4 and 5, but not 3.
.. code-block:: console
......@@ -133,7 +135,7 @@ connected to netowkrd with ids 4 and 5, but not 3.
type: MAC_FILTERED
updated: 2013-06-19T13:54:57.672744+00:00
user_id: s0m3-u53r-1d
4 For VM 141
4 For virtual server 141
attachments:
nic-141-1
cidr: 192.168.2.0/24
......@@ -148,7 +150,7 @@ connected to netowkrd with ids 4 and 5, but not 3.
type: MAC_FILTERED
updated: 2013-06-19T13:54:57.672744+00:00
user_id: s0m3-u53r-1d
5 For VM 142
5 For virtual server 142
attachments:
nic-141-2
cidr: 192.168.3.0/24
......@@ -165,7 +167,7 @@ connected to netowkrd with ids 4 and 5, but not 3.
user_id: s0m3-u53r-1d
[network]:
It is time to make meaningful connections: connect two servers to a private
It is time to make a meaningful connection: connect two servers to a private
network
.. code-block:: console
......@@ -174,7 +176,7 @@ network
[network]: connect 142 3
[network]:
Now the servers can communicate with eachother through their shared private
Now the servers can communicate with each other through their shared private
network. Let's see the network details to confirm that
.. code-block:: console
......@@ -213,7 +215,7 @@ Attempt to destroy the public network
.. warning:: Public networks cannot be destroyed in Synnefo
Attempt to destroy the useless `For VM 141` network
Attempt to destroy the useless `For virtual server 141` network
.. code-block:: console
......@@ -221,8 +223,8 @@ Attempt to destroy the useless `For VM 141` network
(403) Network with id 4 is in use
[network]:
The attached VMs should be disconnected first (recall that the nic-141-1
connects network with id 4 to VM with id 141)
The attached virtual servers should be disconnected first (recall that the
nic-141-1 connects network with id 4 to virtual server with id 141)
.. code-block:: console
......@@ -237,17 +239,17 @@ respective nics (nic-141-2, nic-142-2) first
[network]: disconnect nic-142-2
[network]: disconnect nic-141-2
(404) No nic nic-141-2 on server(VM) with id 141
| * check server(VM) with id 142: /server info 141
| * list nics for server(VM) with id 141:
(404) No nic nic-141-2 on server(virtual server) with id 141
| * check server(virtual server) with id 142: /server info 141
| * list nics for server(virtual server) with id 141:
| /server addr 141
| Network Interface nic-141-2 not found on server 141
[network]:
Strangely, kamaki did not find any nic-141-2 nics. Why?
Answer: A listing of the 141 nics shows that the network connection to network
with id 3 is now renamed as nic-141-1
Answer: Get the addresses of server 141 to find out that the nic which connects
the server to network 3 is automatically renamed (nic-141-2 --> nic-141-1)
.. code-block:: console
......@@ -266,8 +268,8 @@ with id 3 is now renamed as nic-141-1
network_id: 1
[network]:
.. warning:: Synnefo network server renames the nics of a VM whenever another
nic is of the same server is deleted
.. warning:: Synnefo network server may rename the nics of a virtual server if
another nic on the same server is deleted
Let's remove the correct nic, then, and check if any other nics are related to
the network with id 3.
......
......@@ -2,7 +2,7 @@ Creating Servers (Virtual Machines)
===================================
A `server` (also known as `virtual machine`), is created based on a registered
`image` and a reconfigured hardware setup (also known as `flavor`).
`image` and a preconfigured hardware setup (also known as `flavor`).
Create a virtual server
-----------------------
......@@ -50,7 +50,7 @@ List available images
[kamaki]:
Let's pick the `C1R128D1drbd` (id: 1) flavor and the `Debian Base Alpha` (id:
f1r57-1m4g3-1d) image to create a new VM called 'My First Server'
f1r57-1m4g3-1d) image to create a new virtual server called 'My First Server'
.. code-block:: console
......@@ -85,32 +85,32 @@ f1r57-1m4g3-1d) image to create a new VM called 'My First Server'
[kamaki]:
.. note:: The adminPass field is not stored anywhere, therefore users would
rather write it down and change it the first time they use the VM
rather write it down and change it the first time they use the virtual server
Wait for the VM with id 141 to build (optional)
Wait for the virtual server with id 141 to build (optional)
.. code-block:: console
[kamaki]: server wait 141
<bar showing build progress, until 100%>
Server 141 is not in ACTIVE mode
Server 141 is now in ACTIVE mode
[kamaki]:
Destroy the VM (wait is still optional)
Destroy the virtual server (wait is still optional)
.. code-block:: console
[kamaki]: server delete 141
[kamaki]: server wait 141 ACTIVE
<bar showing destruction progress, until 100%>
Server 141 is not in DELETED mode
Server 141 is now in DELETED mode
[kamaki]:
Inject ssh keys to a debian server
----------------------------------
Assume that the servers build from the image `Debian Base Alpha` accept ssh
connections. We need to build servers that can log us as roots without a
connections. We need to build servers that can log us as root without a
password. This can be achieved if the `/root/.ssh/authorized_keys` file exists
and contains the public key of the current user.
......@@ -119,7 +119,7 @@ Assume that the public key file of the current user is located at
`/root/.ssh/authorized_keys` while creating the virtual server.
Luckily, Synnefo fully supports the OpenStack suggestion for file injections on
VMs and kamaki allows it by using the **-p** argument (p stands for
virtual servers and kamaki allows it by using the **-p** argument (p stands for
`PERSONALITY` and is the term used in the
`respective OpenStack <http://docs.openstack.org/api/openstack-compute/2/content/CreateServers.html>`_ description).
......@@ -135,7 +135,7 @@ The syntax of the -p argument is something called "the personlity string"::
default behavior depends on the remote server, e.g. for a debian image we
expect the file to have root ownership, if the ownership is not specified.
Create a vm while injecting current users public key to root account
Create a virtual server while injecting current user public key to root account
.. code-block:: console
......@@ -170,14 +170,14 @@ Create a vm while injecting current users public key to root account
user_id: s0m3-u53r-1d
[server]:
When the VM is ready, get the VMs external IP from the web UI. Let's assume the
When the virtual server is ready, get the virtual servers external IP from the web UI. Let's assume the
IP is 123.456.78.90 .
.. code-block:: console
[server]: /exit
$ ssh 123.456.78.90
Linux remote-vm-4241 2.6.32-5-amd64 #1 SMP XXXX x86_64
Linux remote-virtual server-4241 2.6.32-5-amd64 #1 SMP XXXX x86_64
The programs included with the Debian GNU/Linux system are free software;