# -- Welcome!

  You have come across a cloud computing network fabric controller.  It has
  identified itself as "Quantum."  It aims to tame your (cloud) networking!

# -- Basics:

1) Quantum REST API: Quantum supports a REST-ful programmatic interface to
   manage your cloud networking fabric.

2) Quantum Plugins: Quantum sports a plug-able architecture that allows
   Quantum's REST API to be backed by various entities that can create a
   cloud-class virtual networking fabric.  The advantages of this plug-able
   architecture is two-folds:

   a) Allows for ANY open-source project or commercial vendor to write a
   Quantum plug-in.

   b) Allows Quantum users to not be tied down to a single Quantum
   implementation and enables them to switch out a plug-in by simple editing a
   config file - plugins.ini

# -- Layout

  The Quantum project includes 3 core packages:

    quantum-common (General utils for Quantum and its plugins)
    quantum-server (The actual Quantum service itself)
    quantum-client (The Quantum CLI and API Python library)

  As well as some plugins.

# -- Dependencies

 The following python packages are required to run quantum.  These can be
 installed using pip:

 eventlet>=0.9.12
 nose
 Paste
 PasteDeploy
 pep8==0.5.0
 python-gflags
 routes
 simplejson
 webob
 webtest

1) Install easy_install (there is probably a distribution specific package for
this)

2) Install pip:
   $ easy_install pip==dev
3) Install packages with pip:
   $ pip install <package name>

# -- Running from the source code

  bin/quantum-server      #Server
  bin/quantum             #CLI
  sh run_tests.sh         #Tests

# -- Installing from the source code

  You have 3 options:
    a) sudo python setup.py install
       # Installs to /usr/lib, /usr/bin, /etc, etc

    b) python setup.py install --user
       # Install into $HOME/.local/...

    c) python setup.py install --venv
       # Creates and installs into a virtual-env at ~/.quantum-venv

# -- Configuring Quantum plug-in

1) Identify your desired plug-in.  Choose a plugin from one of he options in
   the quantum/plugins directory.

2) Update plug-in configuration by editing the quantum/plugins.ini file and
   modify "provider" property to point to the location of the Quantum plug-in.
   It should specify the class path to the plugin and the class name (i.e. for
   a plugin class MyPlugin in quantum/plugins/myplugin/myplugin.py the
   provider would be: quantum.plugins.myplugin.myplugin.MyPlugin)

3) Read the plugin specific README, this is usually found in the same
   directory as your Quantum plug-in, and follow configuration instructions.

# -- Launching the Quantum Service

  # If you're running from the source
  bin/quantum-server

  # If you installed Quantum
  quantum-server

# -- Making requests against the Quantum Service

  Quantum comes with a programmatic CLI that is driven by the Quantum Web
  Service.  You can use the CLI by issuing the following command:

  # If you're running from the source
  bin/quantum

  # If you installed Quantum
  quantum

  This will show help all of the available commands.

  An example session looks like this:

  $ export TENANT=t1
  $ quantum -v create_net $TENANT network1
  Created a new Virtual Network with ID:e754e7c0-a8eb-40e5-861a-b182d30c3441

# -- Authentication and Authorization

Requests to Quantum API are authenticated with the Keystone identity service
using a token-based authentication protocol. 

1) Enabling Authentication and Authorization
The Keystone identity service is a requirement. It must be installed, although
not necessarily on the same machine where Quantum is running; both Keystone's
admin API and service API should be running

Authentication and Authorization middleware should be enabled in the Quantum
pipeline. To this aim, uncomment the following line in /etc/quantum.conf:

pipeline = authN authZ extensions quantumapiapp

The final step concerns configuring access to Keystone. The following attributes
must be specified in the [filter:authN] section of quantum.conf:

auth_host           IP address or host name of the server where Keystone is running
auth_port           Port where the Keystone Admin API is listening
auth_protocol       Protocol used for communicating with Keystone (http/https)
auth_version        Keystone API version (default: 2.0)
auth_admin_token    Keystone token for administrative access
auth_admin_user     Keystone user with administrative rights
auth_admin_password Password for the user specified with auth_admin_user

NOTE: aut_admin_token and auth_admin_user/password are exclusive. 
If both are specified, auth_admin_token has priority.

2) Authenticating and Authorizing request for Quantum API 

A user should first authenticate with Keystone, supplying user credentials;
the Keystone service will return an authentication token, together with
informations concerning token expirations and endpoint where that token can
be used. 

The authentication token must be included in every request for the Quantum
API, in the 'X_AUTH_TOKEN' header. Quantum will look for the authentication
token in this header, and validate it with the Keystone service.

In order to validate authentication tokens, Quantum uses Keystone's
administrative API. It therefore requires credentials for an administrative
user, which can be specified in Quantum's configuration file
(etc/quantum.conf)
Either username and password, or an authentication token for an administrative
user can be specified in the configuration file: 

- Credentials:

auth_admin_user = admin
auth_admin_password = secrete

- Admin token:

auth_admin_token = 9a82c95a-99e9-4c3a-b5ee-199f6ba7ff04

As of the current release, any user for a tenant is allowed to perform
every operation on the networks owned by the tenant itself, except for
plugging interfaces. In order to perform such operation, the user must have
the Quantum:NetworkAdmin roles. Roles can be configured in Keystone using 
the administrative API.


# -- Writing your own Quantum plug-in

If you wish the write your own Quantum plugin, please refer to some concrete as
well as sample plugins available in:

../quantum/quantum/plugins/.. directory.

There are a few requirements to writing your own plugin:

1) Your plugin should implement all methods defined in the
   quantum/quantum_plugin_base.QuantumPluginBase class

2) Copy your Quantum plug-in over to the quantum/quantum/plugins/.. directory

3) The next step is to edit the plugins.ini file in the same directory
   as QuantumPluginBase class and specify the location of your custom plugin
   as the "provider"

4) Launch the Quantum Service, and your plug-in is configured and ready to
   manage a Cloud Networking Fabric.

# -- Extensions

1) Creating Extensions:
   a) Extension files should be placed under ./extensions folder. 
   b) The extension file should have a class with the same name as the filename. 
      This class should implement the contract required by the extension framework. 
      See ExtensionDescriptor class in ./quantum/common/extensions.py for details
   c) To stop a file in ./extensions folder from being loaded as an extension, 
      the filename should start with an "_"
   For an example of an extension file look at Foxinsocks class in 
   ./tests/unit/extensions/foxinsocks.py
   The unit tests in ./tests/unit/test_extensions.py document all the ways in 
   which you can use extensions

2) Associating plugins with extensions:
   a) A Plugin can advertize all the extensions it supports through the 
     'supported_extension_aliases' attribute. Eg:
 
      class SomePlugin:
        ...
        supported_extension_aliases = ['extension1_alias', 
                                     'extension2_alias',
                                     'extension3_alias']
      Any extension not in this list will not be loaded for the plugin

  b) Extension Interfaces for plugins (optional)
     The extension can mandate an interface that plugins have to support with the
     'get_plugin_interface' method in the extension.
     For an example see the FoxInSocksPluginInterface in foxinsocks.py.

  The QuantumEchoPlugin lists foxinsox in its supported_extension_aliases 
  and implements the method from FoxInSocksPluginInterface.

# -- Building packages

  rpms:
    python setup.py build rpm

  debs:
    python setup.py build deb