doc updates

10 files changed, 918 insertions, 386 deletions

diff --git a/docs/source/api_curl_examples.rst b/docs/source/api_curl_examples.rst
new file mode 100644
index 00000000..686e8bd5
--- /dev/null
+++ b/docs/source/api_curl_examples.rst
@@ -0,0 +1,442 @@
+..
+      Copyright 2011 OpenStack, LLC
+      All Rights Reserved.
+
+      Licensed under the Apache License, Version 2.0 (the "License"); you may
+      not use this file except in compliance with the License. You may obtain
+      a copy of the License at
+
+          http://www.apache.org/licenses/LICENSE-2.0
+
+      Unless required by applicable law or agreed to in writing, software
+      distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
+      WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the
+      License for the specific language governing permissions and limitations
+      under the License.
+
+
+===============================
+Service API Examples Using Curl
+===============================
+
+The service API is defined to be a subset of the Admin API and, by
+default, runs on port 5000.
+
+GET /
+=====
+
+This call is identical to that documented for the Admin API, except
+that it uses port 5000, instead of port 35357, by default::
+
+    $ curl http://0.0.0.0:5000
+
+or::
+
+    $ curl http://0.0.0.0:5000/v2.0/
+
+See the `Admin API Examples Using Curl`_ for more info.
+
+.. _`Admin API Examples Using Curl`: adminAPI_curl_examples.html
+
+GET /extensions
+===============
+
+This call is identical to that documented for the Admin API.
+
+POST /tokens
+============
+
+This call is identical to that documented for the Admin API.
+
+GET /tenants
+============
+
+List all of the tenants your token can access::
+
+    $ curl -H "X-Auth-Token:887665443383838" http://localhost:5000/v2.0/tenants
+
+Returns::
+
+    {
+        "tenants_links": [],
+        "tenants": [
+            {
+                "enabled": true,
+                "description": "None",
+                "name": "customer-x",
+                "id": "1"
+            }
+        ]
+    }
+
+=============================
+Admin API Examples Using Curl
+=============================
+
+These examples assume a default port value of 35357, and depend on the
+``sampledata`` bundled with keystone.
+
+GET /
+=====
+
+Disover API version information, links to documentation (PDF, HTML, WADL),
+and supported media types::
+
+    $ curl http://0.0.0.0:35357
+
+or::
+
+    $ curl http://0.0.0.0:35357/v2.0/
+
+Returns::
+
+    {
+        "version":{
+            "id":"v2.0",
+            "status":"beta",
+            "updated":"2011-11-19T00:00:00Z",
+            "links":[
+                {
+                    "rel":"self",
+                    "href":"http://127.0.0.1:35357/v2.0/"
+                },
+                {
+                    "rel":"describedby",
+                    "type":"text/html",
+                    "href":"http://docs.openstack.org/api/openstack-identity-service/2.0/content/"
+                },
+                {
+                    "rel":"describedby",
+                    "type":"application/pdf",
+                    "href":"http://docs.openstack.org/api/openstack-identity-service/2.0/identity-dev-guide-2.0.pdf"
+                },
+                {
+                    "rel":"describedby",
+                    "type":"application/vnd.sun.wadl+xml",
+                    "href":"http://127.0.0.1:35357/v2.0/identity-admin.wadl"
+                }
+            ],
+            "media-types":[
+                {
+                    "base":"application/xml",
+                    "type":"application/vnd.openstack.identity-v2.0+xml"
+                },
+                {
+                    "base":"application/json",
+                    "type":"application/vnd.openstack.identity-v2.0+json"
+                }
+            ]
+        }
+    }
+
+GET /extensions
+===============
+
+Discover the API extensions enabled at the endpoint::
+
+    $ curl http://0.0.0.0:35357/extensions
+
+Returns::
+
+    {
+        "extensions":{
+            "values":[]
+        }
+    }
+
+POST /tokens
+============
+
+Authenticate by exchanging credentials for an access token::
+
+    $ curl -d '{"auth":{"passwordCredentials":{"username": "joeuser", "password": "secrete"}}}' -H "Content-type: application/json" http://localhost:35357/v2.0/tokens
+
+Returns::
+
+    {
+        "access":{
+            "token":{
+                "expires":"2012-02-05T00:00:00",
+                "id":"887665443383838",
+                "tenant":{
+                    "id":"1",
+                    "name":"customer-x"
+                }
+            },
+            "serviceCatalog":[
+                {
+                    "endpoints":[
+                    {
+                        "adminURL":"http://swift.admin-nets.local:8080/",
+                        "region":"RegionOne",
+                        "internalURL":"http://127.0.0.1:8080/v1/AUTH_1",
+                        "publicURL":"http://swift.publicinternets.com/v1/AUTH_1"
+                    }
+                    ],
+                    "type":"object-store",
+                    "name":"swift"
+                },
+                {
+                    "endpoints":[
+                    {
+                        "adminURL":"http://cdn.admin-nets.local/v1.1/1",
+                        "region":"RegionOne",
+                        "internalURL":"http://127.0.0.1:7777/v1.1/1",
+                        "publicURL":"http://cdn.publicinternets.com/v1.1/1"
+                    }
+                    ],
+                    "type":"object-store",
+                    "name":"cdn"
+                }
+            ],
+            "user":{
+                "id":"1",
+                "roles":[
+                    {
+                    "tenantId":"1",
+                    "id":"3",
+                    "name":"Member"
+                    }
+                ],
+                "name":"joeuser"
+            }
+        }
+    }
+
+.. note::
+
+    Take note of the value ['access']['token']['id'] value produced here (``887665443383838``, above), as you can use it in the calls below.
+
+GET /tokens/{token_id}
+======================
+
+.. note::
+
+    This call refers to a token known to be valid, ``887665443383838`` in this case.
+
+Validate a token::
+
+    $ curl -H "X-Auth-Token:999888777666" http://localhost:35357/v2.0/tokens/887665443383838
+
+If the token is valid, returns::
+
+    {
+        "access":{
+            "token":{
+                "expires":"2012-02-05T00:00:00",
+                "id":"887665443383838",
+                "tenant":{
+                    "id":"1",
+                    "name":"customer-x"
+                }
+            },
+            "user":{
+                "name":"joeuser",
+                "tenantName":"customer-x",
+                "id":"1",
+                "roles":[
+                    {
+                        "serviceId":"1",
+                        "id":"3",
+                        "name":"Member"
+                    }
+                ],
+                "tenantId":"1"
+            }
+        }
+    }
+
+HEAD /tokens/{token_id}
+=======================
+
+This is a high-performance variant of the GET call documented above, which
+by definition, returns no response body::
+
+    $ curl -I -H "X-Auth-Token:999888777666" http://localhost:35357/v2.0/tokens/887665443383838
+
+... which returns ``200``, indicating the token is valid::
+
+    HTTP/1.1 200 OK
+    Content-Length: 0
+    Content-Type: None
+    Date: Tue, 08 Nov 2011 23:07:44 GMT
+
+GET /tokens/{token_id}/endpoints
+================================
+
+List all endpoints for a token::
+
+    $ curl -H "X-Auth-Token:999888777666" http://localhost:35357/v2.0/tokens/887665443383838/endpoints
+
+Returns::
+
+    {
+        "endpoints_links": [
+            {
+                "href": "http://127.0.0.1:35357/tokens/887665443383838/endpoints?'marker=5&limit=10'",
+                "rel": "next"
+            }
+        ],
+        "endpoints": [
+            {
+                "internalURL": "http://127.0.0.1:8080/v1/AUTH_1",
+                "name": "swift",
+                "adminURL": "http://swift.admin-nets.local:8080/",
+                "region": "RegionOne",
+                "tenantId": 1,
+                "type": "object-store",
+                "id": 1,
+                "publicURL": "http://swift.publicinternets.com/v1/AUTH_1"
+            },
+            {
+                "internalURL": "http://localhost:8774/v1.0",
+                "name": "nova_compat",
+                "adminURL": "http://127.0.0.1:8774/v1.0",
+                "region": "RegionOne",
+                "tenantId": 1,
+                "type": "compute",
+                "id": 2,
+                "publicURL": "http://nova.publicinternets.com/v1.0/"
+            },
+            {
+                "internalURL": "http://localhost:8774/v1.1",
+                "name": "nova",
+                "adminURL": "http://127.0.0.1:8774/v1.1",
+                "region": "RegionOne",
+                "tenantId": 1,
+                "type": "compute",
+                "id": 3,
+                "publicURL": "http://nova.publicinternets.com/v1.1/
+            },
+            {
+                "internalURL": "http://127.0.0.1:9292/v1.1/",
+                "name": "glance",
+                "adminURL": "http://nova.admin-nets.local/v1.1/",
+                "region": "RegionOne",
+                "tenantId": 1,
+                "type": "image",
+                "id": 4,
+                "publicURL": "http://glance.publicinternets.com/v1.1/"
+            },
+            {
+                "internalURL": "http://127.0.0.1:7777/v1.1/1",
+                "name": "cdn",
+                "adminURL": "http://cdn.admin-nets.local/v1.1/1",
+                "region": "RegionOne",
+                "tenantId": 1,
+                "versionId": "1.1",
+                "versionList": "http://127.0.0.1:7777/",
+                "versionInfo": "http://127.0.0.1:7777/v1.1",
+                "type": "object-store",
+                "id": 5,
+                "publicURL": "http://cdn.publicinternets.com/v1.1/1"
+            }
+        ]
+    }
+
+GET /tenants
+============
+
+List all of the tenants in the system (requires an Admin ``X-Auth-Token``)::
+
+    $ curl -H "X-Auth-Token:999888777666" http://localhost:35357/v2.0/tenants
+
+Returns::
+
+    {
+        "tenants_links": [],
+        "tenants": [
+            {
+                "enabled": false,
+                "description": "None",
+                "name": "project-y",
+                "id": "3"
+            },
+            {
+                "enabled": true,
+                "description": "None",
+                "name": "ANOTHER:TENANT",
+                "id": "2"
+            },
+            {
+                "enabled": true,
+                "description": "None",
+                "name": "customer-x",
+                "id": "1"
+            }
+        ]
+    }
+
+GET /tenants/{tenant_id}
+========================
+
+Retrieve information about a tenant, by tenant ID::
+
+    $ curl -H "X-Auth-Token:999888777666" http://localhost:35357/v2.0/tenants/1
+
+Returns::
+
+    {
+        "tenant":{
+            "enabled":true,
+            "description":"None",
+            "name":"customer-x",
+            "id":"1"
+        }
+    }
+
+GET /tenants/{tenant_id}/users/{user_id}/roles
+==============================================
+
+List the roles a user has been granted on a tenant::
+
+    $ curl -H "X-Auth-Token:999888777666" http://localhost:35357/v2.0/tenants/1/users/1/roles
+
+Returns::
+
+    {
+        "roles_links":[],
+        "roles":[
+            {
+                "id":"3",
+                "name":"Member"
+            }
+        ]
+    }
+
+GET /users/{user_id}
+====================
+
+Retrieve information about a user, by user ID::
+
+    $ curl -H "X-Auth-Token:999888777666" http://localhost:35357/v2.0/users/1
+
+Returns::
+
+    {
+        "user":{
+            "tenantId":"1",
+            "enabled":true,
+            "id":"1",
+            "name":"joeuser"
+        }
+    }
+
+GET /users/{user_id}/roles
+==========================
+
+Retrieve the roles granted to a user, given a user ID::
+
+    $ curl -H "X-Auth-Token:999888777666" http://localhost:35357/v2.0/users/4/roles
+
+Returns::
+
+    {
+        "roles_links":[],
+        "roles":[
+            {
+                "id":"2",
+                "name":"KeystoneServiceAdmin"
+            }
+        ]
+    }
diff --git a/docs/source/architecture.rst b/docs/source/architecture.rst
index 8de45502..21d9b895 100644
--- a/docs/source/architecture.rst
+++ b/docs/source/architecture.rst
@@ -17,6 +17,10 @@
 Keystone Architecture
 =====================
 
