From 9aed303f37b221a142b330a1ced23b4135c81b82 Mon Sep 17 00:00:00 2001 From: Clark Boylan Date: Fri, 8 Jun 2012 15:41:05 -0700 Subject: [PATCH 01/40] Move docs to doc. To better facilitate the building and publishing of sphinx documentation by Jenkins we are moving all openstack projects with sphinx documentation to a common doc tree structure. Documentation goes in project/doc/source and build results go in project/doc/build. Change-Id: I205e8bb1ddf6dae1d7392b32975319c6a6d98673 --- .gitignore | 1 + Makefile | 90 +++++++++++++++ source/conf.py | 200 ++++++++++++++++++++++++++++++++++ source/index.rst | 37 +++++++ source/ref/client.rst | 8 ++ source/ref/endpoints.rst | 11 ++ source/ref/exceptions.rst | 8 ++ source/ref/generic-client.rst | 12 ++ source/ref/index.rst | 16 +++ source/ref/roles.rst | 9 ++ source/ref/services.rst | 11 ++ source/ref/tenants.rst | 11 ++ source/ref/users.rst | 9 ++ source/releases.rst | 106 ++++++++++++++++++ source/shell.rst | 59 ++++++++++ source/using-api.rst | 109 ++++++++++++++++++ 16 files changed, 697 insertions(+) create mode 100644 .gitignore create mode 100644 Makefile create mode 100644 source/conf.py create mode 100644 source/index.rst create mode 100644 source/ref/client.rst create mode 100644 source/ref/endpoints.rst create mode 100644 source/ref/exceptions.rst create mode 100644 source/ref/generic-client.rst create mode 100644 source/ref/index.rst create mode 100644 source/ref/roles.rst create mode 100644 source/ref/services.rst create mode 100644 source/ref/tenants.rst create mode 100644 source/ref/users.rst create mode 100644 source/releases.rst create mode 100644 source/shell.rst create mode 100644 source/using-api.rst diff --git a/.gitignore b/.gitignore new file mode 100644 index 00000000..567609b1 --- /dev/null +++ b/.gitignore @@ -0,0 +1 @@ +build/ diff --git a/Makefile b/Makefile new file mode 100644 index 00000000..430e5a33 --- /dev/null +++ b/Makefile @@ -0,0 +1,90 @@ +# Makefile for Sphinx documentation +# + +# You can set these variables from the command line. +SPHINXOPTS = +SPHINXBUILD = sphinx-build +SPHINXSOURCE = source +PAPER = +BUILDDIR = build + +# Internal variables. +PAPEROPT_a4 = -D latex_paper_size=a4 +PAPEROPT_letter = -D latex_paper_size=letter +ALLSPHINXOPTS = -d $(BUILDDIR)/doctrees $(PAPEROPT_$(PAPER)) $(SPHINXOPTS) $(SPHINXSOURCE) + +.PHONY: help clean html dirhtml pickle json htmlhelp qthelp latex changes linkcheck doctest + +help: + @echo "Please use \`make ' where is one of" + @echo " html to make standalone HTML files" + @echo " dirhtml to make HTML files named index.html in directories" + @echo " pickle to make pickle files" + @echo " json to make JSON files" + @echo " htmlhelp to make HTML files and a HTML help project" + @echo " qthelp to make HTML files and a qthelp project" + @echo " latex to make LaTeX files, you can set PAPER=a4 or PAPER=letter" + @echo " changes to make an overview of all changed/added/deprecated items" + @echo " linkcheck to check all external links for integrity" + @echo " doctest to run all doctests embedded in the documentation (if enabled)" + +clean: + -rm -rf $(BUILDDIR)/* + +html: + $(SPHINXBUILD) -b html $(ALLSPHINXOPTS) $(BUILDDIR)/html + @echo + @echo "Build finished. The HTML pages are in $(BUILDDIR)/html." + +dirhtml: + $(SPHINXBUILD) -b dirhtml $(ALLSPHINXOPTS) $(BUILDDIR)/dirhtml + @echo + @echo "Build finished. The HTML pages are in $(BUILDDIR)/dirhtml." + +pickle: + $(SPHINXBUILD) -b pickle $(ALLSPHINXOPTS) $(BUILDDIR)/pickle + @echo + @echo "Build finished; now you can process the pickle files." + +json: + $(SPHINXBUILD) -b json $(ALLSPHINXOPTS) $(BUILDDIR)/json + @echo + @echo "Build finished; now you can process the JSON files." + +htmlhelp: + $(SPHINXBUILD) -b htmlhelp $(ALLSPHINXOPTS) $(BUILDDIR)/htmlhelp + @echo + @echo "Build finished; now you can run HTML Help Workshop with the" \ + ".hhp project file in $(BUILDDIR)/htmlhelp." + +qthelp: + $(SPHINXBUILD) -b qthelp $(ALLSPHINXOPTS) $(BUILDDIR)/qthelp + @echo + @echo "Build finished; now you can run "qcollectiongenerator" with the" \ + ".qhcp project file in $(BUILDDIR)/qthelp, like this:" + @echo "# qcollectiongenerator $(BUILDDIR)/qthelp/python-keystoneclient.qhcp" + @echo "To view the help file:" + @echo "# assistant -collectionFile $(BUILDDIR)/qthelp/python-keystoneclient.qhc" + +latex: + $(SPHINXBUILD) -b latex $(ALLSPHINXOPTS) $(BUILDDIR)/latex + @echo + @echo "Build finished; the LaTeX files are in $(BUILDDIR)/latex." + @echo "Run \`make all-pdf' or \`make all-ps' in that directory to" \ + "run these through (pdf)latex." + +changes: + $(SPHINXBUILD) -b changes $(ALLSPHINXOPTS) $(BUILDDIR)/changes + @echo + @echo "The overview file is in $(BUILDDIR)/changes." + +linkcheck: + $(SPHINXBUILD) -b linkcheck $(ALLSPHINXOPTS) $(BUILDDIR)/linkcheck + @echo + @echo "Link check complete; look for any errors in the above output " \ + "or in $(BUILDDIR)/linkcheck/output.txt." + +doctest: + $(SPHINXBUILD) -b doctest $(ALLSPHINXOPTS) $(BUILDDIR)/doctest + @echo "Testing of doctests in the sources finished, look at the " \ + "results in $(BUILDDIR)/doctest/output.txt." diff --git a/source/conf.py b/source/conf.py new file mode 100644 index 00000000..15112e75 --- /dev/null +++ b/source/conf.py @@ -0,0 +1,200 @@ +# -*- coding: utf-8 -*- +# +# python-keystoneclient documentation build configuration file, created by +# sphinx-quickstart on Sun Dec 6 14:19:25 2009. +# +# 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, os + +sys.path.insert(0, os.path.abspath(os.path.join(os.path.dirname(__file__), "..", ".."))) + +# 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.append(os.path.abspath('.')) + +# -- General configuration ----------------------------------------------------- + +# 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'] + +# Add any paths that contain templates here, relative to this directory. +templates_path = ['_templates'] + +# The suffix of source filenames. +source_suffix = '.rst' + +# The encoding of source files. +#source_encoding = 'utf-8' + +# The master toctree document. +master_doc = 'index' + +# General information about the project. +project = u'python-keystoneclient' +copyright = u'Rackspace, based on work by Jacob Kaplan-Moss' + +# 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 = '2.7' +# The full version, including alpha/beta/rc tags. +release = '2.7.0' + +# 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 documents that shouldn't be included in the build. +#unused_docs = [] + +# List of directories, relative to source directory, that shouldn't be searched +# for source files. +exclude_trees = [] + +# The reST default role (used for this markup: `text`) to use for all documents. +#default_role = None + +# If true, '()' will be appended to :func: etc. cross-reference text. +add_function_parentheses = True + +# If true, the current module name will be prepended to all description +# unit titles (such as .. function::). +add_module_names = True + +# If true, sectionauthor and moduleauthor directives will be shown in the +# output. They are ignored by default. +#show_authors = False + +# The name of the Pygments (syntax highlighting) style to use. +pygments_style = 'sphinx' + +# A list of ignored prefixes for module index sorting. +#modindex_common_prefix = [] + + +# -- Options for HTML output --------------------------------------------------- + +# The theme to use for HTML and HTML Help pages. Major themes that come with +# Sphinx are currently 'default' and 'sphinxdoc'. +html_theme = 'nature' + +# 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'] + +# 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_use_modindex = 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, 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 = '' + +# If nonempty, this is the file name suffix for HTML files (e.g. ".xhtml"). +#html_file_suffix = '' + +# Output file base name for HTML help builder. +htmlhelp_basename = 'python-keystoneclientdoc' + + +# -- Options for LaTeX output -------------------------------------------------- + +# The paper size ('letter' or 'a4'). +#latex_paper_size = 'letter' + +# The font size ('10pt', '11pt' or '12pt'). +#latex_font_size = '10pt' + +# Grouping the document tree into LaTeX files. List of tuples +# (source start file, target name, title, author, documentclass [howto/manual]). +latex_documents = [ + ('index', 'python-keystoneclient.tex', u'python-keystoneclient Documentation', + u'Nebula Inc, based on work by Rackspace and Jacob Kaplan-Moss', '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 + +# Additional stuff for the LaTeX preamble. +#latex_preamble = '' + +# Documents to append as an appendix to all manuals. +#latex_appendices = [] + +# If false, no module index is generated. +#latex_use_modindex = True + + +# Example configuration for intersphinx: refer to the Python standard library. +intersphinx_mapping = {'http://docs.python.org/': None} diff --git a/source/index.rst b/source/index.rst new file mode 100644 index 00000000..bece0aa9 --- /dev/null +++ b/source/index.rst @@ -0,0 +1,37 @@ +Python bindings to the OpenStack Keystone API +================================================== + +This is a client for OpenStack Keystone API. There's :doc:`a Python API +` (the :mod:`keystoneclient` module), and a :doc:`command-line script +` (installed as :program:`keystone`). + +Contents: + +.. toctree:: + :maxdepth: 1 + + using-api + shell + ref/index + releases + +Contributing +============ + +Code is hosted `on GitHub`_. Submit bugs to the Keystone project on +`Launchpad`_. Submit code to the openstack/python-keystoneclient project using +`Gerrit`_. + +.. _on GitHub: https://github.com/openstack/python-keystoneclient +.. _Launchpad: https://launchpad.net/keystone +.. _Gerrit: http://wiki.openstack.org/GerritWorkflow + +Run tests with ``python setup.py test``. + +Indices and tables +================== + +* :ref:`genindex` +* :ref:`modindex` +* :ref:`search` + diff --git a/source/ref/client.rst b/source/ref/client.rst new file mode 100644 index 00000000..cb21e3ec --- /dev/null +++ b/source/ref/client.rst @@ -0,0 +1,8 @@ +Client +====== + +.. currentmodule:: keystoneclient.v2_0.client + +.. autoclass:: Client + + .. automethod:: authenticate diff --git a/source/ref/endpoints.rst b/source/ref/endpoints.rst new file mode 100644 index 00000000..ed2b4e2c --- /dev/null +++ b/source/ref/endpoints.rst @@ -0,0 +1,11 @@ +============================== +Endpoint Manager and Endpoints +============================== + + + +.. currentmodule:: keystoneclient.v2_0.endpoints + +.. automodule:: keystoneclient.v2_0.endpoints + :members: + diff --git a/source/ref/exceptions.rst b/source/ref/exceptions.rst new file mode 100644 index 00000000..988f7d06 --- /dev/null +++ b/source/ref/exceptions.rst @@ -0,0 +1,8 @@ +Exceptions +========== + +.. currentmodule:: keystoneclient.exceptions + +.. automodule:: keystoneclient.exceptions + :members: + diff --git a/source/ref/generic-client.rst b/source/ref/generic-client.rst new file mode 100644 index 00000000..99055587 --- /dev/null +++ b/source/ref/generic-client.rst @@ -0,0 +1,12 @@ +Generic client +============== + +Use the generic client to obtain access to a specific endpoint version. + + +.. currentmodule:: keystoneclient.generic.client + +.. autoclass:: Client + + .. automethod:: discover + diff --git a/source/ref/index.rst b/source/ref/index.rst new file mode 100644 index 00000000..d99127e3 --- /dev/null +++ b/source/ref/index.rst @@ -0,0 +1,16 @@ +API Reference +============= + +The following API reference documents are available: + +.. toctree:: + :maxdepth: 1 + + client + generic-client + tenants + users + roles + services + endpoints + exceptions diff --git a/source/ref/roles.rst b/source/ref/roles.rst new file mode 100644 index 00000000..9cb92839 --- /dev/null +++ b/source/ref/roles.rst @@ -0,0 +1,9 @@ +====================== +Role Manager and Roles +====================== + +.. currentmodule:: keystoneclient.v2_0.roles + +.. automodule:: keystoneclient.v2_0.roles + :members: + diff --git a/source/ref/services.rst b/source/ref/services.rst new file mode 100644 index 00000000..a4b677cf --- /dev/null +++ b/source/ref/services.rst @@ -0,0 +1,11 @@ +============================ +Service Manager and Services +============================ + + + +.. currentmodule:: keystoneclient.v2_0.services + +.. automodule:: keystoneclient.v2_0.services + :members: + diff --git a/source/ref/tenants.rst b/source/ref/tenants.rst new file mode 100644 index 00000000..d6e38618 --- /dev/null +++ b/source/ref/tenants.rst @@ -0,0 +1,11 @@ +========================== +Tenant Manager and Tenants +========================== + + + +.. currentmodule:: keystoneclient.v2_0.tenants + +.. automodule:: keystoneclient.v2_0.tenants + :members: + diff --git a/source/ref/users.rst b/source/ref/users.rst new file mode 100644 index 00000000..953daeca --- /dev/null +++ b/source/ref/users.rst @@ -0,0 +1,9 @@ +====================== +User Manager and Users +====================== + +.. currentmodule:: keystoneclient.v2_0.users + +.. automodule:: keystoneclient.v2_0.users + :members: + diff --git a/source/releases.rst b/source/releases.rst new file mode 100644 index 00000000..4a9d281e --- /dev/null +++ b/source/releases.rst @@ -0,0 +1,106 @@ +============= +Release notes +============= + +2.7.0 (October 21, 2011) +======================== +* Forked from http://github.com/rackspace/python-novaclient +* Rebranded to python-keystoneclient +* Refactored to support Keystone API (auth, tokens, services, roles, tenants, + users, etc.) + +2.5.8 (July 11, 2011) +===================== +* returns all public/private ips, not just first one +* better 'nova list' search options + +2.5.7 - 2.5.6 = minor tweaks + +2.5.5 (June 21, 2011) +===================== +* zone-boot min/max instance count added thanks to comstud +* create for user added thanks to cerberus +* fixed tests + +2.5.3 (June 15, 2011) +===================== +* ProjectID can be None for backwards compatability. +* README/docs updated for projectId thanks to usrleon + +2.5.1 (June 10, 2011) +===================== +* ProjectID now part of authentication + +2.5.0 (June 3, 2011) +==================== + +* better logging thanks to GridDynamics + +2.4.4 (June 1, 2011) +==================== + +* added support for GET /servers with reservation_id (and /servers/detail) + +2.4.3 (May 27, 2011) +==================== + +* added support for POST /zones/select (client only, not cmdline) + +2.4 (March 7, 2011) +=================== + +* added Jacob Kaplan-Moss copyright notices to older/untouched files. + + +2.3 (March 2, 2011) +=================== + +* package renamed to python-novaclient. Module to novaclient + + +2.2 (March 1, 2011) +=================== + +* removed some license/copywrite notices from source that wasn't + significantly changed. + + +2.1 (Feb 28, 2011) +================== + +* shell renamed to nova from novatools + +* license changed from BSD to Apache + +2.0 (Feb 7, 2011) +================= + +* Forked from https://github.com/jacobian/python-cloudservers + +* Rebranded to python-novatools + +* Auth URL support + +* New OpenStack specific commands added (pause, suspend, etc) + +1.2 (August 15, 2010) +===================== + +* Support for Python 2.4 - 2.7. + +* Improved output of :program:`cloudservers ipgroup-list`. + +* Made ``cloudservers boot --ipgroup `` work (as well as ``--ipgroup + ``). + +1.1 (May 6, 2010) +================= + +* Added a ``--files`` option to :program:`cloudservers boot` supporting + the upload of (up to five) files at boot time. + +* Added a ``--key`` option to :program:`cloudservers boot` to key the server + with an SSH public key at boot time. This is just a shortcut for ``--files``, + but it's a useful shortcut. + +* Changed the default server image to Ubuntu 10.04 LTS. diff --git a/source/shell.rst b/source/shell.rst new file mode 100644 index 00000000..c44d6b3d --- /dev/null +++ b/source/shell.rst @@ -0,0 +1,59 @@ +The :program:`keystone` shell utility +========================================= + +.. program:: keystone +.. highlight:: bash + + +The :program:`keystone` shell utility interacts with OpenStack Keystone API +from the command line. It supports the entirety of the OpenStack Keystone API. + +First, you'll need an OpenStack Keystone account. You get this by using the +`keystone-manage` command in OpenStack Keystone. + +You'll need to provide :program:`keystone` with your OpenStack username and +password. You can do this with the :option:`--os_username`, :option:`--os_password`. +You can optionally specify a :option:`--os_tenant_id` or :option:`--os_tenant_name`, +to scope your token to a specific tenant. If you don't specify a tenant, you +will be scoped to your default tenant if you have one. Instead of using +options, it is easier to just set them as environment variables: + +.. envvar:: OS_USERNAME + + Your Keystone username. + +.. envvar:: OS_PASSWORD + + Your Keystone password. + +.. envvar:: OS_TENANT_NAME + + Name of Keystone Tenant. + +.. envvar:: OS_TENANT_ID + + ID of Keystone Tenant. + +.. envvar:: OS_AUTH_URL + + The OpenStack API server URL. + +.. envvar:: OS_IDENTITY_API_VERSION + + The OpenStack Identity API version. + +For example, in Bash you'd use:: + + export OS_USERNAME=yourname + export OS_PASSWORD=yadayadayada + export OS_TENANT_NAME=myproject + export OS_AUTH_URL=http://example.com:5000/v2.0/ + export OS_IDENTITY_API_VERSION=2.0 + +From there, all shell commands take the form:: + + keystone [arguments...] + +Run :program:`keystone help` to get a full list of all possible commands, +and run :program:`keystone help ` to get detailed help for that +command. diff --git a/source/using-api.rst b/source/using-api.rst new file mode 100644 index 00000000..d8fa0bcf --- /dev/null +++ b/source/using-api.rst @@ -0,0 +1,109 @@ +============== +The client API +============== + +Introduction +============ +The main concepts in the Keystone API are: + + * tenants + * users + * roles + * services + * endpoints + +The Keystone API lets you query and make changes through managers. For example, +to maipulate tenants, you interact with a +``keystoneclient.v2_0.tenants.TenantManger`` object. + +You obtain access to managers through via atributes of the ``keystoneclient.v2_0.client.Client`` object. For example, the ``tenants`` attribute of the ``Client`` +class is a tenant manager:: + + >>> from keystoneclient.v2_0 import client + >>> keystone = client.Client(...) + >>> keystone.tenants.list() # List tenants + +You create a valid ``keystoneclient.v2_0.client.Client`` object by passing +authentication data to the constructor. Authentication and examples of common +tasks are provided below. + +Authenticating +============== + +There are two ways to authenticate against Keystone: + * against the admin endpoint with the admin token + * against the public endpoint with a username and password + +If you are an administrator, you can authenticate by connecting to the admin +endpoint and using the admin token (sometimes referred to as the service +token). The token is specified as the ``admin_token`` configuration option in your +keystone.conf config file, which is typically in /etc/keystone:: + + >>> from keystoneclient.v2_0 import client + >>> token = '012345SECRET99TOKEN012345' + >>> endpoint = 'http://192.168.206.130:35357/v2.0' + >>> keystone = client.Client(token=token, endpoint=endpoint) + +If you have a username and password, authentication is done against the +public endpoint. You must also specify a tenant that is associated with the +user:: + + >>> from keystoneclient.v2_0 import client + >>> username='adminUser' + >>> password='secreetword' + >>> tenant_name='openstackDemo' + >>> auth_url='http://192.168.206.130:5000/v2.0' + >>> keystone = client.Client(username=username, password=password, + ... tenant_name, auth_url=auth_url) + +Creating tenants +================ + +This example will create a tenant named *openStackDemo*:: + + >>> from keystoneclient.v2_0 import client + >>> keystone = client.Client(...) + >>> keystone.tenants.create(tenant_name="openstackDemo", + ... description="Default Tenant", enabled=True) + + +Creating users +============== + +This example will create a user named *adminUser* with a password *secretword* +in the opoenstackDemo tenant. We first need to retrieve the tenant:: + + >>> from keystoneclient.v2_0 import client + >>> keystone = client.Client(...) + >>> tenants = keystone.tenants.list() + >>> my_tenant = [x for x in tenants if x.name=='openstackDemo'][0] + >>> my_user = keystone.users.create(name="adminUser", password="secretword", + ... tenant_id=my_tenant.id) + +Creating roles and adding users +=============================== + +This example will create an admin role and add the *my_user* user to that +role, but only for the *my_tenant* tenant: + + >>> from keystoneclient.v2_0 import client + >>> keystone = client.Client(...) + >>> role = keystone.roles.create('admin') + >>> my_tenant = ... + >>> my_user = ... + >>> keystone.roles.add_user_role(my_user, role, my_tenant) + +Creating services and endpoints +=============================== + +This example will create the service and corresponding endpoint for the +Compute service:: + + >>> from keystoneclient.v2_0 import client + >>> keystone = client.Client(...) + >>> service = keystone.services.create(name="nova", service_type="compute", + ... description="Nova Compute Service") + >>> keystone.endpoints.create(region="RegionOne", service_id=service.id, + ... publicurl="http://192.168.206.130:8774/v2/%(tenant_id)s", + ... adminurl="http://192.168.206.130:8774/v2/%(tenant_id)s", + ... internalurl="http://192.168.206.130:8774/v2/%(tenant_id)s") From 2055db28c1a62caf610a3efda481c2c3b99dd352 Mon Sep 17 00:00:00 2001 From: Dean Troyer Date: Thu, 28 Jun 2012 11:53:44 -0500 Subject: [PATCH 02/40] Change CLI options to use dashes Change documented options to use dashes instead of underscores in option names. Continue to support old underscore names for backward compatibility for a release or two (TBD). Blueprint: command-options Change-Id: Ied0d325a9fdd32f80bf8c993887e1975aa6adf16 --- source/shell.rst | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/source/shell.rst b/source/shell.rst index c44d6b3d..f86af725 100644 --- a/source/shell.rst +++ b/source/shell.rst @@ -12,8 +12,8 @@ First, you'll need an OpenStack Keystone account. You get this by using the `keystone-manage` command in OpenStack Keystone. You'll need to provide :program:`keystone` with your OpenStack username and -password. You can do this with the :option:`--os_username`, :option:`--os_password`. -You can optionally specify a :option:`--os_tenant_id` or :option:`--os_tenant_name`, +password. You can do this with the :option:`--os-username`, :option:`--os-password`. +You can optionally specify a :option:`--os-tenant-id` or :option:`--os-tenant-name`, to scope your token to a specific tenant. If you don't specify a tenant, you will be scoped to your default tenant if you have one. Instead of using options, it is easier to just set them as environment variables: From e27818704b430586c957c177886458a3e6ccded8 Mon Sep 17 00:00:00 2001 From: Liem Nguyen Date: Wed, 23 May 2012 18:16:50 +0000 Subject: [PATCH 03/40] Support 2-way SSL with Keystone server if it is configured to enforce 2-way SSL. See also https://review.openstack.org/#/c/7706/ for the corresponding review for the 2-way SSL addition to Keystone. Change-Id: If0cb46a43d663687396d93604a7139d85a4e7114 --- source/shell.rst | 21 ++++++++++++++++++++- 1 file changed, 20 insertions(+), 1 deletion(-) diff --git a/source/shell.rst b/source/shell.rst index f86af725..209d681a 100644 --- a/source/shell.rst +++ b/source/shell.rst @@ -42,13 +42,32 @@ options, it is easier to just set them as environment variables: The OpenStack Identity API version. +.. envvar:: OS_CA_CERT + + The location for the CA truststore (PEM formatted) for this client. + +.. envvar:: OS_CERT + + The location for the keystore (PEM formatted) containing the public + key of this client. This keystore can also optionally contain the + private key of this client. + +.. envvar:: OS_KEY + + The location for the keystore (PEM formatted) containing the private + key of this client. This value can be empty if the private key is + included in the OS_CERT file. + For example, in Bash you'd use:: export OS_USERNAME=yourname export OS_PASSWORD=yadayadayada export OS_TENANT_NAME=myproject - export OS_AUTH_URL=http://example.com:5000/v2.0/ + export OS_AUTH_URL=http(s)://example.com:5000/v2.0/ export OS_IDENTITY_API_VERSION=2.0 + export OS_CA_CERT=/etc/keystone/yourca.pem + export OS_CERT=/etc/keystone/yourpublickey.pem + export OS_KEY=/etc/keystone/yourprivatekey.pem From there, all shell commands take the form:: From 73ba9c23f7c729a7f665d9d614d61f8e12f5eb1d Mon Sep 17 00:00:00 2001 From: Dean Troyer Date: Wed, 22 Aug 2012 11:41:11 -0500 Subject: [PATCH 04/40] Change underscores in new cert options to dashes * --os_cacert -> --os-cacert * --os_cert -> --os-cert * --os_key -> --os-key * OS_CA_CERT didn't match --os-cacert, change to OS_CACERT Fixes bug 1040162 Change-Id: Ib03ff492b6ab2b76e54974e5436a444725615ea6 --- source/shell.rst | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/source/shell.rst b/source/shell.rst index 209d681a..cc0daa65 100644 --- a/source/shell.rst +++ b/source/shell.rst @@ -42,7 +42,7 @@ options, it is easier to just set them as environment variables: The OpenStack Identity API version. -.. envvar:: OS_CA_CERT +.. envvar:: OS_CACERT The location for the CA truststore (PEM formatted) for this client. @@ -65,7 +65,7 @@ For example, in Bash you'd use:: export OS_TENANT_NAME=myproject export OS_AUTH_URL=http(s)://example.com:5000/v2.0/ export OS_IDENTITY_API_VERSION=2.0 - export OS_CA_CERT=/etc/keystone/yourca.pem + export OS_CACERT=/etc/keystone/yourca.pem export OS_CERT=/etc/keystone/yourpublickey.pem export OS_KEY=/etc/keystone/yourprivatekey.pem From a01d64ac0228f672d2475ed4903585aa7941ad77 Mon Sep 17 00:00:00 2001 From: lrqrun Date: Wed, 29 Aug 2012 13:55:32 +0800 Subject: [PATCH 05/40] Fix PEP8 issues. Fix some pep8 issues in doc/source/conf.py make the code looks pretty. Change-Id: Ib1e2f8214ad7f4bc49c8c3dfa016843f8df15fe6 --- source/conf.py | 29 ++++++++++++++++++----------- 1 file changed, 18 insertions(+), 11 deletions(-) diff --git a/source/conf.py b/source/conf.py index 15112e75..b9c3d53f 100644 --- a/source/conf.py +++ b/source/conf.py @@ -3,7 +3,8 @@ # python-keystoneclient documentation build configuration file, created by # sphinx-quickstart on Sun Dec 6 14:19:25 2009. # -# This file is execfile()d with the current directory set to its containing dir. +# 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. @@ -11,18 +12,21 @@ # All configuration values have a default; values that are commented out # serve to show the default. -import sys, os +import os +import sys -sys.path.insert(0, os.path.abspath(os.path.join(os.path.dirname(__file__), "..", ".."))) +sys.path.insert(0, os.path.abspath(os.path.join(os.path.dirname(__file__), + "..", ".."))) # 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.append(os.path.abspath('.')) -# -- General configuration ----------------------------------------------------- +# -- General configuration ---------------------------------------------------- -# Add any Sphinx extension module names here, as strings. They can be extensions +# 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'] @@ -68,7 +72,8 @@ release = '2.7.0' # for source files. exclude_trees = [] -# The reST default role (used for this markup: `text`) to use for all documents. +# 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. @@ -89,7 +94,7 @@ pygments_style = 'sphinx' #modindex_common_prefix = [] -# -- Options for HTML output --------------------------------------------------- +# -- Options for HTML output -------------------------------------------------- # The theme to use for HTML and HTML Help pages. Major themes that come with # Sphinx are currently 'default' and 'sphinxdoc'. @@ -163,7 +168,7 @@ html_static_path = ['_static'] htmlhelp_basename = 'python-keystoneclientdoc' -# -- Options for LaTeX output -------------------------------------------------- +# -- Options for LaTeX output ------------------------------------------------- # The paper size ('letter' or 'a4'). #latex_paper_size = 'letter' @@ -172,10 +177,12 @@ htmlhelp_basename = 'python-keystoneclientdoc' #latex_font_size = '10pt' # Grouping the document tree into LaTeX files. List of tuples -# (source start file, target name, title, author, documentclass [howto/manual]). +# (source start file, target name, title, author, documentclass [howto/manual]) +# . latex_documents = [ - ('index', 'python-keystoneclient.tex', u'python-keystoneclient Documentation', - u'Nebula Inc, based on work by Rackspace and Jacob Kaplan-Moss', 'manual'), + ('index', 'python-keystoneclient.tex', + u'python-keystoneclient Documentation', + u'Nebula Inc, based on work by Rackspace and Jacob Kaplan-Moss', 'manual'), ] # The name of an image file (relative to this directory) to place at the top of From 804bf96c12188bc586de2b4acdcb9f0fb6729133 Mon Sep 17 00:00:00 2001 From: Joe Heck Date: Sat, 29 Sep 2012 15:28:08 -0700 Subject: [PATCH 06/40] updating keystoneclient doc theme adding in openstack theming enabling last update from git removing old manual references to API, converted entirely to autodoc updated .gitignore fixed docstring warnings and errors Change-Id: Id22ddc446331d52cbf56c3462d8b532fc37f64ac --- source/_templates/.placeholder | 0 source/_theme/layout.html | 83 ++++++ source/_theme/theme.conf | 4 + source/conf.py | 33 ++- source/index.rst | 11 +- source/ref/client.rst | 8 - source/ref/endpoints.rst | 11 - source/ref/exceptions.rst | 8 - source/ref/generic-client.rst | 12 - source/ref/index.rst | 16 -- source/ref/roles.rst | 9 - source/ref/services.rst | 11 - source/ref/tenants.rst | 11 - source/ref/users.rst | 9 - source/static/basic.css | 416 +++++++++++++++++++++++++++++++ source/static/default.css | 230 +++++++++++++++++ source/static/header-line.gif | Bin 0 -> 48 bytes source/static/header_bg.jpg | Bin 0 -> 3738 bytes source/static/jquery.tweet.js | 154 ++++++++++++ source/static/nature.css | 245 ++++++++++++++++++ source/static/openstack_logo.png | Bin 0 -> 3670 bytes source/static/tweaks.css | 94 +++++++ 22 files changed, 1254 insertions(+), 111 deletions(-) create mode 100644 source/_templates/.placeholder create mode 100644 source/_theme/layout.html create mode 100644 source/_theme/theme.conf delete mode 100644 source/ref/client.rst delete mode 100644 source/ref/endpoints.rst delete mode 100644 source/ref/exceptions.rst delete mode 100644 source/ref/generic-client.rst delete mode 100644 source/ref/index.rst delete mode 100644 source/ref/roles.rst delete mode 100644 source/ref/services.rst delete mode 100644 source/ref/tenants.rst delete mode 100644 source/ref/users.rst create mode 100644 source/static/basic.css create mode 100644 source/static/default.css create mode 100644 source/static/header-line.gif create mode 100644 source/static/header_bg.jpg create mode 100644 source/static/jquery.tweet.js create mode 100644 source/static/nature.css create mode 100644 source/static/openstack_logo.png create mode 100644 source/static/tweaks.css diff --git a/source/_templates/.placeholder b/source/_templates/.placeholder new file mode 100644 index 00000000..e69de29b diff --git a/source/_theme/layout.html b/source/_theme/layout.html new file mode 100644 index 00000000..750b7822 --- /dev/null +++ b/source/_theme/layout.html @@ -0,0 +1,83 @@ +{% extends "basic/layout.html" %} +{% set css_files = css_files + ['_static/tweaks.css'] %} +{% set script_files = script_files + ['_static/jquery.tweet.js'] %} + +{%- 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 %} + {%- endblock %} +
+
+ {%- endif %}{% endif %} +{%- endmacro %} + +{% block relbar1 %}{% endblock relbar1 %} + +{% block header %} + +{% endblock %} \ No newline at end of file diff --git a/source/_theme/theme.conf b/source/_theme/theme.conf new file mode 100644 index 00000000..1cc40044 --- /dev/null +++ b/source/_theme/theme.conf @@ -0,0 +1,4 @@ +[theme] +inherit = basic +stylesheet = nature.css +pygments_style = tango diff --git a/source/conf.py b/source/conf.py index b9c3d53f..94865076 100644 --- a/source/conf.py +++ b/source/conf.py @@ -16,7 +16,7 @@ import os import sys sys.path.insert(0, os.path.abspath(os.path.join(os.path.dirname(__file__), - "..", ".."))) + '..', '..'))) # 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 @@ -28,7 +28,12 @@ sys.path.insert(0, os.path.abspath(os.path.join(os.path.dirname(__file__), # 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'] +extensions = ['sphinx.ext.autodoc', + 'sphinx.ext.todo', + 'sphinx.ext.coverage', + 'sphinx.ext.intersphinx'] + +todo_include_todos = True # Add any paths that contain templates here, relative to this directory. templates_path = ['_templates'] @@ -50,10 +55,10 @@ copyright = u'Rackspace, based on work by Jacob Kaplan-Moss' # |version| and |release|, also used in various other places throughout the # built documents. # -# The short X.Y version. -version = '2.7' +# The short XXXX.Y version. +version = '2012.3' # The full version, including alpha/beta/rc tags. -release = '2.7.0' +release = '2012.3-dev' # The language for content autogenerated by Sphinx. Refer to documentation # for a list of supported languages. @@ -98,7 +103,8 @@ pygments_style = 'sphinx' # The theme to use for HTML and HTML Help pages. Major themes that come with # Sphinx are currently 'default' and 'sphinxdoc'. -html_theme = 'nature' +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 @@ -127,11 +133,12 @@ html_theme = 'nature' # 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'] +html_static_path = ['static'] # 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' +git_cmd = "git log --pretty=format:'%ad, commit %h' --date=local -n1" +html_last_updated_fmt = os.popen(git_cmd).read() # If true, SmartyPants will be used to convert quotes and dashes to # typographically correct entities. @@ -181,8 +188,9 @@ htmlhelp_basename = 'python-keystoneclientdoc' # . latex_documents = [ ('index', 'python-keystoneclient.tex', - u'python-keystoneclient Documentation', - u'Nebula Inc, based on work by Rackspace and Jacob Kaplan-Moss', 'manual'), + u'python-keystoneclient Documentation', + u'Nebula Inc, based on work by Rackspace and Jacob Kaplan-Moss', + 'manual'), ] # The name of an image file (relative to this directory) to place at the top of @@ -204,4 +212,7 @@ latex_documents = [ # 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/source/index.rst b/source/index.rst index bece0aa9..51bc647f 100644 --- a/source/index.rst +++ b/source/index.rst @@ -10,20 +10,21 @@ Contents: .. toctree:: :maxdepth: 1 - using-api - shell - ref/index releases + shell + using-api + + api/autoindex Contributing ============ -Code is hosted `on GitHub`_. Submit bugs to the Keystone project on +Code is hosted `on GitHub`_. Submit bugs to the Keystone project on `Launchpad`_. Submit code to the openstack/python-keystoneclient project using `Gerrit`_. .. _on GitHub: https://github.com/openstack/python-keystoneclient -.. _Launchpad: https://launchpad.net/keystone +.. _Launchpad: https://launchpad.net/python-keystoneclient .. _Gerrit: http://wiki.openstack.org/GerritWorkflow Run tests with ``python setup.py test``. diff --git a/source/ref/client.rst b/source/ref/client.rst deleted file mode 100644 index cb21e3ec..00000000 --- a/source/ref/client.rst +++ /dev/null @@ -1,8 +0,0 @@ -Client -====== - -.. currentmodule:: keystoneclient.v2_0.client - -.. autoclass:: Client - - .. automethod:: authenticate diff --git a/source/ref/endpoints.rst b/source/ref/endpoints.rst deleted file mode 100644 index ed2b4e2c..00000000 --- a/source/ref/endpoints.rst +++ /dev/null @@ -1,11 +0,0 @@ -============================== -Endpoint Manager and Endpoints -============================== - - - -.. currentmodule:: keystoneclient.v2_0.endpoints - -.. automodule:: keystoneclient.v2_0.endpoints - :members: - diff --git a/source/ref/exceptions.rst b/source/ref/exceptions.rst deleted file mode 100644 index 988f7d06..00000000 --- a/source/ref/exceptions.rst +++ /dev/null @@ -1,8 +0,0 @@ -Exceptions -========== - -.. currentmodule:: keystoneclient.exceptions - -.. automodule:: keystoneclient.exceptions - :members: - diff --git a/source/ref/generic-client.rst b/source/ref/generic-client.rst deleted file mode 100644 index 99055587..00000000 --- a/source/ref/generic-client.rst +++ /dev/null @@ -1,12 +0,0 @@ -Generic client -============== - -Use the generic client to obtain access to a specific endpoint version. - - -.. currentmodule:: keystoneclient.generic.client - -.. autoclass:: Client - - .. automethod:: discover - diff --git a/source/ref/index.rst b/source/ref/index.rst deleted file mode 100644 index d99127e3..00000000 --- a/source/ref/index.rst +++ /dev/null @@ -1,16 +0,0 @@ -API Reference -============= - -The following API reference documents are available: - -.. toctree:: - :maxdepth: 1 - - client - generic-client - tenants - users - roles - services - endpoints - exceptions diff --git a/source/ref/roles.rst b/source/ref/roles.rst deleted file mode 100644 index 9cb92839..00000000 --- a/source/ref/roles.rst +++ /dev/null @@ -1,9 +0,0 @@ -====================== -Role Manager and Roles -====================== - -.. currentmodule:: keystoneclient.v2_0.roles - -.. automodule:: keystoneclient.v2_0.roles - :members: - diff --git a/source/ref/services.rst b/source/ref/services.rst deleted file mode 100644 index a4b677cf..00000000 --- a/source/ref/services.rst +++ /dev/null @@ -1,11 +0,0 @@ -============================ -Service Manager and Services -============================ - - - -.. currentmodule:: keystoneclient.v2_0.services - -.. automodule:: keystoneclient.v2_0.services - :members: - diff --git a/source/ref/tenants.rst b/source/ref/tenants.rst deleted file mode 100644 index d6e38618..00000000 --- a/source/ref/tenants.rst +++ /dev/null @@ -1,11 +0,0 @@ -========================== -Tenant Manager and Tenants -========================== - - - -.. currentmodule:: keystoneclient.v2_0.tenants - -.. automodule:: keystoneclient.v2_0.tenants - :members: - diff --git a/source/ref/users.rst b/source/ref/users.rst deleted file mode 100644 index 953daeca..00000000 --- a/source/ref/users.rst +++ /dev/null @@ -1,9 +0,0 @@ -====================== -User Manager and Users -====================== - -.. currentmodule:: keystoneclient.v2_0.users - -.. automodule:: keystoneclient.v2_0.users - :members: - diff --git a/source/static/basic.css b/source/static/basic.css new file mode 100644 index 00000000..d909ce37 --- /dev/null +++ b/source/static/basic.css @@ -0,0 +1,416 @@ +/** + * 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/source/static/default.css b/source/static/default.css new file mode 100644 index 00000000..c8091ecb --- /dev/null +++ b/source/static/default.css @@ -0,0 +1,230 @@ +/** + * 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/source/static/header-line.gif b/source/static/header-line.gif new file mode 100644 index 0000000000000000000000000000000000000000..3601730e03488b7b5f92dc992d23ad753357c167 GIT binary patch literal 48 zcmZ?wbhEHbWMg1uXkcVG`smgF|Nj+#vM@3*Ff!;c00Bsbfr-7RpY8O^Kn4bD08FwB Aga7~l literal 0 HcmV?d00001 diff --git a/source/static/header_bg.jpg b/source/static/header_bg.jpg new file mode 100644 index 0000000000000000000000000000000000000000..f788c41c26481728fa4329c17c87bde36001adc1 GIT binary patch literal 3738 zcmd5-YdDna8vedHnM0NtYi6>>At7O=uyTsZup5R_40A9)aXQa}U(l^=gSg=J*&3mKp$aM0r>UIFDe9Zy(vs} zWf)kqO2Y_n0$>ZQ0D&hY4tWjpY?Ii5?V)h*kc0fz?%ZIj3|{;F8E5l%d0)&*Hx~ulvc_*73u8%R zsVMV~ne!JY);&pWott~QIZYJFTXliYc2};JEU{X7W6;ZPfz;)U;U4#mEuK@K*=SC3BR-m&x9(Nna@>b@%FS34|P^jtsXRb5>z9gtPp;_MI2F3o*k z>csA-?CX4b;~4P-*L$+Mmb|51F)eD*wCc`Jt(9}C${Zo=!Uin=u_yMC^;`X!x$##4 z+~}dkT`NF@Uhw0r+6g_)?e!h8IX+OE^C96>UOsv0GPMD6(kr#ljhXRnA=O>Qj@%iT zqBF7aQ*}BG)h@6r0%#azk!r9yrN6>9dq~>KadV$~cGG?Hjk>~it^5rd#zS4KE*p+4 z;;B)%oBK8PNTs=A)a-z`n?3zJ%+h{`=>ijk4sYKr*>`eN1H`~Lo|Tm!o6qN{S* zeNl=NcpGzD55)XnLC|>g)~w={=c#4*x^;mk4Zo_FOFlffP@!?1`c+TogTVR4kp9-q z`d5cMBzNxk6qjPRK9*WY3uHS=bnm_QJvSMBBS_A#3i=ywsg6^|9rfruW0MhdGwHDO z?1gJRMQVecKE^gV{%uo(b)zl^Hd&vmnwFh88h*-?FJ;y=Hdqvt!K|s<$>xlzR=G4{ zZgGOCF43IXS?62B)w*N&dXt%U8X^Bjx}^%Yf>VFpFoKSGP%k?ems;&&J)|Dx(qtQD zu2tS)<_Qz4#LhBKYkl@Og}G)^5+F4P($Fk>)}{uMVv|;Sz2i4$XJ_WTw*;n>3N805rnXhbC52SC={E3rXRlrs|I6f;o|Cn%eje59{axu9sivy4oYmg=j|fLt3<3 zFce84aNb8GbK;y>RbBu71YBcYKL3@M3N25yoE%BtG z^K!`WTQ|fb-Ysa7T)mEw&4_b)PWYgc!)3W)H+neR9o^f|AXdgY1`gN+pvgzbbk`M z*Ts6${7M`2)9XIPy^MoXTiiP2GTp_OtgWMshnH)M&ZSO0)cet!oWo_0_&hV(0?Qdb zdo(sw{I#{hI`SWPM`N=U^#+MgN-*rZ#J7Cm7Jj89`5ehd_{z&9->Jc7$F(X4)&|`K z5rEgd;@dhi-IzJnSVpMd!Gf_G-QW+ zjVMrIas1)g%)GJ;(=oaK};O^)NYdS1`XR?K_;I7qj zhii5}x^he{U3M+GF+WpYws#=Pt#S9xB_X5QE7W+_rQdwMhukJnQj}5cnCz_sIJ#r0 zJa5drkRPI$X(4YdpCswJe#5aN4Jjw3V3Nzt&`lcKBI~#;!>jq7j8y# zvHrFg_#P376A45^hp-KU*P=R;DVdPK*w7D@Gw+`XsSpm^L-VkCooZF61sPAnnjsT# zND4C{>G#P10F_&txEoE!rX%Iy*L}Kna=Q%fDLJ_rF*LujRITZ)$g!?UYLkCXOoz-S z_p`Hny*Rh--l)aYQC&-2dd%;%VKGC1<1DJm_n~`nk4^yS`}&P zM}5bOypW0hwtvrwnE>}g1Mq+B>09qPp1b$hn6kC_iqF`tX#G-t7D$n}Ky9t}sUqiI zOe@odQ?JueZ+sg`-zoQ}J4if6vv1c9x{BDme+F6z{8esU^Kio zK_oPy9}@nlGywSOZy9`^- zzBg>C9|rgWF{pcCogEV@;d}VHrgeBl=5Dr*th4V!1`Z9Zrz9le1zHC#sM3{j#G2R?WMhl6b_yyoEAxX>Zixl$16`+^d$ihNtuIBUafyiCEv#oksNL<4= z*oDXsc7-(ww^9-b-6_|bITySG1N2C-7p0L4+V@R%j=4@ygc=89bmSNy38$S=ZiDyP z0SrqrVA;zi8kYBZ2@Mx(2Lx~-*bc@d1#4R($RJv$9ZTfx_t7Kc|HIHnd&@I386P?& z?d6Vd(48n${cTNFFCoSIUj#O{mmt%M&xCIFmR9Y3f{2UnF4e9@uFZOaYiY|CLdbDa z%xS9x4SHi7Fr-1?CnDqRK?)n&$TTBW5J?O&o{TnNCnLw*{QmT7{c}flSbp9&xi*zF z1TdUn&_!$_WxQbMKGkgsl}B%+N5ZV%Hy6_zJ>dejD89yCBMw9(d}z2fWjYH_nV6!F zqe_rI2H5Pi0^~S6)jjnu%lqZN*eQq6!||a24+edpSH_{C8Ew^g8dw2qdrH!@*E7K* z)00Bb8uUsai%v6Oa^L@3E02r|EG%EdV>q;=#2Q9Wjv3l?dAur$4bzyOl3M6 z1hf%&o*#2R&xnS1z4&R`Uq%`Ut0_P{BOwt;FuDb$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/source/static/nature.css b/source/static/nature.css new file mode 100644 index 00000000..a98bd420 --- /dev/null +++ b/source/static/nature.css @@ -0,0 +1,245 @@ +/* + * nature.css_t + * ~~~~~~~~~~~~ + * + * Sphinx stylesheet -- nature theme. + * + * :copyright: Copyright 2007-2011 by the Sphinx team, see AUTHORS. + * :license: BSD, see LICENSE for details. + * + */ + +@import url("basic.css"); + +/* -- page layout ----------------------------------------------------------- */ + +body { + font-family: Arial, sans-serif; + font-size: 100%; + background-color: #111; + color: #555; + margin: 0; + padding: 0; +} + +div.documentwrapper { + float: left; + width: 100%; +} + +div.bodywrapper { + margin: 0 0 0 {{ theme_sidebarwidth|toint }}px; +} + +hr { + border: 1px solid #B1B4B6; +} + +div.document { + background-color: #eee; +} + +div.body { + background-color: #ffffff; + color: #3E4349; + padding: 0 30px 30px 30px; + font-size: 0.9em; +} + +div.footer { + color: #555; + width: 100%; + padding: 13px 0; + text-align: center; + font-size: 75%; +} + +div.footer a { + color: #444; + text-decoration: underline; +} + +div.related { + background-color: #6BA81E; + line-height: 32px; + color: #fff; + text-shadow: 0px 1px 0 #444; + font-size: 0.9em; +} + +div.related a { + color: #E2F3CC; +} + +div.sphinxsidebar { + font-size: 0.75em; + line-height: 1.5em; +} + +div.sphinxsidebarwrapper{ + padding: 20px 0; +} + +div.sphinxsidebar h3, +div.sphinxsidebar h4 { + font-family: Arial, sans-serif; + color: #222; + font-size: 1.2em; + font-weight: normal; + margin: 0; + padding: 5px 10px; + background-color: #ddd; + text-shadow: 1px 1px 0 white +} + +div.sphinxsidebar h4{ + font-size: 1.1em; +} + +div.sphinxsidebar h3 a { + color: #444; +} + + +div.sphinxsidebar p { + color: #888; + padding: 5px 20px; +} + +div.sphinxsidebar p.topless { +} + +div.sphinxsidebar ul { + margin: 10px 20px; + padding: 0; + color: #000; +} + +div.sphinxsidebar a { + color: #444; +} + +div.sphinxsidebar input { + border: 1px solid #ccc; + font-family: sans-serif; + font-size: 1em; +} + +div.sphinxsidebar input[type=text]{ + margin-left: 20px; +} + +/* -- body styles ----------------------------------------------------------- */ + +a { + color: #005B81; + text-decoration: none; +} + +a:hover { + color: #E32E00; + text-decoration: underline; +} + +div.body h1, +div.body h2, +div.body h3, +div.body h4, +div.body h5, +div.body h6 { + font-family: Arial, sans-serif; + background-color: #BED4EB; + font-weight: normal; + color: #212224; + margin: 30px 0px 10px 0px; + padding: 5px 0 5px 10px; + text-shadow: 0px 1px 0 white +} + +div.body h1 { border-top: 20px solid white; margin-top: 0; font-size: 200%; } +div.body h2 { font-size: 150%; background-color: #C8D5E3; } +div.body h3 { font-size: 120%; background-color: #D8DEE3; } +div.body h4 { font-size: 110%; background-color: #D8DEE3; } +div.body h5 { font-size: 100%; background-color: #D8DEE3; } +div.body h6 { font-size: 100%; background-color: #D8DEE3; } + +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 { + line-height: 1.5em; +} + +div.admonition p.admonition-title + p { + display: inline; +} + +div.highlight{ + background-color: white; +} + +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: 10px; + background-color: White; + color: #222; + line-height: 1.2em; + border: 1px solid #C6C9CB; + font-size: 1.1em; + margin: 1.5em 0 1.5em 0; + -webkit-box-shadow: 1px 1px 1px #d8d8d8; + -moz-box-shadow: 1px 1px 1px #d8d8d8; +} + +tt { + background-color: #ecf0f3; + color: #222; + /* padding: 1px 2px; */ + font-size: 1.1em; + font-family: monospace; +} + +.viewcode-back { + font-family: Arial, sans-serif; +} + +div.viewcode-block:target { + background-color: #f4debf; + border-top: 1px solid #ac9; + border-bottom: 1px solid #ac9; +} diff --git a/source/static/openstack_logo.png b/source/static/openstack_logo.png new file mode 100644 index 0000000000000000000000000000000000000000..146faec5cfe3773824f4caf39e4480e4974d10df GIT binary patch literal 3670 zcmV-c4yo~pP)CW75Qp#l)U;+N6jaIz6Nf$t6dNV>^>ETzcpQ=%tMaf0k|rg72+IW`z$FyfE+D{1@tt$t5DmX)*;QV?c;%+5Z&egAgfXTQJq-mZkC z>pFAHu}U=Axde_?s!99ZfDg_+9TYzDa6N1R3adhx&2Mb7>9w`KpMNz!>U5t2XQ8lZ zu+!+H7(PRwF@jAkwvI;|8|=Z_dfzV`Kpi;I!e=|Ql+HAdEag?VZ^Ilw9XJj9N1#1a z?UFC!)X62`CRIe^9YCLKbJ` z&O@f0zt{Z1YDF1utg2$F+rzvrncys+g37Xsd8)idSW(=}t#~qF#qBo29*@^ZCs<$W zpa144=o4g0z63h_ttPfIpH-FyG^MAH+6B~r$(4qw+Uv{2d#h`$lq+i+#Tf%CAzDFUh!pzX(6nW{EASJAQkhm!+}aGpHc z;(+N`S*@tYmump1T37E}J;!$0#F>^M*mT_X1x~bvnp&qP9IHI#bj-0z8FR+=p+e#*w3ugV#wX``sR-CI1!YiQsfc@Om<;1MBw zlfqH9z4Q|m*C?URU1OG(`UYn>Q8<|I!mby#FlN5MMFE8;Pyh$skbR?ngFLt?%nWSkS-#W5umy>@^DyAERP~{E&`M%0(qi&((^ahqL}u^jT<2dcf)p< z%Fxc9J$nh_`>_oNYC?oy`rIDY46Yrw4si3Qn~oXV%dJ}IlUD-40>QipyGa_dV0Z%J ztcEXm5yxR0gySJ04{nnbm#vP=Hq&GI<8VxcZ34pRjt6m%pE2H|!+HBJQrdBdyKHJR z2O_}hp!5bXuwniQYTF>yI|=cjT+2l`9T3|H+l4%ryPxWQm(ODW#8Ctj_CplcO=)qj zD#d~V6BahR9NY1kE5rF)_j<|!Cqnpq0uOKhL%w z>y8OyeTM1?REXc{0|3b=#WPZneh80PxL=Ljau1~+CgtMgg-vccMDX-L z9^7An_;!lFAi`#G_1F*OdM|Z$EVQs0m0$?mY}(baOZ%Zpd62#Pyg!3Jd4d zD^8+lSir&T6Y9-p9L#Wz6$5nXLjdOl?7Lv!TeMr}F14ranauW9=L>ubu*x>Bcrgwp zjrT@{rL*2Fc}Ilwn07QvdJfMOO2=(1Px)6&ih7lg839!Bx&}lQER~T`^7_x@fXo({ zCZMeZYt*!VgMTg>PR)PBaIwubzRY%jjE`-s zG;B}>2!lD=QLOTfQOEZKIEz*;yTJ9(Af0zNv;IDq7#Fr#W{Ap+7Sq1N3TL21X|h2t z=Dk>^bGSsRX-u+cZ23mMB_Ioc0yNIfcfLWB>$hVU3W3>d&a?IM+bGRGt+t}aiv(eh z(D6Z9N>U2|Qxle(!UVTeEKE6W))3WI5z48Rs8d5v0GwmyC8iQiUJO8KS?QwHl2abL zNW+hadDdPc8z%MSOG$l&WR@!!&M{WLmrnS=-0G#&`a)chX>mN9W1>|yqve@lL8a`f zXRmn$B8P=dLxE!2rIi}a*gh%FI4j?C;b@L=WgypiTRf==n6DKr9mUExo6a@{wLM-I z9%V9{!;5G!<8fMYikfEbrGXRQN-9*24}kIIpP&dEg@fiLqAY5|jjv}$P3x0avZODU zdX`c|G>h`1f=3uEu)L9C)H5%frni#HZXcX`TD{iQ-e2qXxj_f%|WW;byDMc%7+uBy}Y?KLC?jp%yyyeBNkqQ-*osw2ex&97Q{#C7%CdSDMNIV zTdC(LEm?&qPcNOjM)h9Grs|M(gsuhV8@96?m4WkQ>j{bJIs)m^neL%ua!i+N8>Lh+ zKu#7rF~VOH@hb{zGXYwys!Um4Vkf+H8Hj6?^eI%kT%j+HA0K=6qdQ@nfR57Q`Jm9T zc)Yg9-`e~BRE!xoKZ z=mP|0Kihr}V1$5sHw$QekmoL)lQ;~@H$S)}s3xuwypiubB?1%OyBpwC08TH!=?BrQ zhOp`PTu;%u0}Q=XKGb7d$g8*;de8c1UI|Re2R;;Radh_D!FIZg+JP`oJg>5 z;&B7eVAomZe>j~hOOIVRO_Q7eSGz37hxmnsG!n%HX`C6gSqFcg(RLmikn%EPR*wel zrsc;>!vQ<>2ZW`lk`MbNLopFd#_9mh8iKPH;KbjC@xJU${pdxuTF{uO(eG#9t*>XP z_4Seh`r_#q$^xeiuy(=eSouv66cpS!t3n`|j`6xnmSs1q@;0!I)m<6eYHHGMRdB87 ziruozT=gn@yp`B9oGxD-b7PqhZum|oJCfLB38&8v51ijj-Pb`qvCr3FtJ0aFms2h3(n0-}3jJ~J$ zCzep7-MIZFbo$(m8zWm?SoRl__blLE+!fFBVVk1&XLg+vmVNcTk9O2+q?x#F0LZUN zu6oM~C)(7^0|az4nM}@aZf<@RkH0CR8<-Yn-fZe+Dbr#iJWSt#tnR4^h<@ePXWmeHIO4q^X zCbiy(=k3R1o1}0E+7x*OOe-qnIXG{#N_rqK*1NH}Qz6aumTR`YTgo5K=q=61;5@b- zrgUA_Qz=)(TPN!tCZE|{?B0*r9ov5Fcip6xQ2;Yqs*2_o7TFKGp0|~bcP@6+a(rz^ zXXmmyBfT}ucw_t(6s+f^t_)nc>RKW<-q_&J35vN+RPLsR?VAsQeHLyCR7AWvxFOVc zAg-xl=j*RipzaKWx3lAf?ei`PoM;bbAL>svH?JqQwjSulb9bghytRt%*5x-no>xlf zh7qj0LYRXVDU})?Btsy7^71*ujsEP_ACyd)P)*ULWBCXox@PUfwmQ#)Vl&oeIqpQY zHMgU+xe0EhQ)RmjdB3JHGdrsvJ9?A=WwOrn)J?BH{+D&O_@SKdrj2|8Z{hS1T(k>&Zlt;p=tqw*mVY1aLt=u^eAHkW>8cb#@q& z4-SLa@ii zCt7NGrLv)1Scy9ew-sOwwLYn2a6T#KzJgnbacm7Z20q6tcs~C!0DI+r(=$l+x{=W0A}~0&W)ll4*&oF07*qoM6N<$f~n6U7ytkO literal 0 HcmV?d00001 diff --git a/source/static/tweaks.css b/source/static/tweaks.css new file mode 100644 index 00000000..3f3fb3f0 --- /dev/null +++ b/source/static/tweaks.css @@ -0,0 +1,94 @@ +body { + background: #fff url(../_static/header_bg.jpg) top left no-repeat; +} + +#header { + width: 950px; + margin: 0 auto; + height: 102px; +} + +#header h1#logo { + background: url(../_static/openstack_logo.png) top left no-repeat; + display: block; + float: left; + text-indent: -9999px; + width: 175px; + height: 55px; +} + +#navigation { + background: url(../_static/header-line.gif) repeat-x 0 bottom; + display: block; + float: left; + margin: 27px 0 0 25px; + padding: 0; +} + +#navigation li{ + float: left; + display: block; + margin-right: 25px; +} + +#navigation li a { + display: block; + font-weight: normal; + text-decoration: none; + background-position: 50% 0; + padding: 20px 0 5px; + color: #353535; + font-size: 14px; +} + +#navigation li a.current, #navigation li a.section { + border-bottom: 3px solid #cf2f19; + color: #cf2f19; +} + +div.related { + background-color: #cde2f8; + border: 1px solid #b0d3f8; +} + +div.related a { + color: #4078ba; + text-shadow: none; +} + +div.sphinxsidebarwrapper { + padding-top: 0; +} + +pre { + color: #555; +} + +div.documentwrapper h1, div.documentwrapper h2, div.documentwrapper h3, div.documentwrapper h4, div.documentwrapper h5, div.documentwrapper h6 { + font-family: 'PT Sans', sans-serif !important; + color: #264D69; + border-bottom: 1px dotted #C5E2EA; + padding: 0; + background: none; + padding-bottom: 5px; +} + +div.documentwrapper h3 { + color: #CF2F19; +} + +a.headerlink { + color: #fff !important; + margin-left: 5px; + background: #CF2F19 !important; +} + +div.body { + margin-top: -25px; + margin-left: 230px; +} + +div.document { + width: 960px; + margin: 0 auto; +} \ No newline at end of file From 7dd1821be4cf9361de160fdff5a335718b5ff0ea Mon Sep 17 00:00:00 2001 From: Joe Heck Date: Fri, 28 Sep 2012 15:57:25 +0000 Subject: [PATCH 07/40] updating base keystoneclient documentation * updated changelog * described CLI authentication for admin and user * tweaked API usage docs a bit with formatting and typos Change-Id: I61c3aab99bb0ecbad1de6d32a767558ca1a2ab5b --- source/index.rst | 2 +- source/releases.rst | 129 ++++++++++--------------------------------- source/shell.rst | 39 ++++++++++--- source/using-api.rst | 27 +++++---- 4 files changed, 74 insertions(+), 123 deletions(-) diff --git a/source/index.rst b/source/index.rst index bece0aa9..bfa63b83 100644 --- a/source/index.rst +++ b/source/index.rst @@ -18,7 +18,7 @@ Contents: Contributing ============ -Code is hosted `on GitHub`_. Submit bugs to the Keystone project on +Code is hosted `on GitHub`_. Submit bugs to the Keystone project on `Launchpad`_. Submit code to the openstack/python-keystoneclient project using `Gerrit`_. diff --git a/source/releases.rst b/source/releases.rst index 4a9d281e..2f1ed422 100644 --- a/source/releases.rst +++ b/source/releases.rst @@ -2,105 +2,32 @@ Release notes ============= -2.7.0 (October 21, 2011) -======================== -* Forked from http://github.com/rackspace/python-novaclient -* Rebranded to python-keystoneclient -* Refactored to support Keystone API (auth, tokens, services, roles, tenants, +0.1.3 (August 31, 2012) +======================= +* changed logging to report request and response independently in --debug mode +* changed options to use hyphens instead of underscores +* added support for PKI signed tokens with Keystone + + +0.1.2 (July 9, 2012) +==================== +* added support for two-way SSL and --insecure option to allow for self-signed + certificates +* added support for password prompting if not provided +* added support for bash completion for keystone +* updated CLI options to use dashes instead of underscores + +0.1.1 (June 25, 2012) +===================== +* corrected versioning + +0.1.0 (March 29, 2012) +====================== +* released with OpenStack Essex and Diablo compatibility +* forked from http://github.com/rackspace/python-novaclient +* refactored to support Keystone API (auth, tokens, services, roles, tenants, users, etc.) - -2.5.8 (July 11, 2011) -===================== -* returns all public/private ips, not just first one -* better 'nova list' search options - -2.5.7 - 2.5.6 = minor tweaks - -2.5.5 (June 21, 2011) -===================== -* zone-boot min/max instance count added thanks to comstud -* create for user added thanks to cerberus -* fixed tests - -2.5.3 (June 15, 2011) -===================== -* ProjectID can be None for backwards compatability. -* README/docs updated for projectId thanks to usrleon - -2.5.1 (June 10, 2011) -===================== -* ProjectID now part of authentication - -2.5.0 (June 3, 2011) -==================== - -* better logging thanks to GridDynamics - -2.4.4 (June 1, 2011) -==================== - -* added support for GET /servers with reservation_id (and /servers/detail) - -2.4.3 (May 27, 2011) -==================== - -* added support for POST /zones/select (client only, not cmdline) - -2.4 (March 7, 2011) -=================== - -* added Jacob Kaplan-Moss copyright notices to older/untouched files. - - -2.3 (March 2, 2011) -=================== - -* package renamed to python-novaclient. Module to novaclient - - -2.2 (March 1, 2011) -=================== - -* removed some license/copywrite notices from source that wasn't - significantly changed. - - -2.1 (Feb 28, 2011) -================== - -* shell renamed to nova from novatools - -* license changed from BSD to Apache - -2.0 (Feb 7, 2011) -================= - -* Forked from https://github.com/jacobian/python-cloudservers - -* Rebranded to python-novatools - -* Auth URL support - -* New OpenStack specific commands added (pause, suspend, etc) - -1.2 (August 15, 2010) -===================== - -* Support for Python 2.4 - 2.7. - -* Improved output of :program:`cloudservers ipgroup-list`. - -* Made ``cloudservers boot --ipgroup `` work (as well as ``--ipgroup - ``). - -1.1 (May 6, 2010) -================= - -* Added a ``--files`` option to :program:`cloudservers boot` supporting - the upload of (up to five) files at boot time. - -* Added a ``--key`` option to :program:`cloudservers boot` to key the server - with an SSH public key at boot time. This is just a shortcut for ``--files``, - but it's a useful shortcut. - -* Changed the default server image to Ubuntu 10.04 LTS. +* removed legacy arguments of --username, --password, etc in migration to + support a cross-openstack unified CLI convention defined at + http://wiki.openstack.org/UnifiedCLI +* required service ID for listing endpoints diff --git a/source/shell.rst b/source/shell.rst index cc0daa65..e4baf4b8 100644 --- a/source/shell.rst +++ b/source/shell.rst @@ -1,5 +1,5 @@ The :program:`keystone` shell utility -========================================= +===================================== .. program:: keystone .. highlight:: bash @@ -8,15 +8,36 @@ The :program:`keystone` shell utility The :program:`keystone` shell utility interacts with OpenStack Keystone API from the command line. It supports the entirety of the OpenStack Keystone API. -First, you'll need an OpenStack Keystone account. You get this by using the -`keystone-manage` command in OpenStack Keystone. +To communicate with the API, you will need to be authenticated - and the +:program:`keystone` provides multiple options for this. -You'll need to provide :program:`keystone` with your OpenStack username and -password. You can do this with the :option:`--os-username`, :option:`--os-password`. -You can optionally specify a :option:`--os-tenant-id` or :option:`--os-tenant-name`, -to scope your token to a specific tenant. If you don't specify a tenant, you -will be scoped to your default tenant if you have one. Instead of using -options, it is easier to just set them as environment variables: +While bootstrapping keystone the authentication is accomplished with a +shared secret token and the location of the keystone API endpoint. The +shared secret token is configured in keystone.conf as "admin_token". + +You can specify those values on the command line with :option:`--os-token` +and :option:`--os-endpoint`, or set them in environment variables: + +.. envvar:: OS_SERVICE_TOKEN + + Your keystone administrative token + +.. envvar:: OS_SERVICE_ENDPOINT + + Your keystone API endpoint + +The command line options will override any environment variables set. + +If you already have accounts, you can use your OpenStack username and +password. You can do this with the :option:`--os-username`, +:option:`--os-password`. + +Keystone allows a user to be associated with one or more tenants. To specify +the tenant for which you want to authorize against, you may optionally +specify a :option:`--os-tenant-id` or :option:`--os-tenant-name`. + +Instead of using options, it is easier to just set them as environment +variables: .. envvar:: OS_USERNAME diff --git a/source/using-api.rst b/source/using-api.rst index d8fa0bcf..809093e0 100644 --- a/source/using-api.rst +++ b/source/using-api.rst @@ -13,11 +13,12 @@ The main concepts in the Keystone API are: * endpoints The Keystone API lets you query and make changes through managers. For example, -to maipulate tenants, you interact with a +to manipulate tenants, you interact with a ``keystoneclient.v2_0.tenants.TenantManger`` object. -You obtain access to managers through via atributes of the ``keystoneclient.v2_0.client.Client`` object. For example, the ``tenants`` attribute of the ``Client`` -class is a tenant manager:: +You obtain access to managers through via atributes of the +``keystoneclient.v2_0.client.Client`` object. For example, the ``tenants`` +attribute of the ``Client`` class is a tenant manager:: >>> from keystoneclient.v2_0 import client >>> keystone = client.Client(...) @@ -36,8 +37,8 @@ There are two ways to authenticate against Keystone: If you are an administrator, you can authenticate by connecting to the admin endpoint and using the admin token (sometimes referred to as the service -token). The token is specified as the ``admin_token`` configuration option in your -keystone.conf config file, which is typically in /etc/keystone:: +token). The token is specified as the ``admin_token`` configuration option in +your keystone.conf config file, which is typically in /etc/keystone:: >>> from keystoneclient.v2_0 import client >>> token = '012345SECRET99TOKEN012345' @@ -54,7 +55,7 @@ user:: >>> tenant_name='openstackDemo' >>> auth_url='http://192.168.206.130:5000/v2.0' >>> keystone = client.Client(username=username, password=password, - ... tenant_name, auth_url=auth_url) + ... tenant_name=tenant_name, auth_url=auth_url) Creating tenants ================ @@ -77,8 +78,9 @@ in the opoenstackDemo tenant. We first need to retrieve the tenant:: >>> keystone = client.Client(...) >>> tenants = keystone.tenants.list() >>> my_tenant = [x for x in tenants if x.name=='openstackDemo'][0] - >>> my_user = keystone.users.create(name="adminUser", password="secretword", - ... tenant_id=my_tenant.id) + >>> my_user = keystone.users.create(name="adminUser", + ... password="secretword", + ... tenant_id=my_tenant.id) Creating roles and adding users =============================== @@ -103,7 +105,8 @@ Compute service:: >>> keystone = client.Client(...) >>> service = keystone.services.create(name="nova", service_type="compute", ... description="Nova Compute Service") - >>> keystone.endpoints.create(region="RegionOne", service_id=service.id, - ... publicurl="http://192.168.206.130:8774/v2/%(tenant_id)s", - ... adminurl="http://192.168.206.130:8774/v2/%(tenant_id)s", - ... internalurl="http://192.168.206.130:8774/v2/%(tenant_id)s") + >>> keystone.endpoints.create( + ... region="RegionOne", service_id=service.id, + ... publicurl="http://192.168.206.130:8774/v2/%(tenant_id)s", + ... adminurl="http://192.168.206.130:8774/v2/%(tenant_id)s", + ... internalurl="http://192.168.206.130:8774/v2/%(tenant_id)s") From 27ba1be179c3106e2c7fcb5c9012ac032aa94989 Mon Sep 17 00:00:00 2001 From: Dolph Mathews Date: Wed, 24 Oct 2012 07:12:30 -0500 Subject: [PATCH 08/40] Replace refs to 'Keystone API' with 'Identity API' Formally, OpenStack Keystone implements the OpenStack Identity API, and this is a client to the API, not to Keystone itself. Change-Id: If568866221a29ba041f0f2cd56dc81deeb9ebc00 --- source/index.rst | 10 +++++----- source/releases.rst | 2 +- source/shell.rst | 8 ++++---- source/using-api.rst | 9 +++++---- 4 files changed, 15 insertions(+), 14 deletions(-) diff --git a/source/index.rst b/source/index.rst index 51bc647f..faffc4f3 100644 --- a/source/index.rst +++ b/source/index.rst @@ -1,7 +1,7 @@ -Python bindings to the OpenStack Keystone API -================================================== +Python bindings to the OpenStack Identity API (Keystone) +======================================================== -This is a client for OpenStack Keystone API. There's :doc:`a Python API +This is a client for OpenStack Identity API. There's :doc:`a Python API ` (the :mod:`keystoneclient` module), and a :doc:`command-line script ` (installed as :program:`keystone`). @@ -20,8 +20,8 @@ Contributing ============ Code is hosted `on GitHub`_. Submit bugs to the Keystone project on -`Launchpad`_. Submit code to the openstack/python-keystoneclient project using -`Gerrit`_. +`Launchpad`_. Submit code to the ``openstack/python-keystoneclient`` project +using `Gerrit`_. .. _on GitHub: https://github.com/openstack/python-keystoneclient .. _Launchpad: https://launchpad.net/python-keystoneclient diff --git a/source/releases.rst b/source/releases.rst index 2f1ed422..bb3f1a0c 100644 --- a/source/releases.rst +++ b/source/releases.rst @@ -25,7 +25,7 @@ Release notes ====================== * released with OpenStack Essex and Diablo compatibility * forked from http://github.com/rackspace/python-novaclient -* refactored to support Keystone API (auth, tokens, services, roles, tenants, +* refactored to support Identity API (auth, tokens, services, roles, tenants, users, etc.) * removed legacy arguments of --username, --password, etc in migration to support a cross-openstack unified CLI convention defined at diff --git a/source/shell.rst b/source/shell.rst index e4baf4b8..02d158c8 100644 --- a/source/shell.rst +++ b/source/shell.rst @@ -5,14 +5,14 @@ The :program:`keystone` shell utility .. highlight:: bash -The :program:`keystone` shell utility interacts with OpenStack Keystone API -from the command line. It supports the entirety of the OpenStack Keystone API. +The :program:`keystone` shell utility interacts with OpenStack Identity API +from the command line. It supports the entirety of the OpenStack Identity API. To communicate with the API, you will need to be authenticated - and the :program:`keystone` provides multiple options for this. While bootstrapping keystone the authentication is accomplished with a -shared secret token and the location of the keystone API endpoint. The +shared secret token and the location of the Identity API endpoint. The shared secret token is configured in keystone.conf as "admin_token". You can specify those values on the command line with :option:`--os-token` @@ -24,7 +24,7 @@ and :option:`--os-endpoint`, or set them in environment variables: .. envvar:: OS_SERVICE_ENDPOINT - Your keystone API endpoint + Your Identity API endpoint The command line options will override any environment variables set. diff --git a/source/using-api.rst b/source/using-api.rst index 809093e0..b5d630c1 100644 --- a/source/using-api.rst +++ b/source/using-api.rst @@ -4,7 +4,8 @@ The client API Introduction ============ -The main concepts in the Keystone API are: + +The main concepts in the Identity API are: * tenants * users @@ -12,11 +13,11 @@ The main concepts in the Keystone API are: * services * endpoints -The Keystone API lets you query and make changes through managers. For example, +The Identity API lets you query and make changes through managers. For example, to manipulate tenants, you interact with a -``keystoneclient.v2_0.tenants.TenantManger`` object. +``keystoneclient.v2_0.tenants.TenantManager`` object. -You obtain access to managers through via atributes of the +You obtain access to managers through via attributes of the ``keystoneclient.v2_0.client.Client`` object. For example, the ``tenants`` attribute of the ``Client`` class is a tenant manager:: From c0fcae769d251fa34cafca910217b82c74e02691 Mon Sep 17 00:00:00 2001 From: Guang Yee Date: Wed, 19 Dec 2012 15:50:34 -0800 Subject: [PATCH 09/40] Blueprint memcache-protection: enable memcache value encryption/integrity check DocImpact Change-Id: I8b733256a3c2cdcf7c2ec5edac491ac4739aa847 --- source/images/graphs_authComp.svg | 48 ++++ source/images/graphs_authCompDelegate.svg | 53 ++++ source/middlewarearchitecture.rst | 309 ++++++++++++++++++++++ 3 files changed, 410 insertions(+) create mode 100644 source/images/graphs_authComp.svg create mode 100644 source/images/graphs_authCompDelegate.svg create mode 100644 source/middlewarearchitecture.rst diff --git a/source/images/graphs_authComp.svg b/source/images/graphs_authComp.svg new file mode 100644 index 00000000..6be629c1 --- /dev/null +++ b/source/images/graphs_authComp.svg @@ -0,0 +1,48 @@ + + + + + + +AuthComp + + +AuthComp + +Auth +Component + + + +AuthComp->Reject + + +Reject +Unauthenticated +Requests + + +Service + +OpenStack +Service + + +AuthComp->Service + + +Forward +Authenticated +Requests + + + +Start->AuthComp + + + + + diff --git a/source/images/graphs_authCompDelegate.svg b/source/images/graphs_authCompDelegate.svg new file mode 100644 index 00000000..4788829a --- /dev/null +++ b/source/images/graphs_authCompDelegate.svg @@ -0,0 +1,53 @@ + + + + + + +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/source/middlewarearchitecture.rst b/source/middlewarearchitecture.rst new file mode 100644 index 00000000..59a6db02 --- /dev/null +++ b/source/middlewarearchitecture.rst @@ -0,0 +1,309 @@ +.. + 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 a common authentication protocol +in use between the OpenStack projects. By using keystone as a common +authentication and authorization mechanisms, the OpenStack project can plug in +to existing authentication and authorization systems in use by existing +environments. + +In this document, we describe the architecture and responsibilities of the +authentication middleware which acts as the internal API mechanism for +OpenStack projects based on the WSGI standard. + +For the architecture of keystone and its services, please see +:doc:`architecture`. This documentation primarily describes the implementation +in ``keystoneclient/middleware/auth_token.py`` +(:py:class:`keystoneclient.middleware.auth_token.AuthProtocol`) + +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. OpenStack is +using a token based mechanism to represent authentication and authorization. + +At a high level, an authentication middleware component is a proxy that +intercepts HTTP calls from clients and populates HTTP headers in the request +context for other WSGI middleware or applications to use. The general flow +of the middleware processing is: + +* clear any existing authorization headers to prevent forgery +* collect the token from the existing HTTP request headers +* validate the token + + * if valid, populate additional headers representing the identity that has + been authenticated and authorized + * in invalid, or not token present, reject the request (HTTPUnauthorized) + or pass along a header indicating the request is unauthorized (configurable + in the middleware) + * if the keystone service is unavailable to validate the token, reject + the request with HTTPServiceUnavailable. + +.. _authComponent: + +Authentication Component +------------------------ + +Figure 1. Authentication Component + +.. image:: images/graphs_authComp.svg + :width: 100% + :height: 180 + :alt: An Authentication Component + +The middleware may also be configured to operated in a 'delegated mode'. +In this mode, the decision reject an unauthenticated client is delegated to +the OpenStack service, as 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. + +.. _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) + +.. _deployStrategies: + +Deployment Strategy +=================== + +The middleware is intended to be used inline with OpenStack wsgi components, +based on the openstack-common WSGI middleware class. It is typically deployed +as a configuration element in a paste configuration pipeline of other +middleware components, with the pipeline terminating in the service +application. The middleware conforms to the python WSGI standard [PEP-333]_. +In initializing the middleware, a configuration item (which acts like a python +dictionary) is passed to the middleware with relevant configuration options. + +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 = Super999Sekret888Password777 + admin_user = admin + admin_password = SuperSekretPassword + admin_tenant_name = service + ;Uncomment next line to use Swift MemcacheRing + ;cache = swift.cache + ;Uncomment next line and check ip:port to use memcached to cache tokens + ;memcache_servers = 127.0.0.1:11211 + ;Uncomment next 2 lines to turn on memcache protection + ;memcache_security_strategy = ENCRYPT + ;memcache_secret_key = change_me + ;Uncomment next 2 lines if Keystone server is validating client cert + ;certfile = + ;keyfile = + +For services which have separate paste-deploy ini file, auth_token middleware +can be alternatively configured in [keystone_authtoken] section in the main +config file. For example in Nova, all middleware parameters can be removed +from api-paste.ini:: + + [filter:authtoken] + paste.filter_factory = keystone.middleware.auth_token:filter_factory + +and set in nova.conf:: + + [DEFAULT] + ... + auth_strategy=keystone + + [keystone_authtoken] + auth_host = 127.0.0.1 + auth_port = 35357 + auth_protocol = http + auth_uri = http://127.0.0.1:5000/ + admin_user = admin + admin_password = SuperSekretPassword + admin_tenant_name = service + +Note that middleware parameters in paste config take priority, they must be +removed to use values in [keystone_authtoken] section. + +Configuration Options +--------------------- + +* ``auth_host``: (required) the host providing the keystone service API endpoint + for validating and requesting tokens +* ``admin_token``: either this or the following three options are required. If + set, this is a single shared secret with the keystone configuration used to + validate tokens. +* ``admin_user``, ``admin_password``, ``admin_tenant_name``: if ``admin_token`` + is not set, or invalid, then admin_user, admin_password, and + admin_tenant_name are defined as a service account which is expected to have + been previously configured in Keystone to validate user tokens. + +* ``delay_auth_decision``: (optional, default `0`) (off). If on, the middleware + will not reject invalid auth requests, but will delegate that decision to + downstream WSGI components. +* ``auth_port``: (optional, default `35357`) the port used to validate tokens +* ``auth_protocol``: (optional, default `https`) +* ``auth_uri``: (optional, defaults to `auth_protocol`://`auth_host`:`auth_port`) +* ``certfile``: (required, if Keystone server requires client cert) +* ``keyfile``: (required, if Keystone server requires client cert) This can be + the same as the certfile if the certfile includes the private key. + +Caching for improved response +----------------------------- + +In order to prevent every service request, the middleware may be configured +to utilize a cache, and the keystone API returns the tokens with an +expiration (configurable in duration on the keystone service). The middleware +supports memcache based caching. + +* ``memcache_servers``: (optonal) if defined, the memcache server(s) to use for + cacheing. It will be ignored if Swift MemcacheRing is used instead. +* ``token_cache_time``: (optional, default 300 seconds) Only valid if + memcache_servers is defined. + +When deploying auth_token middleware with Swift, user may elect +to use Swift MemcacheRing instead of the local Keystone memcache. +The Swift MemcacheRing object is passed in from the request environment +and it defaults to 'swift.cache'. However it could be +different, depending on deployment. To use Swift MemcacheRing, you must +provide the ``cache`` option. + +* ``cache``: (optional) if defined, the environment key where the Swift + MemcacheRing object is stored. + +Memcached and System Time +========================= + +When using `memcached`_ with ``auth_token`` middleware, ensure that the system +time of memcached hosts is set to UTC. Memcached uses the host's system +time in determining whether a key has expired, whereas Keystone sets +key expiry in UTC. The timezone used by Keystone and memcached must +match if key expiry is to behave as expected. + +.. _`memcached`: http://memcached.org/ + +Memcache Protection +=================== + +When using memcached, we are storing user tokens and token validation +information into the cache as raw data. Which means anyone who have access +to the memcache servers can read and modify data stored there. To mitigate +this risk, ``auth_token`` middleware provides an option to either encrypt +or authenticate the token data stored in the cache. + +* ``memcache_security_strategy``: (optional) if defined, indicate whether token + data should be encrypted or authenticated. Acceptable values are ``ENCRYPT`` + or ``MAC``. If ``ENCRYPT``, token data is encrypted in the cache. If + ``MAC``, token data is authenticated (with HMAC) in the cache. If its value + is neither ``MAC`` nor ``ENCRYPT``, ``auth_token`` will raise an exception + on initialization. +* ``memcache_secret_key``: (optional, mandatory if + ``memcache_security_strategy`` is defined) if defined, + a random string to be used for key derivation. If + ``memcache_security_strategy`` is defined and ``memcache_secret_key`` is + absent, ``auth_token`` will raise an exception on initialization. + +Exchanging User Information +=========================== + +The middleware expects to find a token representing the user with the header +``X-Auth-Token`` or ``X-Storage-Token``. `X-Storage-Token` is supported for +swift/cloud files and for legacy Rackspace use. If the token isn't present and +the middleware is configured to not delegate auth responsibility, it will +respond to the HTTP request with HTTPUnauthorized, returning the header +``WWW-Authenticate`` with the value `Keystone uri='...'` to indicate where to +request a token. The auth_uri returned is configured with the middleware. + +The authentication middleware extends the HTTP request with the header +``X-Identity-Status``. If a request is successfully authenticated, the value +is set to `Confirmed`. If the middleware is delegating the auth decision to the +service, then the status is set to `Invalid` if the auth request was +unsuccessful. + +Extended the request with additional User Information +----------------------------------------------------- + +:py:class:`keystone.middleware.auth_token.AuthProtocol` extends the request +with additional information if the user has been authenticated. + + +X-Identity-Status + Provides information on whether the request was authenticated or not. + +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-Roles + The roles associated with that user + +Deprecated additions +-------------------- + +X-Tenant + Provides the tenant name. This is to support any legacy implementations + before Keystone switched to an ID/Name schema for tenants. + +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-Role + The roles associated with that user + +References +========== + +.. [PEP-333] pep0333 Phillip J Eby. 'Python Web Server Gateway Interface + v1.0.'' http://www.python.org/dev/peps/pep-0333/. From d27ea6e1cb4ff39745d499d3584cbb076b0a6ccc Mon Sep 17 00:00:00 2001 From: Chmouel Boudjnah Date: Thu, 14 Feb 2013 14:43:54 +0100 Subject: [PATCH 10/40] Allow configure auth_token http connect timeout. - Fixes bug 939613. Change-Id: Ic8cfc36e02212eeb987e509893369c0a47d9209a --- source/middlewarearchitecture.rst | 2 ++ 1 file changed, 2 insertions(+) diff --git a/source/middlewarearchitecture.rst b/source/middlewarearchitecture.rst index 59a6db02..407a5d27 100644 --- a/source/middlewarearchitecture.rst +++ b/source/middlewarearchitecture.rst @@ -184,6 +184,8 @@ Configuration Options * ``delay_auth_decision``: (optional, default `0`) (off). If on, the middleware will not reject invalid auth requests, but will delegate that decision to downstream WSGI components. +* ``http_connect_timeout``: (optional, default `python default` allow increase + the timeout when validating token by http). * ``auth_port``: (optional, default `35357`) the port used to validate tokens * ``auth_protocol``: (optional, default `https`) * ``auth_uri``: (optional, defaults to `auth_protocol`://`auth_host`:`auth_port`) From aa4604d4620f5a78f1facc3dc9f311a94c19ca40 Mon Sep 17 00:00:00 2001 From: Vishvananda Ishaya Date: Fri, 1 Mar 2013 10:15:26 -0800 Subject: [PATCH 11/40] Cache tokens using memorycache from oslo. Verifying tokens accounts for a significant portion of the time taken by the various api servers. This uses the simple memory cache from oslo so that there is a simple default cache even if memcached is not deployed. Also cleans up the tests and removes unnecessary fakes. DocImpact Change-Id: I501c14f2f51da058cb574c32d49dd769e6f6ad86 --- source/middlewarearchitecture.rst | 13 +++++++------ 1 file changed, 7 insertions(+), 6 deletions(-) diff --git a/source/middlewarearchitecture.rst b/source/middlewarearchitecture.rst index 407a5d27..803fbd90 100644 --- a/source/middlewarearchitecture.rst +++ b/source/middlewarearchitecture.rst @@ -196,15 +196,16 @@ Configuration Options Caching for improved response ----------------------------- -In order to prevent every service request, the middleware may be configured -to utilize a cache, and the keystone API returns the tokens with an -expiration (configurable in duration on the keystone service). The middleware -supports memcache based caching. +In order to prevent excessive requests and validations, the middleware uses an +in-memory cache for the tokens the keystone API returns. Keep in mind that +invalidated tokens may continue to work if they are still in the token cache, +so token_cache_time is configurable. For larger deployments, the middleware +also supports memcache based caching. * ``memcache_servers``: (optonal) if defined, the memcache server(s) to use for cacheing. It will be ignored if Swift MemcacheRing is used instead. -* ``token_cache_time``: (optional, default 300 seconds) Only valid if - memcache_servers is defined. +* ``token_cache_time``: (optional, default 300 seconds) Set to -1 to disable + caching completely. When deploying auth_token middleware with Swift, user may elect to use Swift MemcacheRing instead of the local Keystone memcache. From e1651e8cdc18ba5910613b1cccff1e7257e15e20 Mon Sep 17 00:00:00 2001 From: Joe Heck Date: Wed, 3 Apr 2013 09:44:20 -0700 Subject: [PATCH 12/40] adding notes about dealing with exceptions in the client Change-Id: I661b10414e0281bc695236bb32f985b0ef5b7600 --- source/using-api.rst | 4 ++++ 1 file changed, 4 insertions(+) diff --git a/source/using-api.rst b/source/using-api.rst index b5d630c1..fb1aa3a2 100644 --- a/source/using-api.rst +++ b/source/using-api.rst @@ -29,6 +29,10 @@ You create a valid ``keystoneclient.v2_0.client.Client`` object by passing authentication data to the constructor. Authentication and examples of common tasks are provided below. +You can generally expect that when the client needs to propogate an exception +it will raise an instance of subclass of +``keystoneclient.exceptions.ClientException`` + Authenticating ============== From c3562cac6fe09d49c24876c6703e6a6d2a973807 Mon Sep 17 00:00:00 2001 From: Jakub Ruzicka Date: Tue, 28 May 2013 20:37:43 +0200 Subject: [PATCH 13/40] Provide keystone CLI man page. Resolves: bug 1185142 Implements blueprint: clients-man-pages Provide basic but hopefully useful man page. shell.rst was merged into and replaced by the man page in HTML docs. Change-Id: I0a90e4638cc7e4ed9c02c5abd7d84a4079e5f50d --- source/conf.py | 18 ++++-- source/index.rst | 2 +- source/{shell.rst => man/keystone.rst} | 77 +++++++++++++++++++++----- 3 files changed, 78 insertions(+), 19 deletions(-) rename source/{shell.rst => man/keystone.rst} (60%) diff --git a/source/conf.py b/source/conf.py index 94865076..603daf26 100644 --- a/source/conf.py +++ b/source/conf.py @@ -14,6 +14,7 @@ import os import sys +import pbr.version sys.path.insert(0, os.path.abspath(os.path.join(os.path.dirname(__file__), '..', '..'))) @@ -49,16 +50,16 @@ master_doc = 'index' # General information about the project. project = u'python-keystoneclient' -copyright = u'Rackspace, based on work by Jacob Kaplan-Moss' +copyright = u'OpenStack Contributors' # 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 XXXX.Y version. -version = '2012.3' +version_info = pbr.version.VersionInfo('python-keystoneclient') +# The short X.Y version. +version = version_info.version_string() # The full version, including alpha/beta/rc tags. -release = '2012.3-dev' +release = version_info.release_string() # The language for content autogenerated by Sphinx. Refer to documentation # for a list of supported languages. @@ -98,6 +99,13 @@ pygments_style = 'sphinx' # A list of ignored prefixes for module index sorting. #modindex_common_prefix = [] +# Grouping the document tree for man pages. +# List of tuples 'sourcefile', 'target', u'title', u'Authors name', 'manual' + +man_pages = [ + ('man/keystone', 'keystone', u'Client for OpenStack Identity API', + [u'OpenStack Contributors'], 1), +] # -- Options for HTML output -------------------------------------------------- diff --git a/source/index.rst b/source/index.rst index faffc4f3..45cb1d64 100644 --- a/source/index.rst +++ b/source/index.rst @@ -11,7 +11,7 @@ Contents: :maxdepth: 1 releases - shell + man/keystone using-api api/autoindex diff --git a/source/shell.rst b/source/man/keystone.rst similarity index 60% rename from source/shell.rst rename to source/man/keystone.rst index 02d158c8..61890da7 100644 --- a/source/shell.rst +++ b/source/man/keystone.rst @@ -1,12 +1,25 @@ -The :program:`keystone` shell utility -===================================== +======================================= +:program:`keystone` command line utility +======================================= .. program:: keystone .. highlight:: bash +SYNOPSIS +======== -The :program:`keystone` shell utility interacts with OpenStack Identity API -from the command line. It supports the entirety of the OpenStack Identity API. +:program:`keystone` [options] [command-options] + +:program:`keystone help` + +:program:`keystone help` + + +DESCRIPTION +=========== + +The :program:`keystone` command line utility interacts with services providing +OpenStack Identity API (e.g. Keystone). To communicate with the API, you will need to be authenticated - and the :program:`keystone` provides multiple options for this. @@ -32,9 +45,10 @@ If you already have accounts, you can use your OpenStack username and password. You can do this with the :option:`--os-username`, :option:`--os-password`. -Keystone allows a user to be associated with one or more tenants. To specify -the tenant for which you want to authorize against, you may optionally -specify a :option:`--os-tenant-id` or :option:`--os-tenant-name`. +Keystone allows a user to be associated with one or more projects which are +historically called tenants. To specify the project for which you want to +authorize against, you may optionally specify a :option:`--os-tenant-id` or +:option:`--os-tenant-name`. Instead of using options, it is easier to just set them as environment variables: @@ -49,7 +63,7 @@ variables: .. envvar:: OS_TENANT_NAME - Name of Keystone Tenant. + Name of Keystone project. .. envvar:: OS_TENANT_ID @@ -90,10 +104,47 @@ For example, in Bash you'd use:: export OS_CERT=/etc/keystone/yourpublickey.pem export OS_KEY=/etc/keystone/yourprivatekey.pem -From there, all shell commands take the form:: - keystone [arguments...] +OPTIONS +======= -Run :program:`keystone help` to get a full list of all possible commands, -and run :program:`keystone help ` to get detailed help for that -command. +To get a list of available commands and options run:: + + keystone help + +To get usage and options of a command:: + + keystone help + + +EXAMPLES +======== + +Get information about endpoint-create command:: + + keystone help endpoint-create + +View endpoints of OpenStack services:: + + keystone catalog + +Create a 'service' project:: + + keystone tenant-create --name=service + +Create service user for nova:: + + keystone user-create --name=nova \ + --tenant_id= \ + --email=nova@nothing.com + +View roles:: + + keystone role-list + + +BUGS +==== + +Keystone client is hosted in Launchpad so you can view current bugs at +https://bugs.launchpad.net/python-keystoneclient/. From 3cc0d909b70ec1f4c53a949b00d6492f008d3486 Mon Sep 17 00:00:00 2001 From: "Bryan D. Payne" Date: Fri, 7 Jun 2013 09:34:25 -0700 Subject: [PATCH 14/40] Fix memcache encryption middleware This fixes lp1175367 and lp1175368 by redesigning the memcache crypt middleware to not do dangerous things. It is forward compatible, but will invalidate any existing ephemeral encrypted or signed memcache entries. Change-Id: Ice8724949a48bfad3b8b7c41b5f50a18a9ad9f42 Signed-off-by: Bryan D. Payne --- source/middlewarearchitecture.rst | 35 +++++++++++++++++-------------- 1 file changed, 19 insertions(+), 16 deletions(-) diff --git a/source/middlewarearchitecture.rst b/source/middlewarearchitecture.rst index 803fbd90..894d40dd 100644 --- a/source/middlewarearchitecture.rst +++ b/source/middlewarearchitecture.rst @@ -1,5 +1,5 @@ .. - Copyright 2011-2012 OpenStack, LLC + Copyright 2011-2013 OpenStack, LLC All Rights Reserved. Licensed under the Apache License, Version 2.0 (the "License"); you may @@ -188,7 +188,8 @@ Configuration Options the timeout when validating token by http). * ``auth_port``: (optional, default `35357`) the port used to validate tokens * ``auth_protocol``: (optional, default `https`) -* ``auth_uri``: (optional, defaults to `auth_protocol`://`auth_host`:`auth_port`) +* ``auth_uri``: (optional, defaults to + `auth_protocol`://`auth_host`:`auth_port`) * ``certfile``: (required, if Keystone server requires client cert) * ``keyfile``: (required, if Keystone server requires client cert) This can be the same as the certfile if the certfile includes the private key. @@ -232,22 +233,24 @@ Memcache Protection =================== When using memcached, we are storing user tokens and token validation -information into the cache as raw data. Which means anyone who have access -to the memcache servers can read and modify data stored there. To mitigate -this risk, ``auth_token`` middleware provides an option to either encrypt -or authenticate the token data stored in the cache. +information into the cache as raw data. Which means that anyone who +has access to the memcache servers can read and modify data stored +there. To mitigate this risk, ``auth_token`` middleware provides an +option to authenticate and optionally encrypt the token data stored in +the cache. -* ``memcache_security_strategy``: (optional) if defined, indicate whether token - data should be encrypted or authenticated. Acceptable values are ``ENCRYPT`` - or ``MAC``. If ``ENCRYPT``, token data is encrypted in the cache. If - ``MAC``, token data is authenticated (with HMAC) in the cache. If its value - is neither ``MAC`` nor ``ENCRYPT``, ``auth_token`` will raise an exception - on initialization. +* ``memcache_security_strategy``: (optional) if defined, indicate + whether token data should be authenticated or authenticated and + encrypted. Acceptable values are ``MAC`` or ``ENCRYPT``. If ``MAC``, + token data is authenticated (with HMAC) in the cache. If + ``ENCRYPT``, token data is encrypted and authenticated in the + cache. If the value is not one of these options or empty, + ``auth_token`` will raise an exception on initialization. * ``memcache_secret_key``: (optional, mandatory if - ``memcache_security_strategy`` is defined) if defined, - a random string to be used for key derivation. If - ``memcache_security_strategy`` is defined and ``memcache_secret_key`` is - absent, ``auth_token`` will raise an exception on initialization. + ``memcache_security_strategy`` is defined) this string is used for + key derivation. If ``memcache_security_strategy`` is defined and + ``memcache_secret_key`` is absent, ``auth_token`` will raise an + exception on initialization. Exchanging User Information =========================== From 7ee07100a5747bc844a8bf50a711e6a6f880d009 Mon Sep 17 00:00:00 2001 From: xingzhou Date: Tue, 4 Jun 2013 01:44:09 -0400 Subject: [PATCH 15/40] Change memcache config entry name in Keystone to be consistent with Oslo Currently, Keystone-Client is using 'memcache_servers' config option to store the memcache server info, while in OSLO project, it is using 'memcached_servers' to config the same option. It is better to change keystone-client's 'memcache_servers' to 'memcached_servers' to keep consistent between these two projects. Change-Id: I93ca0aa368f95a3ccf6de6984262057e61f75ffe Fixes: Bug 1172793 --- source/middlewarearchitecture.rst | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/source/middlewarearchitecture.rst b/source/middlewarearchitecture.rst index 894d40dd..f5fbae7c 100644 --- a/source/middlewarearchitecture.rst +++ b/source/middlewarearchitecture.rst @@ -134,7 +134,7 @@ a WSGI component. Example for the auth_token middleware:: ;Uncomment next line to use Swift MemcacheRing ;cache = swift.cache ;Uncomment next line and check ip:port to use memcached to cache tokens - ;memcache_servers = 127.0.0.1:11211 + ;memcached_servers = 127.0.0.1:11211 ;Uncomment next 2 lines to turn on memcache protection ;memcache_security_strategy = ENCRYPT ;memcache_secret_key = change_me @@ -203,7 +203,7 @@ invalidated tokens may continue to work if they are still in the token cache, so token_cache_time is configurable. For larger deployments, the middleware also supports memcache based caching. -* ``memcache_servers``: (optonal) if defined, the memcache server(s) to use for +* ``memcached_servers``: (optonal) if defined, the memcache server(s) to use for cacheing. It will be ignored if Swift MemcacheRing is used instead. * ``token_cache_time``: (optional, default 300 seconds) Set to -1 to disable caching completely. From 7eac851fb98729de8a78442e8f7ef7dd0d81b745 Mon Sep 17 00:00:00 2001 From: Chuck Short Date: Fri, 23 Aug 2013 10:02:01 -0400 Subject: [PATCH 16/40] python3: Use from future import unicode_literals use "from future import unicode_literals" instead of u"" To the road to Python3, a possible next step would be to use the from __future__ import unicode_literals and remove the u'' prefixes, as it is not supported in Python3. Change-Id: Ic7afb3cf2d8dfad47b8a1626ab264f6d4f50d00e Signed-off-by: Chuck Short --- source/conf.py | 16 +++++++++------- 1 file changed, 9 insertions(+), 7 deletions(-) diff --git a/source/conf.py b/source/conf.py index 603daf26..c1d68b82 100644 --- a/source/conf.py +++ b/source/conf.py @@ -12,6 +12,8 @@ # All configuration values have a default; values that are commented out # serve to show the default. +from __future__ import unicode_literals + import os import sys import pbr.version @@ -49,8 +51,8 @@ source_suffix = '.rst' master_doc = 'index' # General information about the project. -project = u'python-keystoneclient' -copyright = u'OpenStack Contributors' +project = 'python-keystoneclient' +copyright = 'OpenStack Contributors' # The version info for the project you're documenting, acts as replacement for # |version| and |release|, also used in various other places throughout the @@ -100,11 +102,11 @@ pygments_style = 'sphinx' #modindex_common_prefix = [] # Grouping the document tree for man pages. -# List of tuples 'sourcefile', 'target', u'title', u'Authors name', 'manual' +# List of tuples 'sourcefile', 'target', 'title', 'Authors name', 'manual' man_pages = [ - ('man/keystone', 'keystone', u'Client for OpenStack Identity API', - [u'OpenStack Contributors'], 1), + ('man/keystone', 'keystone', 'Client for OpenStack Identity API', + ['OpenStack Contributors'], 1), ] # -- Options for HTML output -------------------------------------------------- @@ -196,8 +198,8 @@ htmlhelp_basename = 'python-keystoneclientdoc' # . latex_documents = [ ('index', 'python-keystoneclient.tex', - u'python-keystoneclient Documentation', - u'Nebula Inc, based on work by Rackspace and Jacob Kaplan-Moss', + 'python-keystoneclient Documentation', + 'Nebula Inc, based on work by Rackspace and Jacob Kaplan-Moss', 'manual'), ] From 04ecee21d61f121fafd60287f438b52f3079d586 Mon Sep 17 00:00:00 2001 From: Jamie Lennox Date: Mon, 12 Aug 2013 13:12:27 +1000 Subject: [PATCH 17/40] Replace HttpConnection in auth_token with Requests Requests is becoming the standard way of doing http communication, it also vastly simplifies adding other authentication mechanisms. Use it in the auth_token middleware. This adds the ability to specify a CA file that will be used to verify a HTTPS connections or insecure to specifically ignore HTTPS validation. SecurityImpact DocImpact Partial-Bug: #1188189 Change-Id: Iae94329e7abd105bf95224d28f39f4b746b9eb70 --- source/middlewarearchitecture.rst | 4 ++++ 1 file changed, 4 insertions(+) diff --git a/source/middlewarearchitecture.rst b/source/middlewarearchitecture.rst index f5fbae7c..03782fa3 100644 --- a/source/middlewarearchitecture.rst +++ b/source/middlewarearchitecture.rst @@ -193,6 +193,10 @@ Configuration Options * ``certfile``: (required, if Keystone server requires client cert) * ``keyfile``: (required, if Keystone server requires client cert) This can be the same as the certfile if the certfile includes the private key. +* ``cafile``: (optional, defaults to use system CA bundle) the path to a PEM + encoded CA file/bundle that will be used to verify HTTPS connections. +* ``insecure``: (optional, default `False`) Don't verify HTTPS connections + (overrides `cafile`). Caching for improved response ----------------------------- From a804f25eb3e806ac2ea79283113ae11af5289b46 Mon Sep 17 00:00:00 2001 From: ZhiQiang Fan Date: Fri, 20 Sep 2013 04:30:41 +0800 Subject: [PATCH 18/40] Replace OpenStack LLC with OpenStack Foundation Some files still use trademark OpenStack LLC in header, which should be changed to OpenStack Foundation. NOTE: tools/install_venv.py is not touched, should sync with oslo Change-Id: I01d4f6b64cf1a152c4e190407799ce7d53de845f Fixes-Bug: #1214176 --- source/middlewarearchitecture.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/source/middlewarearchitecture.rst b/source/middlewarearchitecture.rst index 03782fa3..caeff218 100644 --- a/source/middlewarearchitecture.rst +++ b/source/middlewarearchitecture.rst @@ -1,5 +1,5 @@ .. - Copyright 2011-2013 OpenStack, LLC + Copyright 2011-2013 OpenStack Foundation All Rights Reserved. Licensed under the Apache License, Version 2.0 (the "License"); you may From c7f60b4d7ddeebfcca9cbb511f61d7b66b01c734 Mon Sep 17 00:00:00 2001 From: guang-yee Date: Fri, 11 Oct 2013 14:08:57 -0700 Subject: [PATCH 19/40] Opt-out of service catalog Introducing a config option 'include_service_catalog' to indicate whether service catalog is needed. If the 'include_service_catalog' option is set to False, middleware will not ask for service catalog on token validation and will not set the X-Service-Catalog header. This option is backward compatible as it is default to True. DocImpact Fixed bug 1228317 Change-Id: Id8c410a7ae0443ac425d20cb9c6a24ee5bb2cb8d --- source/middlewarearchitecture.rst | 6 ++++++ 1 file changed, 6 insertions(+) diff --git a/source/middlewarearchitecture.rst b/source/middlewarearchitecture.rst index caeff218..6b089046 100644 --- a/source/middlewarearchitecture.rst +++ b/source/middlewarearchitecture.rst @@ -141,6 +141,8 @@ a WSGI component. Example for the auth_token middleware:: ;Uncomment next 2 lines if Keystone server is validating client cert ;certfile = ;keyfile = + ;Uncomment next line to opt-out of service catalog + ;include_service_catalog = False For services which have separate paste-deploy ini file, auth_token middleware can be alternatively configured in [keystone_authtoken] section in the main @@ -197,6 +199,10 @@ Configuration Options encoded CA file/bundle that will be used to verify HTTPS connections. * ``insecure``: (optional, default `False`) Don't verify HTTPS connections (overrides `cafile`). +* ``include_service_catalog``: (optional, default `True`) Indicate whether to + set the X-Service-Catalog header. If False, middleware will not ask for + service catalog on token validation and will not set the X-Service-Catalog + header. Caching for improved response ----------------------------- From 8953560acfd3ed63a809b73002694e375fe175eb Mon Sep 17 00:00:00 2001 From: Emilien Macchi Date: Fri, 6 Dec 2013 15:00:31 +0100 Subject: [PATCH 20/40] Rename tokenauth to authtoken in the doc Change-Id: Iedacd3ac76999570d5507953b9665948a3e3888f Signed-off-by: Emilien Macchi --- source/middlewarearchitecture.rst | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/source/middlewarearchitecture.rst b/source/middlewarearchitecture.rst index 6b089046..703437b3 100644 --- a/source/middlewarearchitecture.rst +++ b/source/middlewarearchitecture.rst @@ -119,9 +119,9 @@ a WSGI component. Example for the auth_token middleware:: paste.app_factory = myService:app_factory [pipeline:main] - pipeline = tokenauth myService + pipeline = authtoken myService - [filter:tokenauth] + [filter:authtoken] paste.filter_factory = keystone.middleware.auth_token:filter_factory auth_host = 127.0.0.1 auth_port = 35357 From cb4006039a06fa5717b8dd1e2cbe36e862765bb2 Mon Sep 17 00:00:00 2001 From: Florent Flament Date: Fri, 20 Dec 2013 13:24:03 +0000 Subject: [PATCH 21/40] Documents keystone v3 API usage - part 1 docs/source/using-api.rst documents how to use the V2 API. This patch starts the equivalent documentation (using-api-v3.rst) about how to use Keystone v3 API. Introduction and Authentication sections have been written. Change-Id: I5a2d45d80ba712492717a75ac5901f5ca775daa4 Partial-Bug: #1260527 --- source/using-api-v3.rst | 110 ++++++++++++++++++++++++++++++++++++++++ 1 file changed, 110 insertions(+) create mode 100644 source/using-api-v3.rst diff --git a/source/using-api-v3.rst b/source/using-api-v3.rst new file mode 100644 index 00000000..a842f634 --- /dev/null +++ b/source/using-api-v3.rst @@ -0,0 +1,110 @@ +================= +The Client v3 API +================= + +Introduction +============ + +The main concepts in the Identity v3 API are: + + * credentials + * domains + * endpoints + * groups + * policies + * projects + * roles + * services + * trusts + * users + +The ``keystoneclient.v3.client`` API lets you query and make changes +through ``managers``. For example, to manipulate a project (formerly +called tenant), you interact with a +``keystoneclient.v3.projects.ProjectManager`` object. + +You obtain access to managers through attributes of a +``keystoneclient.v3.client.Client`` object. For example, the +``projects`` attribute of a ``Client`` object is a projects manager:: + + >>> from keystoneclient.v3 import client + >>> keystone = client.Client(...) + >>> keystone.projects.list() # List projects + +While it is possible to instantiate a +``keystoneclient.v3.client.Client`` object (as done above for +clarity), the recommended approach is to use the discovery mechanism +provided by the ``keystone.client.Client`` class. The appropriate +class will be instantiated depending on the API versions available:: + + >>> from keystoneclient import client + >>> keystone = + ... client.Client(auth_url='http://localhost:5000', ...) + >>> type(keystone) + + +One can force the use of a specific version of the API, either by +using the ``version`` keyword argument:: + + >>> from keystoneclient import client + >>> keystone = client.Client(auth_url='http://localhost:5000', + version=(2,), ...) + >>> type(keystone) + + >>> keystone = client.Client(auth_url='http://localhost:5000', + version=(3,), ...) + >>> type(keystone) + + +Or by specifying directly the specific API version authentication URL +as the auth_url keyword argument:: + + >>> from keystoneclient import client + >>> keystone = + ... client.Client(auth_url='http://localhost:5000/v2.0', ...) + >>> type(keystone) + + >>> keystone = + ... client.Client(auth_url='http://localhost:5000/v3', ...) + >>> type(keystone) + + +Upon successful authentication, a ``keystoneclient.v3.client.Client`` +object is returned (when using the Identity v3 API). Authentication and +examples of common tasks are provided below. + +You can generally expect that when the client needs to propagate an +exception it will raise an instance of subclass of +``keystoneclient.exceptions.ClientException`` + +Authenticating +============== + +You can authenticate against Keystone using a username, a user domain +name (which will default to 'Default' if it is not specified) and a +password:: + + >>> from keystoneclient import client + >>> auth_url = 'http://localhost:5000' + >>> username = 'adminUser' + >>> user_domain_name = 'Default' + >>> password = 'secreetword' + >>> keystone = client.Client(auth_url=auth_url, version=(3,), + ... username=username, password=password, + ... user_domain_name=user_domain_name) + +You may optionally specify a domain or project (along with its project +domain name), to obtain a scoped token:: + + >>> from keystoneclient import client + >>> auth_url = 'http://localhost:5000' + >>> username = 'adminUser' + >>> user_domain_name = 'Default' + >>> project_name = 'demo' + >>> project_domain_name = 'Default' + >>> password = 'secreetword' + >>> keystone = client.Client(auth_url=auth_url, version=(3,), + ... username=username, password=password, + ... user_domain_name=user_domain_name, + ... project_name=project_name, + ... project_domain_name=project_domain_name) From 4b12acd4a57aed6189b954b1b07b3eb260d61e96 Mon Sep 17 00:00:00 2001 From: Florent Flament Date: Tue, 24 Dec 2013 15:57:20 +0000 Subject: [PATCH 22/40] Rename using-api.rst to using-api-v2.rst Renaming file for consistency, since using-api-v3.rst is being written there: https://review.openstack.org/#/c/63408 Minor changes have been made to indicate that the file documents the keystone v2 API. Change-Id: I694b658a8b59d21615af5d88edc0f7b394ebbe7b Partial-Bug: #1260527 --- source/index.rst | 2 +- source/{using-api.rst => using-api-v2.rst} | 12 ++++++------ 2 files changed, 7 insertions(+), 7 deletions(-) rename source/{using-api.rst => using-api-v2.rst} (94%) diff --git a/source/index.rst b/source/index.rst index 45cb1d64..c982b378 100644 --- a/source/index.rst +++ b/source/index.rst @@ -12,7 +12,7 @@ Contents: releases man/keystone - using-api + using-api-v2 api/autoindex diff --git a/source/using-api.rst b/source/using-api-v2.rst similarity index 94% rename from source/using-api.rst rename to source/using-api-v2.rst index fb1aa3a2..f491daf2 100644 --- a/source/using-api.rst +++ b/source/using-api-v2.rst @@ -1,11 +1,11 @@ -============== -The client API -============== +================= +The client v2 API +================= Introduction ============ -The main concepts in the Identity API are: +The main concepts in the Identity v2 API are: * tenants * users @@ -13,8 +13,8 @@ The main concepts in the Identity API are: * services * endpoints -The Identity API lets you query and make changes through managers. For example, -to manipulate tenants, you interact with a +The client v2 API lets you query and make changes through +managers. For example, to manipulate tenants, you interact with a ``keystoneclient.v2_0.tenants.TenantManager`` object. You obtain access to managers through via attributes of the From 180b0fbd084036f9cdf3b7f00e134b69ba53460d Mon Sep 17 00:00:00 2001 From: Eric Guo Date: Fri, 17 Jan 2014 20:13:24 +0800 Subject: [PATCH 23/40] Adjust import items according to hacking import rule This patch adjust import items and add missing blank lines acording to http://docs.openstack.org/developer/hacking/#imports {{stdlib imports in human alphabetical order}} \n {{third-party lib imports in human alphabetical order}} \n {{project imports in human alphabetical order}} \n \n {{begin your code}} hacking project also enforce some checks for import group. Let make the change in keytoneclient Change-Id: Ic83bd5ee426905588f4a2d555851a9a01fc69f02 --- source/conf.py | 2 ++ 1 file changed, 2 insertions(+) diff --git a/source/conf.py b/source/conf.py index c1d68b82..354d08ce 100644 --- a/source/conf.py +++ b/source/conf.py @@ -16,8 +16,10 @@ from __future__ import unicode_literals import os import sys + import pbr.version + sys.path.insert(0, os.path.abspath(os.path.join(os.path.dirname(__file__), '..', '..'))) From 89b8c2dd6687f8fd178d5ead11f354293942ae01 Mon Sep 17 00:00:00 2001 From: Eric Guo Date: Thu, 23 Jan 2014 16:30:19 +0800 Subject: [PATCH 24/40] Fix typos in documents and comments Fix typos detected by toolkit misspellings. * pip install misspellings * git ls-files | grep -v locale | misspellings -f - Change-Id: Ifbbc29537d9d129aad238de6c37718c4fbb8349b --- source/using-api-v2.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/source/using-api-v2.rst b/source/using-api-v2.rst index f491daf2..2f6b3cfd 100644 --- a/source/using-api-v2.rst +++ b/source/using-api-v2.rst @@ -29,7 +29,7 @@ You create a valid ``keystoneclient.v2_0.client.Client`` object by passing authentication data to the constructor. Authentication and examples of common tasks are provided below. -You can generally expect that when the client needs to propogate an exception +You can generally expect that when the client needs to propagate an exception it will raise an instance of subclass of ``keystoneclient.exceptions.ClientException`` From 3f01d2af0237ccfa1fd547173cabbea93e1a3a0b Mon Sep 17 00:00:00 2001 From: Brant Knudson Date: Sun, 2 Feb 2014 11:14:56 -0600 Subject: [PATCH 25/40] Update middlewarearchitecture config options docs The configuration options documented in middlewarearchitecture.rst were incomplete. This change adds all the options defined in middleware.auth_token. Change-Id: I4a479bfa90e941f5094516cdb97cd58f91727f1c --- source/middlewarearchitecture.rst | 54 +++++++++++++++++++++++++------ 1 file changed, 45 insertions(+), 9 deletions(-) diff --git a/source/middlewarearchitecture.rst b/source/middlewarearchitecture.rst index 703437b3..16f60b7f 100644 --- a/source/middlewarearchitecture.rst +++ b/source/middlewarearchitecture.rst @@ -173,8 +173,26 @@ removed to use values in [keystone_authtoken] section. Configuration Options --------------------- +* ``auth_admin_prefix``: Prefix to prepend at the beginning of the path * ``auth_host``: (required) the host providing the keystone service API endpoint for validating and requesting tokens +* ``auth_port``: (optional, default `35357`) the port used to validate tokens +* ``auth_protocol``: (optional, default `https`) +* ``auth_uri``: (optional, defaults to + `auth_protocol`://`auth_host`:`auth_port`) +* ``auth_version``: API version of the admin Identity API endpoint +* ``delay_auth_decision``: (optional, default `0`) (off). If on, the middleware + will not reject invalid auth requests, but will delegate that decision to + downstream WSGI components. +* ``http_connect_timeout``: (optional) Request timeout value for communicating + with Identity API server. +* ``http_request_max_retries``: (default 3) How many times are we trying to + reconnect when communicating with Identity API Server. +* ``http_handler``: (optional) Allows to pass in the name of a fake + http_handler callback function used instead of `httplib.HTTPConnection` or + `httplib.HTTPSConnection`. Useful for unit testing where network is not + available. + * ``admin_token``: either this or the following three options are required. If set, this is a single shared secret with the keystone configuration used to validate tokens. @@ -183,15 +201,8 @@ Configuration Options admin_tenant_name are defined as a service account which is expected to have been previously configured in Keystone to validate user tokens. -* ``delay_auth_decision``: (optional, default `0`) (off). If on, the middleware - will not reject invalid auth requests, but will delegate that decision to - downstream WSGI components. -* ``http_connect_timeout``: (optional, default `python default` allow increase - the timeout when validating token by http). -* ``auth_port``: (optional, default `35357`) the port used to validate tokens -* ``auth_protocol``: (optional, default `https`) -* ``auth_uri``: (optional, defaults to - `auth_protocol`://`auth_host`:`auth_port`) +* ``cache``: (optional) Env key for the swift cache + * ``certfile``: (required, if Keystone server requires client cert) * ``keyfile``: (required, if Keystone server requires client cert) This can be the same as the certfile if the certfile includes the private key. @@ -199,10 +210,35 @@ Configuration Options encoded CA file/bundle that will be used to verify HTTPS connections. * ``insecure``: (optional, default `False`) Don't verify HTTPS connections (overrides `cafile`). + +* ``signing_dir``: (optional) Directory used to cache files related to PKI + tokens + +* ``memcached_servers``: (optional) If defined, the memcache server(s) to use + for caching +* ``token_cache_time``: (default 300) In order to prevent excessive requests + and validations, the middleware uses an in-memory cache for the tokens the + Keystone API returns. This is only valid if memcache_servers s defined. Set + to -1 to disable caching completely. +* ``memcache_security_strategy``: (optional) if defined, indicate whether token + data should be authenticated or authenticated and encrypted. Acceptable + values are MAC or ENCRYPT. If MAC, token data is authenticated (with HMAC) + in the cache. If ENCRYPT, token data is encrypted and authenticated in the + cache. If the value is not one of these options or empty, auth_token will + raise an exception on initialization. +* ``memcache_secret_key``: (mandatory if memcache_security_strategy is defined) + this string is used for key derivation. * ``include_service_catalog``: (optional, default `True`) Indicate whether to set the X-Service-Catalog header. If False, middleware will not ask for service catalog on token validation and will not set the X-Service-Catalog header. +* ``enforce_token_bind``: (default ``permissive``) Used to control the use and + type of token binding. Can be set to: "disabled" to not check token binding. + "permissive" (default) to validate binding information if the bind type is of + a form known to the server and ignore it if not. "strict" like "permissive" + but if the bind type is unknown the token will be rejected. "required" any + form of token binding is needed to be allowed. Finally the name of a binding + method that must be present in tokens. Caching for improved response ----------------------------- From 2438fa5c100657727dee8d548e220cb28aa7415a Mon Sep 17 00:00:00 2001 From: Brant Knudson Date: Sun, 2 Feb 2014 11:01:34 -0600 Subject: [PATCH 26/40] Fix references to auth_token in middlewarearchitecture doc The middlewarearchitecture doc was still referring to keystone.middleware.auth_token, but the middleware was moved to keystoneclient. Also, corrected some other minor typos. Change-Id: I270ea2ccc739596e99a4a852bff3b5b7d1c85c82 --- source/middlewarearchitecture.rst | 28 ++++++++++++---------------- 1 file changed, 12 insertions(+), 16 deletions(-) diff --git a/source/middlewarearchitecture.rst b/source/middlewarearchitecture.rst index 703437b3..2f54e530 100644 --- a/source/middlewarearchitecture.rst +++ b/source/middlewarearchitecture.rst @@ -23,7 +23,7 @@ Abstract The Keystone middleware architecture supports a common authentication protocol in use between the OpenStack projects. By using keystone as a common -authentication and authorization mechanisms, the OpenStack project can plug in +authentication and authorization mechanism, the OpenStack project can plug in to existing authentication and authorization systems in use by existing environments. @@ -31,10 +31,8 @@ In this document, we describe the architecture and responsibilities of the authentication middleware which acts as the internal API mechanism for OpenStack projects based on the WSGI standard. -For the architecture of keystone and its services, please see -:doc:`architecture`. This documentation primarily describes the implementation -in ``keystoneclient/middleware/auth_token.py`` -(:py:class:`keystoneclient.middleware.auth_token.AuthProtocol`) +This documentation describes the implementation in +:class:`keystoneclient.middleware.auth_token` Specification Overview ====================== @@ -57,7 +55,7 @@ of the middleware processing is: * if valid, populate additional headers representing the identity that has been authenticated and authorized - * in invalid, or not token present, reject the request (HTTPUnauthorized) + * if invalid, or no token present, reject the request (HTTPUnauthorized) or pass along a header indicating the request is unauthorized (configurable in the middleware) * if the keystone service is unavailable to validate the token, reject @@ -75,8 +73,8 @@ Figure 1. Authentication Component :height: 180 :alt: An Authentication Component -The middleware may also be configured to operated in a 'delegated mode'. -In this mode, the decision reject an unauthenticated client is delegated to +The middleware may also be configured to operate in a 'delegated mode'. +In this mode, the decision to reject an unauthenticated client is delegated to the OpenStack service, as illustrated in :ref:`authComponentDelegated`. Here, requests are forwarded to the OpenStack service with an identity status @@ -102,7 +100,7 @@ Deployment Strategy =================== The middleware is intended to be used inline with OpenStack wsgi components, -based on the openstack-common WSGI middleware class. It is typically deployed +based on the Oslo WSGI middleware class. It is typically deployed as a configuration element in a paste configuration pipeline of other middleware components, with the pipeline terminating in the service application. The middleware conforms to the python WSGI standard [PEP-333]_. @@ -122,11 +120,10 @@ a WSGI component. Example for the auth_token middleware:: pipeline = authtoken myService [filter:authtoken] - paste.filter_factory = keystone.middleware.auth_token:filter_factory + paste.filter_factory = keystoneclient.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 = Super999Sekret888Password777 admin_user = admin admin_password = SuperSekretPassword @@ -144,13 +141,13 @@ a WSGI component. Example for the auth_token middleware:: ;Uncomment next line to opt-out of service catalog ;include_service_catalog = False -For services which have separate paste-deploy ini file, auth_token middleware +For services which have a separate paste-deploy ini file, auth_token middleware can be alternatively configured in [keystone_authtoken] section in the main config file. For example in Nova, all middleware parameters can be removed from api-paste.ini:: [filter:authtoken] - paste.filter_factory = keystone.middleware.auth_token:filter_factory + paste.filter_factory = keystoneclient.middleware.auth_token:filter_factory and set in nova.conf:: @@ -162,7 +159,6 @@ and set in nova.conf:: auth_host = 127.0.0.1 auth_port = 35357 auth_protocol = http - auth_uri = http://127.0.0.1:5000/ admin_user = admin admin_password = SuperSekretPassword admin_tenant_name = service @@ -282,8 +278,8 @@ unsuccessful. Extended the request with additional User Information ----------------------------------------------------- -:py:class:`keystone.middleware.auth_token.AuthProtocol` extends the request -with additional information if the user has been authenticated. +:py:class:`keystoneclient.middleware.auth_token.AuthProtocol` extends the +request with additional information if the user has been authenticated. X-Identity-Status From 05bc52a908afef09d56a9fd6023eb17eadfa97be Mon Sep 17 00:00:00 2001 From: Brant Knudson Date: Sun, 2 Feb 2014 10:36:38 -0600 Subject: [PATCH 27/40] Add link to the v3 client api doc There was no link from the main page to the v3 client API doc so there's no easy way to get to it or to know that it's there. This adds the link. Change-Id: I3fd49eedcf7b79f6d810ed22cfcffba4ce47dece --- source/index.rst | 8 +++++--- 1 file changed, 5 insertions(+), 3 deletions(-) diff --git a/source/index.rst b/source/index.rst index c982b378..001a1ec5 100644 --- a/source/index.rst +++ b/source/index.rst @@ -1,9 +1,10 @@ Python bindings to the OpenStack Identity API (Keystone) ======================================================== -This is a client for OpenStack Identity API. There's :doc:`a Python API -` (the :mod:`keystoneclient` module), and a :doc:`command-line script -` (installed as :program:`keystone`). +This is a client for OpenStack Identity API. There's a Python API for +:doc:`Identity API v3 ` and :doc:`v2 ` (the +:mod:`keystoneclient` modules), and a :doc:`command-line script ` +(installed as :program:`keystone`). Contents: @@ -13,6 +14,7 @@ Contents: releases man/keystone using-api-v2 + using-api-v3 api/autoindex From 5b69680c0b0edaed0adf0c4dabd60998393b94c8 Mon Sep 17 00:00:00 2001 From: Brant Knudson Date: Sun, 16 Feb 2014 11:48:31 -0600 Subject: [PATCH 28/40] Fix keystone command man page The overline/underline for the title was too short which generated an error. Change-Id: I2ba30ff9c819c425d5973c8cf5fd92d5642b5885 --- source/man/keystone.rst | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/source/man/keystone.rst b/source/man/keystone.rst index 61890da7..d96d89f7 100644 --- a/source/man/keystone.rst +++ b/source/man/keystone.rst @@ -1,6 +1,6 @@ -======================================= +======================================== :program:`keystone` command line utility -======================================= +======================================== .. program:: keystone .. highlight:: bash From 6f084852376a1c3d10d0f9e332ddd8919fd7dfe6 Mon Sep 17 00:00:00 2001 From: Brant Knudson Date: Fri, 28 Feb 2014 16:35:28 -0600 Subject: [PATCH 29/40] Capitalize Client API title consistently The "client v2 API" and "Client v2 API" titles were inconsistenly capitalized. This makes the title capitalization consistent so the index page looks better. Change-Id: I85d033fd5d7f5204cd3d18e8c613dfd0c2a1cdd6 --- source/using-api-v2.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/source/using-api-v2.rst b/source/using-api-v2.rst index 2f6b3cfd..9a31adda 100644 --- a/source/using-api-v2.rst +++ b/source/using-api-v2.rst @@ -1,5 +1,5 @@ ================= -The client v2 API +The Client v2 API ================= Introduction From 707dcfaf3acc2c8189a28bb74555d36f34ce5bfc Mon Sep 17 00:00:00 2001 From: Brant Knudson Date: Sun, 2 Feb 2014 11:36:39 -0600 Subject: [PATCH 30/40] Remove reference to non-existent shell doc There's no "shell.rst" document, so the index shouldn't reference it. Change-Id: I0d02b32349cfb6592b432700b4e04fda7fecbba8 --- source/index.rst | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/source/index.rst b/source/index.rst index 001a1ec5..c103c45a 100644 --- a/source/index.rst +++ b/source/index.rst @@ -3,8 +3,8 @@ Python bindings to the OpenStack Identity API (Keystone) This is a client for OpenStack Identity API. There's a Python API for :doc:`Identity API v3 ` and :doc:`v2 ` (the -:mod:`keystoneclient` modules), and a :doc:`command-line script ` -(installed as :program:`keystone`). +:mod:`keystoneclient` modules), and a command-line script (installed as +:doc:`keystone `). Contents: From 88064b51a6ad4a8936310aa6c4fefadfeaa50a5d Mon Sep 17 00:00:00 2001 From: Brant Knudson Date: Mon, 10 Feb 2014 18:47:37 -0600 Subject: [PATCH 31/40] Generate module docs The module docs were not being generated. Co-Authored-By: David Stanek Change-Id: I26e1d9a3d407474eb6b016f3ada4c495b5043460 Closes-Bug: #1278662 --- ext/__init__.py | 0 ext/apidoc.py | 46 ++++++++++++++++++++++++++++++++++++++++++++++ source/conf.py | 13 ++++++++++++- 3 files changed, 58 insertions(+), 1 deletion(-) create mode 100644 ext/__init__.py create mode 100644 ext/apidoc.py diff --git a/ext/__init__.py b/ext/__init__.py new file mode 100644 index 00000000..e69de29b diff --git a/ext/apidoc.py b/ext/apidoc.py new file mode 100644 index 00000000..60ad23e8 --- /dev/null +++ b/ext/apidoc.py @@ -0,0 +1,46 @@ +# Copyright 2014 OpenStack Foundation +# +# 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. + +# NOTE(blk-u): Uncomment the [pbr] section in setup.cfg and remove this +# Sphinx extension when https://launchpad.net/bugs/1260495 is fixed. + +import os.path as path + +from sphinx import apidoc + + +# NOTE(blk-u): pbr will run Sphinx multiple times when it generates +# documentation. Once for each builder. To run this extension we use the +# 'builder-inited' hook that fires at the beginning of a Sphinx build. +# We use ``run_already`` to make sure apidocs are only generated once +# even if Sphinx is run multiple times. +run_already = False + + +def run_apidoc(app): + global run_already + if run_already: + return + run_already = True + + package_dir = path.abspath(path.join(app.srcdir, '..', '..', + 'keystoneclient')) + source_dir = path.join(app.srcdir, 'api') + apidoc.main(['apidoc', package_dir, '-f', + '-H', 'keystoneclient Modules', + '-o', source_dir]) + + +def setup(app): + app.connect('builder-inited', run_apidoc) diff --git a/source/conf.py b/source/conf.py index 354d08ce..e0e877ee 100644 --- a/source/conf.py +++ b/source/conf.py @@ -23,6 +23,12 @@ import pbr.version sys.path.insert(0, os.path.abspath(os.path.join(os.path.dirname(__file__), '..', '..'))) +# NOTE(blk-u): Path for our Sphinx extension, remove when +# https://launchpad.net/bugs/1260495 is fixed. +sys.path.insert(0, os.path.abspath(os.path.join(os.path.dirname(__file__), + '..'))) + + # 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. @@ -36,7 +42,12 @@ sys.path.insert(0, os.path.abspath(os.path.join(os.path.dirname(__file__), extensions = ['sphinx.ext.autodoc', 'sphinx.ext.todo', 'sphinx.ext.coverage', - 'sphinx.ext.intersphinx'] + 'sphinx.ext.intersphinx', + # NOTE(blk-u): Uncomment the [pbr] section in setup.cfg and + # remove this Sphinx extension when + # https://launchpad.net/bugs/1260495 is fixed. + 'ext.apidoc', + ] todo_include_todos = True From 2b22fccd082f93e3db4795a909d7d62e152dc4dc Mon Sep 17 00:00:00 2001 From: Brant Knudson Date: Sun, 16 Feb 2014 12:03:58 -0600 Subject: [PATCH 32/40] Fix doc build errors There were some parts that had invalid RST in their docstrings which caused warnings and errors to be generated. Related-Bug: #1278662 Change-Id: Ibb53e6f49b5fa100fa6ecfe47331f9a70729d03b --- source/index.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/source/index.rst b/source/index.rst index c103c45a..440f463f 100644 --- a/source/index.rst +++ b/source/index.rst @@ -16,7 +16,7 @@ Contents: using-api-v2 using-api-v3 - api/autoindex + api/modules Contributing ============ From cb645cf0902aa1a0fc3c8b7023417497624ec616 Mon Sep 17 00:00:00 2001 From: Brant Knudson Date: Sun, 2 Feb 2014 10:34:05 -0600 Subject: [PATCH 33/40] Docs link to middlewarearchitecture There was no link to the middleware architecture from the main page so nobody would know that it's there. This adds the link. Change-Id: I2cd7a458b48d2c2889e4305e01bc013796a67c6e --- source/index.rst | 2 ++ 1 file changed, 2 insertions(+) diff --git a/source/index.rst b/source/index.rst index 440f463f..e5cd3dec 100644 --- a/source/index.rst +++ b/source/index.rst @@ -16,6 +16,8 @@ Contents: using-api-v2 using-api-v3 + middlewarearchitecture + api/modules Contributing From d591b1edc0f05b587db830522172b209a70b9966 Mon Sep 17 00:00:00 2001 From: Brant Knudson Date: Sun, 2 Feb 2014 11:29:45 -0600 Subject: [PATCH 34/40] Reference docstring for auth_token fields The documented variables that the auth_token middleware sets for the request was out of date with the code. Rather than maintain the documentation for the fields in 2 places we'll now link to the auth_token module docs. Change-Id: Id4ca1843f749c1ed0b515c8860764add3ec4a3da --- source/middlewarearchitecture.rst | 37 ++++--------------------------- 1 file changed, 4 insertions(+), 33 deletions(-) diff --git a/source/middlewarearchitecture.rst b/source/middlewarearchitecture.rst index 245c79cf..2b28c2ab 100644 --- a/source/middlewarearchitecture.rst +++ b/source/middlewarearchitecture.rst @@ -315,41 +315,12 @@ Extended the request with additional User Information ----------------------------------------------------- :py:class:`keystoneclient.middleware.auth_token.AuthProtocol` extends the -request with additional information if the user has been authenticated. +request with additional information if the user has been authenticated. See the +"What we add to the request for use by the OpenStack service" section in +:py:mod:`keystoneclient.middleware.auth_token` for the list of fields set by +the auth_token middleware. -X-Identity-Status - Provides information on whether the request was authenticated or not. - -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-Roles - The roles associated with that user - -Deprecated additions --------------------- - -X-Tenant - Provides the tenant name. This is to support any legacy implementations - before Keystone switched to an ID/Name schema for tenants. - -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-Role - The roles associated with that user - References ========== From 9cf3ef5d408fbed99617adefdbca591ea39bd5e3 Mon Sep 17 00:00:00 2001 From: Steve Martinelli Date: Tue, 25 Mar 2014 20:22:22 -0500 Subject: [PATCH 35/40] Remove releases.rst from keystone docs The most recent update to releases.rst was made back in 2012, but it's references in the docs page. It is providing false (or at least, inaccurate) information. Suggest removing it since the server side doesn't have a release related file either. Change-Id: If2a71b55117c450afdade3cad697eba5a626263f --- source/index.rst | 1 - source/releases.rst | 33 --------------------------------- 2 files changed, 34 deletions(-) delete mode 100644 source/releases.rst diff --git a/source/index.rst b/source/index.rst index e5cd3dec..bb53cb0c 100644 --- a/source/index.rst +++ b/source/index.rst @@ -11,7 +11,6 @@ Contents: .. toctree:: :maxdepth: 1 - releases man/keystone using-api-v2 using-api-v3 diff --git a/source/releases.rst b/source/releases.rst deleted file mode 100644 index bb3f1a0c..00000000 --- a/source/releases.rst +++ /dev/null @@ -1,33 +0,0 @@ -============= -Release notes -============= - -0.1.3 (August 31, 2012) -======================= -* changed logging to report request and response independently in --debug mode -* changed options to use hyphens instead of underscores -* added support for PKI signed tokens with Keystone - - -0.1.2 (July 9, 2012) -==================== -* added support for two-way SSL and --insecure option to allow for self-signed - certificates -* added support for password prompting if not provided -* added support for bash completion for keystone -* updated CLI options to use dashes instead of underscores - -0.1.1 (June 25, 2012) -===================== -* corrected versioning - -0.1.0 (March 29, 2012) -====================== -* released with OpenStack Essex and Diablo compatibility -* forked from http://github.com/rackspace/python-novaclient -* refactored to support Identity API (auth, tokens, services, roles, tenants, - users, etc.) -* removed legacy arguments of --username, --password, etc in migration to - support a cross-openstack unified CLI convention defined at - http://wiki.openstack.org/UnifiedCLI -* required service ID for listing endpoints From 12773a843a82a51066564cc4055c08064e6cbbd2 Mon Sep 17 00:00:00 2001 From: Brant Knudson Date: Sun, 16 Feb 2014 11:25:58 -0600 Subject: [PATCH 36/40] Update docs for auth_token middleware config options The documentation for the auth_token middleware config options was out of date. Change-Id: I8d03d77c58c714375e1e5174962991aa3adc61af --- source/middlewarearchitecture.rst | 138 ++++++++++++++++++++++++++---- 1 file changed, 119 insertions(+), 19 deletions(-) diff --git a/source/middlewarearchitecture.rst b/source/middlewarearchitecture.rst index 2b28c2ab..47ae5316 100644 --- a/source/middlewarearchitecture.rst +++ b/source/middlewarearchitecture.rst @@ -121,25 +121,124 @@ a WSGI component. Example for the auth_token middleware:: [filter:authtoken] paste.filter_factory = keystoneclient.middleware.auth_token:filter_factory - auth_host = 127.0.0.1 - auth_port = 35357 - auth_protocol = http - admin_token = Super999Sekret888Password777 - admin_user = admin - admin_password = SuperSekretPassword - admin_tenant_name = service - ;Uncomment next line to use Swift MemcacheRing - ;cache = swift.cache - ;Uncomment next line and check ip:port to use memcached to cache tokens - ;memcached_servers = 127.0.0.1:11211 - ;Uncomment next 2 lines to turn on memcache protection - ;memcache_security_strategy = ENCRYPT - ;memcache_secret_key = change_me - ;Uncomment next 2 lines if Keystone server is validating client cert - ;certfile = - ;keyfile = - ;Uncomment next line to opt-out of service catalog - ;include_service_catalog = False + + # Prefix to prepend at the beginning of the path (string + # value) + #auth_admin_prefix= + + # Host providing the admin Identity API endpoint (string + # value) + auth_host=127.0.0.1 + + # Port of the admin Identity API endpoint (integer value) + auth_port=35357 + + # Protocol of the admin Identity API endpoint(http or https) + # (string value) + auth_protocol=https + + # Complete public Identity API endpoint (string value) + #auth_uri= + + # API version of the admin Identity API endpoint (string + # value) + #auth_version= + + # Do not handle authorization requests within the middleware, + # but delegate the authorization decision to downstream WSGI + # components (boolean value) + #delay_auth_decision=false + + # Request timeout value for communicating with Identity API + # server. (boolean value) + #http_connect_timeout= + + # How many times are we trying to reconnect when communicating + # with Identity API Server. (integer value) + #http_request_max_retries=3 + + # Single shared secret with the Keystone configuration used + # for bootstrapping a Keystone installation, or otherwise + # bypassing the normal authentication process. (string value) + #admin_token= + + # Keystone account username (string value) + #admin_user= + + # Keystone account password (string value) + admin_password=SuperSekretPassword + + # Keystone service account tenant name to validate user tokens + # (string value) + #admin_tenant_name=admin + + # Env key for the swift cache (string value) + #cache= + + # Required if Keystone server requires client certificate + # (string value) + #certfile= + + # Required if Keystone server requires client certificate + # (string value) + #keyfile= + + # A PEM encoded Certificate Authority to use when verifying + # HTTPs connections. Defaults to system CAs. (string value) + #cafile= + + # Verify HTTPS connections. (boolean value) + #insecure=false + + # Directory used to cache files related to PKI tokens (string + # value) + #signing_dir= + + # If defined, the memcache server(s) to use for caching (list + # value) + # Deprecated group/name - [DEFAULT]/memcache_servers + #memcached_servers= + + # In order to prevent excessive requests and validations, the + # middleware uses an in-memory cache for the tokens the + # Keystone API returns. This is only valid if memcache_servers + # is defined. Set to -1 to disable caching completely. + # (integer value) + #token_cache_time=300 + + # Value only used for unit testing (integer value) + #revocation_cache_time=1 + + # (optional) if defined, indicate whether token data should be + # authenticated or authenticated and encrypted. Acceptable + # values are MAC or ENCRYPT. If MAC, token data is + # authenticated (with HMAC) in the cache. If ENCRYPT, token + # data is encrypted and authenticated in the cache. If the + # value is not one of these options or empty, auth_token will + # raise an exception on initialization. (string value) + #memcache_security_strategy= + + # (optional, mandatory if memcache_security_strategy is + # defined) this string is used for key derivation. (string + # value) + #memcache_secret_key= + + # (optional) indicate whether to set the X-Service-Catalog + # header. If False, middleware will not ask for service + # catalog on token validation and will not set the X-Service- + # Catalog header. (boolean value) + #include_service_catalog=true + + # Used to control the use and type of token binding. Can be + # set to: "disabled" to not check token binding. "permissive" + # (default) to validate binding information if the bind type + # is of a form known to the server and ignore it if not. + # "strict" like "permissive" but if the bind type is unknown + # the token will be rejected. "required" any form of token + # binding is needed to be allowed. Finally the name of a + # binding method that must be present in tokens. (string + # value) + #enforce_token_bind=permissive For services which have a separate paste-deploy ini file, auth_token middleware can be alternatively configured in [keystone_authtoken] section in the main @@ -162,6 +261,7 @@ and set in nova.conf:: admin_user = admin admin_password = SuperSekretPassword admin_tenant_name = service + # Any of the options that could be set in api-paste.ini can be set here. Note that middleware parameters in paste config take priority, they must be removed to use values in [keystone_authtoken] section. From e7c5a51f746ca82db4801ec7875c8279f62d6ca8 Mon Sep 17 00:00:00 2001 From: Rodrigo Duarte Sousa Date: Mon, 2 Jun 2014 18:02:21 -0300 Subject: [PATCH 37/40] Add role assignments as concept in Client API V3 docs Change-Id: Ia04e51d98b5f00a28d94c24ed7665fcead3f6507 Closes-Bug: #1325739 --- source/using-api-v3.rst | 1 + 1 file changed, 1 insertion(+) diff --git a/source/using-api-v3.rst b/source/using-api-v3.rst index a842f634..bf2c727c 100644 --- a/source/using-api-v3.rst +++ b/source/using-api-v3.rst @@ -13,6 +13,7 @@ The main concepts in the Identity v3 API are: * groups * policies * projects + * role assignments * roles * services * trusts From 24e644aae3fb68a074e6062d879d04b9b901f180 Mon Sep 17 00:00:00 2001 From: Brant Knudson Date: Thu, 12 Jun 2014 14:30:07 -0500 Subject: [PATCH 38/40] Link to docstrings in using-api-v3 The references to classes and modules were just the names and didn't link to the docstrings for the class or module. With this change, names are now links to the class or module. Change-Id: I9c7c03e8221ca71c7fddc0682abadc7a78d371db --- source/using-api-v3.rst | 18 ++++++++++-------- 1 file changed, 10 insertions(+), 8 deletions(-) diff --git a/source/using-api-v3.rst b/source/using-api-v3.rst index bf2c727c..814f16f2 100644 --- a/source/using-api-v3.rst +++ b/source/using-api-v3.rst @@ -19,13 +19,13 @@ The main concepts in the Identity v3 API are: * trusts * users -The ``keystoneclient.v3.client`` API lets you query and make changes +The :py:mod:`keystoneclient.v3.client` API lets you query and make changes through ``managers``. For example, to manipulate a project (formerly called tenant), you interact with a -``keystoneclient.v3.projects.ProjectManager`` object. +:py:class:`keystoneclient.v3.projects.ProjectManager` object. You obtain access to managers through attributes of a -``keystoneclient.v3.client.Client`` object. For example, the +:py:class:`keystoneclient.v3.client.Client` object. For example, the ``projects`` attribute of a ``Client`` object is a projects manager:: >>> from keystoneclient.v3 import client @@ -33,10 +33,11 @@ You obtain access to managers through attributes of a >>> keystone.projects.list() # List projects While it is possible to instantiate a -``keystoneclient.v3.client.Client`` object (as done above for +:py:class:`keystoneclient.v3.client.Client` object (as done above for clarity), the recommended approach is to use the discovery mechanism -provided by the ``keystone.client.Client`` class. The appropriate -class will be instantiated depending on the API versions available:: +provided by the :py:class:`keystoneclient.client.Client` class. The +appropriate class will be instantiated depending on the API versions +available:: >>> from keystoneclient import client >>> keystone = @@ -70,13 +71,14 @@ as the auth_url keyword argument:: >>> type(keystone) -Upon successful authentication, a ``keystoneclient.v3.client.Client`` +Upon successful authentication, a :py:class:`keystoneclient.v3.client.Client` object is returned (when using the Identity v3 API). Authentication and examples of common tasks are provided below. You can generally expect that when the client needs to propagate an exception it will raise an instance of subclass of -``keystoneclient.exceptions.ClientException`` +``keystoneclient.exceptions.ClientException`` (see +:py:class:`keystoneclient.openstack.common.apiclient.exceptions.ClientException`) Authenticating ============== From 83882a8575cb6cc0f09f171e7441e561a023b1e1 Mon Sep 17 00:00:00 2001 From: Jamie Lennox Date: Mon, 31 Mar 2014 15:16:53 +1000 Subject: [PATCH 39/40] Session Documentation Include some client documentation for how to work with a Session object. This is generally high level with this expectation that a developer could take the concepts found here and determine more from the module documentation. Change-Id: I5e44c1029ce160cb2798cfb8a535aa9f3311799a --- source/index.rst | 1 + source/using-sessions.rst | 198 ++++++++++++++++++++++++++++++++++++++ 2 files changed, 199 insertions(+) create mode 100644 source/using-sessions.rst diff --git a/source/index.rst b/source/index.rst index bb53cb0c..53224629 100644 --- a/source/index.rst +++ b/source/index.rst @@ -12,6 +12,7 @@ Contents: :maxdepth: 1 man/keystone + using-sessions using-api-v2 using-api-v3 diff --git a/source/using-sessions.rst b/source/using-sessions.rst new file mode 100644 index 00000000..099dc701 --- /dev/null +++ b/source/using-sessions.rst @@ -0,0 +1,198 @@ +============== +Using Sessions +============== + +Introduction +============ + +The :py:class:`keystoneclient.session.Session` class was introduced into +keystoneclient as an attempt to bring a unified interface to the various +OpenStack clients that share common authentication and request parameters +between a variety of services. + +The model for using a Session and auth plugin as well as the general terms used +have been heavily inspired by the `requests `_ +library. However neither the Session class nor any of the authentication +plugins rely directly on those concepts from the requests library so you should +not expect a direct translation. + +Features +-------- + +- Common client authentication + + Authentication is handled by one of a variety of authentication plugins and + then this authentication information is shared between all the services that + use the same Session object. + +- Security maintenance + + Security code is maintained in a single place and reused between all + clients such that in the event of problems it can be fixed in a single + location. + +- Standard discovery mechanisms + + Clients are not expected to have any knowledge of an identity token or any + other form of identification credential. Service and endpoint discovery are + handled by the Session and plugins. + + +Sessions for Users +================== + +The Session object is the contact point to your OpenStack cloud services. It +stores the authentication credentials and connection information required to +communicate with OpenStack such that it can be reused to communicate with many +services. When creating services this Session object is passed to the client +so that it may use this information. + +A Session will authenticate on demand. When a request that requires +authentication passes through the Session the authentication plugin will be +asked for a valid token. If a valid token is available it will be used +otherwise the authentication plugin may attempt to contact the authentication +service and fetch a new one. + +An example from keystoneclient:: + + >>> from keystoneclient.auth.identity import v3 + >>> from keystoneclient import session + >>> from keystoneclient.v3 import client + + >>> auth = v3.Password(auth_url='https://my.keystone.com:5000/v2.0', + ... username='myuser', + ... password='mypassword', + ... project_id='proj') + >>> sess = session.Session(auth=auth, + ... verify='/path/to/ca.cert') + >>> ks = client.Client(session=sess) + >>> users = ks.users.list() + +As clients adopt this means of operating they will be created in a similar +fashion by passing the Session object to the client's constructor. + + +Migrating keystoneclient to use a Session +----------------------------------------- + +By using a session with a keystonclient Client we define that you have opted in +to new behaviour defined by the session. For example authentication is now +on-demand rather than on creation. To allow this change in behaviour there are +a number of functions that have changed behaviour or are no longer available. + +For example the +:py:meth:`keystoneclient.httpclient.HTTPClient.authenticate` command used +to be able to always re-authenticate the current client and fetch a new token. +As this is now controlled by the Session and not the client this has changed, +however the function will still exist to provide compatibility with older +clients. + +Likewise certain parameters such as ``user_id`` and ``auth_token`` that used to +be available on the client object post authentication will remain +uninitialized. + +When converting an application to use a session object with keystoneclient you +should be aware of the possibility of changes to authentication and +authentication parameters and make sure to test your code thoroughly. It should +have no impact on the typical CRUD interaction with the client. + + +Sharing Authentication Plugins +------------------------------ + +A session can only contain one authentication plugin however there is nothing +that specifically binds the authentication plugin to that session, a new +Session can be created that reuses the existing authentication plugin:: + + >>> new_sess = session.Session(auth=sess.auth, + verify='/path/to/different-cas.cert') + +In this case we cannot know which session object will be used when the plugin +performs the authentication call so the command must be able to succeed with +either. + +Authentication plugins can also be provided on a per-request basis. This will +be beneficial in a situation where a single session is juggling multiple +authentication credentials:: + + >>> sess.get('https://my.keystone.com:5000/v3', + auth=my_auth_plugin) + +If an auth plugin is provided via parameter then it will override any auth +plugin on the session. + +Sessions for Client Developers +============================== + +Sessions are intended to take away much of the hassle of dealing with +authentication data and token formats. Clients should be able to specify filter +parameters for selecting the endpoint and have the parsing of the catalog +managed for them. + +Authentication +-------------- + +When making a request with a session object you can simply pass the keyword +parameter ``authenticated`` to indicate whether the argument should contain a +token, by default a token is included if an authentication plugin is available:: + + >>> # In keystone this route is unprotected by default + >>> resp = sess.get('https://my.keystone.com:5000/v3', + authenticated=False) + + +Service Discovery +----------------- + +In OpenStack the URLs of available services are distributed to the user as a +part of the token they receive called the Service Catalog. Clients are expected +to use the URLs from the Service Catalog rather than have them provided. + +In general a client does not need to know the full URL for the server that they +are communicating with, simply that it should send a request to a path +belonging to the correct service. + +This is controlled by the ``endpoint_filter`` parameter to a request which +contains all the information an authentication plugin requires to determine the +correct URL to which to send a request. When using this mode only the path for +the request needs to be specified:: + + >>> resp = session.get('/v3/users', + endpoint_filter={'service_type': 'identity', + 'interface': 'public', + 'region_name': 'myregion'}) + +``endpoint_filter`` accepts a number of arguments with which it can determine +an endpoint url: + +- ``service_type``: the type of service. For example ``identity``, ``compute``, + ``volume`` or many other predefined identifiers. + +- ``interface``: the network exposure the interface has. This will be one of: + + - ``public``: An endpoint that is available to the wider internet or network. + - ``internal``: An endpoint that is only accessible within the private network. + - ``admin``: An endpoint to be used for administrative tasks. + +- ``region_name``: the name of the region where the endpoint resides. + +The endpoint filter is a simple key-value filter and can be provided with any +number of arguments. It is then up to the auth plugin to correctly use the +parameters it understands. + +The session object determines the URL matching the filter and append to it the +provided path and so create a valid request. If multiple URL matches are found +then any one may be chosen. + +While authentication plugins will endeavour to maintain a consistent set of +arguments for an ``endpoint_filter`` the concept of an authentication plugin is +purposefully generic and a specific mechanism may not know how to interpret +certain arguments and ignore them. For example the +:py:class:`keystoneclient.auth.token_endpoint.Token` plugin (which is used when +you want to always use a specific endpoint and token combination) will always +return the same endpoint regardless of the parameters to ``endpoint_filter`` or +a custom OpenStack authentication mechanism may not have the concept of +multiple ``interface`` options and choose to ignore that parameter. + +There is some expectation on the user that they understand the limitations of +the authentication system they are using. From 46e9c2dfa4e1accd02eeea7eff791c4201873900 Mon Sep 17 00:00:00 2001 From: Morgan Fainberg Date: Thu, 19 Jun 2014 18:09:27 -0700 Subject: [PATCH 40/40] Move Docs to the right location --- .gitignore => docs/.gitignore | 0 Makefile => docs/Makefile | 0 {ext => docs/ext}/__init__.py | 0 {ext => docs/ext}/apidoc.py | 0 {source => docs/source}/_templates/.placeholder | 0 {source => docs/source}/_theme/layout.html | 0 {source => docs/source}/_theme/theme.conf | 0 {source => docs/source}/conf.py | 0 {source => docs/source}/images/graphs_authComp.svg | 0 .../source}/images/graphs_authCompDelegate.svg | 0 {source => docs/source}/index.rst | 0 {source => docs/source}/man/keystone.rst | 0 {source => docs/source}/middlewarearchitecture.rst | 0 {source => docs/source}/static/basic.css | 0 {source => docs/source}/static/default.css | 0 {source => docs/source}/static/header-line.gif | Bin {source => docs/source}/static/header_bg.jpg | Bin {source => docs/source}/static/jquery.tweet.js | 0 {source => docs/source}/static/nature.css | 0 {source => docs/source}/static/openstack_logo.png | Bin {source => docs/source}/static/tweaks.css | 0 {source => docs/source}/using-api-v2.rst | 0 {source => docs/source}/using-api-v3.rst | 0 {source => docs/source}/using-sessions.rst | 0 24 files changed, 0 insertions(+), 0 deletions(-) rename .gitignore => docs/.gitignore (100%) rename Makefile => docs/Makefile (100%) rename {ext => docs/ext}/__init__.py (100%) rename {ext => docs/ext}/apidoc.py (100%) rename {source => docs/source}/_templates/.placeholder (100%) rename {source => docs/source}/_theme/layout.html (100%) rename {source => docs/source}/_theme/theme.conf (100%) rename {source => docs/source}/conf.py (100%) rename {source => docs/source}/images/graphs_authComp.svg (100%) rename {source => docs/source}/images/graphs_authCompDelegate.svg (100%) rename {source => docs/source}/index.rst (100%) rename {source => docs/source}/man/keystone.rst (100%) rename {source => docs/source}/middlewarearchitecture.rst (100%) rename {source => docs/source}/static/basic.css (100%) rename {source => docs/source}/static/default.css (100%) rename {source => docs/source}/static/header-line.gif (100%) rename {source => docs/source}/static/header_bg.jpg (100%) rename {source => docs/source}/static/jquery.tweet.js (100%) rename {source => docs/source}/static/nature.css (100%) rename {source => docs/source}/static/openstack_logo.png (100%) rename {source => docs/source}/static/tweaks.css (100%) rename {source => docs/source}/using-api-v2.rst (100%) rename {source => docs/source}/using-api-v3.rst (100%) rename {source => docs/source}/using-sessions.rst (100%) diff --git a/.gitignore b/docs/.gitignore similarity index 100% rename from .gitignore rename to docs/.gitignore diff --git a/Makefile b/docs/Makefile similarity index 100% rename from Makefile rename to docs/Makefile diff --git a/ext/__init__.py b/docs/ext/__init__.py similarity index 100% rename from ext/__init__.py rename to docs/ext/__init__.py diff --git a/ext/apidoc.py b/docs/ext/apidoc.py similarity index 100% rename from ext/apidoc.py rename to docs/ext/apidoc.py diff --git a/source/_templates/.placeholder b/docs/source/_templates/.placeholder similarity index 100% rename from source/_templates/.placeholder rename to docs/source/_templates/.placeholder diff --git a/source/_theme/layout.html b/docs/source/_theme/layout.html similarity index 100% rename from source/_theme/layout.html rename to docs/source/_theme/layout.html diff --git a/source/_theme/theme.conf b/docs/source/_theme/theme.conf similarity index 100% rename from source/_theme/theme.conf rename to docs/source/_theme/theme.conf diff --git a/source/conf.py b/docs/source/conf.py similarity index 100% rename from source/conf.py rename to docs/source/conf.py diff --git a/source/images/graphs_authComp.svg b/docs/source/images/graphs_authComp.svg similarity index 100% rename from source/images/graphs_authComp.svg rename to docs/source/images/graphs_authComp.svg diff --git a/source/images/graphs_authCompDelegate.svg b/docs/source/images/graphs_authCompDelegate.svg similarity index 100% rename from source/images/graphs_authCompDelegate.svg rename to docs/source/images/graphs_authCompDelegate.svg diff --git a/source/index.rst b/docs/source/index.rst similarity index 100% rename from source/index.rst rename to docs/source/index.rst diff --git a/source/man/keystone.rst b/docs/source/man/keystone.rst similarity index 100% rename from source/man/keystone.rst rename to docs/source/man/keystone.rst diff --git a/source/middlewarearchitecture.rst b/docs/source/middlewarearchitecture.rst similarity index 100% rename from source/middlewarearchitecture.rst rename to docs/source/middlewarearchitecture.rst diff --git a/source/static/basic.css b/docs/source/static/basic.css similarity index 100% rename from source/static/basic.css rename to docs/source/static/basic.css diff --git a/source/static/default.css b/docs/source/static/default.css similarity index 100% rename from source/static/default.css rename to docs/source/static/default.css diff --git a/source/static/header-line.gif b/docs/source/static/header-line.gif similarity index 100% rename from source/static/header-line.gif rename to docs/source/static/header-line.gif diff --git a/source/static/header_bg.jpg b/docs/source/static/header_bg.jpg similarity index 100% rename from source/static/header_bg.jpg rename to docs/source/static/header_bg.jpg diff --git a/source/static/jquery.tweet.js b/docs/source/static/jquery.tweet.js similarity index 100% rename from source/static/jquery.tweet.js rename to docs/source/static/jquery.tweet.js diff --git a/source/static/nature.css b/docs/source/static/nature.css similarity index 100% rename from source/static/nature.css rename to docs/source/static/nature.css diff --git a/source/static/openstack_logo.png b/docs/source/static/openstack_logo.png similarity index 100% rename from source/static/openstack_logo.png rename to docs/source/static/openstack_logo.png diff --git a/source/static/tweaks.css b/docs/source/static/tweaks.css similarity index 100% rename from source/static/tweaks.css rename to docs/source/static/tweaks.css diff --git a/source/using-api-v2.rst b/docs/source/using-api-v2.rst similarity index 100% rename from source/using-api-v2.rst rename to docs/source/using-api-v2.rst diff --git a/source/using-api-v3.rst b/docs/source/using-api-v3.rst similarity index 100% rename from source/using-api-v3.rst rename to docs/source/using-api-v3.rst diff --git a/source/using-sessions.rst b/docs/source/using-sessions.rst similarity index 100% rename from source/using-sessions.rst rename to docs/source/using-sessions.rst