Synnefo

	@echo "# qcollectiongenerator $(BUILDDIR)/qthelp/Synnefo.qhcp"

	@echo "# assistant -collectionFile $(BUILDDIR)/qthelp/Synnefo.qhc"

	@echo "# mkdir -p $$HOME/.local/share/devhelp/Synnefo"

	@echo "# ln -s $(BUILDDIR)/devhelp $$HOME/.local/share/devhelp/Synnefo"

# -*- coding: utf-8 -*-

#

# Synnefo documentation build configuration file, created by

# sphinx-quickstart on Mon Nov 21 10:56:41 2011.

#

# This file is execfile()d with the current directory set to its containing dir.

#

# Note that not all possible configuration values are present in this

# autogenerated file.

#

# All configuration values have a default; values that are commented out

# serve to show the default.

# If extensions (or modules to document with autodoc) are in another directory,

# add these directories to sys.path here. If the directory is relative to the

# documentation root, use os.path.abspath to make it absolute, like shown here.

sys.path.insert(0, os.path.abspath('..'))

from synnefo import settings

from django.core.management import setup_environ

setup_environ(settings)

# -- General configuration -----------------------------------------------------

# If your documentation needs a minimal Sphinx version, state it here.

#needs_sphinx = '1.0'

# Add any Sphinx extension module names here, as strings. They can be extensions

# coming with Sphinx (named 'sphinx.ext.*') or your custom ones.

extensions = ['sphinx.ext.autodoc', 'sphinx.ext.todo']

# Add any paths that contain templates here, relative to this directory.

# The suffix of source filenames.

# The encoding of source files.

#source_encoding = 'utf-8-sig'

# The master toctree document.

# General information about the project.

project = u'Synnefo'

copyright = u'2011, GRNET'

# The version info for the project you're documenting, acts as replacement for

# |version| and |release|, also used in various other places throughout the

# built documents.

#

# The short X.Y version.

version = '0.8'

# The full version, including alpha/beta/rc tags.

release = '0.8rc1'

# The language for content autogenerated by Sphinx. Refer to documentation

# for a list of supported languages.

#language = None

# There are two options for replacing |today|: either, you set today to some

# non-false value, then it is used:

#today = ''

# Else, today_fmt is used as the format for a strftime call.

#today_fmt = '%B %d, %Y'

# List of patterns, relative to source directory, that match files and

# directories to ignore when looking for source files.

# The reST default role (used for this markup: `text`) to use for all documents.

#default_role = None

# If true, '()' will be appended to :func: etc. cross-reference text.

#add_function_parentheses = True

# If true, the current module name will be prepended to all description

# unit titles (such as .. function::).

#add_module_names = True

# If true, sectionauthor and moduleauthor directives will be shown in the

# output. They are ignored by default.

#show_authors = False

# The name of the Pygments (syntax highlighting) style to use.

# A list of ignored prefixes for module index sorting.

#modindex_common_prefix = []

# -- Options for HTML output ---------------------------------------------------

# The theme to use for HTML and HTML Help pages.  See the documentation for

# a list of builtin themes.

# Theme options are theme-specific and customize the look and feel of a theme

# further.  For a list of options available for each theme, see the

# documentation.

#html_theme_options = {}

# Add any paths that contain custom themes here, relative to this directory.

#html_theme_path = []

# The name for this set of Sphinx documents.  If None, it defaults to

# "<project> v<release> documentation".

#html_title = None

# A shorter title for the navigation bar.  Default is the same as html_title.

#html_short_title = None

# The name of an image file (relative to this directory) to place at the top

# of the sidebar.

#html_logo = None

# The name of an image file (within the static path) to use as favicon of the

# docs.  This file should be a Windows icon file (.ico) being 16x16 or 32x32

# pixels large.

#html_favicon = None

# Add any paths that contain custom static files (such as style sheets) here,

# relative to this directory. They are copied after the builtin static files,

# so a file named "default.css" will overwrite the builtin "default.css".

# If not '', a 'Last updated on:' timestamp is inserted at every page bottom,

# using the given strftime format.

#html_last_updated_fmt = '%b %d, %Y'

# If true, SmartyPants will be used to convert quotes and dashes to

# typographically correct entities.

#html_use_smartypants = True

# Custom sidebar templates, maps document names to template names.

#html_sidebars = {}

# Additional templates that should be rendered to pages, maps page names to

# template names.

#html_additional_pages = {}

# If false, no module index is generated.

#html_domain_indices = True

# If false, no index is generated.

#html_use_index = True

# If true, the index is split into individual pages for each letter.

#html_split_index = False