+Much of the design is precipitated from the expectation that the auth backends
+for most deployments will actually be shims in front of existing user systems.
+
+.........JOEEDIT..........
 Keystone has two major components: Authentication and a Service Catalog.
 
 Authentication
diff --git a/docs/source/community.rst b/docs/source/community.rst
index bbad2421..d3e32178 100644
--- a/docs/source/community.rst
+++ b/docs/source/community.rst
@@ -33,20 +33,6 @@ from blueprint designs to documentation to testing to deployment scripts.
 .. _Launchpad: https://launchpad.net/keystone
 .. _wiki: http://wiki.openstack.org/
 
-
-
-Contributing Code
------------------
-
-To contribute code, sign up for a Launchpad account and sign a contributor license agreement,
-available on the `<http://wiki.openstack.org/CLA>`_. Once the CLA is signed you 
-can contribute code through the Gerrit version control system which is related to your Launchpad account.
-
-To contribute tests, docs, code, etc, refer to our `Gerrit-Jenkins-Github Workflow`_.
-
-.. _`Gerrit-Jenkins-Github Workflow`: http://wiki.openstack.org/GerritJenkinsGithub
-
-
 #openstack on Freenode IRC Network
 ----------------------------------
 
@@ -68,10 +54,10 @@ to write drafts for specs or documentation, describe a blueprint, or collaborate
 Keystone on Launchpad
 ---------------------
 
