docs/source/ref/rest-api.rst

   1 ========
   2 REST API
   3 ========
   4
   5 Development of the RESTful API for GWM started as a Google Summer of
   6 Code 2011 project.
   7 The developer, Bojan Suzic, can be reached at bojan.suzic@gmail.com.
   8 The mentor for this project is Peter Krenesky.
   9
  10 The current version of the page describes its status as of ~end August
  11 2011. Currently it supports a fair amount of the underlying
  12 functionality.
  13
  14 Additionally, this page is intented as a development resource and
  15 documentation source for the project.
  16
  17 The project code can be reached at https://github.com/bsu/GWM2.
  18 The additional code (changes in other related modules) can be found at
  19 the following locations:
  20
  21 * https://github.com/bsu/django_obj_perm
  22 * https://github.com/bsu/django_obj_log.
  23
  24 Users and developers are encouraged to try this addon and send their
  25 suggestions/bug reports/improvements either directly to the author,
  26 using the `GWM mailing list <http://groups.google.com/group/ganeti-webmgr>`_ or
  27 `issue tracker <http://code.osuosl.org/projects/ganeti-webmgr/issues>`_.
  28 Please put the line ****[REST-API]**** in the subject if you are sending email
  29 message.
  30
  31 REST API for GWM can now be considered as a beta software. For the
  32 further development the following is proposed:
  33
  34 Roadmap:
  35
  36 * completion of unit tests
  37 * relocate parts of endpoints which may contain long answers - that
  38   variables should be accessed separately (such as object logs)
  39 * further refinement of the code and documentation
  40 * work on further integration (like cloud driver)
  41
  42 The **users/developers/visitors are advised to test** the code and **submit
  43 the comments/notices/wishes**. Comments can be submitted either directly
  44 to the author, here on this wiki or using the `Redmine ticket <http://code.osuosl.org/issues/3573>`_
  45
  46 The version containing significant changes to this version may be
  47 expected in **November 2011**.
  48
  49 About this documentation
  50 ------------------------
  51
  52 This documentation covers basic functionality of the REST API. It
  53 consists of the subsections, referring to particular endpoints forming
  54 the API. As an endpoints referred are application resources exposed as
  55 URIs through appropriate hierarchy. Currently, the system exposes the
  56 following resources as REST API endpoints: **User**,
  57 **Group**, **Virtual Machine**, **Cluster**,
  58 **Node**, **Job**. These are accessible in the form of
  59 CRUD operations using HTTP protocol.
  60
  61 By default, each API endpoint returns a list of resources.
  62
  63 For example::
  64
  65     /api/vm/
  66
  67 would return a list of Virtual Machines in the system, while the
  68 particular VM resource is accessed through::
  69
  70     /api/vm/1/
  71
  72 where 1 represents identifier of particular Virtual Machine. This way
  73 only that particular resource is returned.
  74 Each resource contains fields related to particular instance in the
  75 system. The field types and their properties are described further in
  76 the documentation, as a part of related subsections.
  77
  78 For each endpoint described is basic scheme of its resource
  79 representation. The scheme includes name, type and description of the
  80 particular fields, Additional properties described are  possibility for
  81 the field to be modified and whether the field returned may be excluded
  82 from the representation e.g. nullable. The later one might be useful for
  83 clients to prevent unexpected behavior.
  84
  85 While **type** field represents basic data types, it should be
  86 noted that **related** type points to other resource in the
  87 system. For example::
  88
  89     ...
  90     <cluster>
  91     ...
  92     <virtualmachine>
  93     /api/vm/5
  94     </virtualmachine>
  95     </cluster>
  96     ...
  97
  98 says that particular cluster resource includes virtualmachine
  99 resource, described by related URI. Therefore, if necessary, the
 100 complete resource referred at that point may be obtained through
 101 provided URI.
 102
 103 This documentation trends to provide as much as complete list of
 104 resources and their schematic description. However, due to the level of
 105 deepness and limitations of the current wiki system, in some cases this
 106 representation is simplified and explained in words rather than in
 107 tabular form. It should be noted that all these descriptions are already
 108 included in the system.
 109
 110 Using::
 111
 112     http://somesite.com/api/?format=xml
 113
 114 user is able to get the list of resources exposed, while with the help of::
 115
 116     http://somesite.com/api/resource/schema/?format=xml
 117
 118 the system returns detailed schema of resource representation and field
 119 properties in XML format. Therefore, the user is always able to take a
 120 look and check detailed description about a resource, if the one
 121 provided here in documentation is not detailed and clear enough.
 122
 123 Design principles
 124 -----------------
 125
 126 This API aims to expose the resources of Ganeti Web Manager, making
 127 suitable for integration into other systems or just performing of simple
 128 operations on resources. It does not aim to expose all resources and
 129 functions contained in the software, but only the set deemed necessary
 130 in order to support its business functions. Currently, it means that the
 131 most of the functionality present in the web interface is available for
 132 usage and manipulation also using this REST API.
 133
 134 Installation
 135 ------------
 136
 137 The most of the code of this addon comes under **/api**
 138 directory of GWM distribution. Other code changes are done in some of
 139 views and dependent modules (like **django_object_log** and
 140 **django_object_permissions**). Its inclusion in the GWM is
 141 done in **/urls.py** via::
 142
 143     urlpatterns = patterns('',
 144     ...
 145         (r'^', include('api.urls')),
 146     ...
 147
 148 The prerequisite for running RESTful API over Ganeti Web Manager is to
 149 have **django-tastypie** installed. The latest active
 150 version/commit of **tastypie** should be used in order to
 151 support **ApiKeys** based authentication. That means, as of
 152 time of writing this documentation, that **tastypie** should be
 153 installed manually. Additionally, the following line in
 154 **tastypie/authentication.py**::
 155
 156     username = request.GET.get('username') or request.POST.get('username')
 157
 158 should be changed to::
 159
 160     username = request.GET.get('username') or request.POST.get('username')
 161     or request.GET.get('user') or request.POST.get('user')
 162
 163 This is the known issue with **tastypie** already reported in
 164 its bug system. If not changed, the part **username** in
 165 **/api/user/?api_key=xxx&username=xxx** will produce error
 166 message during browsing the main user endpoint. This change makes
 167 **tastypie** to accept **user** for authentication
 168 instead of **username**. Later produces collision with the
 169 field of the same name under **User** model class.
 170
 171 The next change related to the installation of the module is inclusion
 172 of **'tastypie'** in **INSTALLED_APPS** of
 173 **settings.py**. This will produce necessary tables during
 174 installation/migration.
 175
 176 Development
 177 -----------
 178
 179 The code is prepared as a part of GSoC activities, and therefore by
 180 person not being a part of narrowed GWM development team before. As a
 181 such, the main principle to be followed is to try not to interfere too
 182 much with existing code. It implies further that the resulting code
 183 should be considered as an simple to install add-on. The core business
 184 logic of the GWM have not been changed or altered. The most changes done
 185 on GWM code are of technical nature, trying to make functions/views
 186 accessible to REST backend interface additionally. The code has been
 187 committed to separate repository. I tried mostly to perform smaller
 188 commits in size, in order to make the code and changes easily readable
 189 and trackable.
 190
 191 The framework used to introduce RESTful interface is **django-tastypie**.
 192 It has been selected after initial research and testing of several
 193 popular Python/Django/REST frameworks. The system supports both XML and
 194 JSON as input/output serializations.
 195
 196 Authentication and Authorization
 197 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 198
 199 The authentication is done using **API keys**. For each user
 200 the appropriate API key is generated automatically. The key can be
 201 renewed/recreated using **POST** request and appropriate action
 202 inside API. The access to the system looks like in the following
 203 example::
 204
 205     http://localhost:8000/api/?format=xml&api_key=381a5987a611fb1f8c68ffad49d2cd2b9f92db71&user=test
 206
 207 .. Note:: **username** initially supported by
 208           **tastypie** has been replaced with **user** in the
 209           example query above. The changes and reasons are described in the
 210           installation section of this document.
 211
 212 Authorization is completely dependent on Django's authorization system.
 213 The existing views from the GWM have been used to expose the most of
 214 resources available. Those views are already integrated in Django's
 215 authorization system. Therefore, this API should not contain critical
 216 security flaws or problems and should be easier to maintenance.
 217
 218 REST API endpoints
 219 ------------------
 220
 221 /api/user
 222 ~~~~~~~~~
 223
 224 This endpoint exposes data and operations related to the user
 225 management.
 226 The following table provides the descriptions of the fields:
 227
 228 .. raw:: html
 229
 230         <table>
 231                 <tr>
 232                         <th>Name </th>
 233                         <th>Type </th>
 234                         <th>ReadOnly </th>
 235                         <th>Nullable </th>
 236                         <th>Description </th>
 237                 </tr>
 238                 <tr>
 239                         <td><code>username</code></td>
 240                         <td><code>string</code></td>
 241                         <td> </td>
 242                         <td> </td>
 243                         <td>Required. 30 characters or fewer. Letters, numbers and @/./+/-/_ characters</td>
 244                 </tr>
 245                 <tr>
 246                         <td><code>ssh_keys</code></td>
 247                         <td><code>list</code></td>
 248                         <td> </td>
 249                         <td style="text-align:center;">x</td>
 250                         <td>SSH keys for user's account. The list may be composed of several objects.</td>
 251                 </tr>
 252                 <tr>
 253                         <td><code>first_name</code></td>
 254                         <td><code>string</code></td>
 255                         <td> </td>
 256                         <td> </td>
 257                         <td>Unicode string data. Ex: "Hello World"</td>
 258                 </tr>
 259                 <tr>
 260                         <td><code>last_name</code></td>
 261                         <td><code>string</code></td>
 262                         <td> </td>
 263                         <td> </td>
 264                         <td>Unicode string data. Ex: "Hello World"</td>
 265                 </tr>
 266                 <tr>
 267                         <td><code>actions_on_user</code></td>
 268                         <td><code>list</code></td>
 269                         <td style="text-align:center;">x</td>
 270                         <td style="text-align:center;">x</td>
 271                         <td>Returns the actions done on the user. The list is composed of objects, containing elements as described here.</td>
 272                 </tr>
 273                 <tr>
 274                         <td><code>groups</code></td>
 275                         <td><code>related</code></td>
 276                         <td style="text-align:center;">x</td>
 277                         <td style="text-align:center;">x</td>
 278                         <td>Returns the groups the user is member of</td>
 279                 </tr>
 280                 <tr>
 281                         <td><code>api_key</code></td>
 282                         <td><code>string</code></td>
 283                         <td style="text-align:center;">x</td>
 284                         <td style="text-align:center;">x</td>
 285                         <td>Returns the api key of the user</td>
 286                 </tr>
 287                 <tr>
 288                         <td><code>used_resources</code></td>
 289                         <td><code>list</code></td>
 290                         <td style="text-align:center;">x</td>
 291                         <td style="text-align:center;">x</td>
 292                         <td>Returns the resources used by the objects user has access to in the form of the list.</td>
 293                 </tr>
 294                 <tr>
 295                         <td><code>is_active</code></td>
 296                         <td><code>boolean</code></td>
 297                         <td> </td>
 298                         <td> </td>
 299                         <td>Designates whether this user should be treated as active. Unselect this instead of deleting accounts.</td>
 300                 </tr>
 301                 <tr>
 302                         <td><code>id</code></td>
 303                         <td><code>string</code></td>
 304                         <td style="text-align:center;">x</td>
 305                         <td> </td>
 306                         <td>Unicode string data. Ex: "Hello World"</td>
 307                 </tr>
 308                 <tr>
 309                         <td><code>is_superuser</code></td>
 310                         <td><code>boolean</code></td>
 311                         <td> </td>
 312                         <td> </td>
 313                         <td>Designates that this user has all permissions without explicitly assigning them.</td>
 314                 </tr>
 315                 <tr>
 316                         <td><code>is_staff</code></td>
 317                         <td><code>boolean</code></td>
 318                         <td> </td>
 319                         <td> </td>
 320                         <td>Designates whether the user can log into this admin site.</td>
 321                 </tr>
 322                 <tr>
 323                         <td><code>last_login</code></td>
 324                         <td><code>datetime</code></td>
 325                         <td> </td>
 326                         <td> </td>
 327                         <td>A date &#38; time as a string. Ex: "2010-11-10T03:07:43"</td>
 328                 </tr>
 329                 <tr>
 330                         <td><code>date_joined</code></td>
 331                         <td><code>datetime</code></td>
 332                         <td> </td>
 333                         <td> </td>
 334                         <td>A date &#38; time as a string. Ex: "2010-11-10T03:07:43"</td>
 335                 </tr>
 336                 <tr>
 337                         <td><code>user_actions</code></td>
 338                         <td><code>list</code></td>
 339                         <td style="text-align:center;">x</td>
 340                         <td> </td>
 341                         <td>Returns the actions done by the user. The list is composed of objects, containing elements as described here.</td>
 342                 </tr>
 343                 <tr>
 344                         <td><code>permissions</code></td>
 345                         <td><code>list</code></td>
 346                         <td style="text-align:center;">x</td>
 347                         <td style="text-align:center;">x</td>
 348                         <td>Returns the status of users permissions on different families of objects</td>
 349                 </tr>
 350                 <tr>
 351                         <td><code>password</code></td>
 352                         <td><code>string</code></td>
 353                         <td> </td>
 354                         <td> </td>
 355                         <td>Returns hashed password</td>
 356                 </tr>
 357                 <tr>
 358                         <td><code>email</code></td>
 359                         <td><code>string</code></td>
 360                         <td> </td>
 361                         <td> </td>
 362                         <td>Unicode string data. Ex: "Hello World"</td>
 363                 </tr>
 364                 <tr>
 365                         <td><code>resource_uri</code></td>
 366                         <td><code>string</code></td>
 367                         <td style="text-align:center;">x</td>
 368                         <td> </td>
 369                         <td>Unicode string data. Ex: "Hello World"</td>
 370                 </tr>
 371         </table>
 372
 373 Explanations for particular list elements
 374 '''''''''''''''''''''''''''''''''''''''''
 375
 376 **Container: ssh_keys**
 377
 378 The elements of the list are denoted as **value** nodes,
 379 containing paricular ssh key for the user in the form of **string
 380 hash**
 381
 382 Example::
 383
 384     <ssh_keys type="list">
 385     <object type="hash">
 386     <id type="integer">1</id>
 387     <key>ssh-rsa
 388     A398kuwNzaC1yc2EAAAADAQABAAABAQDI2oqyrleSvAg4CV5A/4ZZ2fTEFAYU1W2i8373zspaJCSO0eHIl+v4fGeIzH7CFokbM98ip2mwe7KtFk2VoO1
 389     /E9ucXR4xcxo77sxGSGH8hiS89aUcHmPKyRYlYj5TwqkZopxYTFmeUhkhP9e5YrlTRXMdhMsIXqXAKRujjySycQ45QLqdYOHbfohU0aKtDN01bYFOQ7/y/9wepXczlXD7rTIhT6
 390     /aq2vvOoyiGo9vaiIfqbtLjqkjwecDGykesw1c9d07vH53myiLLLkAGGk4KudKSWV6ZxK0ap3/olzzJ3HZpk5MAel5ELX6XuT8VmA3H3Yl5N//DrBUmKciMIaRx
 391     xxx@gmail.com
 392     </key>
 393     </object>
 394     <object>
 395     <id type="integer">2</id>
 396     <key>ssh-rsa
 397     7398kuwNzaC1yc2EAAAADAQABAAABAQDI2oqyrleSvAg4CVjskajslajwFAYU1W2i8373zspaJCSO0eHIl+v4fGeIzH7CFokbM98ip2mwe7KtFk2VoO1
 398     /E9ucXR4xcxo77sxGSGH8hiS89aUcHmPKyRYlYj5TwqkZopxYTFmeUhkhP9e5YrlTRXMdhMsIXqXAKRujjySycQ45QLqdYOHbfohU0aKtDN01bYFOQ7/y/9wepXczlXD7rTIhT6
 399     /aq2vvOoyiGo9vaiIfqbtLjqkjwecDGykesw1c9d07vH53myiLLLkAGGk4KudKSWV6ZxK0ap3/olzzJ3HZpk5MAel5ELX6XuT8VmA3H3Yl5N//DrBUmKciMIYYY
 400     yyy@gmail.com
 401     </key>
 402     </object>
 403     </ssh_keys>
 404
 405 **Containers: user_actions and actions_on_users**
 406
 407 This is the list of **objects**, each object consisting of
 408 nullable fields denoted as **obj1, obj2, user, action_name**.
 409 The both containers share the representation. The difference between
 410 these is the fact that first describes actions performed by user, while
 411 the second one describes actions performed on user (by administrator,
 412 for instance).
 413 The both containers provide read only information.
 414
 415 .. raw:: html
 416
 417         <table>
 418                 <tr>
 419                         <th>Name </th>
 420                         <th>Type </th>
 421                         <th>Description </th>
 422                 </tr>
 423                 <tr>
 424                         <td><code>obj1</code>, <code>obj2</code> </td>
 425                         <td> <code>related</code> </td>
 426                         <td> Describe action object</td>
 427                 </tr>
 428                 <tr>
 429                         <td><code>timestamp</code> </td>
 430                         <td> <code>timestamp&gt;</code> </td>
 431                         <td> Date and time of action execution</td>
 432                 </tr>
 433                 <tr>
 434                         <td><code>user</code></td>
 435                         <td><code>related</code></td>
 436                         <td>User performing the action</td>
 437                 </tr>
 438                 <tr>
 439                         <td><code>action_name</code></td>
 440                         <td><code>string</code></td>
 441                         <td>Describes action name using internal descriptions</td>
 442                 </tr>
 443         </table>
 444
 445 Example::
 446
 447     <user_actions type="list">
 448     <object type="hash">
 449     <obj1>/api/vm/3/</obj1>
 450     <timestamp>2011-07-31T15:23:45.533479</timestamp>
 451     <obj2>/api/job/68/</obj2>
 452     <user>/api/user/2/</user>
 453     <action_name>VM_REBOOT</action_name>
 454     </object>
 455     <object type="hash">
 456     <obj1>/api/vm/3/</obj1>
 457     <timestamp>2011-07-31T17:04:02.333061</timestamp>
 458     <user>/api/user/2/</user>
 459     <action_name>EDIT</action_name>
 460     </object>
 461
 462 **Container used_resources**
 463
 464 This list consists of **object** elements, each containing
 465 **resource**, **object** and **type**.
 466 The field **object** represents related resource for which the
 467 system resources consumption is given. The **type** is
 468 **string** describing the object type using internal
 469 descriptions (like **VirtualMachine** for virtual machine).
 470 The **resource** contains subfields **virtual_cpus**,
 471 **disk** and **ram**, each of type
 472 **integer** and representing actual consumption of the
 473 particular system resource in system's default dimension (e.g. MBs for
 474 RAM consumption).
 475
 476 Example::
 477
 478     <used_resources type="list">
 479     <object type="hash">
 480     <resource type="hash">
 481     <virtual_cpus type="integer">0</virtual_cpus>
 482     <disk type="integer">0</disk>
 483     <ram type="integer">0</ram>
 484     </resource>
 485     <object>/api/vm/3/</object><
 486     type>VirtualMachine</type>
 487     </object>
 488     <object type="hash">
 489     <resource type="hash">
 490     <virtual_cpus type="integer">0</virtual_cpus>
 491     <disk type="integer">0</disk>
 492     <ram type="integer">0</ram></resource>
 493     <object>/api/vm/11/</object>
 494     <type>VirtualMachine</type>
 495     </object>
 496     </used_resources>
 497
 498 **Container permissions**
 499
 500 **Permissions** contains elements describing particular
 501 resource type, each further containing a list of resources. The primary
 502 **elements** are described as **Cluster**,
 503 **VirtualMachine**, **Group**. Their list member main
 504 nodes are described as **object**, containing
 505 **object** reference (related resource) for which the
 506 permissions are set, and the **permissions** list containing
 507 list of **values** as strings, describing permission type in
 508 internal format (like **create_vm**).
 509
 510 Example::
 511
 512     <permissions type="hash">
 513     <Cluster type="list"/>
 514     <Group type="list"/>
 515     <VirtualMachine type="list">
 516     <object type="hash">
 517     <object>/api/vm/3/</object>
 518     <permissions type="list">
 519     <value>admin</value>
 520     <value>power</value>
 521     <value>tags</value>
 522     </permissions>
 523     </object>
 524     <object type="hash">
 525     <object>/api/vm/11/</object>
 526     <permissions type="list">
 527     <value>admin</value>
 528     </permissions></object>
 529     </VirtualMachine>
 530     </permissions>
 531
 532
 533 Manipulation and operations using POST/PUT/DELETE methods
 534 '''''''''''''''''''''''''''''''''''''''''''''''''''''''''
 535
 536 The fields marked as non-readonly (table above) can be subject of
 537 further manipulation and operations. **The same applies to the rest of
 538 the document - those fields can be automatically updated or deleted by
 539 performing analog request.**
 540 In order to maintain consistency with REST approach, the
 541 **PUT** method is used on currently available resources with
 542 purpose to change or update them. On another side, **POST**
 543 method is used either to generate new resources, or to perform
 544 predefined actions on currently existing resources.
 545
 546 The following example demonstrates changing of users lastname and status
 547 in system (disabling its account).
 548 Request URI::
 549
 550     PUT /api/user/1/?api_key=xxxxx&username=yyyyy
 551
 552 Request header::
 553
 554     Content-Type: application/json
 555     Accept: application/json
 556
 557 Request payload::
 558
 559     {"last_name":"New LastName", "is_active":false}
 560
 561 Server response::
 562
 563     HTTP/1.1 204 NO CONTENT
 564     Date: Sat, 06 Aug 2011 11:18:25 GMT
 565     Server: WSGIServer/0.1 Python/2.7.1+
 566     Vary: Accept-Language, Cookie
 567     Content-Length: 0
 568     Content-Type: text/html; charset=utf-8
 569     Content-Language: en
 570
 571 The next example demonstrates generating of new Api key for the user:
 572
 573 Request URI::
 574
 575     POST /api/user/2/?api_key=xxxxx&username=yyyyy
 576
 577 Request header::
 578
 579     Content-Type: application/json
 580     Accept: application/xml
 581
 582 Request payload::
 583
 584     {"action":"generate_api_key"}
 585
 586 Server response::
 587
 588     HTTP/1.1 201 CREATED
 589     Date: Sat, 06 Aug 2011 11:21:56 GMT
 590     Server: WSGIServer/0.1 Python/2.7.1+
 591     Vary: Accept-Language, Cookie
 592     Content-Type: text/html; charset=utf-8
 593     Content-Language: en
 594
 595 Response body::
 596
 597     <?xml version='1.0' encoding='utf-8'?>
 598     <object>
 599     <api_key>de0a57db0ce43d0f3c52f83eaf33387750ac9953</api_key>
 600     <userid>2</userid>
 601     </object>
 602
 603 For the API Key manipulation under **/api/user/** endpoint
 604 implemented are two POST actions: **generate_api_key**, as
 605 demonstrated in the example above, and **clean_api_key**.
 606 The former generates a new API key for the user and returns it in the
 607 response, while the later one cleans user's API key. This way its access
 608 to the system using REST API is disabled, but the standard access using
 609 web interface is untouch.
 610
 611 Additionally, two POST actions are implemented for user-group membership
 612 manipulation.
 613
 614 .. raw:: html
 615
 616         <table>
 617                 <tr>
 618                         <th>Action </th>
 619                         <th>Payload </th>
 620                         <th>Description </th>
 621                         <th>Example </th>
 622                 </tr>
 623                 <tr>
 624                         <td><code>add_to_group</code></td>
 625                         <td><code>group</code></td>
 626                         <td>Add the user to the group</td>
 627                         <td><pre>{'action':'add_to_group', 'group':'/api/group/1/'}</pre></td>
 628                 </tr>
 629                 <tr>
 630                         <td><code>remove_from_group</code></td>
 631                         <td><code>group</code></td>
 632                         <td>Remove the user from the group</td>
 633                         <td><pre>{'action':'remove_from_group', 'group':'/api/group/1/'}</pre></td>
 634                 </tr>
 635                 <tr>
 636                         <td><code>generate_api_key</code></td>
 637                         <td style="text-align:center;">-</td>
 638                         <td>Generate API key for the user </td>
 639                         <td><pre>{'action':'generate_api_key'}</pre></td>
 640                 </tr>
 641                 <tr>
 642                         <td><code>clean_api_key</code></td>
 643                         <td style="text-align:center;">-</td>
 644                         <td>Clean API key for the user </td>
 645                         <td><pre>{'action':'clean_api_key'}</pre></td>
 646                 </tr>
 647         </table>
 648
 649 /api/group
 650 ~~~~~~~~~~
 651
 652 This endpoint exposes data and operations related to the group
 653 management.
 654 The following table summarizes supported fields.
 655
 656 .. raw:: html
 657
 658         <table>
 659                 <tr>
 660                         <th>Name </th>
 661                         <th>Type </th>
 662                         <th>ReadOnly </th>
 663                         <th>Nullable </th>
 664                         <th>Description </th>
 665                 </tr>
 666                 <tr>
 667                         <td><code>actions_on_group</code></td>
 668                         <td><code>list</code></td>
 669                         <td style="text-align:center;">x</td>
 670                         <td> </td>
 671                         <td>Returns the actions done on the group. The list is composed of objects, containing elements as described here.</td>
 672                 </tr>
 673                 <tr>
 674                         <td><code>users</code></td>
 675                         <td><code>related</code></td>
 676                         <td> </td>
 677                         <td style="text-align:center;">x</td>
 678                         <td>Returns a list of the users belonging to the group.</td>
 679                 </tr>
 680                 <tr>
 681                         <td><code>used_resources</code></td>
 682                         <td><code>list</code></td>
 683                         <td style="text-align:center;">x</td>
 684                         <td style="text-align:center;">x</td>
 685                         <td>Returns the resources used by the objects the group has access to in the form of the list.</td>
 686                 </tr>
 687                 <tr>
 688                         <td><code>permissions</code></td>
 689                         <td><code>list</code></td>
 690                         <td style="text-align:center;">x</td>
 691                         <td style="text-align:center;">x</td>
 692                         <td>Returns the status of users permissions on different families of objects</td>
 693                 </tr>
 694                 <tr>
 695                         <td><code>resource_uri</code></td>
 696                         <td><code>string</code></td>
 697                         <td style="text-align:center;">x</td>
 698                         <td> </td>
 699                         <td>Unicode string data. Ex: "Hello World"</td>
 700                 </tr>
 701                 <tr>
 702                         <td><code>id</code></td>
 703                         <td><code>string</code></td>
 704                         <td style="text-align:center;">x</td>
 705                         <td> </td>
 706                         <td>Unicode string data. Ex: "Hello World"</td>
 707                 </tr>
 708                 <tr>
 709                         <td><code>name</code></td>
 710                         <td><code>string</code></td>
 711                         <td> </td>
 712                         <td> </td>
 713                         <td>Unicode string data. Ex: "Hello World"</td>
 714                 </tr>
 715         </table>
 716
 717 **Container: actions_on_group**
 718
 719 This is the list of **objects**, each object consisting of
 720 nullable fields denoted as **obj1, obj2, user, action_name**.
 721 This container describes actions performed on the group (by
 722 administrator, for instance) in the form of read-only information.
 723 Please note that inclusion od **obj1** and **obj2**
 724 depends on the action type, e.g. one of these may be omitted.
 725
 726 .. raw:: html
 727
 728         <table>
 729                 <tr>
 730                         <th>Name </th>
 731                         <th>Type </th>
 732                         <th>Description </th>
 733                 </tr>
 734                 <tr>
 735                         <td><code>obj1</code>, <code>obj2</code> </td>
 736                         <td> <code>related</code> </td>
 737                         <td> Describe action object</td>
 738                 </tr>
 739                 <tr>
 740                         <td><code>timestamp</code> </td>
 741                         <td> <code>timestamp&gt;</code> </td>
 742                         <td> Date and time of action execution</td>
 743                 </tr>
 744                 <tr>
 745                         <td><code>user</code></td>
 746                         <td><code>related</code></td>
 747                         <td>User performing the action</td>
 748                 </tr>
 749                 <tr>
 750                         <td><code>action_name</code></td>
 751                         <td><code>string</code></td>
 752                         <td>Describes action name using internal descriptions</td>
 753                 </tr>
 754         </table>
 755
 756 Example::
 757
 758     <actions_on_group type="list">
 759     <object type="hash">
 760     <obj1>/api/group/1/</obj1>
 761     <timestamp>2011-07-29T08:28:24.566903</timestamp>
 762     <user>/api/user/1/</user>
 763     <action_name>CREATE</action_name>
 764     </object>
 765     <object type="hash">
 766     <obj1>/api/cluster/1/</obj1>
 767     <timestamp>2011-07-29T08:28:59.854791</timestamp>
 768     <obj2>/api/group/1/</obj2>
 769     <user>/api/user/1/</user>
 770     <action_name>ADD_USER</action_name>
 771     </object>
 772     </actions_on_group>
 773
 774 **Field: users**
 775
 776 This simple field contains a list of users belonging to the group. The
 777 type of the resource is **related**, which means that it points
 778 to the URI representing the resource. Example::
 779
 780     <users type="list">
 781     <value>/api/user/2/</value>
 782     <value>/api/user/3/</value>
 783     </users>
 784
 785 **Container used_resources**
 786
 787 The syntax used here is the same as used in the <object>User</object>
 788 resource. For more information and example, please refer to the user
 789 section of this document.
 790
 791 **Container permissions**
 792
 793 The syntax used here is the same as used in the <object>User</object>
 794 resource. For more information and example, please refer to the user
 795 section of this document.
 796
 797
 798 Manipulation actions
 799 ''''''''''''''''''''
 800
 801 .. raw:: html
 802
 803         <table>
 804                 <tr>
 805                         <th>Action </th>
 806                         <th>Payload </th>
 807                         <th>Description </th>
 808                         <th>Example </th>
 809                 </tr>
 810                 <tr>
 811                         <td><code>add_user</code></td>
 812                         <td><code>user</code></td>
 813                         <td>Add the user to the group</td>
 814                         <td><pre>{'action':'add_user', 'user':'/api/user/2/'}</pre></td>
 815                 </tr>
 816                 <tr>
 817                         <td><code>remove_user</code></td>
 818                         <td><code>user</code></td>
 819                         <td>Remove the user from the group</td>
 820                         <td><pre>{'action':'remove_user', 'user':'/api/user/2/'}</pre></td>
 821                 </tr>
 822         </table>
 823
 824 /api/vm
 825 ~~~~~~~
 826
 827 This endpoint exposes methods for VirtualMachine inspection and
 828 manipulation.
 829
 830 **Important**: as the attributes exposing VM object are related to many
 831 other objects and many calls are done on different views, here the
 832 somewhat different approach to attribute exposure is used. At the main
 833 point **/api/vm/**, which provides a list of virtual machines,
 834 only the basic attributes of VM are provided. However, when the
 835 particular object is called, sad **/api/vm/3/**, the system
 836 returns additional set of its attributes. This is due to need to perform
 837 additional calls which introduce network latency. Performing all those
 838 calls at once for all virtual machines could produce unnecessary
 839 overhead.
 840
 841 Fields exposed (main endpoint):
 842
 843 .. raw:: html
 844
 845         <table>
 846                 <tr>
 847                         <th>Name </th>
 848                         <th>Type </th>
 849                         <th>ReadOnly </th>
 850                         <th>Nullable </th>
 851                         <th>Description </th>
 852                 </tr>
 853                 <tr>
 854                         <td><code>pending_delete</code></td>
 855                         <td><code>boolean</code></td>
 856                         <td> </td>
 857                         <td> </td>
 858                         <td>Boolean data. Ex: True</td>
 859                 </tr>
 860                 <tr>
 861                         <td><code>ram</code></td>
 862                         <td><code>integer</code></td>
 863                         <td> </td>
 864                         <td> </td>
 865                         <td>Integer data. Ex: 2673</td>
 866                 </tr>
 867                 <tr>
 868                         <td><code>cluster</code></td>
 869                         <td><code>related</code></td>
 870                         <td> </td>
 871                         <td style="text-align:center;">x</td>
 872                         <td>A single related resource. Can be either a URI or set of nested resource data.</td>
 873                 </tr>
 874                 <tr>
 875                         <td><code>last_job</code></td>
 876                         <td><code>related</code></td>
 877                         <td> </td>
 878                         <td style="text-align:center;">x</td>
 879                         <td>A single related resource. Can be either a URI or set of nested resource data.</td>
 880                 </tr>
 881                 <tr>
 882                         <td><code>virtual_cpus</code></td>
 883                         <td><code>integer</code></td>
 884                         <td> </td>
 885                         <td> </td>
 886                         <td>Integer data. Ex: 2673</td>
 887                 </tr>
 888                 <tr>
 889                         <td><code>id</code></td>
 890                         <td><code>string</code></td>
 891                         <td> </td>
 892                         <td> </td>
 893                         <td>Unicode string data. Ex: "Hello World"</td>
 894                 </tr>
 895                 <tr>
 896                         <td><code>hostname</code></td>
 897                         <td><code>string</code></td>
 898                         <td> </td>
 899                         <td> </td>
 900                         <td>Unicode string data. Ex: "Hello World"</td>
 901                 </tr>
 902                 <tr>
 903                         <td><code>status</code></td>
 904                         <td><code>string</code></td>
 905                         <td> </td>
 906                         <td> </td>
 907                         <td>Unicode string data. Ex: "Hello World"</td>
 908                 </tr>
 909                 <tr>
 910                         <td><code>secondary_node</code></td>
 911                         <td><code>related</code></td>
 912                         <td> </td>
 913                         <td style="text-align:center;">x</td>
 914                         <td>A single related resource. Can be either a URI or set of nested resource data.</td>
 915                 </tr>
 916                 <tr>
 917                         <td><code>operating_system</code></td>
 918                         <td><code>string</code></td>
 919                         <td> </td>
 920                         <td> </td>
 921                         <td>Unicode string data. Ex: "Hello World"</td>
 922                 </tr>
 923                 <tr>
 924                         <td><code>disk_size</code></td>
 925                         <td><code>integer</code></td>
 926                         <td> </td>
 927                         <td> </td>
 928                         <td>Integer data. Ex: 2673</td>
 929                 </tr>
 930                 <tr>
 931                         <td><code>primary_node</code></td>
 932                         <td><code>related</code></td>
 933                         <td> </td>
 934                         <td style="text-align:center;">x</td>
 935                         <td>A single related resource. Can be either a URI or set of nested resource data.</td>
 936                 </tr>
 937                 <tr>
 938                         <td><code>resource_uri</code></td>
 939                         <td><code>string</code></td>
 940                         <td> </td>
 941                         <td> </td>
 942                         <td>Unicode string data. Ex: "Hello World"</td>
 943                 </tr>
 944         </table>
 945
 946 Fields exposed (additionally, particular object):
 947
 948 .. raw:: html
 949
 950         <table>
 951                 <tr>
 952                         <th>Name </th>
 953                         <th>Type </th>
 954                         <th>ReadOnly </th>
 955                         <th>Nullable </th>
 956                         <th>Description </th>
 957                 </tr>
 958                 <tr>
 959                         <td><code>cluster_admin</code></td>
 960                         <td><code>Boolean</code></td>
 961                         <td style="text-align:center;">x</td>
 962                         <td> </td>
 963                         <td>Determines if the current user has admin permissions over cluster.</td>
 964                 </tr>
 965                 <tr>
 966                         <td><code>power</code></td>
 967                         <td><code>Boolean</code></td>
 968                         <td style="text-align:center;">x</td>
 969                         <td> </td>
 970                         <td>Determines if the current user has admin permissions to power vm.</td>
 971                 </tr>
 972                 <tr>
 973                         <td><code>modify</code></td>
 974                         <td><code>Boolean</code></td>
 975                         <td style="text-align:center;">x</td>
 976                         <td> </td>
 977                         <td>Determines if the current user has admin permissions to modify vm.</td>
 978                 </tr>
 979                 <tr>
 980                         <td><code>job</code></td>
 981                         <td><code>Boolean</code></td>
 982                         <td style="text-align:center;">x</td>
 983                         <td style="text-align:center;">x</td>
 984                         <td>Points to the jobs related to the vm, if any.</td>
 985                 </tr>
 986                 <tr>
 987                         <td><code>actions_on_vm</code></td>
 988                         <td><code>list</code></td>
 989                         <td style="text-align:center;">x</td>
 990                         <td style="text-align:center;">x</td>
 991                         <td>Returns the actions done on the user. The list is composed of objects, containing elements as described here.</td>
 992                 </tr>
 993                 <tr>
 994                         <td><code>permissions</code></td>
 995                         <td><code>list</code></td>
 996                         <td style="text-align:center;">x</td>
 997                         <td> </td>
 998                         <td>Lists the objects (users and groups) having permissions over vm. Contains sublists users and groups, each having objects pointing to related user/group.</td>
 999                 </tr>
1000                 <tr>
1001                         <td><code>admin</code></td>
1002                         <td><code>Boolean</code></td>
1003                         <td style="text-align:center;">x</td>
1004                         <td> </td>
1005                         <td>Determines if the current user has admin permissions over vm.</td>
1006                 </tr>
1007                 <tr>
1008                         <td><code>remove</code></td>
1009                         <td><code>Boolean</code></td>
1010                         <td style="text-align:center;">x</td>
1011                         <td> </td>
1012                         <td>Determines if the current user has permissions to remove vm.</td>
1013                 </tr>
1014                 <tr>
1015                         <td><code>migrate</code></td>
1016                         <td><code>Boolean</code></td>
1017                         <td style="text-align:center;">x</td>
1018                         <td> </td>
1019                         <td>Determines if the current user has admin permissions to migrate.</td>
1020                 </tr>
1021         </table>
1022
1023 **Containers: actions_on_vm and permissions**
1024
1025 The format and members of those lists are similar to previous mentioned
1026 fields, e.g. in **cluster** endpoint. For detailed description,
1027 please refer to those.
1028
1029 The field **actions_on_vm** contains object(s) taking part in
1030 action, user initiated the action, timestamp and the internal
1031 description of the action in form of the string. The field
1032 **permissions>** lists users and groups (as related fields)
1033 which have any form of permissions on virtual machine.
1034
1035 **Operations supported**
1036
1037 Operations on VM are accomplished in form of action. Action is initiated
1038 using POST request.
1039 Example::
1040
1041     POST /api/vm/7
1042     {"action":"shutdown"}
1043
1044 In this example, user initiates @POST@ request on Virtual Machine
1045 described with @id=7@. The action type is described in field @action@ in
1046 request header.
1047
1048 After the action is initiated, server sends back response.
1049 Example:
1050
1051 Header::
1052
1053     HTTP/1.1 200 OK
1054     Date: Wed, 27 Jul 2011 18:39:31 GMT
1055     Server: WSGIServer/0.1 Python/2.7.1+
1056     Vary: Accept-Language, Cookie
1057     Content-Type: application/json
1058     Content-Language: en
1059
1060 Body::
1061
1062     {"end_ts": null, "id": "138722", "oplog": [[]], "opresult": [null],
1063     "ops": [{"OP_ID": "OP_INSTANCE_SHUTDOWN", "debug_level": 0, "dry_run":
1064     false, "ignore_offline_nodes": false, "instance_name":
1065     "ooga.osuosl.org", "priority": 0, "timeout": 120}], "opstatus":
1066     ["running"], "received_ts": [1311791966, 837045], "start_ts":
1067     [1311791966, 870332], "status": "running", "summary":
1068     ["INSTANCE_SHUTDOWN(ooga.osuosl.org)"]}
1069
1070 The following actions and parameters are supported:
1071
1072 .. raw:: html
1073
1074         <table>
1075                 <tr>
1076                         <td>Action</td>
1077                         <td>Parameters</td>
1078                         <td>Description</td>
1079                 </tr>
1080                 <tr>
1081                         <td>reboot</td>
1082                         <td></td>
1083                         <td>Reboot VM</td>
1084                 </tr>
1085                 <tr>
1086                         <td>shutdown</td>
1087                         <td></td>
1088                         <td>Shutdown VM</td>
1089                 </tr>
1090                 <tr>
1091                         <td>startup</td>
1092                         <td></td>
1093                         <td>Start VM up</td>
1094                 </tr>
1095                 <tr>
1096                         <td>rename</td>
1097                         <td>hostname,ip_check,name_check</td>
1098                         <td>Rename VM</td>
1099                 </tr>
1100         </table>
1101
1102 /api/cluster
1103 ~~~~~~~~~~~~
1104
1105 This endpoint describes fields and operations available for the Cluster.
1106
1107 .. raw:: html
1108
1109     <table>
1110                 <tr>
1111                         <th>Name </th>
1112                         <th>Type </th>
1113                         <th>ReadOnly </th>
1114                         <th>Nullable </th>
1115                         <th>Description </th>
1116                 </tr>
1117                 <tr>
1118                         <td><code>ram</code></td>
1119                         <td><code>integer</code></td>
1120                         <td> </td>
1121                         <td style="text-align:center;">x</td>
1122                         <td>Integer data. Ex: 2673</td>
1123                 </tr>
1124                 <tr>
1125                         <td><code>nodes_count</code></td>
1126                         <td><code>Integer</code></td>
1127                         <td style="text-align:center;">x</td>
1128                         <td style="text-align:center;">x</td>
1129                         <td>Returns nodes count for the cluster.</td>
1130                 </tr>
1131                 <tr>
1132                         <td><code>default_hypervisor</code></td>
1133                         <td><code>string</code></td>
1134                         <td style="text-align:center;">x</td>
1135                         <td> </td>
1136                         <td>Returns a default hypervisor for the cluster.</td>
1137                 </tr>
1138                 <tr>
1139                         <td><code>virtual_cpus</code></td>
1140                         <td><code>integer</code></td>
1141                         <td> </td>
1142                         <td style="text-align:center;">x</td>
1143                         <td>Integer data. Ex: 2673</td>
1144                 </tr>
1145                 <tr>
1146                         <td><code>disk</code></td>
1147                         <td><code>integer</code></td>
1148                         <td> </td>
1149                         <td style="text-align:center;">x</td>
1150                         <td>Integer data. Ex: 2673</td>
1151                 </tr>
1152                 <tr>
1153                         <td><code>port</code></td>
1154                         <td><code>integer</code></td>
1155                         <td> </td>
1156                         <td> </td>
1157                         <td>Integer data. Ex: 2673</td>
1158                 </tr>
1159                 <tr>
1160                         <td><code>hostname</code></td>
1161                         <td><code>string</code></td>
1162                         <td> </td>
1163                         <td> </td>
1164                         <td>Unicode string data. Ex: "Hello World"</td>
1165                 </tr>
1166                 <tr>
1167                         <td><code>id</code></td>
1168                         <td><code>string</code></td>
1169                         <td> </td>
1170                         <td> </td>
1171                         <td>Unicode string data. Ex: "Hello World"</td>
1172                 </tr>
1173                 <tr>
1174                         <td><code>available_ram</code></td>
1175                         <td><code>list</code></td>
1176                         <td style="text-align:center;">x</td>
1177                         <td style="text-align:center;">x</td>
1178                         <td>Returns a list with elements describing RAM status, including total, allocated, used and free memory.</td>
1179                 </tr>
1180                 <tr>
1181                         <td><code>master</code></td>
1182                         <td><code>string</code></td>
1183                         <td style="text-align:center;">x</td>
1184                         <td> </td>
1185                         <td>Returns master node</td>
1186                 </tr>
1187                 <tr>
1188                         <td><code>missing_ganeti</code></td>
1189                         <td><code>list</code></td>
1190                         <td style="text-align:center;">x</td>
1191                         <td style="text-align:center;">x</td>
1192                         <td>Returns a list with names of missing nodes in ganeti.</td>
1193                 </tr>
1194                 <tr>
1195                         <td><code>username</code></td>
1196                         <td><code>string</code></td>
1197                         <td> </td>
1198                         <td style="text-align:center;">x</td>
1199                         <td>Unicode string data. Ex: "Hello World"</td>
1200                 </tr>
1201                 <tr>
1202                         <td><code>missing_db</code></td>
1203                         <td><code>list</code></td>
1204                         <td style="text-align:center;">x</td>
1205                         <td style="text-align:center;">x</td>
1206                         <td>Returns a list with names of missing nodes in DB.</td>
1207                 </tr>
1208                 <tr>
1209                         <td><code>description</code></td>
1210                         <td><code>string</code></td>
1211                         <td> </td>
1212                         <td style="text-align:center;">x</td>
1213                         <td>Unicode string data. Ex: "Hello World"</td>
1214                 </tr>
1215                 <tr>
1216                         <td><code>software_version</code></td>
1217                         <td><code>string</code></td>
1218                         <td style="text-align:center;">x</td>
1219                         <td> </td>
1220                         <td>Returns a software version.</td>
1221                 </tr>
1222                 <tr>
1223                         <td><code>quota</code></td>
1224                         <td><code>list</code></td>
1225                         <td style="text-align:center;">x</td>
1226                         <td style="text-align:center;">x</td>
1227                         <td>Returns a list containing objects describing quotas for the user performing the request.</td>
1228                 </tr>
1229                 <tr>
1230                         <td><code>slug</code></td>
1231                         <td><code>string</code></td>
1232                         <td> </td>
1233                         <td> </td>
1234                         <td>Unicode string data. Ex: "Hello World"</td>
1235                 </tr>
1236                 <tr>
1237                         <td><code>info</code></td>
1238                         <td><code>list</code></td>
1239                         <td style="text-align:center;">x</td>
1240                         <td style="text-align:center;">x</td>
1241                         <td>Complex container exposing many information related to the cluster. More details with example can be found in documentation/wiki.</td>
1242                 </tr>
1243                 <tr>
1244                         <td><code>available_disk</code></td>
1245                         <td><code>list</code></td>
1246                         <td style="text-align:center;">x</td>
1247                         <td style="text-align:center;">x</td>
1248                         <td>Returns a list with elements describing disk status, including total, allocated, used and free disk space.</td>
1249                 </tr>
1250                 <tr>
1251                         <td><code>default_quota</code></td>
1252                         <td><code>list</code></td>
1253                         <td style="text-align:center;">x</td>
1254                         <td style="text-align:center;">x</td>
1255                         <td>Returns a list containing objects describing default quotas.</td>
1256                 </tr>
1257                 <tr>
1258                         <td><code>resource_uri</code></td>
1259                         <td><code>string</code></td>
1260                         <td> </td>
1261                         <td> </td>
1262                         <td>Unicode string data. Ex: "Hello World"</td>
1263                 </tr>
1264                 <tr>
1265                         <td><code>vm_count</code></td>
1266                         <td><code>Integer</code></td>
1267                         <td style="text-align:center;">x</td>
1268                         <td style="text-align:center;">x</td>
1269                         <td>Returns a number of virtual machines on the cluster.</td>
1270                 </tr>
1271         </table>
1272
1273 **Containers: available_ram and available_disk**
1274
1275 The first container provides information about status of the RAM in the
1276 cluster. Analogously, the second one provides information about disk
1277 space in the cluster.
1278
1279 .. raw:: html
1280
1281     <table>
1282                 <tr>
1283                         <th>Name </th>
1284                         <th>Type </th>
1285                         <th>Description </th>
1286                 </tr>
1287                 <tr>
1288                         <td><code>total</code> </td>
1289                         <td> <code>Integer</code> </td>
1290                         <td> Total RAM available to the cluster</td>
1291                 </tr>
1292                 <tr>
1293                         <td><code>allocated</code> </td>
1294                         <td> <code>Integer&gt;</code> </td>
1295                         <td> Allocated RAM</td>
1296                 </tr>
1297                 <tr>
1298                         <td><code>used</code></td>
1299                         <td><code>Integer</code></td>
1300                         <td>Amount of RAM used in the cluster</td>
1301                 </tr>
1302                 <tr>
1303                         <td><code>free</code></td>
1304                         <td><code>Integer</code></td>
1305                         <td>Free RAM</td>
1306                 </tr>
1307         </table>
1308
1309 Example::
1310
1311     <available_ram type="hash">
1312     <allocated type="integer">1024</allocated>
1313     <total type="integer">2004</total>
1314     <used type="integer">874</used>
1315     <free type="integer">980</free>
1316     </available_ram>
1317
1318 **Containers: missing_ganeti and missing_db**
1319
1320 Here the names of the missing machines are provided in the simple form.
1321 The former container describes machines missing in the Ganeti, while the
1322 former contains the machines missing in the database.
1323
1324 Example::
1325
1326     <missing_db type="list">
1327     <value>3429_test</value>
1328     <value>breakthis.gwm.osuosl.org</value>
1329     <value>brookjon.gwm.osuosl.org</value>
1330     <value>noinstall2.gwm.osuosl.org</value>
1331     </missing_db>
1332
1333 **Container: quota and default_quota**
1334
1335 This container returns the quotas for the user performing request. If
1336 the user is not found or do not have a quotas assigned, default quota is
1337 returned.
1338 If there are no values for the specific quota element, null is returned.
1339 Default_quota container is additionally returned for the case that quota
1340 for the user if found.
1341
1342 .. raw:: html
1343
1344     <table>
1345                 <tr>
1346                         <th>Name </th>
1347                         <th>Type </th>
1348                         <th>Description </th>
1349                 </tr>
1350                 <tr>
1351                         <td><code>default</code> </td>
1352                         <td> <code>Integer</code> </td>
1353                         <td> Used if default quota is returned</td>
1354                 </tr>
1355                 <tr>
1356                         <td><code>virtual_cpus</code> </td>
1357                         <td> <code>Integer</code> </td>
1358                         <td> Virtual CPUs</td>
1359                 </tr>
1360                 <tr>
1361                         <td><code>ram</code></td>
1362                         <td><code>Integer</code></td>
1363                         <td>Amount of RAM available to the user</td>
1364                 </tr>
1365                 <tr>
1366                         <td><code>disk</code></td>
1367                         <td><code>Integer</code></td>
1368                         <td>Amount of disk available to the user</td>
1369                 </tr>
1370         </table>
1371
1372 Example::
1373
1374     <quota type="hash">
1375     <default type="integer">1</default>
1376     <virtual_cpus type="null"/>
1377     <ram type="null"/>
1378     <disk type="null"/>
1379     </quota>
1380
1381 **Container: info**
1382
1383 This element provides extensive information related to the cluster.
1384 These information are used internally in Ganeti Web Manager to render
1385 specific pages. As of level of detail used, the field contained here
1386 will not be described but just provided in detail in example.
1387
1388 ::
1389
1390     <info type="hash">
1391     <default_iallocator/>
1392     <maintain_node_health type="boolean">False</maintain_node_health>
1393     <hvparams type="hash">
1394     <kvm type="hash">
1395     <nic_type>paravirtual</nic_type>
1396     <use_chroot type="boolean">False</use_chroot>
1397     <migration_port type="integer">8102</migration_port>
1398     <vnc_bind_address>0.0.0.0</vnc_bind_address>
1399     <cdrom2_image_path/>
1400     <usb_mouse/>
1401     <migration_downtime type="integer">30</migration_downtime>
1402     <floppy_image_path/>
1403     <kernel_args>ro</kernel_args>
1404     <cdrom_image_path/>
1405     <boot_order>disk</boot_order>
1406     <vhost_net type="boolean">False</vhost_net>
1407     <disk_cache>default</disk_cache>
1408     <kernel_path/>
1409     <initrd_path/>
1410     <vnc_x509_verify type="boolean">False</vnc_x509_verify>
1411     <vnc_tls type="boolean">False</vnc_tls>
1412     <cdrom_disk_type/>
1413     <use_localtime type="boolean">False</use_localtime>
1414     <security_domain/>
1415     <serial_console type="boolean">False</serial_console>
1416     <kvm_flag/>
1417     <vnc_password_file/>
1418     <migration_bandwidth type="integer">32</migration_bandwidth>
1419     <disk_type>paravirtual</disk_type>
1420     <migration_mode>live</migration_mode>
1421     <security_model>pool</security_model>
1422     <root_path>/dev/vda3</root_path>
1423     <vnc_x509_path/>
1424     <acpi type="boolean">True</acpi>
1425     <mem_path/>
1426     </kvm>
1427     </hvparams>
1428     <default_hypervisor>kvm</default_hypervisor>
1429     <uid_pool type="list">
1430     <objects>
1431     <value type="integer">8001</value>
1432     <value type="integer">8030</value>
1433     </objects>
1434     </uid_pool>
1435     <prealloc_wipe_disks type="boolean">False</prealloc_wipe_disks>
1436     <primary_ip_version type="integer">4</primary_ip_version>
1437     <mtime type="float">1308862451.98</mtime>
1438     <os_hvp type="hash"/>
1439     <osparams type="hash"/>
1440     <uuid>0b3b2432-a8e1-4c17-a99b-87303841cb95</uuid>
1441     <export_version type="integer">0</export_version>
1442     <hidden_os type="list"/>
1443     <master>gwm1.osuosl.org</master>
1444     <nicparams type="hash">
1445     <default type="hash">
1446     <link>br0</link>
1447     <mode>bridged</mode>
1448     </default>
1449     </nicparams>
1450     <protocol_version type="integer">2040000</protocol_version>
1451     <config_version type="integer">2040000</config_version>
1452     <software_version>2.4.2</software_version>
1453     <tags type="list"/>
1454     <os_api_version type="integer">20</os_api_version>
1455     <candidate_pool_size type="integer">10</candidate_pool_size>
1456     <file_storage_dir>/var/lib/ganeti-storage/file</file_storage_dir>
1457     <blacklisted_os type="list"/>
1458     <enabled_hypervisors type="list">
1459     <value>kvm</value>
1460     </enabled_hypervisors>
1461     <drbd_usermode_helper>/bin/true</drbd_usermode_helper>
1462     <reserved_lvs type="list"/>
1463     <ctime type="float">1292887189.41</ctime>
1464     <name>gwm.osuosl.org</name>
1465     <master_netdev>eth0</master_netdev>
1466     <ndparams type="hash">
1467     <oob_program type="null"/>
1468     </ndparams>
1469     <architecture type="list">
1470     <value>64bit</value>
1471     <value>x86_64</value>
1472     </architecture>
1473     <volume_group_name>ganeti</volume_group_name>
1474     <beparams type="hash">
1475     <default type="hash">
1476     <auto_balance type="boolean">True</auto_balance>
1477     <vcpus type="integer">2</vcpus>
1478     <memory type="integer">512</memory>
1479     </default>
1480     </beparams>
1481     </info>
1482
1483 /api/node
1484 ~~~~~~~~~
1485
1486 In this endpoint exposed are the attributes and operations on the
1487 Cluster.
1488
1489 .. raw:: html
1490
1491     <table>
1492                 <tr>
1493                         <th>Name </th>
1494                         <th>Type </th>
1495                         <th>ReadOnly </th>
1496                         <th>Nullable </th>
1497                         <th>Description </th>
1498                 </tr>
1499                 <tr>
1500                         <td><code>info</code></td>
1501                         <td><code>list</code></td>
1502                         <td style="text-align:center;">x</td>
1503                         <td> </td>
1504                         <td>This complex field returns various information related to the node.</td>
1505                 </tr>
1506                 <tr>
1507                         <td><code>ram_free</code></td>
1508                         <td><code>integer</code></td>
1509                         <td style="text-align:center;">x</td>
1510                         <td> </td>
1511                         <td>Integer data. Ex: 2673</td>
1512                 </tr>
1513                 <tr>
1514                         <td><code>Admin</code></td>
1515                         <td><code>boolean</code></td>
1516                         <td style="text-align:center;">x</td>
1517                         <td> </td>
1518                         <td>Determines if the user has admin status on the node</td>
1519                 </tr>
1520                 <tr>
1521                         <td><code>hostname</code></td>
1522                         <td><code>string</code></td>
1523                         <td style="text-align:center;">x</td>
1524                         <td> </td>
1525                         <td>Hostname of the node</td>
1526                 </tr>
1527                 <tr>
1528                         <td><code>modify</code></td>
1529                         <td><code>boolean</code></td>
1530                         <td style="text-align:center;">x</td>
1531                         <td> </td>
1532                         <td>Determines if the user is able to modify node parameters</td>
1533                 </tr>
1534                 <tr>
1535                         <td><code>cluster</code></td>
1536                         <td><code>related</code></td>
1537                         <td style="text-align:center;">x</td>
1538                         <td> </td>
1539                         <td>Cluster the node belongs to</td>
1540                 </tr>
1541                 <tr>
1542                         <td><code>disk_total</code></td>
1543                         <td><code>integer</code></td>
1544                         <td> </td>
1545                         <td> </td>
1546                         <td>Integer data. Ex: 2673</td>
1547                 </tr>
1548                 <tr>
1549                         <td><code>node_count</code></td>
1550                         <td><code>Integer</code></td>
1551                         <td style="text-align:center;">x</td>
1552                         <td> </td>
1553                         <td>Number of the nodes in the cluster</td>
1554                 </tr>
1555                 <tr>
1556                         <td><code>last_job</code></td>
1557                         <td><code>related</code></td>
1558                         <td> </td>
1559                         <td style="text-align:center;">x</td>
1560                         <td>A single related resource. Can be either a URI or set of nested resource data.</td>
1561                 </tr>
1562                 <tr>
1563                         <td><code>disk_free</code></td>
1564                         <td><code>integer</code></td>
1565                         <td style="text-align:center;">x</td>
1566                         <td> </td>
1567                         <td>Integer data. Ex: 2673</td>
1568                 </tr>
1569                 <tr>
1570                         <td><code>ram_total</code></td>
1571                         <td><code>integer</code></td>
1572                         <td style="text-align:center;">x</td>
1573                         <td> </td>
1574                         <td>Integer data. Ex: 2673</td>
1575                 </tr>
1576                 <tr>
1577                         <td><code>role</code></td>
1578                         <td><code>string</code></td>
1579                         <td style="text-align:center;">x</td>
1580                         <td> </td>
1581                         <td>Unicode string data. Ex: "Hello World"</td>
1582                 </tr>
1583                 <tr>
1584                         <td><code>offline</code></td>
1585                         <td><code>boolean</code></td>
1586                         <td style="text-align:center;">x</td>
1587                         <td> </td>
1588                         <td>Boolean data. Ex: True</td>
1589                 </tr>
1590                 <tr>
1591                         <td><code>id</code></td>
1592                         <td><code>string</code></td>
1593                         <td style="text-align:center;">x</td>
1594                         <td> </td>
1595                         <td>Unicode string data. Ex: "Hello World"</td>
1596                 </tr>
1597                 <tr>
1598                         <td><code>primary_list</code></td>
1599                         <td><code>list</code></td>
1600                         <td style="text-align:center;">x</td>
1601                         <td style="text-align:center;">x </td>
1602                         <td>List of virtual machines (primary node). Contains vm link (related) and hostname for particular object.</td>
1603                 </tr>
1604                 <tr>
1605                         <td><code>secondary_list</code></td>
1606                         <td><code>list</code></td>
1607                         <td style="text-align:center;">x</td>
1608                         <td style="text-align:center;">x </td>
1609                         <td>List of virtual machines (secondary node). Contains vm link (related) and hostname for particular object.</td>
1610                 </tr>
1611                 <tr>
1612                         <td><code>actions_on_node</code></td>
1613                         <td><code>list</code></td>
1614                         <td style="text-align:center;">x</td>
1615                         <td> </td>
1616                         <td>Returns the actions done on the node. The list is composed of objects, containing elements as described here.</td>
1617                 </tr>
1618                 <tr>
1619                         <td><code>resource_uri</code></td>
1620                         <td><code>string</code></td>
1621                         <td style="text-align:center;">x</td>
1622                         <td> </td>
1623                         <td>Unicode string data. Ex: "Hello World"</td>
1624                 </tr>
1625         </table>
1626
1627 **Container: actions_on_node**
1628
1629 This container provides the actions done on the node in form of the log.
1630 It is similar in the form to the other actions_on_X containers in other
1631 endpoints. For more info please take a look there.
1632
1633 **Container: primary_list and secondary_list**
1634
1635 These containers provide the list of virtual machines existing on the
1636 node in primary and secondary node mode.
1637 The list is simple and includes object hostname and related link.
1638 Example::
1639
1640     <primary_list type="list">
1641     <object type="hash">
1642     <hostname>3429</hostname>
1643     <resource>/api/vm/1/</resource>
1644     </object>
1645     <object type="hash">
1646     <hostname>breakthis.gwm.osuosl.org</hostname>
1647     <resource>/api/vm/2/</resource>
1648     </object>
1649     </primary_list>
1650
1651 **Container: info**
1652
1653 This element provides extensive information related to the node. These
1654 information are used internally in Ganeti Web Manager to render specific
1655 pages. As of level of detail used, the field contained here will be
1656 described partially only. It should be noted that the elements in the
1657 table may be nullable. The full example output is included after the
1658 table.
1659
1660 .. raw:: html
1661
1662     <table>
1663                 <tr>
1664                         <th>Name </th>
1665                         <th>Type </th>
1666                         <th>Description </th>
1667                 </tr>
1668                 <tr>
1669                         <td><code>pinst_cnt</code> </td>
1670                         <td> <code>Integer</code> </td>
1671                         <td> Number of virtual machines for which the node is primary</td>
1672                 </tr>
1673                 <tr>
1674                         <td><code>sinst_cnt</code> </td>
1675                         <td> <code>Integer</code> </td>
1676                         <td> Number of virtual machines for which the node is secondary</td>
1677                 </tr>
1678                 <tr>
1679                         <td><code>pinst_list</code> </td>
1680                         <td> <code>List</code> </td>
1681                         <td> Virtual machines on this node (primary)</td>
1682                 </tr>
1683                 <tr>
1684                         <td><code>sinst_list</code> </td>
1685                         <td> <code>List</code> </td>
1686                         <td> Virtual machines on this node (secondary)</td>
1687                 </tr>
1688                 <tr>
1689                         <td><code>drained</code> </td>
1690                         <td> <code>Boolean</code> </td>
1691                         <td> Determines if the node is drained</td>
1692                 </tr>
1693                 <tr>
1694                         <td><code>offline</code> </td>
1695                         <td> <code>Boolean</code> </td>
1696                         <td> Determines if the node is ofline</td>
1697                 </tr>
1698                 <tr>
1699                         <td><code>vm_capable</code> </td>
1700                         <td> <code>Boolean</code> </td>
1701                         <td> Determines if the node is capable of hosting virtual machines</td>
1702                 </tr>
1703                 <tr>
1704                         <td><code>master_capable</code> </td>
1705                         <td> <code>Boolean</code> </td>
1706                         <td> Determines if the node is capable to become master node</td>
1707                 </tr>
1708                 <tr>
1709                         <td><code>master_candidate</code> </td>
1710                         <td> <code>Boolean</code> </td>
1711                         <td> Determines if the node is master candidate</td>
1712                 </tr>
1713                 <tr>
1714                         <td><code>mnode</code> </td>
1715                         <td> <code>Boolean</code> </td>
1716                         <td> Determines if the node is active master node</td>
1717                 </tr>
1718                 <tr>
1719                         <td><code>pip</code> </td>
1720                         <td> <code>String</code> </td>
1721                         <td> Primary IP address of the node</td>
1722                 </tr>
1723                 <tr>
1724                         <td><code>sip</code> </td>
1725                         <td> <code>String</code> </td>
1726                         <td> Secondary IP address of the node</td>
1727                 </tr>
1728                 <tr>
1729                         <td><code>uuid</code> </td>
1730                         <td> <code>String</code> </td>
1731                         <td> UUID</td>
1732                 </tr>
1733                 <tr>
1734                         <td><code>group.uuid</code> </td>
1735                         <td> <code>String</code> </td>
1736                         <td>group UUID</td>
1737                 </tr>
1738                 <tr>
1739                         <td><code>tags</code> </td>
1740                         <td> <code>List</code> </td>
1741                         <td> Tags attached to the node</td>
1742                 </tr>
1743         </table>
1744
1745 ::
1746
1747     <info type="hash">
1748     <dfree type="integer">30336</dfree>
1749     <cnodes type="integer">1</cnodes>
1750     <serial_no type="integer">1</serial_no>
1751     <dtotal type="integer">60012</dtotal>
1752     <sinst_cnt type="integer">0</sinst_cnt>
1753     <mtime type="null"/>
1754     <pip>140.211.15.61</pip>
1755     <mfree type="integer">1310</mfree>
1756     <sip>140.211.15.61</sip>
1757     <uuid>4a0e9df5-0b59-4643-b156-c133edb035bc</uuid>
1758     <drained type="boolean">False</drained>
1759     <sinst_list type="list"/>
1760     <csockets type="integer">1</csockets>
1761     <role>M</role>
1762     <ctotal type="integer">2</ctotal>
1763     <offline type="boolean">False</offline>
1764     <vm_capable type="boolean">True</vm_capable>
1765     <pinst_cnt type="integer">15</pinst_cnt>
1766     <mtotal type="integer">2004</mtotal>
1767     <tags type="list"/>
1768     <group.uuid>e318906a-40cd-4702-813b-c2185abaf8ec</group.uuid>
1769     <master_capable type="boolean">True</master_capable>
1770     <ctime type="null"/>
1771     <master_candidate type="boolean">True</master_candidate>
1772     <name>gwm1.osuosl.org</name>
1773     <mnode type="integer">730</mnode>
1774     <pinst_list type="list">
1775     <value>3429</value>
1776     <value>noinstall2.gwm.osuosl.org</value>
1777     <value>failed</value>
1778     <value>success</value>
1779     <value>derpers.gwm.osuosl.org</value>
1780     <value>testtest</value
1781     ><value>breakthis.gwm.osuosl.org</value>
1782     <value>foobarherpderp.gwm</value>
1783     <value>brookjon.gwm.osuosl.org</value>
1784     <value>orphanme</value>
1785     <value>foobar352</value>
1786     <value>testcdrom2.gwm.osuosl.org</value>
1787     <value>ooga.osuosl.org</value>
1788     <value>diskless3</value>
1789     <value>noinstall.gwm.osuosl.org</value>
1790     </pinst_list>
1791     </info>
1792
1793 /api/job
1794 ~~~~~~~~
1795
1796 This endpoint exposes information related to the job execution in the
1797 system.
1798
1799 .. raw:: html
1800
1801         <table>
1802                 <tr>
1803                         <th>Name </th>
1804                         <th>Type </th>
1805                         <th>ReadOnly </th>
1806                         <th>Nullable </th>
1807                         <th>Description </th>
1808                 </tr>
1809                 <tr>
1810                         <td><code>status</code></td>
1811                         <td><code>string</code></td>
1812                         <td> </td>
1813                         <td> </td>
1814                         <td>Unicode string data. Ex: "Hello World"</td>
1815                 </tr>
1816                 <tr>
1817                         <td><code>summarys</code></td>
1818                         <td><code>string</code></td>
1819                         <td style="text-align:center;">x</td>
1820                         <td style="text-align:center;">x</td>
1821                         <td>Describes the job summary.</td>
1822                 </tr>
1823                 <tr>
1824                         <td><code>job_id</code></td>
1825                         <td><code>integer</code></td>
1826                         <td> </td>
1827                         <td> </td>
1828                         <td>Integer data. Ex: 2673</td>
1829                 </tr>
1830                 <tr>
1831                         <td><code>cluster_admin</code></td>
1832                         <td><code>Boolean</code></td>
1833                         <td style="text-align:center;">x</td>
1834                         <td> </td>
1835                         <td>Determines if the current user has admin permissions over related cluster.</td>
1836                 </tr>
1837                 <tr>
1838                         <td><code>ops</code></td>
1839                         <td><code>list</code></td>
1840                         <td style="text-align:center;">x</td>
1841                         <td> </td>
1842                         <td>Complex field containing details about job. The field contents depend on the job type. More details can be found in the wiki.</td>
1843                 </tr>
1844                 <tr>
1845                         <td><code>opresult</code></td>
1846                         <td><code>list</code></td>
1847                         <td style="text-align:center;">x</td>
1848                         <td style="text-align:center;">x</td>
1849                         <td>Describes the error occurred during job execution.</td>
1850                 </tr>
1851                 <tr>
1852                         <td><code>cluster</code></td>
1853                         <td><code>related</code></td>
1854                         <td> </td>
1855                         <td> </td>
1856                         <td>A single related resource. Can be either a URI or set of nested resource data.</td>
1857                 </tr>
1858                 <tr>
1859                         <td><code>finished</code></td>
1860                         <td><code>datetime</code></td>
1861                         <td> </td>
1862                         <td style="text-align:center;">x</td>
1863                         <td>A date &#38; time as a string. Ex: "2010-11-10T03:07:43"</td>
1864                 </tr>
1865                 <tr>
1866                         <td><code>cleared</code></td>
1867                         <td><code>boolean</code></td>
1868                         <td> </td>
1869                         <td> </td>
1870                         <td>Boolean data. Ex: True</td>
1871                 </tr>
1872                 <tr>
1873                         <td><code>resource_uri</code></td>
1874                         <td><code>string</code></td>
1875                         <td> </td>
1876                         <td> </td>
1877                         <td>Unicode string data. Ex: "Hello World"</td>
1878                 </tr>
1879         </table>
1880
1881 **Container: opresult**
1882
1883 This field contains a detailed description of error encountered during
1884 job execution.
1885 The fields included are the following:
1886
1887 .. raw:: html
1888
1889         <table>
1890                 <tr>
1891                         <th>Name </th>
1892                         <th>Type </th>
1893                         <th>Description </th>
1894                 </tr>
1895                 <tr>
1896                         <td>error_type</td>
1897                         <td>string</td>
1898                         <td>Denotes the type of the error</td>
1899                 </tr>
1900                 <tr>
1901                         <td>error_message</td>
1902                         <td>string</td>
1903                         <td>Contains a summary description of the error. May be omitted.</td>
1904                 </tr>
1905                 <tr>
1906                         <td>error_family</td>
1907                         <td>string</td>
1908                         <td>Relates error to the family of errors. May be omitted.</td>
1909                 </tr>
1910         </table>
1911
1912 Example::
1913
1914     <opresult type="hash">
1915     <error_type>OpPrereqError</error_type>
1916     <error_message>The given name (owelwjqe) does not resolve: Name or
1917     service not known</error_message>
1918     <error_family>resolver_error</error_family>
1919     </opresult>
1920
1921 **Container: ops**
1922 This field contains information about the job executed. There may be
1923 many subfields included, spanned through several levels.
1924
1925 The following excerpts provide two typical example outputs:
1926
1927 ::
1928
1929     <pre>
1930     <ops type="list">
1931     <object type="hash">
1932     <hvparams type="hash">
1933     <nic_type>paravirtual</nic_type>
1934     <boot_order>disk</boot_order>
1935     <root_path>/dev/vda3</root_path>
1936     <serial_console type="boolean">False</serial_console>
1937     <cdrom_image_path/>
1938     <disk_type>paravirtual</disk_type>
1939     <kernel_path/>
1940     </hvparams>
1941     <debug_level type="integer">0</debug_level>
1942     <disk_template>plain</disk_template>
1943     <name_check type="boolean">True</name_check>
1944     <osparams type="hash"/>
1945     <src_node type="null"/>
1946     <source_x509_ca type="null"/>
1947     <dry_run type="boolean">False</dry_run>
1948     <pnode>gwm1.osuosl.org</pnode>
1949     <nics type="list">
1950     <object type="hash">
1951     <link>br0</link>
1952     <mode>bridged</mode>
1953     </object>
1954     </nics>
1955     <wait_for_sync type="boolean">True</wait_for_sync>
1956     <priority type="integer">0</priority>
1957     <start type="boolean">True</start>
1958     <ip_check type="boolean">True</ip_check>
1959     <source_shutdown_timeout type="integer">120</source_shutdown_timeout>
1960     <file_storage_dir type="null"/>
1961     <no_install type="boolean">False</no_install>
1962     <src_path type="null"/>
1963     <snode type="null"/>
1964     <identify_defaults type="boolean">False</identify_defaults>
1965     <OP_ID>OP_INSTANCE_CREATE</OP_ID>
1966     <source_instance_name type="null"/>
1967     <source_handshake type="null"/>
1968     <hypervisor>kvm</hypervisor>
1969     <force_variant type="boolean">False</force_variant>
1970     <disks type="list">
1971     <object type="hash">
1972     <size type="integer">408</size>
1973     </object>
1974     </disks>
1975     <instance_name>owelwjqe</instance_name>
1976     <mode>create</mode>
1977     <iallocator type="null"/>
1978     <file_driver>loop</file_driver>
1979     <os_type>image+debian-squeeze</os_type>
1980     <beparams type="hash">
1981     <vcpus type="integer">2</vcpus>
1982     <memory type="integer">512</memory>
1983     </beparams>
1984     </object>
1985     </ops>
1986     </pre>
1987
1988 ::
1989
1990     <pre>
1991     <ops type="list">
1992     <object type="hash">
1993     <instance_name>brookjon.gwm.osuosl.org</instance_name>
1994     <ignore_secondaries type="boolean">False</ignore_secondaries>
1995     <dry_run type="boolean">False</dry_run>
1996     <priority type="integer">0</priority>
1997     <debug_level type="integer">0</debug_level>
1998     <OP_ID>OP_INSTANCE_REBOOT</OP_ID>
1999     <reboot_type>hard</reboot_type>
2000     <shutdown_timeout type="integer">120</shutdown_timeout>
2001     </object>
2002     </ops>
2003     </pre>