From f8ba5af130b7ec2d2ec8c0abcadbc27275467ab8 Mon Sep 17 00:00:00 2001 From: Monty Taylor Date: Tue, 28 Feb 2012 00:46:14 -0800 Subject: Align with project configs. * docs in doc/ rather than docs/ * write out changelog from git * freeze requirements file Change-Id: If28d5414f7b2747fd6835546c45e1acfac8a3563 --- docs/source/_templates/.placeholder | 0 docs/source/_theme/layout.html | 86 ---- docs/source/_theme/theme.conf | 5 - docs/source/api_curl_examples.rst | 442 ----------------- docs/source/architecture.rst | 273 ----------- docs/source/community.rst | 92 ---- docs/source/conf.py | 274 ----------- docs/source/configuration.rst | 536 --------------------- docs/source/configuringservices.rst | 285 ----------- docs/source/developing.rst | 172 ------- docs/source/images/authComp.svg | 174 ------- docs/source/images/graphs_305.svg | 41 -- docs/source/images/graphs_authComp.svg | 48 -- docs/source/images/graphs_authCompDelegate.svg | 53 -- docs/source/images/graphs_both.svg | 36 -- .../images/graphs_delegate_forbiden_basic.svg | 53 -- .../images/graphs_delegate_forbiden_proxy.svg | 52 -- .../source/images/graphs_delegate_reject_basic.svg | 55 --- .../source/images/graphs_delegate_reject_oauth.svg | 56 --- .../images/graphs_delegate_unimplemented.svg | 53 -- docs/source/images/graphs_mapper.svg | 73 --- docs/source/images/graphs_proxyAuth.svg | 51 -- docs/source/images/images_layouts.svg | 200 -------- docs/source/index.rst | 80 --- docs/source/man/keystone-all.rst | 83 ---- docs/source/man/keystone-manage.rst | 97 ---- docs/source/middleware_architecture.rst | 529 -------------------- docs/source/nova-api-paste.rst | 143 ------ docs/source/old/backends.rst | 188 -------- docs/source/old/controllingservers.rst | 288 ----------- docs/source/old/endpoints.rst | 430 ----------------- docs/source/old/extensions.rst | 183 ------- docs/source/old/middleware.rst | 169 ------- docs/source/old/migration.rst | 126 ----- docs/source/old/releases.rst | 36 -- docs/source/old/services.rst | 92 ---- docs/source/old/ssl.rst | 118 ----- docs/source/setup.rst | 171 ------- docs/source/static/basic.css | 416 ---------------- docs/source/static/default.css | 230 --------- docs/source/static/jquery.tweet.js | 154 ------ docs/source/static/tweaks.css | 65 --- 42 files changed, 6708 deletions(-) delete mode 100644 docs/source/_templates/.placeholder delete mode 100644 docs/source/_theme/layout.html delete mode 100644 docs/source/_theme/theme.conf delete mode 100644 docs/source/api_curl_examples.rst delete mode 100644 docs/source/architecture.rst delete mode 100644 docs/source/community.rst delete mode 100644 docs/source/conf.py delete mode 100644 docs/source/configuration.rst delete mode 100644 docs/source/configuringservices.rst delete mode 100644 docs/source/developing.rst delete mode 100644 docs/source/images/authComp.svg delete mode 100644 docs/source/images/graphs_305.svg delete mode 100644 docs/source/images/graphs_authComp.svg delete mode 100644 docs/source/images/graphs_authCompDelegate.svg delete mode 100644 docs/source/images/graphs_both.svg delete mode 100644 docs/source/images/graphs_delegate_forbiden_basic.svg delete mode 100644 docs/source/images/graphs_delegate_forbiden_proxy.svg delete mode 100644 docs/source/images/graphs_delegate_reject_basic.svg delete mode 100644 docs/source/images/graphs_delegate_reject_oauth.svg delete mode 100644 docs/source/images/graphs_delegate_unimplemented.svg delete mode 100644 docs/source/images/graphs_mapper.svg delete mode 100644 docs/source/images/graphs_proxyAuth.svg delete mode 100644 docs/source/images/images_layouts.svg delete mode 100644 docs/source/index.rst delete mode 100644 docs/source/man/keystone-all.rst delete mode 100644 docs/source/man/keystone-manage.rst delete mode 100644 docs/source/middleware_architecture.rst delete mode 100644 docs/source/nova-api-paste.rst delete mode 100644 docs/source/old/backends.rst delete mode 100644 docs/source/old/controllingservers.rst delete mode 100644 docs/source/old/endpoints.rst delete mode 100644 docs/source/old/extensions.rst delete mode 100644 docs/source/old/middleware.rst delete mode 100644 docs/source/old/migration.rst delete mode 100644 docs/source/old/releases.rst delete mode 100644 docs/source/old/services.rst delete mode 100644 docs/source/old/ssl.rst delete mode 100644 docs/source/setup.rst delete mode 100644 docs/source/static/basic.css delete mode 100644 docs/source/static/default.css delete mode 100644 docs/source/static/jquery.tweet.js delete mode 100644 docs/source/static/tweaks.css (limited to 'docs/source') diff --git a/docs/source/_templates/.placeholder b/docs/source/_templates/.placeholder deleted file mode 100644 index e69de29b..00000000 diff --git a/docs/source/_theme/layout.html b/docs/source/_theme/layout.html deleted file mode 100644 index e3eb54b7..00000000 --- a/docs/source/_theme/layout.html +++ /dev/null @@ -1,86 +0,0 @@ -{% extends "sphinxdoc/layout.html" %} -{% set css_files = css_files + ['_static/tweaks.css'] %} -{% set script_files = script_files + ['_static/jquery.tweet.js'] %} -{% block extrahead %} - -{% endblock %} - -{%- macro sidebar() %} - {%- if not embedded %}{% if not theme_nosidebar|tobool %} -
-
- {%- block sidebarlogo %} - {%- if logo %} - - {%- endif %} - {%- endblock %} - {%- block sidebartoc %} - {%- if display_toc %} -

{{ _('Table Of Contents') }}

- {{ toc }} - {%- endif %} - {%- endblock %} - {%- block sidebarrel %} - {%- if prev %} -

{{ _('Previous topic') }}

-

{{ prev.title }}

- {%- endif %} - {%- if next %} -

{{ _('Next topic') }}

-

{{ next.title }}

- {%- endif %} - {%- endblock %} - {%- block sidebarsourcelink %} - {%- if show_source and has_source and sourcename %} -

{{ _('This Page') }}

- - {%- endif %} - {%- endblock %} - {%- if customsidebar %} - {% include customsidebar %} - {%- endif %} - {%- block sidebarsearch %} - {%- if pagename != "search" %} - - - {%- endif %} - - {%- if pagename == "index" %} -

{{ _('Twitter Feed') }}