-Launchpad is a code hosting service that hosts the Keystone source code. From
-Launchpad you can report bugs, ask questions, and register blueprints (feature requests). 
+Launchpad is a code hosting that OpenStack is using to track bugs, feature work, and releases of OpenStack. Like other OpenStack projects, Keystone source code is hosted on GitHub
 
-* `Launchpad Keystone Page <http://launchpad.net/keystone>`_
+* `Keystone Project Page on Launchpad <http://launchpad.net/keystone>`_
+* `Keystone Source Repository on GitHub <http://github.com/openstack/keystone>`_
 
 OpenStack Blog
 --------------
@@ -82,9 +68,9 @@ events and posts from OpenStack contributors.
 
 `OpenStack Blog <http://openstack.org/blog>`_
 
-See also: `Planet OpenStack <http://planet.openstack.org/>`_, aggregating blogs
-about OpenStack from around the internet into a single feed. If you'd like to contribute to this blog
-aggregation with your blog posts, there are instructions for `adding your blog <http://wiki.openstack.org/AddingYourBlog>`_.
+See also: `Planet OpenStack <http://planet.openstack.org/>`_, an aggregation of blogs
+about OpenStack from around the internet, combined into a web site and RSS feed. If you'd like to
+contribute with your blog posts, there are instructions for `adding your blog <http://wiki.openstack.org/AddingYourBlog>`_.
 
 Twitter
 -------
diff --git a/docs/source/configuration.rst b/docs/source/configuration.rst
index a98d92f8..02fbd4b4 100644
--- a/docs/source/configuration.rst
+++ b/docs/source/configuration.rst
@@ -21,80 +21,214 @@ Configuring Keystone
 .. toctree::
    :maxdepth: 1
 
-   keystone.conf
    man/keystone-manage
 
-Once Keystone is installed, there are a number of configuration options
-available and potentially some initial data to create and set up.
-
-Sample data / Quick Setup
-=========================
-
-Default sampledata is provided for easy setup and testing in bin/sampeldata. To
-set up the sample data run the following command while Keystone is running::
-
-    $ ./bin/sampledata
-
-The sample data created comes from the file :doc:`sourcecode/keystone.test.sampledata`
+Once Keystone is installed, it is configured via a primary configuration file
+(:doc:`keystone.conf`), possibly a separate logging configuration file, and
+initializing data into keystone using the command line client.
 
 
 Keystone Configuration File
 ===========================
 
-Most configuration is done via configuration files. The default files are
-in ``/etc/keystone.conf``
-
-When starting up a Keystone server, you can specify the configuration file to
-use (see :doc:`controllingservers`).
-If you do **not** specify a configuration file, keystone will look in the following
-directories for a configuration file, in order:
+The keystone configuration file is an 'ini' file format with sections, 
+extended from Paste_, a common system used to configure python WSGI based
+applications. In addition to the paste config entries, general configuration
+values are stored under [DEFAULT] and [sql], and then drivers for the various
+backend components are included under their individual sections.
+
+The driver sections include:
+* ``[identity]`` - the python module that backends the identity system
+* ``[catalog]`` - the python module that backends the service catalog
+* ``[token]`` - the python module that backends the token providing mechanisms
+* ``[policy]`` - the python module that drives the policy system for RBAC
+* ``[ec2]`` - the python module providing the EC2 translations for OpenStack
+
+The keystone configuration file is expected to be named ``keystone.conf``. 
+When starting up Keystone, you can specify a different configuration file to
+use with ``--config-file``. If you do **not** specify a configuration file,
+keystone will look in the following directories for a configuration file, in
+order:
 
 * ``~/.keystone``
 * ``~/``
 * ``/etc/keystone``
 * ``/etc``
 
-The keystone configuration file should be named ``keystone.conf``.
-If you installed keystone via your operating system's
-package management system, it is likely that you will have sample
-configuration files installed in ``/etc/keystone``.
+Logging is configured externally to the rest of keystone, the file specifying
+the logging configuration is in the [DEFAULT] section of the keystone conf
+file under ``log_config``. If you wish to route all your logging through 
+syslog, there is a ``use_syslog`` option also in the [DEFAULT] section that
+easy.
 
-In addition to this documentation page, you can check the
-``etc/keystone.conf`` sample configuration
-files distributed with keystone for example configuration files for each server
-application with detailed comments on what each options does.
+A sample logging file is available with the project in the directory ``etc/logging.conf.sample``. Like other OpenStack projects, keystone uses the
+`python logging module`, which includes extensive configuration options for
+choosing the output levels and formats.
+
+In addition to this documentation page, you can check the ``etc/keystone.conf``
+sample configuration files distributed with keystone for example configuration
+files for each server application.
+
+.. _Paste: http://pythonpaste.org/
+.. _`python logging module`: http://docs.python.org/library/logging.html
 
 Sample Configuration Files
 --------------------------
 