# If true, links to the reST sources are added to the pages.

#html_show_sourcelink = True

# If true, "Created using Sphinx" is shown in the HTML footer. Default is True.

#html_show_sphinx = True

# If true, "(C) Copyright ..." is shown in the HTML footer. Default is True.

#html_show_copyright = True

# If true, an OpenSearch description file will be output, and all pages will

# contain a <link> tag referring to it.  The value of this option must be the

# base URL from which the finished HTML is served.

#html_use_opensearch = ''

# This is the file name suffix for HTML files (e.g. ".xhtml").

#html_file_suffix = None

# Output file base name for HTML help builder.

htmlhelp_basename = 'Synnefodoc'

# -- Options for LaTeX output --------------------------------------------------

latex_elements = {

# The paper size ('letterpaper' or 'a4paper').

#'papersize': 'letterpaper',

# The font size ('10pt', '11pt' or '12pt').

#'pointsize': '10pt',

# Additional stuff for the LaTeX preamble.

#'preamble': '',

# Grouping the document tree into LaTeX files. List of tuples

# (source start file, target name, title, author, documentclass [howto/manual]).

latex_documents = [

  ('index', 'Synnefo.tex', u'Synnefo Documentation',

   u'Authors name', 'manual'),

]

# The name of an image file (relative to this directory) to place at the top of

# the title page.

#latex_logo = None

# For "manual" documents, if this is true, then toplevel headings are parts,

# not chapters.

#latex_use_parts = False

# If true, show page references after internal links.

#latex_show_pagerefs = False

# If true, show URL addresses after external links.

#latex_show_urls = False

# Documents to append as an appendix to all manuals.

#latex_appendices = []

# If false, no module index is generated.

#latex_domain_indices = True

# -- Options for manual page output --------------------------------------------

# One entry per manual page. List of tuples

# (source start file, name, description, authors, manual section).

man_pages = [

    ('index', 'synnefo', u'Synnefo Documentation',

     [u'Authors name'], 1)

]

# If true, show URL addresses after external links.

#man_show_urls = False

# -- Options for Texinfo output ------------------------------------------------

# Grouping the document tree into Texinfo files. List of tuples

# (source start file, target name, title, author,

#  dir menu entry, description, category)

texinfo_documents = [

  ('index', 'Synnefo', u'Synnefo Documentation', u'Authors name',

   'Synnefo', 'One line description of project.', 'Miscellaneous'),

]

# Documents to append as an appendix to all manuals.

#texinfo_appendices = []

# If false, no module index is generated.

#texinfo_domain_indices = True

# How to display URL addresses: 'footnote', 'no', or 'inline'.

#texinfo_show_urls = 'footnote'

# todo extension configuration

todo_include_todos = True

# autodoc config

autodoc_default_flags = ['members']

synnefo

=======

.. image:: /images/synnefo-logo.png

synnefo is software to create massively scalable IaaS clouds.

It powers GRNET's `~okeanos cloud service <https://okeanos.grnet.gr>`_.

This is the main synnefo documentation page.

synnefo comprises the following major components:

.. todo:: turn all of the following to links to the documentation, with

   intersphinx links.

.. toctree::

   :maxdepth: 1

   asterias (name TBD): Compute Service <src/asterias.rst>

   pithos+: File storage service <http://docs.dev.grnet.gr/pithos>

   plankton: Image registry <src/plankton.rst>

   archipelagos: Volume storage service <http://docs.dev.grnet.gr/archipelagos>

   astakos: Identity management module <http://docs.dev.grnet.gr/astakos>

   aquarium: Billing module <http://docs.dev.grnet.gr/aquarium>

   image: Secure image deployment tool <http://docs.dev.grnet.gr/snf-image>

   kamaki: Command-line cloud management tool <http://docs.dev.grnet.gr/kamaki>

You may also see the detailed configuration for all

:ref:`synnefo software components <components>`.

Indices and tables

------------------

* :ref:`genindex`

* :ref:`modindex`

* :ref:`search`

Administration

==============

This file contains notes related to administration of a working Synnefo

deployment. This document should be read *after* README.deploy, which contains

step-by-step Synnefo deployment instructions.

Database

--------

MySQL: manage.py dbshell seems to ignore the setting of 'init_command'

       in settings.DATABASES

Reconciliation mechanism

------------------------

On certain occasions, such as a Ganeti or RabbitMQ failure, the VM state in the

system's database may differ from that in the Ganeti installation. The

reconciliation process is designed to bring the system's database in sync with

what Ganeti knows about each VM, and is able to detect the following three

conditions:

 * Stale DB servers without corresponding Ganeti instances

 * Orphan Ganeti instances, without corresponding DB entries

 * Out-of-sync operstate for DB entries wrt to Ganeti instances

The reconciliation mechanism runs as a management command, e.g., as follows:

[PYTHONPATH needs to contain the parent of the synnefo Django project

directory]:

/srv/synnefo$ export PYTHONPATH=/srv:$PYTHONPATH

vkoukis@dev67:~/synnefo [reconc]$ ./manage.py reconcile --detect-all -v 2

Please see ./manage.py reconcile --help for all the details.

The administrator can also trigger reconciliation of operating state manually,

by issuing a Ganeti OP_INSTANCE_QUERY_DATA command on a Synnefo VM, using

gnt-instance info.

Logging

-------

Logging in Synnefo is using Python's logging module. The module is configured

using dictionary configuration, whose format is described here:

http://docs.python.org/release/2.7.1/library/logging.html#logging-config-dictschema

Note that this is a feature of Python 2.7 that we have backported for use in

Python 2.6.

The logging configuration dictionary is defined in settings.d/00-logging.conf

and is broken in 4 separate dictionaries:

  * LOGGING is the logging configuration used by the web app. By default all

    loggers fall back to the main 'synnefo' logger. The subloggers can be

    changed accordingly for finer logging control. e.g. To disable debug

    messages from the API set the level of 'synnefo.api' to 'INFO'.

  * DISPATCHER_LOGGING is the logging configuration of the logic/dispatcher.py

    command line tool.

  * SNFADMIN_LOGGING is the logging configuration of the snf-admin tool.

    Consider using matching configuration for snf-admin and the synnefo.admin

    logger of the web app.

Please note the following:

  * As of Synnefo v0.7, by default the Django webapp logs to syslog, the

    dispatcher logs to /var/log/synnefo/dispatcher.log and the console,

    snf-admin logs to the console.

  * Different handlers can be set to different logging levels:

    for example, everything may appear to the console, but only INFO and higher

    may actually be stored in a longer-term logfile.

Admin Tools

-----------

snf-admin is a tool used to perform various administrative tasks. It needs to

be able to access the django database, so the following should be able to import

the Django settings.

Additionally, administrative tasks can be performed via the admin web interface

located in /admin. Only users of type ADMIN can access the admin pages. To change

the type of a user to ADMIN, snf-admin can be used:

   snf-admin user modify 42 --type ADMIN

Administration Tools User's Guide

=================================

Registering an Image

--------------------

To upload an image to Pithos and register it for use by Plankton, use the **image upload** command::

    snf-admin image upload Ubuntu /tmp/ubuntu.iso --public

You can additionally pass *disk_format*, *container_format* and other custom metadata::

    snf-admin image upload Ubuntu /tmp/ubuntu.iso --public --disk-format diskdump --meta kernel=2.6.42

The images are uploaded to the *images* container of the *SYSTEM_IMAGES_OWNER* user (defined in settings).

To register an image that is already stored in Pithos, use the **image register** command::

    snf-admin image register Debian pithos://okeanos/images/debian.iso dump --public

As with upload you can additionally pass custom metadata with ``--meta``.

To verify the image use **image list**:

    snf-admin image list -l a58a3cce-c938-6ef4-6b1a-529bda1e9e03

Modifying an Image

------------------

You can modify an already registered image use **image update**::

    snf-admin image update a58a3cce-c938-6ef4-6b1a-529bda1e9e03 --disk-format diskdump --name Xubuntu

To modify just the custom metadata use **image meta**::

    snf-admin image meta a58a3cce-c938-6ef4-6b1a-529bda1e9e03 OS=Linux

To verify all the metadata, use **image meta** with no arguments::

    snf-admin image meta a58a3cce-c938-6ef4-6b1a-529bda1e9e03

.. _asterias-admin-guide:

===================

Administrator Guide

===================

This is the asterias administrator guide.

It contains instructions on how to download, install and configure

the synnefo components necessary to deploy the Compute Service. It also covers

maintenance issues, e.g., upgrades of existing deployments.

The guide assumes you are familiar with all aspects of downloading, installing

and configuring packages for the Linux distribution of your choice.

Overview

--------

This guide covers the following:

Architecture

    Node types needed for a complete deployment of asterias,

    and their roles. Throughout this guide, `node` refers to a physical machine

    in the deployment.

Installation

    The installation of services and synnefo software components for a working

    deployment of asterias, either from source packages or the provided

    packages for Debian Squeeze.

Configuration

    Configuration of the various software components comprising an asterias

    deployment.

Upgrades/Changelogs

    Upgrades of existing deployments of asterias to newer versions, associated

    Changelogs.

.. _asterias-architecture:

Architecture

------------

Nodes in an asterias deployment belong in one of the following types.

For every type, we list the services that execute on corresponding nodes.

.. _DB_NODE:

DB

**

A node [or more than one nodes, if using an HA configuration], running a DB

engine supported by the Django ORM layer. The DB is the single source of

truth for the servicing of API requests by asterias.

*Services:* PostgreSQL / MySQL

.. _APISERVER_NODE:

APISERVER

*********

A node running the ``api`` application contained in

:ref:`snf-asterias-app <snf-asterias-app>`. Any number of

:ref:`APISERVER <APISERVER_NODE>` nodes

can be used, in a load-balancing configuration, without any

special consideration. Access to a common DB ensures consistency.

*Services:* Web server, vncauthproxy

.. _QUEUE_NODE:

QUEUE

*****

A node running the RabbitMQ software, which provides AMQP functionality. More

than one :ref:`QUEUE <QUEUE_NODE>` nodes may be deployed, in an HA

configuration. Such deployments require shared storage, provided e.g., by DRBD.

*Services:* RabbitMQ [rabbitmq-server]

.. _LOGIC_NODE:

LOGIC

*****

A node running the business logic of synnefo, in Django. It dequeues

messages from QUEUE nodes, and provides the context in which business logic

functions run. It uses Django ORM to connect to the common DB and update the

state of the system, based on notifications received from the rest of the

infrastructure, over AMQP.

*Services:* the synnefo logic dispatcher, ``snf-dispatcher``

.. _GANETI_NODES:

.. _GANETI_MASTER:

.. _GANETI_NODE:

GANETI-MASTER and GANETI-NODE

*****************************

A single GANETI-MASTER and a large number of GANETI-NODEs constitute the

Ganeti backend for synnefo, which undertakes all VM management functions.

Any APISERVER can issue commands to the GANETI-MASTER, over RAPI, to effect

changes in the state of the VMs. The GANETI-MASTER runs the Ganeti request

queue.

*Services:*

    * only on :ref:`GANETI-MASTER <GANETI_MASTER>`:

        * the synnefo Ganeti monitoring daemon, ``snf-ganeti-eventd``

        * the synnefo Ganeti hook, ``ganeti/snf-ganeti-hook.py``.

    * on every :ref:`GANETI-NODE <GANETI_NODE>`:

        * a deployment-specific KVM ifup script

        * properly configured :ref:`NFDHCPD <asterias-nfdhcpd-setup>`

.. _WEBAPP_NODE:

Installation

------------

Installation of asterias is a two step process:

1. install the external services (prerequisites) on which asterias depends

2. install the synnefo software components associated with asterias

Prerequisites

*************

.. _asterias-install-ganeti:

Ganeti installation

```````````````````

Synnefo requires a working Ganeti installation at the backend. Installation

of Ganeti is not covered by this document, please refer to

`ganeti documentation <http://docs.ganeti.org/ganeti/current/html>`_ for all the 

gory details. A successful Ganeti installation concludes with a working 

:ref:`GANETI-MASTER <GANETI_NODES>` and a number of :ref:`GANETI-NODEs <GANETI_NODES>`.

.. _asterias-install-db:

Database

````````

Database installation is done as part of the

:ref:`snf-webproject <snf-webproject>` component.

.. _asterias-install-rabbitmq:

RabbitMQ 

````````

RabbitMQ is used as a generic message broker for asterias. It should be

installed on two seperate :ref:`QUEUE <QUEUE_NODE>` nodes in a high availability

configuration as described here:

    http://www.rabbitmq.com/pacemaker.html

After installation, create a user and set its permissions:

.. code-block:: console

    $ rabbitmqctl add_user <username> <password>

    $ rabbitmqctl set_permissions -p / <username>  "^.*" ".*" ".*"

The values set for the user and password must be mirrored in the

``RABBIT_*`` variables in your settings, as managed by

:ref:`snf-common <snf-common>`.

.. todo:: Document an active-active configuration based on the latest version

   of RabbitMQ.

.. _asterias-install-vncauthproxy:

vncauthproxy

````````````

To support OOB console access to the VMs over VNC, the vncauthproxy

daemon must be running on every :ref:`APISERVER <APISERVER_NODE>` node.

.. note:: The Debian package for vncauthproxy undertakes all configuration

   automatically.

Download and install the latest vncauthproxy from its own repository,

at `https://code.grnet.gr/git/vncauthproxy`, or a specific commit:

.. code-block:: console

    $ bin/pip install -e git+https://code.grnet.gr/git/vncauthproxy@INSERT_COMMIT_HERE#egg=vncauthproxy

Create ``/var/log/vncauthproxy`` and set its permissions appropriately.

Alternatively, build and install Debian packages.

.. code-block:: console

    $ git checkout debian

    $ dpkg-buildpackage -b -uc -us

    # dpkg -i ../vncauthproxy_1.0-1_all.deb

.. warning::

    **Failure to build the package on the Mac.**

    ``libevent``, a requirement for gevent which in turn is a requirement for

    vncauthproxy is not included in `MacOSX` by default and installing it with

    MacPorts does not lead to a version that can be found by the gevent

    build process. A quick workaround is to execute the following commands::

        $ cd $SYNNEFO

        $ sudo pip install -e git+https://code.grnet.gr/git/vncauthproxy@5a196d8481e171a#egg=vncauthproxy

        <the above fails>

        $ cd build/gevent

        $ sudo python setup.py -I/opt/local/include -L/opt/local/lib build

        $ cd $SYNNEFO

        $ sudo pip install -e git+https://code.grnet.gr/git/vncauthproxy@5a196d8481e171a#egg=vncauthproxy

.. todo:: Mention vncauthproxy bug, snf-vncauthproxy, inability to install using pip

.. todo:: kpap: fix installation commands

.. _asterias-install-nfdhcpd:

NFDHCPD

```````

Setup Synnefo-specific networking on the Ganeti backend.

This part is deployment-specific and must be customized based on the

specific needs of the system administrators.

A reference installation will use a Synnefo-specific KVM ifup script,

NFDHCPD and pre-provisioned Linux bridges to support public and private

network functionality. For this:

Grab NFDHCPD from its own repository (https://code.grnet.gr/git/nfdhcpd),

install it, modify ``/etc/nfdhcpd/nfdhcpd.conf`` to reflect your network

configuration.

Install a custom KVM ifup script for use by Ganeti, as

``/etc/ganeti/kvm-vif-bridge``, on GANETI-NODEs. A sample implementation is

provided under ``/contrib/ganeti-hooks``. Set ``NFDHCPD_STATE_DIR`` to point

to NFDHCPD's state directory, usually ``/var/lib/nfdhcpd``.

.. todo:: soc: document NFDHCPD installation, settle on KVM ifup script

.. _asterias-install-snfimage:

snf-image

`````````

Install the :ref:`snf-image <snf-image>` Ganeti OS provider for image

deployment.

For :ref:`asterias <asterias>` to be able to launch VMs from specified

Images, you need the snf-image OS Provider installed on *all* Ganeti nodes.

Please see `https://code.grnet.gr/projects/snf-image/wiki`_

for installation instructions and documentation on the design

and implementation of snf-image.

Please see `https://code.grnet.gr/projects/snf-image/files`

for the latest packages.

Images should be stored in ``extdump``, or ``diskdump`` format in a directory

of your choice, configurable as ``IMAGE_DIR`` in 

:file:`/etc/default/snf-image`.

synnefo components

******************

You need to install the appropriate synnefo software components on each node,

depending on its type, see :ref:`Architecture <asterias-architecture>`.

Most synnefo components have dependencies on additional Python packages.

The dependencies are described inside each package, and are setup

automatically when installing using :command:`pip`, or when installing 

using your system's package manager.

Please see the page of each synnefo software component for specific

installation instructions, where applicable.

Install the following synnefo components:

Nodes of type :ref:`APISERVER <APISERVER_NODE>`

    Components

    :ref:`snf-common <snf-common>`,

    :ref:`snf-webproject <snf-webproject>`,

    :ref:`snf-asterias-app <snf-asterias-app>`

Nodes of type :ref:`GANETI-MASTER <GANETI_MASTER>` and :ref:`GANETI-NODE <GANETI_NODE>`

    Components

    :ref:`snf-common <snf-common>`,

    :ref:`snf-asterias-ganeti-tools <snf-asterias-ganeti-tools>`

Nodes of type :ref:`LOGIC <LOGIC_NODE>`

    Components

    :ref:`snf-common <snf-common>`,

    :ref:`snf-webproject <snf-webproject>`,

    :ref:`snf-asterias-app <snf-asterias-app>`.

Configuration

-------------

This section targets the configuration of the prerequisites for asterias,

and the configuration of the associated synnefo software components.

synnefo components

******************

asterias uses :ref:`snf-common <snf-common>` for settings.

Please refer to the configuration sections of

:ref:`snf-webproject <snf-webproject>`,

:ref:`snf-asterias-app <snf-asterias-app>`,

:ref:`snf-asterias-ganeti-tools <snf-asterias-ganeti-tools>` for more

information on their configuration.

Ganeti

``````

Set ``GANETI_NODES``, ``GANETI_MASTER_IP``, ``GANETI_CLUSTER_INFO`` based on

your :ref:`Ganeti installation <asterias-install-ganeti>` and change the

`BACKEND_PREFIX_ID`` setting, using an custom ``PREFIX_ID``.

Database

````````

Once all components are installed and configured,

initialize the Django DB:

.. code-block:: console

   $ snf-manage syncdb

   $ snf-manage migrate

and load fixtures ``{users, flavors, images}``, 

which make the API usable by end users by defining a sample set of users, 

hardware configurations (flavors) and OS images:

.. code-block:: console

   $ snf-manage loaddata /path/to/users.json

   $ snf-manage loaddata flavors

   $ snf-manage loaddata images

.. warning:: 

    Be sure to load a custom users.json and select a unique token 

    for each of the initial and any other users defined in this file. 

    **DO NOT LEAVE THE SAMPLE AUTHENTICATION TOKENS** enabled in deployed

    configurations.

sample users.json file:

.. literalinclude:: ../../synnefo/db/fixtures/users.json

`download <../_static/users.json>`_

RabbitMQ

````````

Change ``RABBIT_*`` settings to match your :ref:`RabbitMQ setup

<asterias-install-rabbitmq>`.

.. include:: ../../Changelog

API Guide

*********

.. todo:: Document the relation of the API to the OpenStack API v1.1.

This is the guide to the REST API of the synnefo Compute Service.

It is meant for users wishing to make calls to the REST API directly.

The :ref:`kamaki <http://docs.dev.grnet.gr/kamaki>` command-line client

and associated python library can be used instead of making direct calls to

:ref:`asterias <asterias>`.

Overview

========

* It is not defined if requests for invalid URLs should return 404 or a Fault.

  We return a BadRequest Fault.

* It is not defined if requests with a wrong HTTP method should return 405 or a

  Fault. We return a BadRequest Fault.

General API Information

=======================

Authentication

--------------

* Authentication support is missing.

Request/Response Types

----------------------

* We only support JSON Requests and JSON/XML Responses. XML Requests are not

  supported for now.

Content Compression

-------------------

* Optional content compression support is missing.

Persistent Connections

----------------------

* Deployment note: "To prevent abuse, HTTP sessions have a timeout of 20

  seconds before being closed."

Links and References

--------------------

* Full URI references support is missing.

* Self and bookmark links support is missing.

Paginated Collections

---------------------

* Pagination support is missing.

Caching

-------

* We do not return cached responses.

Limits

------

 * Limits support is missing.

Efficient Polling with the Changes-Since Parameter

--------------------------------------------------

* We only support the changes-since parameter in **List Servers** and **List

  Images**.

* We assume that garbage collection of deleted servers will only affect servers

  deleted ``POLL_TIME`` seconds in the past or earlier. Else we lose the

  information of a server getting deleted.

* Images do not support a deleted state, so we can not track deletions.

Versions

--------

* Version MIME type support is missing.

* Versionless requests are not supported.

* We hardcode the ``updated`` field in versions list

* Deployment note: The Atom metadata need to be fixed

Extensions

----------

* Extensions support is missing.

Faults

------

API Operations

==============

Servers

-------

* ``hostId`` is always empty.

* ``affinityId`` is not returned.

* ``progress`` is always returned.

* ``self`` and ``bookmark`` atom links are not returned.

* **Get Server Details** will also return servers with a DELETED state.

* **Create Server** ignores ``personality`` of requests.

* **Create Server** ignores the disk size of the flavor.

* **Create Server** hardcodes the OS.

* **Create Server** does not support setting the password in the request.

List Servers

............

* **List Servers** returns just ``id`` and ``name`` if details are not

  requested.

* **List Servers** can return 304 (even though not explicitly stated) when

  ``changes-since`` is given.

**Example List Servers: JSON**

.. code-block:: javascript

  {

      'servers':

          {'values': [

              {

                  'addresses': {'values': [

                          {

                              'id': 'public',

                              'mac': 'aa:00:00:49:2e:7e',

                              'name': 'public',

                              'values': [ {'addr': '192.168.32.6', 'version': 4} ]

                          }

                  ]},

                  'created': '2011-04-19T10:18:52.085737+00:00',

                  'flavorRef': 1,

                  'hostId': '',

                  'id': 1,

                  'imageRef': 3,

                  'metadata': {'values': {'foo': 'bar'}},

                  'name': 'My Server',

                  'status': 'ACTIVE',

                  'updated': u'2011-05-29T14:07:07.037602+00:00'

              },

              {

                  'addresses': {'values': [

                          {

                              'id': 'public',

                              'mac': 'aa:00:00:91:2f:df',

                              'name': 'public',

                              'values': [ {'addr': '192.168.32.7', 'version': 4} ]

                          },

                          {

                              'id': '2',

                              'mac': 'aa:00:00:c3:69:6f',

                              'name': 'private'

                          },

                  ]},

                  'created': '2011-05-02T20:51:08.527759+00:00',

                  'flavorRef': 1,

                  'hostId': '',

                  'id': 2,

                  'imageRef': 3,

                  'name': 'Other Server',

                  'progress': 0,

                  'status': 'ACTIVE',

                  'updated': '2011-05-29T14:59:11.267087+00:00'

              }

          ]

      }

  }

Get Server Stats

................

**GET** /servers/*id*/stats

**Normal Response Code**: 200

**Error Response Codes**: computeFault (400, 500), serviceUnavailable (503),

unauthorized (401), badRequest (400), itemNotFound (404), overLimit (413)

This operation returns URLs to graphs showing CPU and Network statistics. A

``refresh`` attribute is returned as well that is the recommended refresh rate

of the stats for the clients.

This operation does not require a request body.

**Example Get Server Stats Response: JSON**:

.. code-block:: javascript

  {

      "stats": {

          "serverRef": 1,

          "refresh": 60,

          "cpuBar": "http://stats.okeanos.grnet.gr/b9a1c3ca7e3b9fce75112c43565fb9960b16048c/cpu-bar.png",

          "cpuTimeSeries": "http://stats.okeanos.grnet.gr/b9a1c3ca7e3b9fce75112c43565fb9960b16048c/cpu-ts.png",

          "netBar": "http://stats.okeanos.grnet.gr/b9a1c3ca7e3b9fce75112c43565fb9960b16048c/net-bar.png",

          "netTimeSeries": "http://stats.okeanos.grnet.gr/b9a1c3ca7e3b9fce75112c43565fb9960b16048c/net-ts.png"

      }

  }

**Example Get Network Details Response: XML**:

.. code-block:: xml

  <?xml version="1.0" encoding="UTF-8"?>

  <stats xmlns="http://docs.openstack.org/compute/api/v1.1" xmlns:atom="http://www.w3.org/2005/Atom"

      serverRef="1"

      refresh="60"

      cpuBar="http://stats.okeanos.grnet.gr/b9a1c3ca7e3b9fce75112c43565fb9960b16048c/cpu-bar.png"

      cpuTimeSeries="http://stats.okeanos.grnet.gr/b9a1c3ca7e3b9fce75112c43565fb9960b16048c/cpu-ts.png"

      netBar="http://stats.okeanos.grnet.gr/b9a1c3ca7e3b9fce75112c43565fb9960b16048c/net-bar.png"

      netTimeSeries="http://stats.okeanos.grnet.gr/b9a1c3ca7e3b9fce75112c43565fb9960b16048c/net-ts.png">

  </stats>

Server Addresses

----------------

Server Actions

--------------

* **Change Password** is not supported.

* **Rebuild Server** is not supported.

* **Resize Server** is not supported.

* **Confirm Resized Server** is not supported.

* **Revert Resized Server** is not supported.

We have have extended the API with the following commands:

Start Server

............

**Normal Response Code**: 202

**Error Response Codes**: serviceUnavailable (503), itemNotFound (404)

The start function transitions a server from an ACTIVE to a STOPPED state.

**Example Action Start: JSON**:

.. code-block:: javascript

  {

      "start": {}

  }

This operation does not return a response body.

Shutdown Server

...............

**Normal Response Code**: 202

**Error Response Codes**: serviceUnavailable (503), itemNotFound (404)

The start function transitions a server from a STOPPED to an ACTIVE state.

**Example Action Shutdown: JSON**:

.. code-block:: javascript

  {

      "shutdown": {}

  }

This operation does not return a response body.

Get Server Console

**Normal Response Code**: 200

**Error Response Codes**: computeFault (400, 500), serviceUnavailable (503), unauthorized (401), badRequest (400), badMediaType(415), itemNotFound (404), buildInProgress (409), overLimit (413)

The console function arranges for an OOB console of the specified type. Only consoles of type "vnc" are supported for now.

It uses a running instance of vncauthproxy to setup proper VNC forwarding with a random password, then returns the necessary VNC connection info to the caller.

**Example Action Console: JSON**:

.. code-block:: javascript

  {

      "console": {

          "type": "vnc"

      }

  }

**Example Action Console Response: JSON**:

.. code-block:: javascript

  {

      "console": {

          "type": "vnc",

          "host": "vm42.ocean.grnet.gr",

          "port": 1234,

          "password": "IN9RNmaV"

      }

  }

**Example Action Console Response: XML**:

.. code-block:: xml

  <?xml version="1.0" encoding="UTF-8"?>

  <console xmlns="http://docs.openstack.org/compute/api/v1.1" xmlns:atom="http://www.w3.org/2005/Atom"

      type="vnc"

      host="vm42.ocean.grnet.gr"

      port="1234"

      password="IN9RNmaV">

  </console>

Set Firewall Profile

....................

**Normal Response Code**: 202

**Error Response Codes**: computeFault (400, 500), serviceUnavailable (503),

unauthorized (401), badRequest (400), badMediaType(415), itemNotFound (404),

buildInProgress (409), overLimit (413)

The firewallProfile function sets a firewall profile for the public interface

of a server.

The allowed profiles are: **ENABLED**, **DISABLED** and **PROTECTED**.

**Example Action firewallProfile: JSON**:

.. code-block:: javascript

  {

      "firewallProfile": {

          "profile": "ENABLED"

      }

  }

This operation does not return a response body.

Flavors

-------

* ``self`` and ``bookmark`` atom links are not returned.

* **List Flavors** returns just ``id`` and ``name`` if details is not requested.

Images

------

* ``progress`` is always returned.

* ``self`` and ``bookmark`` atom links are not returned.

* **List Images** returns just ``id`` and ``name`` if details are not requested.

* **List Images** can return 304 (even though not explicitly stated) when

  ``changes-since`` is given. 

* **List Images** does not return deleted images when ``changes-since`` is given.

Metadata

--------

* **Update Server Metadata** and **Update Image Metadata** will only return the

  metadata that were updated (some could have been skipped).

Networks

--------

This is an extension to the OpenStack API.

A Server can connect to one or more networks identified by a numeric id. Each

user has access only to networks created by himself. When a network is deleted,

all connections to it are deleted. Likewise, when a server is deleted, all

connections of that server are deleted.

There is a special **public** network with the id *public* that can be accessed

at */networks/public*. All servers are connected to **public** by default and

this network can not be deleted or modified in any way.

List Networks

.............

**GET** /networks

**GET** /networks/detail

**Normal Response Codes**: 200, 203

**Error Response Codes**: computeFault (400, 500), serviceUnavailable (503),

unauthorized (401), badRequest (400), overLimit (413)

This operation provides a list of private networks associated with your account.

This operation does not require a request body.

**Example Networks List Response: JSON (detail)**:

.. code-block:: javascript

  {

      "networks": {

          "values": [

              {

                  "id": "public",

                  "name": "public",

                  "created": "2011-04-20T15:31:08.199640+00:00",

                  "updated": "2011-05-06T12:47:05.582679+00:00",

                  "servers": {

                      "values": [1, 2, 3]

                  }

              },

              {

                  "id": 2,

                  "name": "private",

                  "created": "2011-04-20T14:32:08.199640+00:00",

                  "updated": "2011-05-06T11:40:05.582679+00:00",

                  "servers": {

                      "values": [1]

                  }

              }

          ]

      }

  }

**Example Networks List Response: XML (detail)**:

.. code-block:: xml

  <?xml version="1.0" encoding="UTF-8"?>

  <networks xmlns="http://docs.openstack.org/compute/api/v1.1" xmlns:atom="http://www.w3.org/2005/Atom">

    <network id="public" name="public" updated="2011-05-02T21:33:25.606672+00:00" created="2011-04-20T15:31:08.199640+00:00">

      <servers>

        <server id="1"></server>

        <server id="2"></server>

        <server id="3"></server>

      </servers>

    </network>

    <network id="2" name="private" updated="2011-05-06T12:47:05.582679+00:00" created="2011-04-20T15:31:33.911299+00:00">

      <servers>

        <server id="1"></server>

      </servers>

    </network>

  </networks>

Create Network

..............

**POST** /networks

**Normal Response Code**: 202

**Error Response Codes**: computeFault (400, 500), serviceUnavailable (503),

unauthorized (401), badMediaType(415), badRequest (400), overLimit (413)

This operation asynchronously provisions a new private network.

**Example Create Network Request: JSON**:

.. code-block:: javascript

  {

      "network": {

          "name": "private_net",

      }

  }

**Example Create Network Response: JSON**:

.. code-block:: javascript