- - {%- endif %} - - - {%- endblock %} -
-
- {%- endif %}{% endif %} -{%- endmacro %} diff --git a/docs/source/_theme/theme.conf b/docs/source/_theme/theme.conf deleted file mode 100644 index e039fe01..00000000 --- a/docs/source/_theme/theme.conf +++ /dev/null @@ -1,5 +0,0 @@ -[theme] -inherit = sphinxdoc -stylesheet = sphinxdoc.css -pygments_style = friendly - diff --git a/docs/source/api_curl_examples.rst b/docs/source/api_curl_examples.rst deleted file mode 100644 index 529dec5e..00000000 --- a/docs/source/api_curl_examples.rst +++ /dev/null @@ -1,442 +0,0 @@ -.. - Copyright 2011-2012 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 deleted file mode 100644 index b6498a08..00000000 --- a/docs/source/architecture.rst +++ /dev/null @@ -1,273 +0,0 @@ -.. - Copyright 2011-2012 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. - -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. - ------------- -The Services ------------- - -Keystone is organized as a group of internal services exposed on one or many -endpoints. Many of these services are used in a combined fashion by the -frontend, for example an authenticate call will validate user/tenant -credentials with the Identity service and, upon success, create and return a -token with the Token service. - - -Identity --------- - -The Identity service provides auth credential validation and data about Users, -Tenants and Roles, as well as any associated metadata. - -In the basic case all this data is managed by the service, allowing the service -to manage all the CRUD associated with the data. - -In other cases, this data is pulled, by varying degrees, from an authoritative -backend service. An example of this would be when backending on LDAP. See -`LDAP Backend` below for more details. - - -Token ------ - -The Token service validates and manages Tokens used for authenticating requests -once a user/tenant's credentials have already been verified. - - -Catalog -------- - -The Catalog service provides an endpoint registry used for endpoint discovery. - - -Policy ------- - -The Policy service provides a rule-based authorization engine and the -associated rule management interface. - ------------------------- -Application Construction ------------------------- - -Keystone is an HTTP front-end to several services. Like other OpenStack -applications, this is done using python WSGI interfaces and applications are -configured together using Paste_. The application's HTTP endpoints are made up -of pipelines of WSGI middleware, such as:: - - [pipeline:public_api] - pipeline = token_auth admin_token_auth json_body debug ec2_extension public_service - -These in turn use a subclass of :mod:`keystone.common.wsgi.ComposingRouter` to -link URLs to Controllers (a subclass of -:mod:`keystone.common.wsgi.Application`). Within each Controller, one or more -Managers are loaded (for example, see :mod:`keystone.catalog.core.Manager`), -which are thin wrapper classes which load the appropriate service driver based -on the keystone configuration. - -* Identity - * :mod:`keystone.identity.core.TenantController` - * :mod:`keystone.identity.core.UserController` - * :mod:`keystone.identity.core.RoleController` - -* Catalog - * :mod:`keystone.catalog.core.ServiceController` - * :mod:`keystone.service.VersionController` - -* Token - * :mod:`keystone.service.TokenController` - -* Misc - * :mod:`keystone.service.ExtensionsController` - -At this time, the policy service and associated manager is not exposed as a URL -frontend, and has no associated Controller class. - - -.. _Paste: http://pythonpaste.org/ - ----------------- -Service Backends ----------------- - -Each of the services can configured to use a backend to allow Keystone to fit a -variety of environments and needs. The backend for each service is defined in -the keystone.conf file with the key ``driver`` under a group associated with -each service. - -A general class under each backend named ``Driver`` exists to provide an -abstract base class for any implementations, identifying the expected service -implementations. The drivers for the services are: - -* :mod:`keystone.identity.core.Driver` -* :mod:`keystone.token.core.Driver` - -If you implement a backend driver for one of the keystone services, you're -expected to subclass from these classes. The default response for the defined -apis in these Drivers is to raise a :mod:`keystone.service.TokenController`. - -KVS Backend ------------ - -A simple backend interface meant to be further backended on anything that can -support primary key lookups, the most trivial implementation being an in-memory -dict. - -Supports all features of the general data model. - - -SQL Backend ------------ - -A SQL based backend using SQLAlchemy to store data persistently. The -keystone-manage command introspects the backends to identify SQL based backends -when running "db_sync" to establish or upgrade schema. If the backend driver -has a method db_sync(), it will be invoked to sync and/or migrate schema. - - -PAM Backend ------------ - -Extra simple backend that uses the current system's PAM service to authenticate, -providing a one-to-one relationship between Users and Tenants with the `root` -User also having the 'admin' role. - - -Templated Backend ------------------ - -Largely designed for a common use case around service catalogs in the Keystone -project, a Catalog backend that simply expands pre-configured templates to -provide catalog data. - -Example paste.deploy config (uses $ instead of % to avoid ConfigParser's -interpolation):: - - [DEFAULT] - catalog.RegionOne.identity.publicURL = http://localhost:$(public_port)s/v2.0 - catalog.RegionOne.identity.adminURL = http://localhost:$(public_port)s/v2.0 - catalog.RegionOne.identity.internalURL = http://localhost:$(public_port)s/v2.0 - catalog.RegionOne.identity.name = 'Identity Service' - ----------- -Data Model ----------- - -Keystone was designed from the ground up to be amenable to multiple styles of -backends and as such many of the methods and data types will happily accept -more data than they know what to do with and pass them on to a backend. - -There are a few main data types: - - * **User**: has account credentials, is associated with one or more tenants - * **Tenant**: unit of ownership in openstack, contains one or more users - * **Role**: a first-class piece of metadata associated with many user-tenant pairs. - * **Token**: identifying credential associated with a user or user and tenant - * **Extras**: bucket of key-value metadata associated with a user-tenant pair. - * **Rule**: describes a set of requirements for performing an action. - -While the general data model allows a many-to-many relationship between Users -and Tenants and a many-to-one relationship between Extras and User-Tenant pairs, -the actual backend implementations take varying levels of advantage of that -functionality. - - ----------------- -Approach to CRUD ----------------- - -While it is expected that any "real" deployment at a large company will manage -their users, tenants and other metadata in their existing user systems, a -variety of CRUD operations are provided for the sake of development and testing. - -CRUD is treated as an extension or additional feature to the core feature set -in that it is not required that a backend support it. It is expected that -backends for services that don't support the CRUD operations will raise a -:mod:`NotImplementedError`. - - ----------------------------------- -Approach to Authorization (Policy) ----------------------------------- - -Various components in the system require that different actions are allowed -based on whether the user is authorized to perform that action. - -For the purposes of Keystone there are only a couple levels of authorization -being checked for: - - * Require that the performing user is considered an admin. - * Require that the performing user matches the user being referenced. - -Other systems wishing to use the policy engine will require additional styles -of checks and will possibly write completely custom backends. Backends included -in Keystone are: - - -Trivial True ------------- - -Allows all actions. - - -Simple Match ------------- - -Given a list of matches to check for, simply verify that the credentials -contain the matches. For example:: - - credentials = {'user_id': 'foo', 'is_admin': 1, 'roles': ['nova:netadmin']} - - # An admin only call: - policy_api.can_haz(('is_admin:1',), credentials) - - # An admin or owner call: - policy_api.can_haz(('is_admin:1', 'user_id:foo'), - credentials) - - # A netadmin call: - policy_api.can_haz(('roles:nova:netadmin',), - credentials) - - -Credentials are generally built from the user metadata in the 'extras' part -of the Identity API. So, adding a 'role' to the user just means adding the role -to the user metadata. - - -Capability RBAC ---------------- - -(Not yet implemented.) - -Another approach to authorization can be action-based, with a mapping of roles -to which capabilities are allowed for that role. For example:: - - credentials = {'user_id': 'foo', 'is_admin': 1, 'roles': ['nova:netadmin']} - - # add a policy - policy_api.add_policy('action:nova:add_network', ('roles:nova:netadmin',)) - - policy_api.can_haz(('action:nova:add_network',), credentials) - - -In the backend this would look up the policy for 'action:nova:add_network' and -then do what is effectively a 'Simple Match' style match against the creds. diff --git a/docs/source/community.rst b/docs/source/community.rst deleted file mode 100644 index 975d1bdc..00000000 --- a/docs/source/community.rst +++ /dev/null @@ -1,92 +0,0 @@ -.. - Copyright 2011-2012 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. - -================ -Getting Involved -================ - -The OpenStack community is a very friendly group and there are places online to -join in with the community. Feel free to ask questions. This document points -you to some of the places where you can communicate with people. - -How to Join the Community -========================= - -Our community welcomes all people interested in open source cloud computing, -and there are no formal membership requirements. The best way to join the -community is to talk with others online or at a meetup and offer contributions -through Launchpad_, the wiki_, or blogs. We welcome all types of contributions, - -from blueprint designs to documentation to testing to deployment scripts. - -.. _Launchpad: https://launchpad.net/keystone -.. _wiki: http://wiki.openstack.org/ - -#openstack on Freenode IRC Network ----------------------------------- - -There is a very active chat channel at ``_. This -is usually the best place to ask questions and find your way around. IRC stands -for Internet Relay Chat and it is a way to chat online in real time. You can -also ask a question and come back to the log files to read the answer later. -Logs for the #openstack IRC channel are stored at -``_. - - -OpenStack Wiki --------------- - -The wiki is a living source of knowledge. It is edited by the community, and -has collections of links and other sources of information. Typically the pages -are a good place to write drafts for specs or documentation, describe a -blueprint, or collaborate with others. - -`OpenStack Wiki `_ - -* `useful keystone project links `_ - -Keystone on Launchpad ---------------------- - -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 - -* `Keystone Project Page on Launchpad `_ -* `Keystone Source Repository on GitHub `_ - -OpenStack Blog --------------- - -The OpenStack blog includes a weekly newsletter that aggregates OpenStack news -from around the internet, as well as providing inside information on upcoming -events and posts from OpenStack contributors. - -`OpenStack Blog `_ - -See also: `Planet OpenStack `_, 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 `_. - - -Twitter -------- - -Because all the cool kids do it: `@openstack `_. -Also follow the `#openstack `_ -tag for relevant tweets. - diff --git a/docs/source/conf.py b/docs/source/conf.py deleted file mode 100644 index fc7d9476..00000000 --- a/docs/source/conf.py +++ /dev/null @@ -1,274 +0,0 @@ -# -*- coding: utf-8 -*- -# -# keystone documentation build configuration file, created by -# sphinx-quickstart on Mon Jan 9 12:02:59 2012. -# -# 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. - -import sys -import os - -# 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('../..')) - -# -- 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.intersphinx', 'sphinx.ext.todo', 'sphinx.ext.coverage'] -extensions = ['sphinx.ext.autodoc', - 'sphinx.ext.todo', -# 'sphinx.ect.intersphinx', - 'sphinx.ext.coverage'] - -todo_include_todos = True - -# Add any paths that contain templates here, relative to this directory. -templates_path = [] -if os.getenv('HUDSON_PUBLISH_DOCS'): - templates_path = ['_ga', '_templates'] -else: - templates_path = ['_templates'] - -# The suffix of source filenames. -source_suffix = '.rst' - -# The encoding of source files. -#source_encoding = 'utf-8-sig' - -# The master toctree document. -master_doc = 'index' - -# General information about the project. -project = u'keystone' -copyright = u'2012, OpenStack, LLC' - -# 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 = '2012.1' -# The full version, including alpha/beta/rc tags. -release = '2012.1-dev' - -# 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. -exclude_patterns = [] - -# 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 = True - -# The name of the Pygments (syntax highlighting) style to use. -pygments_style = 'sphinx' - -# A list of ignored prefixes for module index sorting. -modindex_common_prefix = ['keystone.'] - -# -- Options for man page output -------------------------------------------- - -# Grouping the document tree for man pages. -# List of tuples 'sourcefile', 'target', u'title', u'Authors name', 'manual' - -man_pages = [ - ('man/keystone-manage', 'keystone-manage', u'Keystone Management Utility', - [u'OpenStack'], 1), - ('man/keystone-all', 'keystone-all', u'Keystone Startup Command', - [u'OpenStack'], 1), - ] - - -# -- Options for HTML output --------------------------------------------------- - -# The theme to use for HTML and HTML Help pages. See the documentation for -# a list of builtin themes. -html_theme_path = ["."] -html_theme = '_theme' - -# 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 -# " v 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". -html_static_path = ['static', 'images'] - -# 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 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 = 'keystonedoc' - - -# -- 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', 'keystone.tex', u'Keystone Documentation', - u'OpenStack', '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', 'keystone', u'Keystone Documentation', - [u'OpenStack'], 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', 'keystone', u'Keystone Documentation', - u'OpenStack', 'keystone', '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' - - -# Example configuration for intersphinx: refer to the Python standard library. -#intersphinx_mapping = {'http://docs.python.org/': None} -intersphinx_mapping = {'python': ('http://docs.python.org/', None), - 'nova': ('http://nova.openstack.org', None), - 'swift': ('http://swift.openstack.org', None), - 'glance': ('http://glance.openstack.org', None)} diff --git a/docs/source/configuration.rst b/docs/source/configuration.rst deleted file mode 100644 index 1e99f934..00000000 --- a/docs/source/configuration.rst +++ /dev/null @@ -1,536 +0,0 @@ -.. - Copyright 2011-2012 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. - -==================== -Configuring Keystone -==================== - -.. toctree:: - :maxdepth: 1 - - man/keystone-manage - man/keystone-all - -Once Keystone is installed, it is configured via a primary configuration file -(``etc/keystone.conf``), possibly a separate logging configuration file, and -initializing data into keystone using the command line client. - - -Keystone Configuration File -=========================== - -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]``, ``[sql]``, ``[ec2]`` and then drivers -for the various services are included under their individual sections. - -The services 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 - -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`` - -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. - -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 --------------------------- - -* ``etc/keystone.conf`` -* ``etc/logging.conf.sample`` - -Running Keystone -================ - -Running keystone is simply starting the services by using the command:: - - keystone-all - -Invoking this command starts up two wsgi.Server instances, configured by the -``keystone.conf`` file as described above. One of these wsgi 'servers' is -``admin`` (the administration API) and the other is ``main`` (the -primary/public API interface). Both of these run in a single process. - -Migrating from legacy versions of keystone -========================================== -Migration support is provided for the following legacy keystone versions: - -* diablo-5 -* stable/diablo -* essex-2 -* essex-3 - -To migrate from legacy versions of keystone, use the following steps: - -Step 1: Configure keystone.conf -------------------------------- -It is important that the database that you specify be different from the one -containing your existing install. - -Step 2: db_sync your new, empty database ----------------------------------------- -Run the following command to configure the most recent schema in your new -keystone installation:: - - keystone-manage db_sync - -Step 3: Import your legacy data -------------------------------- -Use the following command to import your old data:: - - keystone-manage import_legacy [db_url, e.g. 'mysql://root@foobar/keystone'] - -Specify db_url as the connection string that was present in your old -keystone.conf file. - -Step 4: Import your legacy service catalog ------------------------------------------- -While the older keystone stored the service catalog in the database, -the updated version configures the service catalog using a template file. -An example service catalog template file may be found in -etc/default_catalog.templates. - -To import your legacy catalog, run this command:: - - keystone-manage export_legacy_catalog \ - [db_url e.g. 'mysql://root@foobar/keystone'] > \ - [path_to_templates e.g. 'etc/default_catalog.templates'] - -After executing this command, you will need to restart the keystone service to -see your changes. - -Migrating from Nova Auth -======================== -Migration of users, projects (aka tenants), roles and EC2 credentials -is supported for the Diablo and Essex releases of Nova. To migrate your auth -data from Nova, use the following steps: - -Step 1: Export your data from Nova ----------------------------------- -Use the following command to export your data fron Nova:: - - nova-manage export auth > /path/to/dump - -It is important to redirect the output to a file so it can be imported -in a later step. - -Step 2: db_sync your new, empty database ----------------------------------------- -Run the following command to configure the most recent schema in your new -keystone installation:: - - keystone-manage db_sync - -Step 3: Import your data to Keystone ------------------------------------- -To import your Nova auth data from a dump file created with nova-manage, -run this command:: - - keystone-manage import_nova_auth [dump_file, e.g. /path/to/dump] - -.. note:: - Users are added to Keystone with the user id from Nova as the user name. - Nova's projects are imported with the project id as the tenant name. The - password used to authenticate a user in Keystone will be the api key - (also EC2 access key) used in Nova. Users also lose any administrative - privileges they had in Nova. The necessary admin role must be explicitly - re-assigned to each user. - -.. note:: - Users in Nova's auth system have a single set of EC2 credentials that - works with all projects (tenants) that user can access. In Keystone, these - credentials are scoped to a single user/tenant pair. In order to use the - same secret keys from Nova, you must prefix each corresponding access key - with the id of the project used in Nova. For example, if you had access - to the 'Beta' project in your Nova installation with the access/secret - keys 'XXX'/'YYY', you should use 'Beta:XXX'/'YYY' in Keystone. These - credentials are active once your migration is complete. - -Initializing Keystone -===================== - -keystone-manage is designed to execute commands that cannot be administered -through the normal REST api. At the moment, the following calls are supported: - -* ``db_sync``: Sync the database. -* ``import_legacy``: Import a legacy (pre-essex) version of the db. -* ``export_legacy_catalog``: Export service catalog from a legacy (pre-essex) db. -* ``import_nova_auth``: Load auth data from a dump created with keystone-manage. - - -Generally, the following is the first step after a source installation:: - - keystone-manage db_sync - -Invoking keystone-manage by itself will give you additional usage information. - -Adding Users, Tenants, and Roles with python-keystoneclient -=========================================================== - -User, tenants, and roles must be administered using admin credentials. -There are two ways to configure python-keystoneclient to use admin -credentials, using the token auth method, or password auth method. - -Token Auth Method ------------------ -To use keystone client using token auth, set the following flags - -* ``--endpoint SERVICE_ENDPOINT`` : allows you to specify the keystone endpoint to communicate - with. The default endpoint is http://localhost:35357/v2.0' -* ``--token SERVICE_TOKEN`` : your administrator service token. - -Password Auth Method --------------------- - -* ``--username OS_USERNAME`` : allows you to specify the keystone endpoint to communicate - with. For example, http://localhost:35357/v2.0' -* ``--password OS_PASSWORD`` : Your administrator password -* ``--tenant_name OS_TENANT_NAME`` : Name of your tenant -* ``--auth_url OS_AUTH_URL`` : url of your keystone auth server, for example -http://localhost:5000/v2.0' - -Example usage -------------- -``keystone`` is set up to expect commands in the general form of -``keystone`` ``command`` ``argument``, followed by flag-like keyword arguments to -provide additional (often optional) information. For example, the command -``user-list`` and ``tenant-create`` can be invoked as follows:: - - # Using token auth env variables - export SERVICE_ENDPOINT=http://127.0.0.1:5000/v2.0/ - export SERVICE_TOKEN=secrete_token - keystone user-list - keystone tenant-create --name=demo - - # Using token auth flags - keystone --token=secrete --endpoint=http://127.0.0.1:5000/v2.0/ user-list - keystone --token=secrete --endpoint=http://127.0.0.1:5000/v2.0/ tenant-create --name=demo - - # Using user + password + tenant_name env variables - export OS_USERNAME=admin - export OS_PASSWORD=secrete - export OS_TENANT_NAME=admin - keystone user-list - keystone tenant-create --name=demo - - # Using user + password + tenant_name flags - keystone --username=admin --password=secrete --tenant_name=admin user-list - keystone --username=admin --password=secrete --tenant_name=admin tenant-create --name=demo - -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 associated with more than one tenant, and each tenant - user pairing can -have a role associated with it. - -``tenant-create`` -^^^^^^^^^^^^^^^^^ - -keyword arguments - -* name -* description (optional, defaults to None) -* enabled (optional, defaults to True) - -example:: - - keystone tenant-create --name=demo - -creates a tenant named "demo". - -``tenant-delete`` -^^^^^^^^^^^^^^^^^ - -arguments - -* tenant_id - -example:: - - keystone tenant-delete f2b7b39c860840dfa47d9ee4adffa0b3 - -``tenant-enable`` -^^^^^^^^^^^^^^^^^ - -arguments - -* tenant_id - -example:: - - keystone tenant-enable f2b7b39c860840dfa47d9ee4adffa0b3 - -``tenant-disable`` -^^^^^^^^^^^^^^^^^ - -arguments - -* tenant_id - -example:: - - keystone tenant-disable f2b7b39c860840dfa47d9ee4adffa0b3 - -Users ------ - -``user-create`` -^^^^^^^^^^^^^^^ - -keyword arguments - -* name -* pass -* email -* default_tenant (optional, defaults to None) -* enabled (optional, defaults to True) - -example:: - - keystone user-create - --name=admin \ - --pass=secrete \ - --email=admin@example.com - -``user-delete`` -^^^^^^^^^^^^^^^ - -keyword arguments - -* user - -example:: - - keystone user-delete f2b7b39c860840dfa47d9ee4adffa0b3 - -``user-list`` -^^^^^^^^^^^^^ - -list users in the system, optionally by a specific tenant (identified by tenant_id) - -arguments - -* tenant_id (optional, defaults to None) - -example:: - - keystone user-list - -``user-update-email`` -^^^^^^^^^^^^^^^^^^^^^ - -arguments -* user_id -* email - - -example:: - - keystone user-update-email 03c84b51574841ba9a0d8db7882ac645 "someone@somewhere.com" - -``user-enable`` -^^^^^^^^^^^^^^^^^^^^^^^ - -arguments - -* user_id - -example:: - - keystone user-enable 03c84b51574841ba9a0d8db7882ac645 - -``user-disable`` -^^^^^^^^^^^^^^^^^^^^^^^ - -arguments - -* user_id - -example:: - - keystone user-disable 03c84b51574841ba9a0d8db7882ac645 - - -``user-update-password`` -^^^^^^^^^^^^^^^^^^^^^^^^ - -arguments - -* user_id -* password - -example:: - - keystone user-update-password 03c84b51574841ba9a0d8db7882ac645 foo - -Roles ------ - -``role-create`` -^^^^^^^^^^^^^^^ - -arguments - -* name - -exmaple:: - - keystone role-create --name=demo - -``role-delete`` -^^^^^^^^^^^^^^^ - -arguments - -* role_id - -exmaple:: - - keystone role-delete 19d1d3344873464d819c45f521ff9890 - -``role-list`` -^^^^^^^^^^^^^^^ - -exmaple:: - - keystone role-list - -``role-get`` -^^^^^^^^^^^^ - -arguments - -* role_id - -exmaple:: - - keystone role-get role=19d1d3344873464d819c45f521ff9890 - - -``add-user-role`` -^^^^^^^^^^^^^^^^^^^^^^ - -arguments - -* role_id -* user_id -* tenant_id - -example:: - - keystone role add-user-role \ - 3a751f78ef4c412b827540b829e2d7dd \ - 03c84b51574841ba9a0d8db7882ac645 \ - 20601a7f1d94447daa4dff438cb1c209 - -``remove-user-role`` -^^^^^^^^^^^^^^^^^^^^^^^^^ - -arguments - -* role_id -* user_id -* tenant_id - -example:: - - keystone remove-user-role \ - 19d1d3344873464d819c45f521ff9890 \ - 08741d8ed88242ca88d1f61484a0fe3b \ - 20601a7f1d94447daa4dff438cb1c209 - -Services --------- - -``service-create`` -^^^^^^^^^^^^^^^^^^ - -keyword arguments - -* name -* type -* description - -example:: - - keystone service create \ - --name=nova \ - --type=compute \ - --description="Nova Compute Service" - -``service-list`` -^^^^^^^^^^^^^^^^ - -arguments - -* service_id - -example:: - - keystone service-list - -``service-get`` -^^^^^^^^^^^^^^^ - -arguments - -* service_id - -example:: - - keystone service-get 08741d8ed88242ca88d1f61484a0fe3b - -``service-delete`` -^^^^^^^^^^^^^^^^^^ - -arguments - -* service_id - -example:: - - keystone service-delete 08741d8ed88242ca88d1f61484a0fe3b - diff --git a/docs/source/configuringservices.rst b/docs/source/configuringservices.rst deleted file mode 100644 index bfbada65..00000000 --- a/docs/source/configuringservices.rst +++ /dev/null @@ -1,285 +0,0 @@ -.. - Copyright 2011-2012 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. - -========================================== -Configuring Services to work with Keystone -========================================== - -.. toctree:: - :maxdepth: 1 - - nova-api-paste - middleware_architecture - -Once Keystone is installed and running (see :doc:`configuration`), services -need to be configured to work with it. To do this, we primarily install and -configure middleware for the OpenStack service to handle authentication tasks -or otherwise interact with Keystone. - -In general: -* Clients making calls to the service will pass in an authentication token. -* The Keystone middleware will look for and validate that token, taking the - appropriate action. -* It will also retrive additional information from the token such as user - name, id, tenant name, id, roles, etc... - -The middleware will pass those data down to the service as headers. More -details on the architecture of that setup is described in -:doc:`middleware_architecture` - -Setting up credentials -====================== - -Admin Token ------------ - -For a default installation of Keystone, before you can use the REST API, you -need to define an authorization token. This is configured in ``keystone.conf`` -file under the section ``[DEFAULT]``. In the sample file provided with the -keystone project, the line defining this token is - - [DEFAULT] - admin_token = ADMIN - -This configured token is a "shared secret" between keystone and other -openstack services (for example: nova, swift, glance, or horizon), and will -need to be set the same between those services in order for keystone services -to function correctly. - -Setting up tenants, users, and roles ------------------------------------- - -You need to minimally define a tenant, user, and role to link the tenant and -user as the most basic set of details to get other services authenticating -and authorizing with keystone. See doc:`configuration` for a walk through on -how to create tenants, users, and roles. - -Setting up services -=================== - -Defining Services ------------------ - -Keystone also acts as a service catalog to let other OpenStack systems know -where relevant API endpoints exist for OpenStack Services. The OpenStack -Dashboard, in particular, uses this heavily - and this **must** be configured -for the OpenStack Dashboard to properly function. - -Here's how we define the services:: - - keystone service-create --name=nova \ - --type=compute \ - --description="Nova Compute Service" - keystone service-create --name=ec2 \ - --type=ec2 \ - --description="EC2 Compatibility Layer" - keystone service-create --name=glance \ - --type=image \ - --description="Glance Image Service" - keystone service-create --name=keystone \ - --type=identity \ - --description="Keystone Identity Service" - keystone service-create --name=swift \ - --type=object-store \ - --description="Swift Service" - -The endpoints for these services are defined in a template, an example of -which is in the project as the file ``etc/default_catalog.templates``. - -Setting Up Middleware -===================== - -Keystone Auth-Token Middleware --------------------------------- - -The Keystone auth_token middleware is a WSGI component that can be inserted in -the WSGI pipeline to handle authenticating tokens with Keystone. - -Configuring Nova to use Keystone --------------------------------- - -To configure Nova to use Keystone for authentication, the Nova API service -can be run against the api-paste file provided by Keystone. This is most -easily accomplished by setting the `--api_paste_config` flag in nova.conf to -point to `examples/paste/nova-api-paste.ini` from Keystone. This paste file -included references to the WSGI authentication middleware provided with the -keystone installation. - -When configuring Nova, it is important to create a admin service token for -the service (from the Configuration step above) and include that as the key -'admin_token' in the nova-api-paste.ini. See the documented -:doc:`nova-api-paste` file for references. - -Configuring Swift to use Keystone ---------------------------------- - -Similar to Nova, swift can be configured to use Keystone for authentication -rather than it's built in 'tempauth'. - -1. Add a service endpoint for Swift to Keystone - -2. Configure the paste file for swift-proxy (`/etc/swift/swift-proxy.conf`) - -3. Reconfigure Swift's proxy server to use Keystone instead of TempAuth. - Here's an example `/etc/swift/proxy-server.conf`:: - - [DEFAULT] - bind_port = 8888 - user = - - [pipeline:main] - pipeline = catch_errors healthcheck cache tokenauth keystone proxy-server - - [app:proxy-server] - use = egg:swift#proxy - account_autocreate = true - - [filter:keystone] - paste.filter_factory = keystone.middleware.swift_auth:filter_factory - operator_roles = admin, swiftoperator - - [filter:tokenauth] - paste.filter_factory = keystone.middleware.auth_token:filter_factory - service_port = 5000 - service_host = 127.0.0.1 - auth_port = 35357 - auth_host = 127.0.0.1 - auth_token = ADMIN - admin_token = ADMIN - - [filter:cache] - use = egg:swift#memcache - set log_name = cache - - [filter:catch_errors] - use = egg:swift#catch_errors - - [filter:healthcheck] - use = egg:swift#healthcheck - -.. Note:: - Your user needs to have the role swiftoperator or admin by default - to be able to operate on an swift account or as specified by the - variable `operator_roles`. - -4. Restart swift - -5. Verify that keystone is providing authentication to Swift - - $ swift -V 2 -A http://localhost:5000/v2.0/tokens -U admin:admin -K ADMIN stat - -Configuring Swift with S3 emuluation to use Keystone ----------------------------------------------------- - -Keystone support validating S3 tokens using the same tokens as the -generated EC2 tokens. After you have generated a pair of EC2 access -token and secret you can access your swift cluster directly with the -S3 api. - -1. Configure the paste file for swift-proxy - (`/etc/swift/swift-proxy.conf` to use S3token and Swift3 - middleware. - - Here's an example:: - - [DEFAULT] - bind_port = 8080 - user = - - [pipeline:main] - pipeline = catch_errors healthcheck cache swift3 s3token tokenauth keystone proxy-server - - [app:proxy-server] - use = egg:swift#proxy - account_autocreate = true - - [filter:catch_errors] - use = egg:swift#catch_errors - - [filter:healthcheck] - use = egg:swift#healthcheck - - [filter:cache] - use = egg:swift#memcache - - [filter:swift3] - use = egg:swift#swift3 - - [filter:keystone] - paste.filter_factory = keystone.middleware.swift_auth:filter_factory - operator_roles = admin, swiftoperator - - [filter:s3token] - paste.filter_factory = keystone.middleware.s3_token:filter_factory - service_port = 5000 - service_host = 127.0.0.1 - auth_port = 35357 - auth_host = 127.0.0.1 - auth_protocol = http - auth_token = ADMIN - admin_token = ADMIN - - [filter:tokenauth] - paste.filter_factory = keystone.middleware.auth_token:filter_factory - service_port = 5000 - service_host = 127.0.0.1 - auth_port = 35357 - auth_host = 127.0.0.1 - auth_token = ADMIN - admin_token = ADMIN - -2. You can then access directly your Swift via the S3 API, here's an - example with the `boto` library:: - - import boto - import boto.s3.connection - - connection = boto.connect_s3( - aws_access_key_id='', - aws_secret_access_key='', - port=8080, - host='localhost', - is_secure=False, - calling_format=boto.s3.connection.OrdinaryCallingFormat()) - - -.. Note:: - With the S3 middleware you are connecting to the `Swift` proxy and - not to `keystone`. - -Auth-Token Middleware with Username and Password --------------------------------- - -It is also possible to configure Keystone's auth_token middleware using the -'admin_user' and 'admin_password' options. When using the 'admin_user' and -'admin_password' options the 'admin_token' parameter is optional. If -'admin_token' is specified it will by used only if the specified token is -still valid. - -Here is an example paste config filter that makes use of the 'admin_user' and -'admin_password' parameters:: - - [filter:tokenauth] - paste.filter_factory = keystone.middleware.auth_token:filter_factory - service_port = 5000 - service_host = 127.0.0.1 - auth_port = 35357 - auth_host = 127.0.0.1 - auth_token = ADMIN - admin_user = admin - admin_password = keystone123 - -It should be noted that when using this option an 'admin' tenant/role relationship is required. The admin user is granted access to to the 'admin' role via the 'admin' tenant. diff --git a/docs/source/developing.rst b/docs/source/developing.rst deleted file mode 100644 index 11207a95..00000000 --- a/docs/source/developing.rst +++ /dev/null @@ -1,172 +0,0 @@ -.. - Copyright 2011-2012 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. - -======================== -Developing with Keystone -======================== - -Contributing Code -================= - -To contribute code, sign up for a Launchpad account and sign a contributor -license agreement, available on the ``_. 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 - -Setup ------ - -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 ----------------- - -To run the keystone Admin and API server instances, use:: - - $ tools/with_venv.sh bin/keystone-all - -this runs keystone with the configuration the etc/ directory of the project. -See :doc:`configuration` for details on how Keystone is configured. By default, -keystone is configured with KVS backends, so any data entered into keystone run -in this fashion will not persist across restarts. - - -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, and which keystone itself uses to provide it's -command-line interface. - -When initially getting set up, after you've configured which databases to use, -you're probably going to need to run the following to your database schema in -place:: - - $ bin/keystone-manage db_sync - -.. _`python-keystoneclient`: https://github.com/openstack/python-keystoneclient - -Running Tests -============= - -To run the full suites of tests maintained within Keystone, run:: - - $ ./run_tests.sh - -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. - -Test Structure --------------- - -``./run_test.sh`` uses its python cohort (``run_tests.py``) to iterate -through the ``tests`` directory, using Nosetest to collect the tests and -invoke them using an OpenStack custom test running that displays the tests -as well as the time taken to -run those tests. - -Within the tests directory, the general structure of the tests is a basic -set of tests represented under a test class, and then subclasses of those -tests under other classes with different configurations to drive different -backends through the APIs. - -For example, ``test_backend.py`` has a sequence of tests under the class -``IdentityTests`` that will work with the default drivers as configured in -this projects etc/ directory. ``test_backend_sql.py`` subclasses those tests, -changing the configuration by overriding with configuration files stored in -the tests directory aimed at enabling the SQL backend for the Identity module. - -Likewise, ``test_cli.py`` takes advantage of the tests written aainst -``test_keystoneclient`` to verify the same tests function through different -drivers. - -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/common/sql/migrate_repo/manage.py test \ - --url=sqlite:///test.db \ - --repository=keystone/common/sql/migrate_repo/ - -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. - - -Writing Tests -------------- - -To add tests covering all drivers, update the base test class -(``test_backend.py``, ``test_legacy_compat.py``, and -``test_keystoneclient.py``). - -To add new drivers, subclass the ``test_backend.py`` (look towards -``test_backend_sql.py`` or ``test_backend_kvs.py`` for examples) and update the -configuration of the test class in ``setUp()``. - - -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/tempest - -Building the Documentation -========================== - -The documentation is all generated with Sphinx from within the docs directory. -To generate the full set of HTML documentation: - - cd docs - make autodoc - make html - make man - -the results are in the docs/build/html and docs/build/man directories -respectively. diff --git a/docs/source/images/authComp.svg b/docs/source/images/authComp.svg deleted file mode 100644 index d344b871..00000000 --- a/docs/source/images/authComp.svg +++ /dev/null @@ -1,174 +0,0 @@ - - - - - - - - - - image/svg+xml - - - - - - - - - - Auth - Component - - - OpenStack - Service - - - - - - - Reject - unauthenticated - requests - Forward - authenticated - requests - - - diff --git a/docs/source/images/graphs_305.svg b/docs/source/images/graphs_305.svg deleted file mode 100644 index 1dff61a6..00000000 --- a/docs/source/images/graphs_305.svg +++ /dev/null @@ -1,41 +0,0 @@ - - - - - - -Handle305 - - -AuthComp - -Auth -Component - - -Service - -OpenStack -Service - - - -Service:n->AuthComp:n - - -305 Use Proxy -To Redirect to Auth - - - -Start:sw->Service - - -Request -Service Directly - - - diff --git a/docs/source/images/graphs_authComp.svg b/docs/source/images/graphs_authComp.svg deleted file mode 100644 index 6be629c1..00000000 --- a/docs/source/images/graphs_authComp.svg +++ /dev/null @@ -1,48 +0,0 @@ - - - - - - -AuthComp - - -AuthComp - -Auth -Component - - - -AuthComp->Reject - - -Reject -Unauthenticated -Requests - - -Service - -OpenStack -Service - - -AuthComp->Service - - -Forward -Authenticated -Requests - - - -Start->AuthComp - - - - - diff --git a/docs/source/images/graphs_authCompDelegate.svg b/docs/source/images/graphs_authCompDelegate.svg deleted file mode 100644 index 4788829a..00000000 --- a/docs/source/images/graphs_authCompDelegate.svg +++ /dev/null @@ -1,53 +0,0 @@ - - - - - - -AuthCompDelegate - - -AuthComp - -Auth -Component - - - -AuthComp->Reject - - -Reject Requests -Indicated by the Service - - -Service - -OpenStack -Service - - -AuthComp->Service - - -Forward Requests -with Identiy Status - - -Service->AuthComp - - -Send Response OR -Reject Message - - - -Start->AuthComp - - - - - diff --git a/docs/source/images/graphs_both.svg b/docs/source/images/graphs_both.svg deleted file mode 100644 index 6aa87612..00000000 --- a/docs/source/images/graphs_both.svg +++ /dev/null @@ -1,36 +0,0 @@ - - - - - - -Both - - -AuthComp - -Auth -Component - - -Together - - - -Auth -Component - - -OpenStack -Service - - -AuthComp->Together:OStack:n - - - - - diff --git a/docs/source/images/graphs_delegate_forbiden_basic.svg b/docs/source/images/graphs_delegate_forbiden_basic.svg deleted file mode 100644 index dcd62b77..00000000 --- a/docs/source/images/graphs_delegate_forbiden_basic.svg +++ /dev/null @@ -1,53 +0,0 @@ - - - - - - -DelegateRejectForbidden - - - -AuthComp - -Auth -Component - - -Start->AuthComp - - -Authorization: Basic VTpQ - - -AuthComp->Start - - -403 Forbidden - - -Service - -OpenStack -Service - - -AuthComp->Service - - -Authorization: Basic dTpw -X-Authorization: Proxy U -X-Identity-Status: Confirmed - - -Service->AuthComp - - -403 Forbidden -WWW-Authenticate: Delegated - - - diff --git a/docs/source/images/graphs_delegate_forbiden_proxy.svg b/docs/source/images/graphs_delegate_forbiden_proxy.svg deleted file mode 100644 index df53212b..00000000 --- a/docs/source/images/graphs_delegate_forbiden_proxy.svg +++ /dev/null @@ -1,52 +0,0 @@ - - - - - - -DelegateForbiddnProxy - - - -AuthComp - -Auth -Component - - -Start->AuthComp - - -Authorization: Basic VTpQ - - -AuthComp->Start - - -500 Internal Error - - -Service - -OpenStack -Service - - -AuthComp->Service - - -Authorization: Basic dTpw -X-Authorization: Proxy U -X-Identity-Status: Confirmed - - -Service->AuthComp - - -403 Forbidden - - - diff --git a/docs/source/images/graphs_delegate_reject_basic.svg b/docs/source/images/graphs_delegate_reject_basic.svg deleted file mode 100644 index a33ea095..00000000 --- a/docs/source/images/graphs_delegate_reject_basic.svg +++ /dev/null @@ -1,55 +0,0 @@ - - - - - - -DelegateRejectAuthBasic - - - -AuthComp - -Auth -Component - - -Start->AuthComp - - -Authorization: Basic Yjpw - - -AuthComp->Start - - -401 Unauthorized -WWW-Authenticate: Basic -Realm="API Realm" - - -Service - -OpenStack -Service - - -AuthComp->Service - - -Authorization: Basic dTpw -X-Authorization: Proxy b -X-Identity-Status: Indeterminate - - -Service->AuthComp - - -401 Unauthorized -WWW-Authenticate: Delegated - - - diff --git a/docs/source/images/graphs_delegate_reject_oauth.svg b/docs/source/images/graphs_delegate_reject_oauth.svg deleted file mode 100644 index 760adeb6..00000000 --- a/docs/source/images/graphs_delegate_reject_oauth.svg +++ /dev/null @@ -1,56 +0,0 @@ - - - - - - -DelegateRejectAuthOAuth - - - -AuthComp - -Auth -Component - - -Start->AuthComp - - -Authorization: OAuth 000-999-222 - - -AuthComp->Start - - -401 Unauthorized -WWW-Authenticate: OAuth -Realm=’API Realm’, -Error=’invalid-token’ - - -Service - -OpenStack -Service - - -AuthComp->Service - - -Authorization: Basic dTpw -X-Authorization: Proxy -X-Identity-Status: Indeterminate - - -Service->AuthComp - - -401 Unauthorized -WWW-Authenticate: Delegated - - - diff --git a/docs/source/images/graphs_delegate_unimplemented.svg b/docs/source/images/graphs_delegate_unimplemented.svg deleted file mode 100644 index 8c4fdc6b..00000000 --- a/docs/source/images/graphs_delegate_unimplemented.svg +++ /dev/null @@ -1,53 +0,0 @@ - - - - - - -DelegateUnimplemented - - - -AuthComp - -Auth -Component - - -Start->AuthComp - - -Authorization: Basic VTpQ - - -AuthComp->Start - - -500 Internal Error - - -Service - -OpenStack -Service - - -AuthComp->Service - - -Authorization: Basic dTpw -X-Authorization: Proxy U -X-Identity-Status: Confirmed - - -Service->AuthComp - - -501 Unimplemented -WWW-Authenticate: Delegated - - - diff --git a/docs/source/images/graphs_mapper.svg b/docs/source/images/graphs_mapper.svg deleted file mode 100644 index 52c6c55b..00000000 --- a/docs/source/images/graphs_mapper.svg +++ /dev/null @@ -1,73 +0,0 @@ - - - - - - -Mapper - - - -Mapper - -Mapper - - -Start->Mapper - - - - -Auths - - - -Auth1 - - -Auth2 - - -Auth3 - - -Mapper:sw->Auths:auth1 - - - - -Mapper:s->Auths:auth2 - - - - -Mapper:se->Auths:auth3 - - - - -Service - -OpenStack -Service - - -Auths:auth1->Service - - - - -Auths:auth2->Service - - - - -Auths:auth3->Service - - - - - diff --git a/docs/source/images/graphs_proxyAuth.svg b/docs/source/images/graphs_proxyAuth.svg deleted file mode 100644 index 7b94b077..00000000 --- a/docs/source/images/graphs_proxyAuth.svg +++ /dev/null @@ -1,51 +0,0 @@ - - - - - - -ProxyAuth - - - -AuthComp - -Auth -Component - - -Start->AuthComp - - -Authorization: Basic VTpQ - - -AuthComp:w->Start - - -500 Internal Error - - -Service - -OpenStack -Service - - -AuthComp->Service - - -Authorization: Basic dTpw -X-Authorization: Proxy U - - -Service:w->AuthComp - - -403 Forbidden - - - diff --git a/docs/source/images/images_layouts.svg b/docs/source/images/images_layouts.svg deleted file mode 100644 index e7fe7a95..00000000 --- a/docs/source/images/images_layouts.svg +++ /dev/null @@ -1,200 +0,0 @@ - - - - - - image/svg+xml - - - - - - - - Auth Layouts - (a) - (b) - - - Together - - - - Together - - - Auth - Component - - - OpenStack - Service - - - - Seperate - - - - AuthComp - - Auth - Component - - - - Service - - OpenStack - Service - - - - AuthComp->Service - - - - - diff --git a/docs/source/index.rst b/docs/source/index.rst deleted file mode 100644 index a79fc8d0..00000000 --- a/docs/source/index.rst +++ /dev/null @@ -1,80 +0,0 @@ -.. - Copyright 2011-2012 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. - -==================================================== -Welcome to Keystone, the OpenStack Identity Service! -==================================================== - -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`_. - -.. _`OpenStack's Identity API`: http://docs.openstack.org/api/openstack-identity-service/2.0/content/ -.. _`end-user perspective`: http://docs.openstack.org/ - -This documentation is generated by the Sphinx toolkit and lives in the source -tree. Additional documentation on Keystone and other components of OpenStack can -be found on the `OpenStack wiki`_. Also see the :doc:`community` page for -other ways to interact with the community. - -.. _`OpenStack wiki`: http://wiki.openstack.org - -Getting Started -=============== - -.. toctree:: - :maxdepth: 1 - - setup - configuration - configuringservices - community - -Man Pages ---------- - -.. toctree:: - :maxdepth: 1 - - man/keystone - man/keystone-manage - -Developers Documentation -======================== -.. toctree:: - :maxdepth: 1 - - developing - architecture - api_curl_examples - -Code Documentation -================== -.. toctree:: - :maxdepth: 1 - - modules - -Indices and tables -================== - -* :ref:`genindex` -* :ref:`modindex` -* :ref:`search` - diff --git a/docs/source/man/keystone-all.rst b/docs/source/man/keystone-all.rst deleted file mode 100644 index fc2d68d7..00000000 --- a/docs/source/man/keystone-all.rst +++ /dev/null @@ -1,83 +0,0 @@ -======== -keystone -======== - ---------------------------- -Keystone Management Utility ---------------------------- - -:Author: keystone@lists.launchpad.net -:Date: 2010-11-16 -:Copyright: OpenStack LLC -:Version: 0.1.2 -:Manual section: 1 -:Manual group: cloud computing - -SYNOPSIS -======== - - keystone-all [options] - -DESCRIPTION -=========== - -keystone-all starts both the service and administrative APIs in a single -process to provide catalog, authorization, and authentication services for -OpenStack. - -USAGE -===== - - ``keystone-all [options]`` - -Common Options: -^^^^^^^^^^^^^^^ - -h, --help show this help message and exit - -The following configuration options are common to all keystone -programs.:: - - -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 -===== - -None - -SEE ALSO -======== - -* `Keystone `__ - -SOURCE -====== - -* Keystone source is managed in GitHub `Keystone `__ -* Keystone bugs are managed at Launchpad `Launchpad Keystone `__ diff --git a/docs/source/man/keystone-manage.rst b/docs/source/man/keystone-manage.rst deleted file mode 100644 index 91f2b9e7..00000000 --- a/docs/source/man/keystone-manage.rst +++ /dev/null @@ -1,97 +0,0 @@ -=============== -keystone-manage -=============== - ---------------------------- -Keystone Management Utility ---------------------------- - -:Author: keystone@lists.launchpad.net -:Date: 2010-11-16 -:Copyright: OpenStack LLC -:Version: 0.1.2 -:Manual section: 1 -:Manual group: cloud computing - -SYNOPSIS -======== - - keystone-manage [options] - -DESCRIPTION -=========== - -keystone-manage is the command line tool that interacts with the keystone -service to initialize and update data within Keystone. Generally, -keystone-manage is only used for operations that can not be accomplished -with through the keystone REST api, such data import/export and schema -migrations. - - -USAGE -===== - - ``keystone-manage [options] action [additional args]`` - - -General keystone-manage options: --------------------------------- - -* ``--help`` : display verbose help output. - -Invoking keystone-manage by itself will give you some usage information. - -Available keystone-manage commands: - db_sync: Sync the database. - import_legacy: Import a legacy (pre-essex) version of the db. - export_legacy_catalog: Export service catalog from a legacy (pre-essex) db. - - -OPTIONS -======= - -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. - -FILES -===== - -None - -SEE ALSO -======== - -* `Keystone `__ - -SOURCE -====== - -* Keystone is sourced in GitHub `Keystone `__ -* Keystone bugs are managed at Launchpad `Launchpad Keystone `__ diff --git a/docs/source/middleware_architecture.rst b/docs/source/middleware_architecture.rst deleted file mode 100644 index 68ae4e9b..00000000 --- a/docs/source/middleware_architecture.rst +++ /dev/null @@ -1,529 +0,0 @@ -.. - Copyright 2011-2012 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. - -======================= -Middleware Architecture -======================= - -Abstract -======== - -The Keystone middleware architecture supports multiple authentication protocols -in a pluggable manner in OpenStack. By providing support for authentication via -pluggable authentication components, this architecture allows OpenStack -services to be integrated easily into existing deployment environments. It also -provides a path by which to implement support for emerging authentication -standards such as OAUTH. - -Rationale and Goals -=================== - -Keystone is the Identity service for OpenStack. To support the easy integrating -of OpenStack with existing authentication and identity management systems, -Keystone supports talking to multiple backends like LDAP. -And to support different deployment needs, it can support multiple -authentication protocols via pluggable 'authentication components' implemented -as WSGI middleware. - -In this document, we describe the responsibilities of the authentication -middleware. We describe how these interact with underlying OpenStack services -and how existing services can be modified to take advantage of pluggable -authentication. The goal is to allow OpenStack services to be integrated easily -into existing deployment environments and to provide a path by which to -implement support for emerging authentication standards such as OAUTH. - -Specification Overview -====================== - -'Authentication' is the process of determining that users are who they say they -are. Typically, 'authentication protocols' such as HTTP Basic Auth, Digest -Access, public key, token, etc, are used to verify a user's identity. In this -document, we define an ''authentication component'' as a software module that -implements an authentication protocol for an OpenStack service. - -At a high level, an authentication component is simply a reverse proxy that -intercepts HTTP calls from clients. Once it has verified a user's identity, the -authentication component extends the call with information about the current -user and forwards the request to the OpenStack service. Otherwise, if a user's -identity is not verified, the message is rejected before it gets to the -service. This is illustrated in :ref:`authComponent`. - -.. _authComponent: - -Authentication Component ------------------------- - -Figure 1. Authentication Component - -.. image:: images/graphs_authComp.svg - :width: 100% - :height: 180 - :alt: An Authentication Component - -Authentication components may operate in 'delegated mode'. In this mode, the -decision reject an unauthenticated client is delegated to the OpenStack -service. Delegated mode is illustrated in :ref:`authComponentDelegated`. - -Here, requests are forwarded to the OpenStack service with an identity status -message that indicates whether the client's identity has been confirmed or is -indeterminate. It is the OpenStack service that decides whether or not a reject -message should be sent to the client. Note that it is always the responsibility -of the Authentication Component to transmit reject messages to the client. - -.. _authComponentDelegated: - -Authentication Component (Delegated Mode) ------------------------------------------ - -Figure 2. Authentication Component (Delegated Mode) - -.. image:: images/graphs_authCompDelegate.svg - :width: 100% - :height: 180 - :alt: An Authentication Component (Delegated Mode) - -In this architecture, we define interactions between the authentication component -and the OpenStack service. Interactions between the client and the -authentication component are defined only for exceptional cases. For example, -we define the message that should be returned when the OpenStack service is -down. Other interactions, however, are defined by the underlying authentication -protocol and the OpenStack service and are considered out of scope. - -.. _deployStrategies: - -Deployment Strategies -===================== - -An authentication component may be integrated directly into the service -implementation, or it may be deployed separately as an HTTP reverse proxy. This -is illustrated in :ref:`deployment`, showing both approaches to -authentication, labeled Option (a) and Option (b). - -.. _deployment: - -Authentication Component Deployments Options --------------------------------------------- - -Figure 3. Authentication Component Deployments Options - -.. image:: images/images_layouts.svg - :width: 100% - :height: 180 - :alt: Authentication Component Deployments Options - -In Option (a), the component is integrated into the service implementation. In -this case, communication between the authentication component and the service -can be efficiently implemented via a method call. In Option (b), the component -is deployed separately and communication between the service and the component -involves an HTTP request. In both cases, unauthenticated requests are filtered -before they reach the service. - -Each approach offers some benefits. Option (a) offers low latency and ease of -initial implementation, making it possibly most appropriate as a starting point -for simple configurations. Option (b) offers several key advantages that may be -of particular value in complex and dynamic configurations. It offers the -ability to scale horizontally in cases where authentication is computationally -expensive, such as when verifying digital signatures. Option (b) also allows -authentication components to be written in different programming languages. -Finally, Option (b) allows multiple authentication components to be deployed in -front of the same service. - -OpenStack services can support both embedded (Option (a)) and external (Option -(b)) deployment strategies. Individual authentication components should support -either strategy or they |may| support both strategies. In order to support -option (a), authentication components written in the Python programming -language should be written as WSGI middleware components (in accordance with -the Web Server Gateway Interface (WSGI) standard [PEP-333]_. - -Additionally, services should support the ability to swap between different -embedded or external authentication components via configuration options. - -Exchanging User Information -=========================== - -If a request is successfully authenticated, the authentication component must -extend the request by adding an ``X-Authorization`` header. The header |must| -be formatted as illustrated in :ref:`xAuthHeader`. - -.. _xAuthHeader: - -X-Authorization Header ----------------------- - -Example 1. X-Authorization Header:: - - X-Authorization: Proxy JoeUser - -Here, `Proxy` denotes that the authentication occurred via a proxy (in this -case authentication component) and ''JoeUser'' is the name of the user who -issued the request. - -.. note: - - We considered using an ``Authorization`` header rather than an - ``X-Authorization``, thereby following normal HTTP semantics. There are some - cases, however, where multiple ``Authorization`` headers need to be transmitted - in a single request. We want to assure ourselves that this will not break - common clients before we recommend the approach. - -Authentication components |may| extend the request with additional -information. For example, an authentication system may add additional headers -or modify the target URI to pass authentication information to the back-end -service. Additionally, an authentication component |may| strip sensitive -information — a plain text password, for example — from the request. That said, -an authentication component |should| pass the majority of the request -unmodified. - -Reverse Proxy Authentication ----------------------------- - -An OpenStack service |should| verify that it is receiving requests from a -trusted authentication component. This is particularly important in cases where -the authentication component and the OpenStack service are deployed separately. -In order to trust incoming requests, the OpenStack service should therefore -authenticate the authentication component. To avoid confusion, we call this -'reverse proxy authentication', since in this case the authentication -component is acting as an HTTP reverse proxy. - -Any HTTP-based authentication scheme may be used for reverse proxy -authentication; however, all OpenStack services and all authentication -components |must| support HTTP Basic Authentication as defined in -[RFC-2617]_. - -Whether or not reverse proxy authentication is required is strictly a -deployment concern. For example, an operations team may opt to utilize firewall -rules instead of an authentication protocol to verify the integrity of incoming -request. Because of this, both OpenStack services and authentication components -|must| also allow for unauthenticated communication. - -In cases where reverse proxy authentication is used, the authorization -component may receive an HTTP 401 authentication error or an HTTP 403 -authorization error. These errors indicate that the component does not have -access to the underlying OpenStack service. The authentication component -|must not| return these errors to the client application. Instead, the -component |must| return a 500 internal error. This is illustrated in -:ref:`proxyAuth` and :ref:`proxyAuthDelegated` below. The component -|should| format the errors in a manner that does not break the service -contract defined by the OpenStack service. :ref:`proxyAuthDelegated` -illustrates proxy authorization in delegated mode. Delegated mode is discussed -in detail in the next section. - -.. _proxyAuth: - -Reverse Proxy Authentication ----------------------------- - -Figure 4. Reverse Proxy Authentication - -.. image:: images/graphs_proxyAuth.svg - :width: 100% - :height: 180 - :alt: Reverse Proxy Authentication - -.. _proxyAuthDelegated: - -Reverse Proxy Authentication (Delegated Mode) ---------------------------------------------- - -Figure 5. Reverse Proxy Authentication (Delegated Mode) - -.. image:: images/graphs_delegate_forbiden_proxy.svg - :width: 100% - :height: 180 - :alt: Reverse Proxy Authentication (Delegated Mode) - -Delegated Mode -============== -In some cases, the decision to reject an unauthenticated request should be -delegated to the OpenStack service. An unauthenticated request may be -appropriate in cases when anonymous access is allowed. In order to support -these cases, an authentication component may be placed in Delegated Mode. In -this mode, the component forwards requests to the OpenStack service when the -client's identity has been confirmed or is indeterminate — that is when -credentials are missing. The authentication component directly rejects requests -with invalid credentials. Authentication components |must| extend the -request by adding an `X-Identity-Status` header. The identity status header -|must| contain one of the following values: - -Identity Status Values ----------------------- - -Confirmed - A `confirmed` value indicates that valid credentials were sent and identity - has been confirmed. The service can trust that the request has been sent on - behalf of the user specified in the `X-Authorization` header. - -Indeterminate - An `indeterminate` value indicates that no credentials were sent and - identity has not been confirmed. In this case, the service will receive an - `X-Authorization` header with no user entry as illustrated in - :ref:`xauth-header-indeterminate`. - -.. _xauth-header-indeterminate: - -Indeterminate Identity Headers ------------------------------- - -Example 2. Indeterminate Identity Headers:: - - X-Identity-Status: Indeterminate - X-Authorization: Proxy - -Services |may| reject a delegated request by issuing an HTTP 401 -authentication error or an HTTP 403 authorization error. These responses -|must| contain an ``WWW-Authenticate`` header with a value of ``Delegated`` as -illustrated in :ref:`unauthHeaders`. - -X-Identity-Status - Provides information on whether the request was authenticated or not. - -X-Tenant - Provides the tenant ID (as it appears in the URL in Keystone). This is to support any legacy implementations before Keystone switched to an ID/Name schema for tenants. - -X-Tenant-Id - The unique, immutable tenant Id - -X-Tenant-Name - The unique, but mutable (it can change) tenant name. - -X-User-Id - The user id of the user used to log in - -X-User-Name - The username used to log in - -X-User - The username used to log in. This is to support any legacy implementations before Keystone switched to an ID/Name schema for tenants. - -X-Roles - The roles associated with that user - -.. _unauthHeaders: - -Delegated WWW-Authenticate Header ---------------------------------- - -:: - - WWW-Authenticate: Delegated - -It is important to note that the actual reject message will likely be modified -by the authentication component in order to comply with the authentication -scheme it is implementing. This is illustrated in :ref:`delegateRejectBasic` and -:ref:`delegateRejectOAuth` below. - -.. _delegateRejectBasic: - -Delegated Reject Basic Auth ---------------------------- - -.. image:: images/graphs_delegate_reject_basic.svg - :width: 100% - :height: 180 - :alt: Delegated Reject Basic Auth - -.. _delegateRejectOAuth: - -Delegated Reject OAuth ----------------------- - -.. image:: images/graphs_delegate_reject_oauth.svg - :width: 100% - :height: 180 - :alt: Delegated Reject OAuth - -The presence of the `WWW-Authenticate` header with a value of `Delegated` -distinguishes a client authentication/authorization failure from a component -failure. For example, compare :ref:`delegateForbidden` with :ref:`proxyAuthDelegated`. In -:ref:`delegateForbidden`, the client is not allowed to access the OpenStack service. -In :ref:`proxyAuthDelegated`, it is the authentication component itself which is -unauthorized. - -.. _delegateForbidden: - -Delegated Reject Forbidden --------------------------- - -Figure 8. Delegated Reject Forbidden - -.. image:: images/graphs_delegate_forbiden_basic.svg - :width: 100% - :height: 180 - :alt: Delegated Reject Forbidden - -Authentication components |must| support both delegated and undelegated -(standard) modes. Delegated mode |should| be configured via a configuration -option. Delegated mode |should| be disabled by default. - -OpenStack services are not required to support delegated mode. If a service -does not support delegated mode, it |must| respond with a 501 not implemented -error and an `WWW-Authenticate` header with a value of `Delegated`. The -authentication component |must not| return the error to the client -application. Instead, the component |must| return a 500 internal error; this is -illustrated in :ref:`delegateUnimplemented`. The component |should| -format the error in a manner that does not break the service contract defined -by the OpenStack service. The component should also log the error such that it -that will inform operators of the misconfiguration. - -.. _delegateUnimplemented: - -Unimplemented Delegated Mode ----------------------------- - -.. image:: images/graphs_delegate_unimplemented.svg - :width: 100% - :height: 180 - :alt: Unimplemented Delegated Mode - -Handling Direct Client Connections -================================== - -Requests from the authentication component to an OpenStack service |must| -contain an ``X-Authorization`` header. If the header is missing, and reverse -proxy authentication fails or is switched off, the OpenStack service |may| -assume that the request is coming directly from a client application. In this -case, the OpenStack service |must| redirect the request to the authentication -component by issuing an HTTP 305 User Proxy redirect. This is illustrated in -:ref:`redirect`. Note that the redirect response |must| include a ``Location`` header -specifying the authentication component's URL as shown in :ref:`redirect-response`. - -.. _redirect: - -Auth Component Redirect ------------------------ - -.. image:: images/graphs_305.svg - :width: 100% - :height: 280 - :alt: Auth Component Redirect - -.. _redirect-response: - -Auth Component Redirect Response --------------------------------- - -:: - - HTTP/1.1 305 Use Proxy - Date: Thu, 28 Oct 2011 07:41:16 GMT - Location: http://sample.auth.openstack.com/path/to/resource - -Using Multiple Authentication Components -======================================== - -There are some use cases when a service provider might want to consider using -multiple authentication components for different purposes. For instance, a -service provider may have one authentication scheme to authenticate the users -of the service and another one to authenticate the administrators or operations -personnel that maintain the service. For such scenarios, we propose using a -mapper as illustrated in :ref:`multiAuth`. - -.. _multiAuth: - -Multiple Authentication Components ----------------------------------- - -.. image:: images/graphs_mapper.svg - :width: 100% - :height: 320 - :alt: Multiple Authentication Components - -At a high level, a mapper is a simple reverse proxy that intercepts HTTP calls -from clients and routes the request to the appropriate authentication -component. A mapper can make the routing decisions based on a number of routing -rules that map a resource to a specific authentication component. For example, -a request URI may determine whether a call should be authenticated via one -authentication component or another. - -Note that neither the authentication component nor the OpenStack service need -be aware of the mapper. Any external authentication component can be used -alongside others. Mappers may provide a means by which to offer support for -anonymous or guest access to a subset of service resources. A mapper may be -implemented via a traditional reverse proxy server such as Pound or Zeus. - -The Default Component -===================== - -Individual services |must| be distributed with a simple integrated -authentication component by default. Providing such a component lowers barriers -to the deployment of individual services. This is especially important to] -developers who may want to deploy OpenStack services on their own machines. -Also, since there is no direct dependency on an external authentication system, -OpenStack services can be deployed individually, without the need to stand up -and configure additional services. Finally, having a standard authentication -component that all services share promotes a separation of concerns. That is, -as a community we are explicitly stating that services should not develop their -own authentication mechanisms. Additional authentication components may be -developed, of course, but these components should not be intimately coupled to -any one particular service. - -As discussed in :ref:`deployStrategies`, an authentication component may be -integrated directly into the service implementation (Option (a)), or it may be -deployed separately as an HTTP reverse proxy (Option (b)). The default -component should be implemented to support Option (a) and services should -maintain support for Option (b). One way to achieve this is to provide a -method that allows the disabling of the default authentication component via -configuration. This is illustrated in :ref:`both`. Here, requests are -sent directly to the OpenStack service when the default authentication -component is disabled. - -We will discuss the design of the default component in an upcoming blueprint. - -.. _both: - -Disabled Embedded Component ---------------------------- - -.. image:: images/graphs_both.svg - :width: 100% - :height: 250 - :alt: Disabled Embedded Component - -Questions and Answers -===================== - -#. Why do authentication components send reject messages? Why not have - OpenStack services reject requests themselves? - - The content and format of an authentication failed message is determined by - the authentication scheme (or protocol). For the service to respond - appropriately, it would have to be aware of the authentication scheme in - which it participates; this defeats the purpose of pluggable authentication - components. - -#. Why require support for deploying authentication components in separate - nodes? - - The deployment strategy is very flexible. It allows for authentication - components to be horizontally scalable. It allows for components to be written - in different languages. Finally, it allows different authentication components - to be deployed simultaneously as described above. - -References -========== - -.. [PEP-333] pep0333 Phillip J Eby. 'Python Web Server Gateway Interface - v1.0.'' http://www.python.org/dev/peps/pep-0333/. - -.. [RFC-2617] rfc2617 J Franks. P Hallam-Baker. J Hostetler. S Lawrence. - P Leach. A Luotonen. L Stewart. ''HTTP Authentication: Basic and Digest - Access Authentication.'' http://tools.ietf.org/html/rfc2617. - -.. |must| replace:: must must -.. |should| replace:: should should -.. |may| replace:: may may -.. |must not| replace:: "must not" "must not" - diff --git a/docs/source/nova-api-paste.rst b/docs/source/nova-api-paste.rst deleted file mode 100644 index 879cd4a7..00000000 --- a/docs/source/nova-api-paste.rst +++ /dev/null @@ -1,143 +0,0 @@ -.. - Copyright 2011-2012 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. - -nova-api-paste example -====================== -:: - - ####### - # EC2 # - ####### - - [composite:ec2] - use = egg:Paste#urlmap - /: ec2versions - /services/Cloud: ec2cloud - /services/Admin: ec2admin - /latest: ec2metadata - /2007-01-19: ec2metadata - /2007-03-01: ec2metadata - /2007-08-29: ec2metadata - /2007-10-10: ec2metadata - /2007-12-15: ec2metadata - /2008-02-01: ec2metadata - /2008-09-01: ec2metadata - /2009-04-04: ec2metadata - /1.0: ec2metadata - - [pipeline:ec2cloud] - pipeline = logrequest totoken authtoken keystonecontext cloudrequest authorizer ec2executor - - [pipeline:ec2admin] - pipeline = logrequest totoken authtoken keystonecontext adminrequest authorizer ec2executor - - [pipeline:ec2metadata] - pipeline = logrequest ec2md - - [pipeline:ec2versions] - pipeline = logrequest ec2ver - - [filter:logrequest] - paste.filter_factory = nova.api.ec2:RequestLogging.factory - - [filter:ec2lockout] - paste.filter_factory = nova.api.ec2:Lockout.factory - - [filter:totoken] - paste.filter_factory = keystone.middleware.ec2_token:EC2Token.factory - - [filter:ec2noauth] - paste.filter_factory = nova.api.ec2:NoAuth.factory - - [filter:authenticate] - paste.filter_factory = nova.api.ec2:Authenticate.factory - - [filter:cloudrequest] - controller = nova.api.ec2.cloud.CloudController - paste.filter_factory = nova.api.ec2:Requestify.factory - - [filter:adminrequest] - controller = nova.api.ec2.admin.AdminController - paste.filter_factory = nova.api.ec2:Requestify.factory - - [filter:authorizer] - paste.filter_factory = nova.api.ec2:Authorizer.factory - - [app:ec2executor] - paste.app_factory = nova.api.ec2:Executor.factory - - [app:ec2ver] - paste.app_factory = nova.api.ec2:Versions.factory - - [app:ec2md] - paste.app_factory = nova.api.ec2.metadatarequesthandler:MetadataRequestHandler.factory - - ############# - # Openstack # - ############# - - [composite:osapi] - use = egg:Paste#urlmap - /: osversions - /v1.1: openstackapi - - [pipeline:openstackapi] - pipeline = faultwrap authtoken keystonecontext ratelimit extensions osapiapp - - [filter:faultwrap] - paste.filter_factory = nova.api.openstack:FaultWrapper.factory - - [filter:auth] - paste.filter_factory = nova.api.openstack.auth:AuthMiddleware.factory - - [filter:noauth] - paste.filter_factory = nova.api.openstack.auth:NoAuthMiddleware.factory - - [filter:ratelimit] - paste.filter_factory = nova.api.openstack.limits:RateLimitingMiddleware.factory - - [filter:extensions] - paste.filter_factory = nova.api.openstack.extensions:ExtensionMiddleware.factory - - [app:osapiapp] - paste.app_factory = nova.api.openstack:APIRouter.factory - - [pipeline:osversions] - pipeline = faultwrap osversionapp - - [app:osversionapp] - paste.app_factory = nova.api.openstack.versions:Versions.factory - - ########## - # Shared # - ########## - - [filter:keystonecontext] - paste.filter_factory = keystone.middleware.nova_keystone_context:NovaKeystoneContext.factory - - [filter:authtoken] - paste.filter_factory = keystone.middleware.auth_token:filter_factory - service_protocol = http - service_host = 127.0.0.1 - service_port = 5000 - auth_host = 127.0.0.1 - auth_port = 35357 - auth_protocol = http - auth_uri = http://your_keystone_host.com:5000/ - ;identical to the admin token defined in keystone.conf - admin_token = 999888777666 - ;Uncomment next line and check ip:port to use memcached to cache token requests - ;memcache_hosts = 127.0.0.1:11211 diff --git a/docs/source/old/backends.rst b/docs/source/old/backends.rst deleted file mode 100644 index 9bf83b0c..00000000 --- a/docs/source/old/backends.rst +++ /dev/null @@ -1,188 +0,0 @@ -.. - Copyright 2011-2012 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. - -======== -Backends -======== - -Keystone supports multiple types of data stores for things like users, tenants, and -tokens, including SQL, LDAP, and memcache. - -SQL -=== - -In the default backend configuration (SQL-only), Keystone depends on the following database tables. - -``users`` ---------- - -``id`` - Auto-incremented primary key. -``name`` - Unqiue username used for authentication via ``passwordCredentials``. -``password`` - Password used for authentication via ``passwordCredentials``. - - Salted and hashed using ``passlib``. -``email`` - Email address (uniqueness is expected, but not enforced). -``enabled`` - If false, the user is unable to authenticate and the user's tokens will fail validation. -``tenant_id`` - Default tenant for the user. - -``tokens`` ----------- - -``id`` - The actual token provided after successful authentication (*plaintext*). -``user_id`` - References the user who owns the token. -``tenant_id`` - (*optional*) References the tenant the token is scoped to. -``expires`` - Indicates the expiration date of the token, after which the token can no longer be validated successfully. - -``tenants`` ------------ - -``id`` - Auto-incremented primary key. -``name`` - Unique string identifying the tenant. -``desc`` - Description of the tenant. -``enabled`` - If false, users are unable to scope to the tenant. - -``roles`` ---------- - -``id`` - Auto-incremented primary key. -``name`` - Name of the role. - - If the role is owned by a service, the role name **must** follow the convention:: - - serviceName:roleName -``desc`` - Description of the role. -``service_id`` - (*optional*) References the service that owns the role. - -``user_roles`` --------------- - -Maps users to the roles that have been granted to them (*optionally*, within the scope of a tenant). - -``id`` - Auto-incremented primary key. -``user_id`` - References the user the role is granted to. -``role_id`` - References the granted role. -``tenant_id`` - (*optional*) References a tenant upon which this grant is applies. - -``services`` ------------- - -``id`` - Auto-incremented primary key. -``name`` - Unique name of the service. -``type`` - Indicates the type of service (e.g. ``compute``, ``object``, ``identity``, etc). - - This can also be extended to support non-core services. Extended services - follow the naming convention ``extension:type`` (e.g. ``dnsextension:dns``). -``desc`` - Describes the service. -``owner_id`` - (*optional*) References the user who owns the service. - -``credentials`` ---------------- - -Currently only used for Amazon EC2 credential storage, this table is designed to support multiple -types of credentials in the future. - -``id`` - Auto-incremented primary key. -``user_id`` - References the user who owns the credential. -``tenant_id`` - References the tenant upon which the credential is valid. -``types`` - Indicates the type of credential (e.g. ``Password``, ``APIKey``, ``EC2``). -``key`` - Amazon EC2 access key. -``secret`` - Amazon EC2 secret key. - -``endpoints`` -------------- - -Tenant-specific endpoints map endpoint templates to specific tenants. -The ``tenant_id`` which appears here replaces the -``%tenant_id%`` template variable in the specified endpoint template. - -``id`` - Auto-incremented primary key. -``tenant_id`` - References the tenant this endpoint applies to. -``endpoint_template_id`` - The endpoint template to appear in the user's service catalog. - -``endpoint_templates`` ----------------------- - -A multi-purpose model for the service catalog which can be: - -- Provided to users of a specific tenants via ``endpoints``, when ``is_global`` is false. -- Provided to all users as-is, when ``is_global`` is true. - -``id`` - Auto-incremented primary key. -``region`` - Identifies the geographic region the endpoint is physically located within. -``service_id`` - TODO: References the service which owns the endpoints? -``public_url`` - Appears in the service catalog [#first]_. - - Represents an endpoint available on the public Internet. -``admin_url`` - Appears in the service catalog [#first]_. - - Users of this endpoint must have an Admin or ServiceAdmin role. -``internal_url`` - Appears in the service catalog [#first]_. - - Represents an endpoint on an internal, unmetered network. -``enabled`` - If false, this endpoint template will not appear in the service catalog. -``is_global`` - If true, this endpoint can not be mapped to tenant-specific endpoints, and ``%tenant_id%`` will not be substituted in endpoint URL's. Additionally, this endpoint will appear for all users. -``version_id`` - Identifies the version of the API contract that endpoint supports. -``version_list`` - A URL which lists versions supported by the endpoint. -``version_info`` - A URL which provides detailed version info regarding the service. - -.. [#first] ``%tenant_id%`` may be replaced by actual tenant references, depending on the value of ``is_global`` and the existence of a corresponding ``endpoints`` record. diff --git a/docs/source/old/controllingservers.rst b/docs/source/old/controllingservers.rst deleted file mode 100644 index 50fc0902..00000000 --- a/docs/source/old/controllingservers.rst +++ /dev/null @@ -1,288 +0,0 @@ -.. - Copyright 2011-2012 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. - -============================ -Controlling Keystone Servers -============================ - -This section describes the ways to start, stop, and reload the Keystone -services. - -Keystone Services ------------------ - -Keystone can serve a number of REST APIs and extensions on different TCP/IP -ports. - -The Service API -~~~~~~~~~~~~~~~~ - -The core Keystone -API is primarily a read-only API (the only write operation being POST /tokens -which authenticates a client, and returns a generated token). -This API is sufficient to use OpenStack if all users, roles, endpoints already -exist. This is often the case if Keystone is using an enterprise backend -and the backend is managed through other entperrise tools and business -processes. This core API is called the Service API and can be started -separately from the more complete Admin API. By default, Keystone runs -this API on port 5000. This is not an IANA assigned port and should not -be relied upon (instead, use the Admin API on port 35357 to look for -this endpoint - more on this later) - -The Service API is started using this command in the /bin directory:: - - $ ./keystone-auth - -The Admin API -~~~~~~~~~~~~~ - -Inn order for Keystone to be a fully functional service out of the box, -API extensions that provide full CRUD operations is included with Keystone. -This full set of API calls includes the OS-KSCATALOG, OS-KSADM, and OS-KSEC2 -extensions. These extensions provide a full set of create, read, update, delete -(CRUD) operations that can be used to manage Keystone objects through REST -calls. By default Keystone runs this full REST API on TCP/IP port 35357 -(assigned by IANA to Keystone). - -The Admin API is started using this command in the /bin directory:: - - $ ./keystone-admin - - -Both APIs can be loaded simultaneously (on different ports) using this command:: - - $ ./keystone - -Starting a server ------------------ - -There are two ways to start a Keystone service (either the Service API server -or the Admin API server): - -- Manually calling the server program -- Using the ``keystone-control`` server daemon wrapper program - -We recommend using the second way in production and the first for development -and debugging. - -Manually starting the server -~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -The first is by directly calling the server program, passing in command-line -options and a single argument for a ``paste.deploy`` configuration file to -use when configuring the server application. - -.. note:: - - Keystone ships with an ``etc/`` directory that contains a sample ``paste.deploy`` - configuration files that you can copy to a standard configuration directory and - adapt for your own uses. - -If you do `not` specify a configuration file on the command line, Keystone will -do its best to locate a configuration file in one of the -following directories, stopping at the first config file it finds: - -- ``$CWD`` -- ``~/.keystone`` -- ``~/`` -- ``/etc/keystone`` -- ``/etc`` - -The filename that is searched for is ``keystone.conf`` by default. - -If no configuration file is found, you will see an error, like:: - - $ keystone - ERROR: Unable to locate any configuration file. Cannot load application keystone - -Here is an example showing how you can manually start the ``keystone-auth`` server and ``keystone-registry`` in a shell:: - - $ ./keystone -d - keystone-legacy-auth: INFO ************************************************** - keystone-legacy-auth: INFO Configuration options gathered from config file: - keystone-legacy-auth: INFO /Users/ziadsawalha/Documents/Code/keystone/etc/keystone.conf - keystone-legacy-auth: INFO ================================================ - keystone-legacy-auth: INFO admin_host 0.0.0.0 - keystone-legacy-auth: INFO admin_port 35357 - keystone-legacy-auth: INFO admin_ssl False - keystone-legacy-auth: INFO backends keystone.backends.sqlalchemy - keystone-legacy-auth: INFO ca_certs /etc/keystone/ssl/certs/ca.pem - keystone-legacy-auth: INFO cert_required True - keystone-legacy-auth: INFO certfile /etc/keystone/ssl/certs/keystone.pem - keystone-legacy-auth: INFO debug True - keystone-legacy-auth: INFO default_store sqlite - keystone-legacy-auth: INFO extensions osksadm,oskscatalog,hpidm - keystone-legacy-auth: INFO hash-password True - keystone-legacy-auth: INFO keyfile /etc/keystone/ssl/private/keystonekey.pem - keystone-legacy-auth: INFO keystone-admin-role Admin - keystone-legacy-auth: INFO keystone-service-admin-role KeystoneServiceAdmin - keystone-legacy-auth: INFO log_dir . - keystone-legacy-auth: INFO log_file keystone.log - keystone-legacy-auth: INFO service-header-mappings { - 'nova' : 'X-Server-Management-Url', - 'swift' : 'X-Storage-Url', - 'cdn' : 'X-CDN-Management-Url'} - keystone-legacy-auth: INFO service_host 0.0.0.0 - keystone-legacy-auth: INFO service_port 5000 - keystone-legacy-auth: INFO service_ssl False - keystone-legacy-auth: INFO verbose False - keystone-legacy-auth: INFO ************************************************** - passlib.registry: INFO registered crypt handler 'sha512_crypt': - Starting the RAX-KEY extension - Starting the Legacy Authentication component - admin : INFO ************************************************** - admin : INFO Configuration options gathered from config file: - admin : INFO /Users/ziadsawalha/Documents/Code/keystone/etc/keystone.conf - admin : INFO ================================================ - admin : INFO admin_host 0.0.0.0 - admin : INFO admin_port 35357 - admin : INFO admin_ssl False - admin : INFO backends keystone.backends.sqlalchemy - admin : INFO ca_certs /etc/keystone/ssl/certs/ca.pem - admin : INFO cert_required True - admin : INFO certfile /etc/keystone/ssl/certs/keystone.pem - admin : INFO debug True - admin : INFO default_store sqlite - admin : INFO extensions osksadm,oskscatalog,hpidm - admin : INFO hash-password True - admin : INFO keyfile /etc/keystone/ssl/private/keystonekey.pem - admin : INFO keystone-admin-role Admin - admin : INFO keystone-service-admin-role KeystoneServiceAdmin - admin : INFO log_dir . - admin : INFO log_file keystone.log - admin : INFO service-header-mappings { - 'nova' : 'X-Server-Management-Url', - 'swift' : 'X-Storage-Url', - 'cdn' : 'X-CDN-Management-Url'} - admin : INFO service_host 0.0.0.0 - admin : INFO service_port 5000 - admin : INFO service_ssl False - admin : INFO verbose False - admin : INFO ************************************************** - Using config file: /Users/ziadsawalha/Documents/Code/keystone/etc/keystone.conf - Service API (ssl=False) listening on 0.0.0.0:5000 - Admin API (ssl=False) listening on 0.0.0.0:35357 - eventlet.wsgi.server: DEBUG (77128) wsgi starting up on http://0.0.0.0:5000/ - eventlet.wsgi.server: DEBUG (77128) wsgi starting up on http://0.0.0.0:35357/ - - $ sudo keystone-registry keystone-registry.conf & - jsuh@mc-ats1:~$ 2011-04-13 14:51:16 INFO [sqlalchemy.engine.base.Engine.0x...feac] PRAGMA table_info("images") - 2011-04-13 14:51:16 INFO [sqlalchemy.engine.base.Engine.0x...feac] () - 2011-04-13 14:51:16 DEBUG [sqlalchemy.engine.base.Engine.0x...feac] Col ('cid', 'name', 'type', 'notnull', 'dflt_value', 'pk') - 2011-04-13 14:51:16 DEBUG [sqlalchemy.engine.base.Engine.0x...feac] Row (0, u'created_at', u'DATETIME', 1, None, 0) - 2011-04-13 14:51:16 DEBUG [sqlalchemy.engine.base.Engine.0x...feac] Row (1, u'updated_at', u'DATETIME', 0, None, 0) - 2011-04-13 14:51:16 DEBUG [sqlalchemy.engine.base.Engine.0x...feac] Row (2, u'deleted_at', u'DATETIME', 0, None, 0) - 2011-04-13 14:51:16 DEBUG [sqlalchemy.engine.base.Engine.0x...feac] Row (3, u'deleted', u'BOOLEAN', 1, None, 0) - 2011-04-13 14:51:16 DEBUG [sqlalchemy.engine.base.Engine.0x...feac] Row (4, u'id', u'INTEGER', 1, None, 1) - 2011-04-13 14:51:16 DEBUG [sqlalchemy.engine.base.Engine.0x...feac] Row (5, u'name', u'VARCHAR(255)', 0, None, 0) - 2011-04-13 14:51:16 DEBUG [sqlalchemy.engine.base.Engine.0x...feac] Row (6, u'disk_format', u'VARCHAR(20)', 0, None, 0) - 2011-04-13 14:51:16 DEBUG [sqlalchemy.engine.base.Engine.0x...feac] Row (7, u'container_format', u'VARCHAR(20)', 0, None, 0) - 2011-04-13 14:51:16 DEBUG [sqlalchemy.engine.base.Engine.0x...feac] Row (8, u'size', u'INTEGER', 0, None, 0) - 2011-04-13 14:51:16 DEBUG [sqlalchemy.engine.base.Engine.0x...feac] Row (9, u'status', u'VARCHAR(30)', 1, None, 0) - 2011-04-13 14:51:16 DEBUG [sqlalchemy.engine.base.Engine.0x...feac] Row (10, u'is_public', u'BOOLEAN', 1, None, 0) - 2011-04-13 14:51:16 DEBUG [sqlalchemy.engine.base.Engine.0x...feac] Row (11, u'location', u'TEXT', 0, None, 0) - 2011-04-13 14:51:16 INFO [sqlalchemy.engine.base.Engine.0x...feac] PRAGMA table_info("image_properties") - 2011-04-13 14:51:16 INFO [sqlalchemy.engine.base.Engine.0x...feac] () - 2011-04-13 14:51:16 DEBUG [sqlalchemy.engine.base.Engine.0x...feac] Col ('cid', 'name', 'type', 'notnull', 'dflt_value', 'pk') - 2011-04-13 14:51:16 DEBUG [sqlalchemy.engine.base.Engine.0x...feac] Row (0, u'created_at', u'DATETIME', 1, None, 0) - 2011-04-13 14:51:16 DEBUG [sqlalchemy.engine.base.Engine.0x...feac] Row (1, u'updated_at', u'DATETIME', 0, None, 0) - 2011-04-13 14:51:16 DEBUG [sqlalchemy.engine.base.Engine.0x...feac] Row (2, u'deleted_at', u'DATETIME', 0, None, 0) - 2011-04-13 14:51:16 DEBUG [sqlalchemy.engine.base.Engine.0x...feac] Row (3, u'deleted', u'BOOLEAN', 1, None, 0) - 2011-04-13 14:51:16 DEBUG [sqlalchemy.engine.base.Engine.0x...feac] Row (4, u'id', u'INTEGER', 1, None, 1) - 2011-04-13 14:51:16 DEBUG [sqlalchemy.engine.base.Engine.0x...feac] Row (5, u'image_id', u'INTEGER', 1, None, 0) - 2011-04-13 14:51:16 DEBUG [sqlalchemy.engine.base.Engine.0x...feac] Row (6, u'key', u'VARCHAR(255)', 1, None, 0) - 2011-04-13 14:51:16 DEBUG [sqlalchemy.engine.base.Engine.0x...feac] Row (7, u'value', u'TEXT', 0, None, 0) - - $ ps aux | grep keystone - myuser 77148 0.0 0.0 2434892 472 s012 U+ 11:50AM 0:00.01 grep keystone - myuser 77128 0.0 0.6 2459356 25360 s011 S+ 11:48AM 0:00.82 python ./keystone -d - -Simply supply the configuration file as the first argument -and then any common options -you want to use (``-d`` was used above to show some of the debugging -output that the server shows when starting up. Call the server program -with ``--help`` to see all available options you can specify on the -command line.) - -Using ``--trace-calls`` is useful for showing a trace of calls (errors in red) -for debugging. - -For more information on configuring the server via the ``paste.deploy`` -configuration files, see the section entitled -:doc:`Configuring Keystone ` - -Note that the server `daemonizes` itself by using the standard -shell backgrounding indicator, ``&``, in the previous example. For most use cases, we recommend -using the ``keystone-control`` server daemon wrapper for daemonizing. See below -for more details on daemonization with ``keystone-control``. - -Using ``keystone-control`` to start the server -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -The second way to start up a Keystone server is to use the ``keystone-control`` -program. ``keystone-control`` is a wrapper script that allows the user to -start, stop, restart, and reload the other Keystone server programs in -a fashion that is more conducive to automation and scripting. - -Servers started via the ``keystone-control`` program are always `daemonized`, -meaning that the server program process runs in the background. - -To start a Keystone server with ``keystone-control``, simply call -``keystone-control`` with a server and the word "start", followed by -any command-line options you wish to provide. Start the server with ``keystone-control`` -in the following way:: - - $ sudo keystone-control start [CONFPATH] - -.. note:: - - You must use the ``sudo`` program to run ``keystone-control`` currently, as the - pid files for the server programs are written to /var/run/keystone/ - -Start the ``keystone-admin`` server using ``keystone-control``:: - - $ sudo keystone-control admin start - Starting keystone-admin with /etc/keystone.conf - -The same ``paste.deploy`` configuration files are used by ``keystone-control`` -to start the Keystone server programs, and you can specify (as the example above -shows) a configuration file when starting the server. - -Stopping a server ------------------ - -If you started a Keystone server manually and did not use the ``&`` backgrounding -function, simply send a terminate signal to the server process by typing -``Ctrl-C`` - -If you started the Keystone server using ``keystone-control``, you can -use the ``keystone-control`` program to stop it:: - - $ sudo keystone-control stop - -For example:: - - $ sudo keystone-control auth stop - Stopping keystone-auth pid: 77401 signal: 15 - -Restarting a server -------------------- - -Restart the Keystone server using ``keystone-control``:: - - $ sudo keystone-control admin restart /etc/keystone.conf - Stopping keystone-admin pid: 77401 signal: 15 - Starting keystone-admin with /etc/keystone.conf diff --git a/docs/source/old/endpoints.rst b/docs/source/old/endpoints.rst deleted file mode 100644 index bb334543..00000000 --- a/docs/source/old/endpoints.rst +++ /dev/null @@ -1,430 +0,0 @@ -.. - Copyright 2011-2012 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. - -================================ -Endpoints and Endpoint Templates -================================ - -.. toctree:: - :maxdepth: 1 - -What are Endpoints? -------------------- - -Simply, endpoints are URLs that point to OpenStack services. When you -authenticate to Keystone you get back a token which has a service catalog in -it. The service catalog is basically a list of the OpenStack services that -you have access to and the URLs you can use to get to them; their endpoints. - -Here is an example response from Keystone when you authenticate:: - - { - "access":{ - "token":{ - "id":"ab48a9efdfedb23ty3494", - "expires":"2010-11-01T03:32:15-05:00", - "tenant":{ - "id": "t1000", - "name": "My Project" - } - }, - "user":{ - "id":"u123", - "name":"jqsmith", - "roles":[{ - "id":"100", - "name":"compute:admin" - }, - { - "id":"101", - "name":"object-store:admin", - "tenantId":"t1000" - } - ], - "roles_links":[] - }, - "serviceCatalog":[{ - "name":"Nova", - "type":"compute", - "endpoints":[{ - "tenantId":"t1000", - "publicURL":"https://compute.north.host.com/v1/t1000", - "internalURL":"https://compute.north.internal/v1/t1000", - "region":"North", - "versionId":"1", - "versionInfo":"https://compute.north.host.com/v1/", - "versionList":"https://compute.north.host.com/" - }, - { - "tenantId":"t1000", - "publicURL":"https://compute.north.host.com/v1.1/t1000", - "internalURL":"https://compute.north.internal/v1.1/t1000", - "region":"North", - "versionId":"1.1", - "versionInfo":"https://compute.north.host.com/v1.1/", - "versionList":"https://compute.north.host.com/" - } - ], - "endpoints_links":[] - }, - { - "name":"Swift", - "type":"object-store", - "endpoints":[{ - "tenantId":"t1000", - "publicURL":"https://storage.north.host.com/v1/t1000", - "internalURL":"https://storage.north.internal/v1/t1000", - "region":"North", - "versionId":"1", - "versionInfo":"https://storage.north.host.com/v1/", - "versionList":"https://storage.north.host.com/" - }, - { - "tenantId":"t1000", - "publicURL":"https://storage.south.host.com/v1/t1000", - "internalURL":"https://storage.south.internal/v1/t1000", - "region":"South", - "versionId":"1", - "versionInfo":"https://storage.south.host.com/v1/", - "versionList":"https://storage.south.host.com/" - } - ] - }, - { - "name":"DNS-as-a-Service", - "type":"dnsextension:dns", - "endpoints":[{ - "tenantId":"t1000", - "publicURL":"https://dns.host.com/v2.0/t1000", - "versionId":"2.0", - "versionInfo":"https://dns.host.com/v2.0/", - "versionList":"https://dns.host.com/" - } - ] - } - ] - } - } - -Note the following about this response: - -#. There are two endpoints given to the Nova compute service. The only - difference between them is the version (1.0 vs. 1.1). This allows for code - written to look for the version 1.0 endpoint to still work even after the 1.1 - version is released. - -#. There are two endpoints for the Swift object-store service. The difference - between them is they are in different regions (North and South). - -#. Note the DNS service is global; it does not have a Region. Also, since DNS - is not a core OpenStack service, the endpoint type is "dnsextension:dns" - showing it is coming from an extension to the Keystone service. - -#. The Region, Tenant, and versionId are listed under the endpoint. You do not - (and should not) have to parse those out of the URL. In fact, they may not be - embedded in the URL if the service developer so chooses. - - -What do the fields in an Endpoint mean? ---------------------------------------- - -The schema definition for an endpoint is in endpoints.xsd under -keystone/content/common/xsd in the Keystone code repo. The fields are: - -id - A unique ID for the endpoint. - -type - The OpenStack-registered type (ex. 'compute', 'object-store', 'image service') - This can also be extended using the OpenStack Extension mechanism to support - non-core services. Extended services will be in the form ``extension:type`` - (e.g. ``dnsextension:dns``) - -name - This can be anything that the operator of OpenStack chooses. It could be a - brand or marketing name (ex. Rackspace Cloud Servers). - -region - This is a string that identifies the region where this endpoint exists. - Examples are 'North America', 'Europe', 'Asia'. Or 'North' and 'South'. Or - 'Data Center 1', 'Data Center 2'. - The list of regions and what a region means is decided by the operator. The - spec treats them as opaque strings. - -publicURL - This is the URL to use to access that endpoint over the internet. - -internalURL - This is the URL to use to communicate between services. This is genenrally - a way to communicate between services over a high bandwidth, low latency, - unmetered (free, no bandwidth charges) network. An example would be if you - want to access a swift cluster from inside your Nova VMs and want to make - sure the communication stays local and does not go over a public network - and rack up your bandwidth charges. - -adminURL - This is the URL to use to administer the service. In Keystone, this URL - is only shown to users with the appropriate rights. - -tenantId - If an endpoint is specific to a tenant, the tenantId field identifies the - tenant that URL applies to. Some operators include the tenant in the - URLs for a service, while others may provide one endpoint and use some - other mechanism to identify the tenant. This field is therefore optional. - Having this field also means you do not have to parse the URL to identify - a tenant if the operator includes it in the URL. - -versionId - This identifies the version of the API contract that endpoint supports. - While many APIs include the version in the URL (ex: https://compute.host/v1), - this field allows you to identify the version without parsing the URL. It - therefore also allows operators and service developers to publish endpoints - that do not have versions embedded in the URL. - -versionInfo - This is the URL to call to get some information on the version. This returns - information in this format:: - - { - "version": { - "id": "v2.0", - "status": "CURRENT", - "updated": "2011-01-21T11:33:21-06:00", - "links": [ - { - "rel": "self", - "href": "http://identity.api.openstack.org/v2.0/" - }, { - "rel": "describedby", - "type": "application/pdf", - "href": "http://docs.openstack.org/identity/api/v2.0/identity-latest.pdf" - }, { - "rel": "describedby", - "type": "application/vnd.sun.wadl+xml", - "href": "http://docs.openstack.org/identity/api/v2.0/identity.wadl" - } - ], - "media-types": [ - { - "base": "application/xml", - "type": "application/vnd.openstack.identity+xml;version=2.0" - }, { - "base": "application/json", - "type": "application/vnd.openstack.identity+json;version=2.0" - } - ] - } - } - -versionList - - This is the URL to call to find out which versions are supported at that - endpoint. The response is in this format:: - - { - "versions":[{ - "id":"v1.0", - "status":"DEPRECATED", - "updated":"2009-10-09T11:30:00Z", - "links":[{ - "rel":"self", - "href":"http://identity.api.openstack.org/v1.0/" - } - ] - }, - { - "id":"v1.1", - "status":"CURRENT", - "updated":"2010-12-12T18:30:02.25Z", - "links":[{ - "rel":"self", - "href":"http://identity.api.openstack.org/v1.1/" - } - ] - }, - { - "id":"v2.0", - "status":"BETA", - "updated":"2011-05-27T20:22:02.25Z", - "links":[{ - "rel":"self", - "href":"http://identity.api.openstack.org/v2.0/" - } - ] - } - ], - "versions_links":[] - } - - Here, the response shows that the endpoint supports version 1.0, 1.1, and 2.0. - It also shows that 1.0 is in DEPRECTAED status and 2.0 is in BETA. - -What are Endpoint Templates? ----------------------------- - -Endpoint Templates are a way for an administrator to manage endpoints en masse. -They provide a way to define Endpoints that apply to many or all tenants -without having to a create each endpoint on each tenant manually. Without -Endpoint Templates, if I wanted to create Endpoints for each tenant in my -OpenStack deployment, I'd have to manually create a bunch of endpoints on -each tenant (probably when I created the tenant). And then I'd have to go change -them all whenever a service changed versions or I added a new service. - -To provide a simpler mechanism to manage endpoints on tenants, Keystone uses -Endpoint Templates. I can, for example, define a template with parametrized URLs -and set it's `global` to true and that will show up as an endpoint on all the tenants -I have. Here is an example: - -Define a global Endpoint Template:: - - $ ./keystone-manage endpointTemplates add North nova https://compute.north.example.com/v1/%tenant_id%/ https://compute.north.example.corp/v1/ https://compute.north.example.local/v1/%tenant_id%/ 1 1 - - The arguments are: object_type action 'region' 'service_name' 'publicURL' 'adminURL' 'internalURL' 'enabled' 'global' - -This creates a global endpoint (global means it gets applied to all tenants automatically). - -Now, when a user authenticates, they get that endpoint in their service catalog. Here's an example -authentication request for use against tenant 1:: - - $ curl -H "Content-type: application/json" -d '{"auth":{"passwordCredentials":{"username":"joeuser","password":"secrete"}, "tenantId": "1"}}' http://localhost:5000/v2.0/tokens - -The response is:: - - { - "access": { - "serviceCatalog": [ - { - "endpoints": [ - { - "internalURL": "https://compute.north.example.local", - "publicURL": "https://compute.north.example.com/v1/1/", - "region": "North" - } - ], - "name": "nova", - "type": "compute" - } - ], - "token": { - "expires": "2012-02-05T00:00:00", - "id": "887665443383838", - "tenant": { - "id": "1", - "name": "customer-x" - } - }, - "user": { - "id": "1", - "name": "joeuser", - "roles": [ - { - "id": "3", - "name": "Member", - "tenantId": "1" - } - ] - } - } - } - -Notice the adminURL is not showing (this user is a regular user and does not -have rights to see the adminURL) and the tenant ID has been substituted in the -URL:: - - "publicURL": "https://compute.north.example.com/v1/1/", - -This endpoint will show up for all tenants. The OpenStack administrator does -not need to create the endpoint manually. - -.. note:: Endpoint Templates are not part of the core Keystone API (but Endpoints are). - - -What parameters can I use in a Template URL -------------------------------------------- - -Currently the only parameterization available is %tenant_id% which gets -substituted by the Tenant ID. - - -Endpoint Template Types: Global or not --------------------------------------- - -When the global flag is set to true on an Endpoint Template, it means it should -be available to all tenants. Whenever someone authenticates to a tenant, they -will see the Endpoint generated by that template. - -When the global flag is not set, the template only shows up when it is added to -a tenant manually. To add an endpoint to a tenant manually, you must create -the Endpoint and supply the Endpoint Template ID: - -Create the Endpoint Template:: - - $ ./keystone-manage endpointTemplates add West nova https://compute.west.example.com/v1/%tenant_id%/ https://compute.west.example.corp https://compute.west.example.local 1 0 - - Note the 0 at the end - this Endpoint Template is not global. So it will not show up for users authenticating. - -Find the Endpoint Template ID:: - - $ ./keystone-manage endpointTemplates list - - All EndpointTemplates - id service type region enabled is_global Public URL Admin URL - ------------------------------------------------------------------------------- - 15 nova compute North True True https://compute.north.example.com/v1/%tenant_id%/ https://compute.north.example.corp - 16 nova compute West True False https://compute.west.example.com/v1/%tenant_id%/ https://compute.west.example.corp - -Add the Endpoint to the tenant:: - - $ ./keystone-manage endpoint add customer-x 16 - -Now, when the user authenticates, they get the endpoint:: - - { - "internalURL": "https://compute.west.example.local", - "publicURL": "https://compute.west.example.com/v1/1/", - "region": "West" - } - -Who can see the AdminURL? -------------------------- - -Users who have the Keystone `Admin` or `Service Admin` roles will see the -AdminURL when they authenticate or when they retrieve token information: - -Using an administrator token to authenticate, GET a client token's endpoints:: - - $ curl -H "X-Auth-Token: 999888777666" http://localhost:35357/v2.0/tokens/887665443383838/endpoints - - { - "endpoints": [ - { - "adminURL": "https://compute.west.example.corp", - "id": 6, - "internalURL": "https://compute.west.example.local", - "name": "nova", - "publicURL": "https://compute.west.example.com/v1/1/", - "region": "West", - "tenantId": 1, - "type": "compute" - } - ], - "endpoints_links": [ - { - "href": "http://127.0.0.1:35357/tokens/887665443383838/endpoints?marker=6&limit=10", - "rel": "next" - } - ] - } diff --git a/docs/source/old/extensions.rst b/docs/source/old/extensions.rst deleted file mode 100644 index 70692b8f..00000000 --- a/docs/source/old/extensions.rst +++ /dev/null @@ -1,183 +0,0 @@ -.. - Copyright 2011-2012 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. - -========== -Extensions -========== - -Extensions support adding features and functions to OpenStack APIs at any time, without prior -approval or waiting for a new API and release cycles. - -The extension framework is in development and documented in extensions_ and extensionspresentation_. - -This document describes the extensions included with Keystone, how to enable and disable them, -and briefly touches on how to write your own extensions. - -.. _extensions: http://docs.openstack.org/trunk/openstack-compute/developer/openstack-api-extensions/content/ch02s01.html -.. _extensionspresentation: http://www.slideshare.net/RackerWilliams/openstack-extensions - -Built-in Extensions -------------------- - -Keystone ships with a number of extensions found under the -``keystone/contib/extensions`` folder. - -The following built-in extensions are included: - -OS-KSADM - - This is an extensions that supports managing users, tenants, and roles - through the API. Without this extensions, the ony way to manage those - objects is through keystone-manage or directly in the underlying database. - - This is an Admin API extension only. - -OS-KSCATALOG - - This extensions supports managing Endpoints and prrovides the Endpoint - Template mechanism for managing bulk endpoints. - - This is an Admin API extension only. - -OS-EC2 - - This extension adds support for EC2 credentials. - - This is an Admin and Service API extension. - -RAX-GRP - - This extension adds functionality the enables groups. - - This is an Admin and Service API extension. - -RAX-KEY - - This extensions adds support for authentication with an API Key (the core - Keystone API only supports username/password credentials) - - This is an Admin and Service API extension. - -HP-IDM - - This extension adds capability to filter roles with optional service IDs - for token validation to mitigate security risks with role name conflicts. - See https://bugs.launchpad.net/keystone/+bug/890411 for more details. - - This is an Admin API extension. Applicable to validate token (GET) - and check token (HEAD) APIs only. - -OS-KSVALIDATE - - This extensions supports admin calls to /tokens without having to specify - the token ID in the URL. Instead, the ID is supplied in a header called - X-Subject-Token. This is provided as an alternative to address any security - concerns that arise when token IDs are passed as part of the URL which is - often (and by default) logged to insecure media. - - This is an Admin API extension only. - -.. note:: - - The included extensions are in the process of being rewritten. Currently - osksadm, oskscatalog, hpidm, and osksvalidate work with this new - extensions design. - - -Enabling & Disabling Extensions -------------------------------- - -The Keystone conf file has a property called extensions. This property holds -the list of supported extensions that you want enabled. If you want to -add/remove an extension from being supported, add/remove the extension key -from this property. The key is the name of the folder of the extension -under the keystone/contrib/extensions folder. - -.. note:: - - If you want to load different extensions in the service API than the Admin API - you need to use different config files. - -Creating New Extensions ------------------------ - -#. **Adopt a unique organization abbreviation.** - - This prefix should uniquely identify your organization within the community. - The goal is to avoid schema and resource collisions with similiar extensions. - (e.g. ``OS`` for OpenStack, ``RAX`` for Rackspace, or ``HP`` for Hewlett-Packard) - -#. **Adopt a unique extension abbreviation.** - - Select an abbreviation to identify your extension, and append to - your organization prefix using a hyphen (``-``), by convention - (e.g. ``OS-KSADM`` (for OpenStack's Keystone Administration extension). - - This combination is referred to as your extension's prefix. - -#. **Determine the scope of your extension.** - - Extensions can enhance the Admin API, Service API or both. - -#. **Create a new module.** - - Create a module to isolate your namespace based on the extension prefix - you selected:: - - keystone/contrib/extensions/admin - - ... and/or:: - - keystone/contrib/extensions/service/ - - ... based on which API you are enhancing. - - .. note:: - - In the future, we will support loading external extensions. - -#. Add static extension files for JSON (``*.json``) and XML - (``*.xml``) to the new extension module. - - Refer to `Service Guide `_ - `Sample extension XML `_ - `Sample extension JSON `_ for the the content and structure. - -#. If your extension is adding additional methods override the base class - ``BaseExtensionHandler``, name it ``ExtensionHandler``, and add your methods. - -#. **Document your work.** - - Provide documentation to support your extension. - - Extensions documentation, WADL, and XSD files can be stored in the - ``keystone/content`` folder. - -#. Add your extension name to the list of supported extensions in The - ``keystone.conf`` file. - -Which extensions are enabled? ------------------------------ - -Discover which extensions are available (service API):: - - curl http://localhost:5000/v2.0/extensions - -... or (admin API):: - - curl http://localhost:35357/v2.0/extensions - -The response will list the extensions available. diff --git a/docs/source/old/middleware.rst b/docs/source/old/middleware.rst deleted file mode 100644 index 3738def6..00000000 --- a/docs/source/old/middleware.rst +++ /dev/null @@ -1,169 +0,0 @@ -.. - Copyright 2011-2012 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. - -========== -Middleware -========== - -The Keystone middleware sits in front of an OpenStack service and handles authenticating -incoming requests. The middleware was designed according to `this spec`. - -The middleware is found in source under Keystone/middleware. - -The middleware supports two interfaces; WSGI and REST/HTTP. - -.. _`this spec`: http://wiki.openstack.org/openstack-authn - -REST & HTTP API -=============== - -If an unauthenticated call comes in, the middleware will respond with a 401 Unauthorized error. As per -HTTP standards, it will also return a WWW-Authenticate header informing the caller -of what protocols are supported. For Keystone authentication, the response syntax will be:: - - WWW-Authenticate: Keystone uri="url to Keystone server" - -The client can then make the necessary calls to the Keystone server, obtain a token, and retry the call with the token. - -The token is passed in using ther X-Auth-Token header. - -WSGI API (Headers) -================== - -Upon successful authentication the middleware sends the following -headers to the downstream WSGI app: - -X-Identity-Status - Provides information on whether the request was authenticated or not. - -X-Tenant - Provides the tenant ID (as it appears in the URL in Keystone). This is to support any legacy implementations before Keystone switched to an ID/Name schema for tenants. - -X-Tenant-Id - The unique, immutable tenant Id - -X-Tenant-Name - The unique, but mutable (it can change) tenant name. - -X-User-Id - The user id of the user used to log in - -X-User-Name - The username used to log in - -X-User - The username used to log in. This is to support any legacy implementations before Keystone switched to an ID/Name schema for tenants. - -X-Roles - The roles associated with that user - - -Configuration -============= - -The middleware is configured within the config file of the main application as -a WSGI component. Example for the auth_token middleware:: - - [app:myService] - paste.app_factory = myService:app_factory - - [pipeline:main] - pipeline = - tokenauth - myService - - [filter:tokenauth] - paste.filter_factory = keystone.middleware.auth_token:filter_factory - auth_host = 127.0.0.1 - auth_port = 35357 - auth_protocol = http - auth_uri = http://127.0.0.1:5000/ - admin_token = 999888777666 - ;Uncomment next line and check ip:port to use memcached to cache token requests - ;memcache_hosts = 127.0.0.1:11211 - -*The required configuration entries are:* - -auth_host - The IP address or DNS name of the Keystone server - -auth_port - The TCP/IP port of the Keystone server - -auth_protocol - The protocol of the Keystone server ('http' or 'https') - -auth_uri - The externally accessible URL of the Keystone server. This will be where unauthenticated - clients are redirected to. This is in the form of a URL. For example, if they make an - unauthenticated call, they get this response:: - - HTTP/1.1 401 Unauthorized - Www-Authenticate: Keystone uri='https://auth.example.com/' - Content-Length: 381 - - In this case, the auth_uri setting is set to https://auth.example.com/ - -admin_token - This is the long-lived token issued to the service to authenticate itself when calling - Keystone. See :doc:`configuration` for more information on setting this up. - - -*Optional parameters are:* - -delay_auth_decision - Whether the middleware should reject invalid or unauthenticated calls directly or not. If not, - it will send all calls down to the service to decide, but it will set the HTTP-X-IDENTITY-STATUS - header appropriately (set to'Confirmed' or 'Indeterminate' based on validation) and the - service can then decide if it wants to honor the call or not. This is useful if the service offers - some resources publicly, for example. - -auth_timeout - The amount of time to wait before timing out a call to Keystone (in seconds) - -memcache_hosts - This is used to point to a memcached server (in ip:port format). If supplied, - the middleware will cache tokens and data retrieved from Keystone in memcached - to minimize calls made to Keystone and optimize performance. - -.. warning:: - Tokens are cached for the duration of their validity. If they are revoked eariler in Keystone, - the service will not know and will continue to honor the token as it has them stored in memcached. - Also note that tokens and data stored in memcached are not encrypted. The memcached server must - be trusted and on a secure network. - - -*Parameters needed in a distributed topology.* In this configuration, the middleware is running -on a separate machine or cluster than the protected service (not common - see :doc:`middleware_architecture` -for details on different deployment topologies): - -service_host - The IP address or DNS name of the location of the service (since it is remote - and not automatically down the WSGI chain) - -service_port - The TCP/IP port of the remote service. - -service_protocol - The protocol of the service ('http' or 'https') - -service_pass - The basic auth password used to authenticate to the service (so the service - knows the call is coming from a server that has validated the token and not from - an untrusted source or spoofer) - -service_timeout - The amount of time to wait for the service to respond before timing out. diff --git a/docs/source/old/migration.rst b/docs/source/old/migration.rst deleted file mode 100644 index 460d980b..00000000 --- a/docs/source/old/migration.rst +++ /dev/null @@ -1,126 +0,0 @@ -=================== -Database Migrations -=================== - -Keystone uses SQLAlchemy Migrate (``sqlalchemy-migrate``) to manage -migrations. - -Migrations are tracked using a metadata table (``migrate_version``), which -allows keystone to compare the state of your database to the state it -expects, and to move between versions. - -.. WARNING:: - - Backup your database before applying migrations. Migrations may - attempt to modify both your schema and data, and could result in data - loss. - - Always review the behavior of migrations in a staging environment - before applying them in production. - -Getting Started -=============== - -Your initial approach to migrations should depend on whether you have an -empty database or a schema full of data. - -Starting with an empty database -------------------------------- - -If you have an empty database for keystone to work with, you can simply -run:: - - $ ./bin/keystone-manage database sync - -This command will initialize your metadata table, and run through all the -schema & data migrations necessary to bring your database in sync with -keystone. That's it! - -Starting with an existing database ----------------------------------- - -Place an existing database under version control to enable migration -support:: - - $ ./bin/keystone-manage database version_control - -This command simply creates a ``migrate_version`` table, set at -``version_number`` 0, which indicates that no migrations have been applied. - -If you are starting with an existing schema, you can jump to a specific -schema version without performing migrations using the ``database goto`` -command. For example, if you're starting from a diablo-compatible -database, set your current database ``version_number`` to ``1`` using:: - - $ ./bin/keystone-manage database goto - -Determine your appropriate database ``version_number`` by referencing the -following table: - - +------------+-------------+ - | Release | ``version`` | - +============+=============+ - | pre-diablo | (see below) | - +------------+-------------+ - | diablo | 1 | - +------------+-------------+ - | essex-m1 | 3 | - +------------+-------------+ - | essex-m2 | 4 | - +------------+-------------+ - -From there, you can upgrade normally (see :ref:`upgrading`). - -Starting with a pre-diablo database (cactus) --------------------------------------------- - -You'll need to manually migrate your database to a diablo-compatible -schema, and continue forward from there (if desired) using migrations. - -.. _upgrading: - -Upgrading & Downgrading -======================= - -.. note:: - - Attempting to start keystone with an outdated schema will cause - keystone to abort, to avoid corrupting your data. - -Upgrade to the latest version automatically:: - - $ ./bin/keystone-manage database sync - -Check your current schema version:: - - $ ./bin/keystone-manage database version - -Jump to a specific version without performing migrations:: - - $ ./bin/keystone-manage database goto - -Upgrade to a specific version:: - - $ ./bin/keystone-manage database upgrade - -Downgrade to a specific version (will likely result in data loss!):: - - $ ./bin/keystone-manage database downgrade - -Opting Out of Migrations -======================== - -If you don't want to use migrations (e.g. if you want to manage your -schema manually), keystone will complain in your logs on startup, but -won't actually stop you from doing so. - -It's recommended that you use migrations to get up and running, but if -you want to manage migrations manually after that, simply drop the -``migrate_version`` table:: - - DROP TABLE migrate_version; - -Useful Links -============ - -Principles to follow when developing migrations `OpenStack Deployability `_ diff --git a/docs/source/old/releases.rst b/docs/source/old/releases.rst deleted file mode 100644 index a4b698d7..00000000 --- a/docs/source/old/releases.rst +++ /dev/null @@ -1,36 +0,0 @@ -============= -Release notes -============= - - -E3 (January 26, 2012) -========================================== -* Contract compliance: version response and ATOM, 300 multiple choice -* Global endpoints returned for unscoped calls -* adminUrl only shown to admin clients -* Endpoints have unique ID -* Auth-N/Auth-Z for S3 API (OS-KSS3 extension) -* Default tenant scope optionally returned when authenticating -* Vary header returned for caching proxies - -* Portable identifiers: modifiable, string identifiers in database backend -* Much improved keystone-manage command (see --help and docs) -* OS-KSVALIDATE extension to support not passing tokens in URL -* OS-KSEC2 and OS-KSS3 extensions respond on /tokens -* HP-IDM extension to filter roles to a given service ID -* Additional caching options in middleware (memcache and swift cache) - -* Enhanced configuration management (in line with other OpenStack projects) -* Additional logging -* Enhanced tracer tool (-t or --trace-calls) - -See comprehensive list here https://launchpad.net/keystone/+milestone/essex-3 - - -E2 (December 15, 2011) -======================== -* D5 compatibility middleware -* Database versioning -* Much more documentation: http://keystone.openstack.org - -See https://launchpad.net/keystone/+milestone/essex-2 diff --git a/docs/source/old/services.rst b/docs/source/old/services.rst deleted file mode 100644 index 4c147bd0..00000000 --- a/docs/source/old/services.rst +++ /dev/null @@ -1,92 +0,0 @@ -.. - Copyright 2011-2012 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. - -================ -Services -================ - -.. toctree:: - :maxdepth: 1 - - -What are services? -================== - -Keystone includes service registry and service catalog functionality which it -uses to respond to client authentication requests with information useful to -clients in locating the list of available services they can access. - -The Service entity in Keystone represents an OpenStack service that is integrated -with Keystone. The Service entity is also used as a reference from roles, endpoints, -and endpoint templates. - -Keystone also includes an authorization mechanism to allow a service to own -its own roles and endpoints and prevent other services from changing or -modifying them. - -Who can create services? -======================== - -Any user with the Admin or Service Admin roles in Keystone may create services. - -How are services created? -========================= - -Services can be created using ``keystone-manage`` or through the REST API using -the OS-KSADM extension calls. - -Using ``keystone-manage`` (see :doc:`man/keystone-manage` for details):: - - $ keystone-manage add service compute nova 'This is a sample compute service' - -Using the REST API (see `extensions dev guide `_ for details):: - - $ curl -H "Content-type: application/json" -X POST -d '{ - "OS-KSADM:service": { - "name": "nova", - "type": "compute", - "description": "This is a sample compute service" - } - }' -H "X-Auth-Token: 999888777666" http://localhost:35357/v2.0/OS-KSADM/services/ - -How is service ownership determined? -==================================== - -Currently, the way to assign ownership to a service is to provide the owner's -user id in the keystone-manage add command:: - - $ keystone-manage add service nova compute 'This is a sample compute service' joeuser - -This will assign ownership to the new service to joeuser. - -When a service has an owner, then only that owner (or a global Admin) can create and manage -roles that start with that service name (ex: "nova:admin") and manage endpoints -and endpoint templates associated with that service. - -Listing services -================ - -Using ``keystone-manage``, the list of services and their owners can be listed:: - - $ keystone-manage service list - - id name type owner_id description - ------------------------------------------------------------------------------- - 1 compute nova joeuser This is a sample compute service - -Using the REST API, call ``GET /v2.0/OS-KSADM/services`` - -.. note: The rest API does not yet support service ownership diff --git a/docs/source/old/ssl.rst b/docs/source/old/ssl.rst deleted file mode 100644 index 926efd59..00000000 --- a/docs/source/old/ssl.rst +++ /dev/null @@ -1,118 +0,0 @@ -.. - Copyright 2011-2012 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. - -=========================== -x.509 Client Authentication -=========================== - -Purpose -======= - -Allows the Keystone middleware to authenticate itself with the Keystone server -via an x.509 client certificate. Both Service API and Admin API may be secured -with this feature. - -Certificates -============ - -The following types of certificates are required. A set of certficates is provided -in the examples/ssl directory with the Keystone distribution for testing. Here -is the description of each of them and their purpose: - -ca.pem - Certificate Authority chain to validate against. - -keystone.pem - Public certificate for Keystone server. - -middleware-key.pem - Public and private certificate for Keystone middleware. - -cakey.pem - Private key for the CA. - -keystonekey.pem - Private key for the Keystone server. - -Note that you may choose whatever names you want for these certificates, or combine -the public/private keys in the same file if you wish. These certificates are just -provided as an example. - -Configuration -============= - -By default, the Keystone server does not use SSL. To enable SSL with client authentication, -modify the etc/keystone.conf file accordingly: - -1. To enable SSL for Service API:: - - service_ssl = True - -2. To enable SSL for Admin API:: - - admin_ssl = True - -3. To enable SSL client authentication:: - - cert_required = True - -4. Set the location of the Keystone certificate file (example):: - - certfile = /etc/keystone/ca/certs/keystone.pem - -5. Set the location of the Keystone private file (example):: - - keyfile = /etc/keystone/ca/private/keystonekey.pem - -6. Set the location of the CA chain:: - - ca_certs = /etc/keystone/ca/certs/ca.pem - -Middleware -========== - -Add the following to your middleware configuration to support x.509 client authentication. -If ``cert_required`` is set to ``False`` on the keystone server, the certfile and keyfile parameters -in steps 3) and 4) may be commented out. - -1. Specify 'https' as the auth_protocol:: - - auth_protocol = https - -2. Modify the protocol in 'auth_uri' to be 'https' as well, if the service API is configured - for SSL:: - - auth_uri = https://localhost:5000/ - -3. Set the location of the middleware certificate file (example):: - - certfile = /etc/keystone/ca/certs/middleware-key.pem - -4. Set the location of the Keystone private file (example):: - - keyfile = /etc/keystone/ca/certs/middleware-key.pem - -For an example, take a look at the ``echo.ini`` middleware configuration for the 'echo' example -service in the examples/echo directory. - -Testing -======= - -You can test out how it works by using the ``echo`` example service in the ``examples/echo`` directory -and the certficates included in the ``examples/ssl`` directory. Invoke the ``echo_client.py`` with -the path to the client certificate:: - - python echo_client.py -s diff --git a/docs/source/setup.rst b/docs/source/setup.rst deleted file mode 100644 index 06303039..00000000 --- a/docs/source/setup.rst +++ /dev/null @@ -1,171 +0,0 @@ -.. - Copyright 2011-2012 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. - -============================================= -Setting up a Keystone development environment -============================================= - -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 Repository`: http://github.com/openstack/keystone -.. _`User Documentation`: http://docs.openstack.org/ - -Prerequisites -============= - -This document assumes you are using: - -- Ubuntu 11.10, Fedora 15, or Mac OS X Lion -- `Python 2.7`_ - -.. _`Python 2.7`: http://www.python.org/ - -And that you have the following tools available on your system: - -- git_ -- setuptools_ -- pip_ - -**Reminder**: If you're successfully using a different platform, or a -different version of the above, please document your configuration here! - -.. _git: http://git-scm.com/ -.. _setuptools: http://pypi.python.org/pypi/setuptools - -Getting the latest code -======================= - -Make a clone of the code from our `Github repository`:: - - $ git clone https://github.com/openstack/keystone.git - -When that is complete, you can:: - - $ cd keystone - -Installing dependencies -======================= - -Keystone maintains two lists of dependencies:: - - tools/pip-requires - tools/test-requires - -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 - -However, your system *may* need additional dependencies that `pip` (and by -extension, PyPi) cannot satisfy. These dependencies should be installed -prior to using `pip`, and the installation method may vary depending on -your platform. - -Ubuntu 11.10:: - - $ sudo apt-get install python-dev libxml2-dev libxslt1-dev libsasl2-dev libsqlite3-dev libssl-dev libldap2-dev - -Fedora 15:: - - $ sudo yum install python-sqlite2 python-lxml python-greenlet-devel python-ldap - -Mac OS X Lion (requires MacPorts_):: - - $ sudo port install py-ldap - -.. _MacPorts: http://www.macports.org/ - -PyPi Packages and VirtualEnv ----------------------------- - -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:: - - $ python tools/install_venv.py - -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/ - -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:: - - >>> import keystone - >>> - -If you can import keystone successfully, you should be ready to move on to :doc:`developing` - -Troubleshooting -=============== - -Eventlet segfaults on RedHat / Fedora -------------------------------------- - -[*If this is no longer an issue, please remove this section, thanks!*] - -On some OSes, specifically Fedora 15, the current versions of -greenlet/eventlet segfault when running keystone. To fix this, install -the development versions of greenlet and eventlet:: - - $ pip uninstall greenlet eventlet - $ cd - $ hg clone https://bitbucket.org/ambroff/greenlet - $ cd greenlet - $ sudo python setup.py install - - $ cd - $ hg clone https://bitbucket.org/which_linden/eventlet - $ cd greenlet - $ sudo python setup.py install diff --git a/docs/source/static/basic.css b/docs/source/static/basic.css deleted file mode 100644 index d909ce37..00000000 --- a/docs/source/static/basic.css +++ /dev/null @@ -1,416 +0,0 @@ -/** - * Sphinx stylesheet -- basic theme - * ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - */ - -/* -- main layout ----------------------------------------------------------- */ - -div.clearer { - clear: both; -} - -/* -- relbar ---------------------------------------------------------------- */ - -div.related { - width: 100%; - font-size: 90%; -} - -div.related h3 { - display: none; -} - -div.related ul { - margin: 0; - padding: 0 0 0 10px; - list-style: none; -} - -div.related li { - display: inline; -} - -div.related li.right { - float: right; - margin-right: 5px; -} - -/* -- sidebar --------------------------------------------------------------- */ - -div.sphinxsidebarwrapper { - padding: 10px 5px 0 10px; -} - -div.sphinxsidebar { - float: left; - width: 230px; - margin-left: -100%; - font-size: 90%; -} - -div.sphinxsidebar ul { - list-style: none; -} - -div.sphinxsidebar ul ul, -div.sphinxsidebar ul.want-points { - margin-left: 20px; - list-style: square; -} - -div.sphinxsidebar ul ul { - margin-top: 0; - margin-bottom: 0; -} - -div.sphinxsidebar form { - margin-top: 10px; -} - -div.sphinxsidebar input { - border: 1px solid #98dbcc; - font-family: sans-serif; - font-size: 1em; -} - -img { - border: 0; -} - -/* -- search page ----------------------------------------------------------- */ - -ul.search { - margin: 10px 0 0 20px; - padding: 0; -} - -ul.search li { - padding: 5px 0 5px 20px; - background-image: url(file.png); - background-repeat: no-repeat; - background-position: 0 7px; -} - -ul.search li a { - font-weight: bold; -} - -ul.search li div.context { - color: #888; - margin: 2px 0 0 30px; - text-align: left; -} - -ul.keywordmatches li.goodmatch a { - font-weight: bold; -} - -/* -- index page ------------------------------------------------------------ */ - -table.contentstable { - width: 90%; -} - -table.contentstable p.biglink { - line-height: 150%; -} - -a.biglink { - font-size: 1.3em; -} - -span.linkdescr { - font-style: italic; - padding-top: 5px; - font-size: 90%; -} - -/* -- general index --------------------------------------------------------- */ - -table.indextable td { - text-align: left; - vertical-align: top; -} - -table.indextable dl, table.indextable dd { - margin-top: 0; - margin-bottom: 0; -} - -table.indextable tr.pcap { - height: 10px; -} - -table.indextable tr.cap { - margin-top: 10px; - background-color: #f2f2f2; -} - -img.toggler { - margin-right: 3px; - margin-top: 3px; - cursor: pointer; -} - -/* -- general body styles --------------------------------------------------- */ - -a.headerlink { - visibility: hidden; -} - -h1:hover > a.headerlink, -h2:hover > a.headerlink, -h3:hover > a.headerlink, -h4:hover > a.headerlink, -h5:hover > a.headerlink, -h6:hover > a.headerlink, -dt:hover > a.headerlink { - visibility: visible; -} - -div.body p.caption { - text-align: inherit; -} - -div.body td { - text-align: left; -} - -.field-list ul { - padding-left: 1em; -} - -.first { -} - -p.rubric { - margin-top: 30px; - font-weight: bold; -} - -/* -- sidebars -------------------------------------------------------------- */ - -div.sidebar { - margin: 0 0 0.5em 1em; - border: 1px solid #ddb; - padding: 7px 7px 0 7px; - background-color: #ffe; - width: 40%; - float: right; -} - -p.sidebar-title { - font-weight: bold; -} - -/* -- topics ---------------------------------------------------------------- */ - -div.topic { - border: 1px solid #ccc; - padding: 7px 7px 0 7px; - margin: 10px 0 10px 0; -} - -p.topic-title { - font-size: 1.1em; - font-weight: bold; - margin-top: 10px; -} - -/* -- admonitions ----------------------------------------------------------- */ - -div.admonition { - margin-top: 10px; - margin-bottom: 10px; - padding: 7px; -} - -div.admonition dt { - font-weight: bold; -} - -div.admonition dl { - margin-bottom: 0; -} - -p.admonition-title { - margin: 0px 10px 5px 0px; - font-weight: bold; -} - -div.body p.centered { - text-align: center; - margin-top: 25px; -} - -/* -- tables ---------------------------------------------------------------- */ - -table.docutils { - border: 0; - border-collapse: collapse; -} - -table.docutils td, table.docutils th { - padding: 1px 8px 1px 0; - border-top: 0; - border-left: 0; - border-right: 0; - border-bottom: 1px solid #aaa; -} - -table.field-list td, table.field-list th { - border: 0 !important; -} - -table.footnote td, table.footnote th { - border: 0 !important; -} - -th { - text-align: left; - padding-right: 5px; -} - -/* -- other body styles ----------------------------------------------------- */ - -dl { - margin-bottom: 15px; -} - -dd p { - margin-top: 0px; -} - -dd ul, dd table { - margin-bottom: 10px; -} - -dd { - margin-top: 3px; - margin-bottom: 10px; - margin-left: 30px; -} - -dt:target, .highlight { - background-color: #fbe54e; -} - -dl.glossary dt { - font-weight: bold; - font-size: 1.1em; -} - -.field-list ul { - margin: 0; - padding-left: 1em; -} - -.field-list p { - margin: 0; -} - -.refcount { - color: #060; -} - -.optional { - font-size: 1.3em; -} - -.versionmodified { - font-style: italic; -} - -.system-message { - background-color: #fda; - padding: 5px; - border: 3px solid red; -} - -.footnote:target { - background-color: #ffa -} - -.line-block { - display: block; - margin-top: 1em; - margin-bottom: 1em; -} - -.line-block .line-block { - margin-top: 0; - margin-bottom: 0; - margin-left: 1.5em; -} - -/* -- code displays --------------------------------------------------------- */ - -pre { - overflow: auto; -} - -td.linenos pre { - padding: 5px 0px; - border: 0; - background-color: transparent; - color: #aaa; -} - -table.highlighttable { - margin-left: 0.5em; -} - -table.highlighttable td { - padding: 0 0.5em 0 0.5em; -} - -tt.descname { - background-color: transparent; - font-weight: bold; - font-size: 1.2em; -} - -tt.descclassname { - background-color: transparent; -} - -tt.xref, a tt { - background-color: transparent; - font-weight: bold; -} - -h1 tt, h2 tt, h3 tt, h4 tt, h5 tt, h6 tt { - background-color: transparent; -} - -/* -- math display ---------------------------------------------------------- */ - -img.math { - vertical-align: middle; -} - -div.body div.math p { - text-align: center; -} - -span.eqno { - float: right; -} - -/* -- printout stylesheet --------------------------------------------------- */ - -@media print { - div.document, - div.documentwrapper, - div.bodywrapper { - margin: 0 !important; - width: 100%; - } - - div.sphinxsidebar, - div.related, - div.footer, - #top-link { - display: none; - } -} diff --git a/docs/source/static/default.css b/docs/source/static/default.css deleted file mode 100644 index c8091ecb..00000000 --- a/docs/source/static/default.css +++ /dev/null @@ -1,230 +0,0 @@ -/** - * Sphinx stylesheet -- default theme - * ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - */ - -@import url("basic.css"); - -/* -- page layout ----------------------------------------------------------- */ - -body { - font-family: sans-serif; - font-size: 100%; - background-color: #11303d; - color: #000; - margin: 0; - padding: 0; -} - -div.document { - background-color: #1c4e63; -} - -div.documentwrapper { - float: left; - width: 100%; -} - -div.bodywrapper { - margin: 0 0 0 230px; -} - -div.body { - background-color: #ffffff; - color: #000000; - padding: 0 20px 30px 20px; -} - -div.footer { - color: #ffffff; - width: 100%; - padding: 9px 0 9px 0; - text-align: center; - font-size: 75%; -} - -div.footer a { - color: #ffffff; - text-decoration: underline; -} - -div.related { - background-color: #133f52; - line-height: 30px; - color: #ffffff; -} - -div.related a { - color: #ffffff; -} - -div.sphinxsidebar { -} - -div.sphinxsidebar h3 { - font-family: 'Trebuchet MS', sans-serif; - color: #ffffff; - font-size: 1.4em; - font-weight: normal; - margin: 0; - padding: 0; -} - -div.sphinxsidebar h3 a { - color: #ffffff; -} - -div.sphinxsidebar h4 { - font-family: 'Trebuchet MS', sans-serif; - color: #ffffff; - font-size: 1.3em; - font-weight: normal; - margin: 5px 0 0 0; - padding: 0; -} - -div.sphinxsidebar p { - color: #ffffff; -} - -div.sphinxsidebar p.topless { - margin: 5px 10px 10px 10px; -} - -div.sphinxsidebar ul { - margin: 10px; - padding: 0; - color: #ffffff; -} - -div.sphinxsidebar a { - color: #98dbcc; -} - -div.sphinxsidebar input { - border: 1px solid #98dbcc; - font-family: sans-serif; - font-size: 1em; -} - -/* -- body styles ----------------------------------------------------------- */ - -a { - color: #355f7c; - text-decoration: none; -} - -a:hover { - text-decoration: underline; -} - -div.body p, div.body dd, div.body li { - text-align: left; - line-height: 130%; -} - -div.body h1, -div.body h2, -div.body h3, -div.body h4, -div.body h5, -div.body h6 { - font-family: 'Trebuchet MS', sans-serif; - background-color: #f2f2f2; - font-weight: normal; - color: #20435c; - border-bottom: 1px solid #ccc; - margin: 20px -20px 10px -20px; - padding: 3px 0 3px 10px; -} - -div.body h1 { margin-top: 0; font-size: 200%; } -div.body h2 { font-size: 160%; } -div.body h3 { font-size: 140%; } -div.body h4 { font-size: 120%; } -div.body h5 { font-size: 110%; } -div.body h6 { font-size: 100%; } - -a.headerlink { - color: #c60f0f; - font-size: 0.8em; - padding: 0 4px 0 4px; - text-decoration: none; -} - -a.headerlink:hover { - background-color: #c60f0f; - color: white; -} - -div.body p, div.body dd, div.body li { - text-align: left; - line-height: 130%; -} - -div.admonition p.admonition-title + p { - display: inline; -} - -div.admonition p { - margin-bottom: 5px; -} - -div.admonition pre { - margin-bottom: 5px; -} - -div.admonition ul, div.admonition ol { - margin-bottom: 5px; -} - -div.note { - background-color: #eee; - border: 1px solid #ccc; -} - -div.seealso { - background-color: #ffc; - border: 1px solid #ff6; -} - -div.topic { - background-color: #eee; -} - -div.warning { - background-color: #ffe4e4; - border: 1px solid #f66; -} - -p.admonition-title { - display: inline; -} - -p.admonition-title:after { - content: ":"; -} - -pre { - padding: 5px; - background-color: #eeffcc; - color: #333333; - line-height: 120%; - border: 1px solid #ac9; - border-left: none; - border-right: none; -} - -tt { - background-color: #ecf0f3; - padding: 0 1px 0 1px; - font-size: 0.95em; -} - -.warning tt { - background: #efc2c2; -} - -.note tt { - background: #d6d6d6; -} diff --git a/docs/source/static/jquery.tweet.js b/docs/source/static/jquery.tweet.js deleted file mode 100644 index c93fea87..00000000 --- a/docs/source/static/jquery.tweet.js +++ /dev/null @@ -1,154 +0,0 @@ -(function($) { - - $.fn.tweet = function(o){ - var s = { - username: ["seaofclouds"], // [string] required, unless you want to display our tweets. :) it can be an array, just do ["username1","username2","etc"] - list: null, //[string] optional name of list belonging to username - avatar_size: null, // [integer] height and width of avatar if displayed (48px max) - count: 3, // [integer] how many tweets to display? - intro_text: null, // [string] do you want text BEFORE your your tweets? - outro_text: null, // [string] do you want text AFTER your tweets? - join_text: null, // [string] optional text in between date and tweet, try setting to "auto" - auto_join_text_default: "i said,", // [string] auto text for non verb: "i said" bullocks - auto_join_text_ed: "i", // [string] auto text for past tense: "i" surfed - auto_join_text_ing: "i am", // [string] auto tense for present tense: "i was" surfing - auto_join_text_reply: "i replied to", // [string] auto tense for replies: "i replied to" @someone "with" - auto_join_text_url: "i was looking at", // [string] auto tense for urls: "i was looking at" http:... - loading_text: null, // [string] optional loading text, displayed while tweets load - query: null // [string] optional search query - }; - - if(o) $.extend(s, o); - - $.fn.extend({ - linkUrl: function() { - var returning = []; - var regexp = /((ftp|http|https):\/\/(\w+:{0,1}\w*@)?(\S+)(:[0-9]+)?(\/|\/([\w#!:.?+=&%@!\-\/]))?)/gi; - this.each(function() { - returning.push(this.replace(regexp,"$1")); - }); - return $(returning); - }, - linkUser: function() { - var returning = []; - var regexp = /[\@]+([A-Za-z0-9-_]+)/gi; - this.each(function() { - returning.push(this.replace(regexp,"@$1")); - }); - return $(returning); - }, - linkHash: function() { - var returning = []; - var regexp = / [\#]+([A-Za-z0-9-_]+)/gi; - this.each(function() { - returning.push(this.replace(regexp, ' #$1')); - }); - return $(returning); - }, - capAwesome: function() { - var returning = []; - this.each(function() { - returning.push(this.replace(/\b(awesome)\b/gi, '$1')); - }); - return $(returning); - }, - capEpic: function() { - var returning = []; - this.each(function() { - returning.push(this.replace(/\b(epic)\b/gi, '$1')); - }); - return $(returning); - }, - makeHeart: function() { - var returning = []; - this.each(function() { - returning.push(this.replace(/(<)+[3]/gi, "♥")); - }); - return $(returning); - } - }); - - function relative_time(time_value) { - var parsed_date = Date.parse(time_value); - var relative_to = (arguments.length > 1) ? arguments[1] : new Date(); - var delta = parseInt((relative_to.getTime() - parsed_date) / 1000); - var pluralize = function (singular, n) { - return '' + n + ' ' + singular + (n == 1 ? '' : 's'); - }; - if(delta < 60) { - return 'less than a minute ago'; - } else if(delta < (45*60)) { - return 'about ' + pluralize("minute", parseInt(delta / 60)) + ' ago'; - } else if(delta < (24*60*60)) { - return 'about ' + pluralize("hour", parseInt(delta / 3600)) + ' ago'; - } else { - return 'about ' + pluralize("day", parseInt(delta / 86400)) + ' ago'; - } - } - - function build_url() { - var proto = ('https:' == document.location.protocol ? 'https:' : 'http:'); - if (s.list) { - return proto+"//api.twitter.com/1/"+s.username[0]+"/lists/"+s.list+"/statuses.json?per_page="+s.count+"&callback=?"; - } else if (s.query == null && s.username.length == 1) { - return proto+'//twitter.com/status/user_timeline/'+s.username[0]+'.json?count='+s.count+'&callback=?'; - } else { - var query = (s.query || 'from:'+s.username.join('%20OR%20from:')); - return proto+'//search.twitter.com/search.json?&q='+query+'&rpp='+s.count+'&callback=?'; - } - } - - return this.each(function(){ - var list = $('
    ').appendTo(this); - var intro = '

    '+s.intro_text+'

    '; - var outro = '

    '+s.outro_text+'

    '; - var loading = $('

    '+s.loading_text+'

    '); - - if(typeof(s.username) == "string"){ - s.username = [s.username]; - } - - if (s.loading_text) $(this).append(loading); - $.getJSON(build_url(), function(data){ - if (s.loading_text) loading.remove(); - if (s.intro_text) list.before(intro); - $.each((data.results || data), function(i,item){ - // auto join text based on verb tense and content - if (s.join_text == "auto") { - if (item.text.match(/^(@([A-Za-z0-9-_]+)) .*/i)) { - var join_text = s.auto_join_text_reply; - } else if (item.text.match(/(^\w+:\/\/[A-Za-z0-9-_]+\.[A-Za-z0-9-_:%&\?\/.=]+) .*/i)) { - var join_text = s.auto_join_text_url; - } else if (item.text.match(/^((\w+ed)|just) .*/im)) { - var join_text = s.auto_join_text_ed; - } else if (item.text.match(/^(\w*ing) .*/i)) { - var join_text = s.auto_join_text_ing; - } else { - var join_text = s.auto_join_text_default; - } - } else { - var join_text = s.join_text; - }; - - var from_user = item.from_user || item.user.screen_name; - var profile_image_url = item.profile_image_url || item.user.profile_image_url; - var join_template = ' '+join_text+' '; - var join = ((s.join_text) ? join_template : ' '); - var avatar_template = ''+from_user+'\'s avatar'; - var avatar = (s.avatar_size ? avatar_template : ''); - var date = ''+relative_time(item.created_at)+''; - var text = '' +$([item.text]).linkUrl().linkUser().linkHash().makeHeart().capAwesome().capEpic()[0]+ ''; - - // until we create a template option, arrange the items below to alter a tweet's display. - list.append('
  • ' + avatar + date + join + text + '
    • '); - - list.children('li:first').addClass('tweet_first'); - list.children('li:odd').addClass('tweet_even'); - list.children('li:even').addClass('tweet_odd'); - }); - if (s.outro_text) list.after(outro); - }); - - }); - }; -})(jQuery); \ No newline at end of file diff --git a/docs/source/static/tweaks.css b/docs/source/static/tweaks.css deleted file mode 100644 index 16cd6e76..00000000 --- a/docs/source/static/tweaks.css +++ /dev/null @@ -1,65 +0,0 @@ -ul.todo_list { - list-style-type: none; - margin: 0; - padding: 0; -} - -ul.todo_list li { - display: block; - margin: 0; - padding: 7px 0; - border-top: 1px solid #eee; -} - -ul.todo_list li p { - display: inline; -} - -ul.todo_list li p.link { - font-weight: bold; -} - -ul.todo_list li p.details { - font-style: italic; -} - -ul.todo_list li { -} - -div.admonition { - border: 1px solid #8F1000; -} - -div.admonition p.admonition-title { - background-color: #8F1000; - border-bottom: 1px solid #8E8E8E; -} - -a { - color: #CF2F19; -} - -div.related ul li a { - color: #CF2F19; -} - -div.sphinxsidebar h4 { - background-color:#8E8E8E; - border:1px solid #255E6E; - color:white; - font-size:1em; - margin:1em 0 0.5em; - padding:0.1em 0 0.1em 0.5em; -} - -em { - font-style: normal; -} - -table.docutils { - font-size: 11px; -} - -a tt { - color:#CF2F19; -} \ No newline at end of file -- cgit