-Keystone ships with sample configuration files in keystone/etc. These files are:
+* ``etc/keystone.conf``
+* ``etc/logging.conf.sample``
+
+Initializing Keystone
+=====================
+
+Keystone must be running in order to initialize data within it. This is because
+the keystone-manage commands are all used the same REST API that other
+OpenStack systems utilize.
+
+General keystone-manage options:
+--------------------------------
+
+* ``--id-only`` : causes ``keystone-manage`` to return only the UUID result
+from the API call.
+* ``--endpoint`` : allows you to specify the keystone endpoint to communicate with. The default endpoint is http://localhost:35357/v2.0'
+* ``--auth-token`` : provides the authorization token
+
+``keystone-manage`` is set up to expect commands in the general form of ``keystone-manage`` ``command`` ``subcommand``, with keyword arguments to provide additional information to the command. For example, the command
+``tenant`` has the subcommand ``create``, which takes the required keyword ``tenant_name``::
+
+	keystone-manage tenant create tenant_name=example_tenant
+
+Invoking keystone-manage by itself will give you some usage information.
+
+Available keystone-manage commands:
+  db_sync: Sync the database.
+      ec2: no docs
+     role: Role CRUD functions.
+  service: Service CRUD functions.
+   tenant: Tenant CRUD functions.
+    token: Token CRUD functions.
+     user: User CRUD functions.
+
+Tenants
+-------
+
+Tenants are the high level grouping within Keystone that represent groups of
+users. A tenant is the grouping that owns virtual machines within Nova, or
+containers within Swift. A tenant can have zero or more users, Users can be assocaited with more than one tenant, and each tenant - user pairing can have a role associated with it.
+
+* tenant create
+
+	keyword arguments
+    * tenant_name
+	* id (optional)
+
+example::
+	keystone-manage --id-only tenant create tenant_name=admin
+
+creates a tenant named "admin".
+
+* tenant delete
+
+	keyword arguments
+	* tenant_id
+	
+example::
+	keystone-manage tenant delete tenant_id=f2b7b39c860840dfa47d9ee4adffa0b3
+
+* tenant update
+
+	keyword arguments
+	* description
+	* name
+	* tenant_id
+
+example::
+	keystone-manage tenant update \
+	tenant_id=f2b7b39c860840dfa47d9ee4adffa0b3 \
+	description="those other guys" \
+	name=tog
+
+Users
+-----
+
+* user create
+
+	keyword arguments
+	* name
+	* password
+	* email
+	
+example::
+	keystone-manage user --ks-id-only create \
+	name=admin \
+	password=secrete \
+	email=admin@example.com
+	
+* user delete
+
+	keyword arguments
+
+* user list
+
+	keyword arguments
+
+* user update_email
+
+	keyword arguments
+
+* user update_enabled
+
+	keyword arguments
+
+* user update_password
+ 
+	keyword arguments
 
-1. keystone.conf
+* user update_tenant
 
-    A standard configuration file for running keystone in stand-alone mode.
-    It has a set of default extensions loaded to support administering Keystone
-    over REST. It uses a local SQLite database.
+	keyword arguments
 
-2. memcache.conf
+Roles
+-----
 
-    A configuration that uses memcached for storing tokens (but still SQLite for all
-    other entities). This requires memcached running.
+* role create
 
-3. ssl.conf
+	keyword arguments
+	* name
 
-    A configuration that runs Keystone with SSL (so all URLs are accessed over HTTPS).
+exmaple::
+	keystone-manage role --ks-id-only create name=Admin
+	
+* role add_user_to_tenant
 
-To run any of these configurations, use the `-c` option::
+	keyword arguments
+	* role_id
+	* user_id
+	* tenant_id
 
-    ./keystone -c ../etc/ssl.conf
+example::
 
+	keystone-manage role add_user_to_tenant \
+	role_id=19d1d3344873464d819c45f521ff9890 \
+	user_id=08741d8ed88242ca88d1f61484a0fe3b \
+	tenant_id=20601a7f1d94447daa4dff438cb1c209
+	
+* role remove_user_from_tenant
 
+* role get_user_role_refs
 
-Usefule Links
--------------
+Services
+--------
 
-For a sample configuration file with explanations of the settings, see :doc:`keystone.conf`
+* service create
 
-For configuring an LDAP backend, see http://mirantis.blogspot.com/2011/08/ldap-identity-store-for-openstack.html
+	keyword arguments
+	* name
+	* service_type
+	* description
 
-For configuration settings of middleware components, see :doc:`middleware`
\ No newline at end of file
+example::
+	keystone-manage service create \
+    name=nova \
+    service_type=compute \
+    description="Nova Compute Service"
diff --git a/docs/source/developing.rst b/docs/source/developing.rst
index acd22730..b19fec24 100644
--- a/docs/source/developing.rst
+++ b/docs/source/developing.rst
@@ -18,33 +18,22 @@
 Developing with Keystone
 ========================
 
-Get your development environment set up according to :doc:`setup`.
+Contributing Code
+=================
 
-Running a development instance
-==============================
+To contribute code, sign up for a Launchpad account and sign a contributor license agreement,
+available on the `<http://wiki.openstack.org/CLA>`_. Once the CLA is signed you 
+can contribute code through the Gerrit version control system which is related to your Launchpad account.
 
-Setting up a virtualenv
------------------------
+To contribute tests, docs, code, etc, refer to our `Gerrit-Jenkins-Github Workflow`_.
 
-We recommend establishing a virtualenv to run keystone within. To establish
-this environment, use the command::
+.. _`Gerrit-Jenkins-Github Workflow`: http://wiki.openstack.org/GerritJenkinsGithub
 
-    $ python tools/install_venv.py
+Setup
+-----
 
-This will create a local virtual environment in the directory ``.venv``.
-Once created, you can activate this virtualenv for your current shell using::
-
-    $ source .venv/bin/activate
-
-The virtual environment can be disabled using the command::
-
-    $ deactivate
-
-You can also use ``tools\with_venv.sh`` to prefix commands so that they run
-within the virtual environment. For more information on virtual environments,
-see virtualenv_.
-
-.. _virtualenv: http://www.virtualenv.org/
+Get your development environment set up according to :doc:`setup`. The instructions from here will
+assume that you have installed keystone into a virtualenv. If you chose not to, simply exclude "tools/with_venv.sh" from the example commands below.
 
 Running Keystone
 ----------------
@@ -52,84 +41,69 @@ Running Keystone
 To run the keystone Admin and API server instances, use::
 
     $ tools/with_venv.sh bin/keystone
-
-Running a demo service that uses Keystone
------------------------------------------
-
-To run client demo (with all auth middleware running locally on sample service)::
-
-    $ tools/with_venv.sh examples/echo/bin/echod
-
-which spins up a simple "echo" service on port 8090. To use a simple echo client::
-
-    $ python examples/echo/echo_client.py
+	
+this runs keystone with the configuration the etc/ directory of the project. See :doc:`configuration` for details on how Keystone is configured.
 
 Interacting with Keystone
-=========================
+-------------------------
 
 You can interact with Keystone through the command line using :doc:`man/keystone-manage`
 which allows you to establish tenants, users, etc.
 
 You can also interact with Keystone through it's REST API. There is a python
-keystone client library python-keystoneclient_ which interacts exclusively through
-the REST API.
+keystone client library `python-keystoneclient`_ which interacts exclusively through
+the REST API, and which keystone itself uses to provide it's command-line interface.
+
+.. _`python-keystoneclient`: https://github.com/openstack/python-keystoneclient
+
+Running Tests
+=============
+
+To run the full suites of tests maintained within Keystone, run::
 
-.. _python-keystoneclient: https://github.com/4P/python-keystoneclient
+    $ ./run_tests.sh
 
-The easiest way to establish some base information in Keystone to interact with is
-to invoke::
+This shows realtime feedback during test execution, iterates over
+multiple configuration variations, and uses external projects to do
+light integration testing to verify the keystone API against other projects.
 
-    $ tools/with_venv.sh bin/sampledata
+Test Structure
+--------------
 
-You can see the details of what that creates in ``keystone/test/sampledata.py``
+UPDATE THIS...
 
-Enabling debugging middleware
------------------------------
+Testing Schema Migrations
+-------------------------
 
-You can enable a huge amount of additional data (debugging information) about
-the request and repsonse objects flowing through Keystone using the debugging
-WSGI middleware.
+The application of schema migrations can be tested using SQLAlchemy Migrate’s built-in test runner, one migration at a time.
 
-To enable this, just modify the pipelines in ``etc/keystone.conf``, from::
+.. WARNING::
 
-    [pipeline:admin]
-    pipeline =
-        urlnormalizer
-        admin_api
+    This may leave your database in an inconsistent state; attempt this in non-production environments only!
 
-    [pipeline:keystone-legacy-auth]
-    pipeline =
-        urlnormalizer
-        legacy_auth
-        d5_compat
-        service_api
+This is useful for testing the *next* migration in sequence (both forward & backward) in a database under version control::
 
-... to::
+    python keystone/common/sql/migrate_repo/manage.py test \
+	--url=sqlite:///test.db \
+	--repository=keystone/common/sql/migrate_repo/
 
-    [pipeline:admin]
-    pipeline =
-        debug
-        urlnormalizer
-        d5_compat
-        admin_api
+This command references to a SQLite database (test.db) to be used. Depending on the migration, this command alone does not make assertions as to the integrity of your data during migration.
 
-    [pipeline:keystone-legacy-auth]
-    pipeline =
-        debug
-        urlnormalizer
-        legacy_auth
-        d5_compat
-        service_api
+Writing Tests
+-------------
 
-Two simple and easy debugging tools are using the ``-d`` when you start keystone::
+UPDATE THIS...
 
-    $ ./keystone -d
 
-and the `--trace-calls` flag::
+Further Testing
+---------------
 
-    $ ./keystone -trace-calls
+devstack_ is the *best* way to quickly deploy keystone with the rest of the
+OpenStack universe and should be critical step in your development workflow!
 
-The ``-d`` flag outputs debug information to the console. The ``--trace-calls`` flag
-outputs extensive, nested trace calls to the console and highlights any errors
-in red.
+You may also be interested in either the `OpenStack Continuous Integration Project`_
+or the `OpenStack Integration Testing Project`_.
 
+.. _devstack: http://devstack.org/
+.. _OpenStack Continuous Integration Project: https://github.com/openstack/openstack-ci
+.. _OpenStack Integration Testing Project: https://github.com/openstack/tempest
diff --git a/docs/source/index.rst b/docs/source/index.rst
index 4270033a..427414d4 100644
--- a/docs/source/index.rst
+++ b/docs/source/index.rst
@@ -18,9 +18,9 @@
 Welcome to Keystone, the OpenStack Identity Service!
 ====================================================
 
-Keystone is a cloud identity service written in Python, which provides
-authentication, authorization, and an OpenStack service catalog. It
-implements `OpenStack's Identity API`_.
+Keystone is an OpenStack project that provides Identity, Token, Catalog and
+Policy services for use specifically by projects in the OpenStack family.
+It implements `OpenStack's Identity API`_.
 
 This document describes Keystone for contributors of the project, and assumes
 that you are already familiar with Keystone from an `end-user perspective`_.
@@ -42,9 +42,18 @@ Getting Started
     :maxdepth: 1
 
     setup
+	configuration
+	configuringservices
     community
-    testing
 
+Man Pages
+---------
+
+.. toctree::
+    :maxdepth: 1
+
+    man/keystone
+	man/keystone-manage
 
 Developers Documentation
 ========================
@@ -53,7 +62,8 @@ Developers Documentation
 
    developing
    architecture
-   sourcecode/autoindex
+   api_curl_examples
+   modules
 
 Indices and tables
 ==================
diff --git a/docs/source/man/keystone-manage.rst b/docs/source/man/keystone-manage.rst
index 9e9304f0..da5fc941 100644
--- a/docs/source/man/keystone-manage.rst
+++ b/docs/source/man/keystone-manage.rst
@@ -22,159 +22,202 @@ DESCRIPTION
 ===========
 
 keystone-manage is the command line tool that interacts with the keystone
-service to configure Keystone
+service to initialize and update data within Keystone. Keystone *must* be 
+opertional for the keystone-manage commands to function correctly.
 
 USAGE
 =====
 
     ``keystone-manage [options] type action [additional args]``
 
-user
-----
 
-* **user add** [username] [password]
+General keystone-manage options:
+--------------------------------
 
-  adds a user to Keystone's data store
+* ``--id-only`` : causes ``keystone-manage`` to return only the UUID result
+from the API call.
+* ``--endpoint`` : allows you to specify the keystone endpoint to communicate with. The default endpoint is http://localhost:35357/v2.0'
+* ``--auth-token`` : provides the authorization token
 
-* **user list**
+``keystone-manage`` is set up to expect commands in the general form of ``keystone-manage`` ``command`` ``subcommand``, with keyword arguments to provide additional information to the command. For example, the command
+``tenant`` has the subcommand ``create``, which takes the required keyword ``tenant_name``::
 
-  lists all users
+	keystone-manage tenant create tenant_name=example_tenant
 
-* **user disable** [username]
+Invoking keystone-manage by itself will give you some usage information.
 
-  disables the user *username*
+Available keystone-manage commands:
+  db_sync: Sync the database.
+      ec2: no docs
+     role: Role CRUD functions.
+  service: Service CRUD functions.
+   tenant: Tenant CRUD functions.
+    token: Token CRUD functions.
+     user: User CRUD functions.
 
-tenant
-------
-
-* **tenant add** [tenant_name]
+Tenants
+-------
 
-  adds a tenant to Keystone's data store
+Tenants are the high level grouping within Keystone that represent groups of
+users. A tenant is the grouping that owns virtual machines within Nova, or
+containers within Swift. A tenant can have zero or more users, Users can be assocaited with more than one tenant, and each tenant - user pairing can have a role associated with it.
 
-* **tenant list**
+* tenant create
 
-  lists all users
+	keyword arguments
+    * tenant_name
+	* id (optional)
 
-* **tenant disable** [tenant_name]
+example::
+	keystone-manage --id-only tenant create tenant_name=admin
 
-role
-----
+creates a tenant named "admin".
 
-Roles are used to associated users to tenants. Two roles are defined related
-to the Keystone service in it's configuration file :doc:`../keystone.conf`
+* tenant delete
 
-* **role add** [role_name]
+	keyword arguments
+	* tenant_id
+	
+example::
+	keystone-manage tenant delete tenant_id=f2b7b39c860840dfa47d9ee4adffa0b3
 
-  adds a role
+* tenant update
 
-* **role list** ([tenant_name])
+	keyword arguments
+	* description
+	* name
+	* tenant_id
 
-  lists all roles, or all roles for tenant, if tenant_name is provided
+example::
+	keystone-manage tenant update \
+	tenant_id=f2b7b39c860840dfa47d9ee4adffa0b3 \
+	description="those other guys" \
+	name=tog
 
-* **role grant** [role_name] [username] ([tenant])
+Users
+-----
 
-  grants a role to a specific user. Granted globally if tenant_name is not
-  provided or granted for a specific tenant if tenant_name is provided.
+* user create
 
-service
--------
+	keyword arguments
+	* name
+	* password
+	* email
+	
+example::
+	keystone-manage user --ks-id-only create \
+	name=admin \
+	password=secrete \
+	email=admin@example.com
+	
+* user delete
 
-* **service add** [name] [type] [description] [owner_id]
+	keyword arguments
 
-  adds a service
+* user list
 
-* **service list**
+	keyword arguments
 
-  lists all services with id, name, and type
+* user update_email
 
-endpointTemplate
-----------------
+	keyword arguments
 
-* **endpointTemplate add** [region] [service_name] [public_url] [admin_url] [internal_url] [enabled] [is_global]
+* user update_enabled
 
-  Add a service endpoint for keystone.
+	keyword arguments
 
-  example::
+* user update_password
+ 
+	keyword arguments
 
-      keystone-manage endpointTemplates add RegionOne \
-                      keystone \
-                      http://keystone_host:5000/v2.0 \
-                      http://keystone_host:35357/v2.0 \
-                      http://keystone_host:5000/v2.0 \
-                      1 1
+* user update_tenant
 
-* **endpointTemplate list** ([tenant_name])
+	keyword arguments
 
-  lists endpoint templates with service, region, and public_url. Restricted to
-  tenant endpoints if tenant_name is provided.
-
-token
+Roles
 -----
 
-* **token add** [token] [username] [tenant] [expiration]
+* role create
+
+	keyword arguments
+	* name
 
-  adds a token for a given user and tenant with an expiration
+exmaple::
+	keystone-manage role --ks-id-only create name=Admin
+	
+* role add_user_to_tenant
 
-* **token list**
+	keyword arguments
+	* role_id
+	* user_id
+	* tenant_id
 
-  lists all tokens
+example::
 
-* **token delete** [token]
+	keystone-manage role add_user_to_tenant \
+	role_id=19d1d3344873464d819c45f521ff9890 \
+	user_id=08741d8ed88242ca88d1f61484a0fe3b \
+	tenant_id=20601a7f1d94447daa4dff438cb1c209
+	
+* role remove_user_from_tenant
 
-  deletes the identified token
+* role get_user_role_refs
 
-endpoint
+Services
 --------
 
-* **endpoint add** [tenant_name] [endpoint_template]
+* service create
 
-  adds a tenant-specific endpoint
+	keyword arguments
+	* name
+	* service_type
+	* description
 
-credentials
------------
+example::
+	keystone-manage service create \
+    name=nova \
+    service_type=compute \
+    description="Nova Compute Service"
 
-* **credentials add** [username] [type] [key] [password] ([tenant_name])
 
 OPTIONS
 =======
 
-   --version                     show program's version number and exit
-   -h, --help                    show this help message and exit
-   -v, --verbose                 Print more verbose output
-   -d, --debug                   Print debugging output to console
-   -c PATH, --config-file=PATH   Path to the config file to use. When not
-                                 specified (the default), we generally look at
-                                 the first argument specified to be a config
-                                 file, and if that is also missing, we search
-                                 standard directories for a config file.
-   -p BIND_PORT, --port=BIND_PORT, --bind-port=BIND_PORT
-                                 specifies port to listen on (default is 5000)
-   --host=BIND_HOST, --bind-host=BIND_HOST
-                                 specifies host address to listen on (default
-                                 is all or 0.0.0.0)
-   -t, --trace-calls             Turns on call tracing for troubleshooting
-   -a PORT, --admin-port=PORT    Specifies port for Admin API to listen on
-                                 (default is 35357)
-
-Logging Options:
-================
-
-The following configuration options are specific to logging
-functionality for this program.
-
-   --log-config=PATH             If this option is specified, the logging
-                                 configuration file specified is used and
-                                 overrides any other logging options specified.
-                                 Please see the Python logging module
-                                 documentation for details on logging
-                                 configuration files.
-   --log-date-format=FORMAT      Format string for %(asctime)s in log records.
-                                 Default: %Y-%m-%d %H:%M:%S
-   --log-file=PATH               (Optional) Name of log file to output to. If
-                                 not set, logging will go to stdout.
-   --log-dir=LOG_DIR             (Optional) The directory to keep log files in
-                                 (will be prepended to --logfile)
-
+Options:
+  -h, --help            show this help message and exit
+  --config-file=PATH    Path to a config file to use. Multiple config files
+                        can be specified, with values in later files taking
+                        precedence. The default files used are: []
+  -d, --debug           Print debugging output
+  --nodebug             Print debugging output
+  -v, --verbose         Print more verbose output
+  --noverbose           Print more verbose output
+  --log-config=PATH     If this option is specified, the logging configuration
+                        file specified is used and overrides any other logging
+                        options specified. Please see the Python logging
+                        module documentation for details on logging
+                        configuration files.
+  --log-format=FORMAT   A logging.Formatter log message format string which
+                        may use any of the available logging.LogRecord
+                        attributes. Default: none
+  --log-date-format=DATE_FORMAT
+                        Format string for %(asctime)s in log records. Default:
+                        none
+  --log-file=PATH       (Optional) Name of log file to output to. If not set,
+                        logging will go to stdout.
+  --log-dir=LOG_DIR     (Optional) The directory to keep log files in (will be
+                        prepended to --logfile)
+  --syslog-log-facility=SYSLOG_LOG_FACILITY
+                        (Optional) The syslog facility to use when logging to
+                        syslog (defaults to LOG_USER)
+  --use-syslog          Use syslog for logging.
+  --nouse-syslog        Use syslog for logging.
+  --endpoint=ENDPOINT   
+  --auth-token=AUTH_TOKEN
+                        authorization token
+  --id-only             
+  --noid-only           
+  
 FILES
 =====
 
diff --git a/docs/source/man/keystone.rst b/docs/source/man/keystone.rst
index 48e062e4..74d0bb69 100644
--- a/docs/source/man/keystone.rst
+++ b/docs/source/man/keystone.rst
@@ -21,9 +21,7 @@ SYNOPSIS
 DESCRIPTION
 ===========
 
-keystone starts both the service and administrative API servers for Keystone.
-Use :doc:`keystone-control` to stop/start/restart and manage those services
-once started.
+keystone starts both the service and administrative APIs for Keystone.
 
 USAGE
 =====
@@ -32,47 +30,40 @@ USAGE
 
 Common Options:
 ^^^^^^^^^^^^^^^
-   --version             show program's version number and exit
    -h, --help            show this help message and exit
 
 The following configuration options are common to all keystone
 programs.::
 
-   -v, --verbose                 Print more verbose output
-   -d, --debug                   Print debugging output to console
-   -c PATH, --config-file=PATH   Path to the config file to use. When not
-                                 specified (the default), we generally look at
-                                 the first argument specified to be a config
-                                 file, and if that is also missing, we search
-                                 standard directories for a config file.
-   -p BIND_PORT, --port=BIND_PORT, --bind-port=BIND_PORT
-                                 specifies port to listen on (default is 5000)
-   --host=BIND_HOST, --bind-host=BIND_HOST
-                                 specifies host address to listen on (default
-                                 is all or 0.0.0.0)
-   -t, --trace-calls             Turns on call tracing for troubleshooting
-   -a PORT, --admin-port=PORT    Specifies port for Admin API to listen on
-                                 (default is 35357)
-
-Logging Options:
-^^^^^^^^^^^^^^^^
-
-The following configuration options are specific to logging
-functionality for this program.::
-
-   --log-config=PATH             If this option is specified, the logging
-                                 configuration file specified is used and
-                                 overrides any other logging options specified.
-                                 Please see the Python logging module
-                                 documentation for details on logging
-                                 configuration files.
-   --log-date-format=FORMAT      Format string for %(asctime)s in log records.
-                                 Default: %Y-%m-%d %H:%M:%S
-   --log-file=PATH               (Optional) Name of log file to output to. If
-                                 not set, logging will go to stdout.
-   --log-dir=LOG_DIR             (Optional) The directory to keep log files in
-                                 (will be prepended to --logfile)
-
+  -h, --help            show this help message and exit
+  --config-file=PATH    Path to a config file to use. Multiple config files
+                        can be specified, with values in later files taking
+                        precedence. The default files used are: []
+  -d, --debug           Print debugging output
+  --nodebug             Print debugging output
+  -v, --verbose         Print more verbose output
+  --noverbose           Print more verbose output
+  --log-config=PATH     If this option is specified, the logging configuration
+                        file specified is used and overrides any other logging
+                        options specified. Please see the Python logging
+                        module documentation for details on logging
+                        configuration files.
+  --log-format=FORMAT   A logging.Formatter log message format string which
+                        may use any of the available logging.LogRecord
+                        attributes. Default: none
+  --log-date-format=DATE_FORMAT
+                        Format string for %(asctime)s in log records. Default:
+                        none
+  --log-file=PATH       (Optional) Name of log file to output to. If not set,
+                        logging will go to stdout.
+  --log-dir=LOG_DIR     (Optional) The directory to keep log files in (will be
+                        prepended to --logfile)
+  --syslog-log-facility=SYSLOG_LOG_FACILITY
+                        (Optional) The syslog facility to use when logging to
+                        syslog (defaults to LOG_USER)
+  --use-syslog          Use syslog for logging.
+  --nouse-syslog        Use syslog for logging.
+  
 FILES
 =====
 
diff --git a/docs/source/setup.rst b/docs/source/setup.rst
index e608f09e..25a43655 100644
--- a/docs/source/setup.rst
+++ b/docs/source/setup.rst
@@ -18,12 +18,12 @@
 Setting up a Keystone development environment
 =============================================
 
-This document describes setting up keystone directly from GitHub_
+This document describes getting the source from keystone's `GitHub repository`_
 for development purposes.
 
 To install keystone from packaging, refer instead to Keystone's `User Documentation`_.
 
-.. _GitHub: http://github.com/openstack/keystone
+.. _`GitHub Repository`: http://github.com/openstack/keystone
 .. _`User Documentation`: http://docs.openstack.org/
 
 Prerequisites
@@ -51,7 +51,7 @@ different version of the above, please document your configuration here!
 Getting the latest code
 =======================
 
-You can clone our latest code from our `Github repository`::
+Make a clone of the code from our `Github repository`::
 
     $ git clone https://github.com/openstack/keystone.git
 
@@ -59,13 +59,17 @@ When that is complete, you can::
 
     $ cd keystone
 
-.. _`Github repository`: https://github.com/openstack/keystone
-
 Installing dependencies
 =======================
 
-Keystone maintains a list of PyPi_ dependencies, designed for use by
-pip_.
+Keystone maintains two lists of dependencies:
+
+    tools/pip-requires
+	tools/pip-requires-test
+
+The first is the list of dependencies needed for running keystone, the second list includes dependencies used for active development and testing of keystone itself.
+
+These depdendencies can be installed from PyPi_ using the python tool pip_.
 
 .. _PyPi: http://pypi.python.org/
 .. _pip: http://pypi.python.org/pypi/pip
@@ -89,29 +93,51 @@ Mac OS X Lion (requires MacPorts_)::
 
 .. _MacPorts: http://www.macports.org/
 
-PyPi Packages
--------------
+PyPi Packages and VirtualEnv
+----------------------------
 
-Assuming you have any necessary binary packages & header files available
-on your system, you can then install PyPi dependencies.
+We recommend establishing a virtualenv to run keystone within. Virtualenv limits the python environment
+to just what you're installing as depdendencies, useful to keep a clean environment for working on 
+Keystone. The tools directory in keystone has a script already created to make this very simple::
 
-You may also need to prefix `pip install` with `sudo`, depending on your
-environment::
+    $ python tools/install_venv.py
 
-    # Describe dependencies (including non-PyPi dependencies)
-    $ cat tools/pip-requires
+This will create a local virtual environment in the directory ``.venv``.
+Once created, you can activate this virtualenv for your current shell using::
 
-    # Install all PyPi dependencies (for production, testing, and development)
-    $ pip install -r tools/pip-requires
+    $ source .venv/bin/activate
+
+The virtual environment can be disabled using the command::
+
+    $ deactivate
 
-Updating your PYTHONPATH
-========================
+You can also use ``tools\with_venv.sh`` to prefix commands so that they run
+within the virtual environment. For more information on virtual environments,
+see virtualenv_.
 
-There are a number of methods for getting Keystone into your PYTHON PATH,
-the easiest of which is::
+.. _virtualenv: http://www.virtualenv.org/
 
+If you want to run keystone outside of a virtualenv, you can install the dependencies directly
+into your system from the requires files::
+
+    # Install the dependencies for running keystone
+    $ pip install -r tools/pip-requires
+
+    # Install the dependencies for developing, testing, and running keystone
+    $ pip install -r tools/pip-requires-test
+	
     # Fake-install the project by symlinking Keystone into your Python site-packages
     $ python setup.py develop
+	
+
+Verifying Keystone is set up
+============================
+
+Once set up, either directly or within a virtualenv, you should be able to invoke python and import
+the libraries. If you're using a virtualenv, don't forget to activate it::
+
+	$ source .venv/bin/activate
+	$ python
 
 You should then be able to `import keystone` from your Python shell
 without issue::
@@ -124,8 +150,7 @@ If you want to check the version of Keystone you are running:
     >>> print keystone.version.version()
     2012.1-dev
 
-
-If you can import keystone successfully, you should be ready to move on to :doc:`testing`.
+If you can import keystone successfully, you should be ready to move on to :doc:`testing` and :doc:`developing`
 
 Troubleshooting
 ===============
diff --git a/docs/source/testing.rst b/docs/source/testing.rst
deleted file mode 100644
index 82a33604..00000000
--- a/docs/source/testing.rst
+++ /dev/null
@@ -1,77 +0,0 @@
-================
-Testing Keystone
-================
-
-Keystone uses a number of testing methodologies to ensure correctness.
-
-Running Built-In Tests
-======================
-
-To run the full suites of tests maintained within Keystone, run::
-
-    $ ./run_tests.sh --with-progress
-
-This shows realtime feedback during test execution, and iterates over
-multiple configuration variations.
-
-This differs from how tests are executed from the continuous integration
-environment. Specifically, Jenkins doesn't care about realtime progress,
-and aborts after the first test failure (a fail-fast behavior)::
-
-    $ ./run_tests.sh
-
-Testing Schema Migrations
-=========================
-
-The application of schema migrations can be tested using SQLAlchemy Migrate’s built-in test runner, one migration at a time.
-
-.. WARNING::
-
-    This may leave your database in an inconsistent state; attempt this in non-production environments only!
-
-This is useful for testing the *next* migration in sequence (both forward & backward) in a database under version control::
-
-    $ python keystone/backends/sqlalchemy/migrate_repo/manage.py test --url=sqlite:///test.db --repository=keystone/backends/sqlalchemy/migrate_repo/
-
-This command refers to a SQLite database used for testing purposes. Depending on the migration, this command alone does not make assertions as to the integrity of your data during migration.
-
-Writing Tests
-=============
-
-Tests are maintained in the ``keystone.test`` module. Unit tests are
-isolated from functional tests.
-
-Functional Tests
-----------------
-
-The ``keystone.test.functional.common`` module provides a ``unittest``-based
-``httplib`` client which you can extend and use for your own tests.
-Generally, functional tests should serve to illustrate intended use cases
-and API behaviors. To help make your tests easier to read, the test client:
-
-- Authenticates with a known user name and password combination
-- Asserts 2xx HTTP status codes (unless told otherwise)
-- Abstracts keystone REST verbs & resources into single function calls
-
-Testing Multiple Configurations
--------------------------------
-
-Several variations of the default configuration are iterated over to
-ensure test coverage of mutually exclusive featuresets, such as the
-various backend options.
-
-These configuration templates are maintained in ``keystone/test/etc`` and
-are iterated over by ``run_tests.py``.
-
-Further Testing
-===============
-
-devstack_ is the *best* way to quickly deploy keystone with the rest of the
-OpenStack universe and should be critical step in your development workflow!
-
-You may also be interested in either the `OpenStack Continuous Integration Project`_
-or the `OpenStack Integration Testing Project`_.
-
-.. _devstack: http://devstack.org/
-.. _OpenStack Continuous Integration Project: https://github.com/openstack/openstack-ci
-.. _OpenStack Integration Testing Project: https://github.com/openstack/openstack-integration-tests