From ef9f0392a3614439ab5b3c9d4a79f9516f1880e5 Mon Sep 17 00:00:00 2001 From: termie Date: Wed, 19 Oct 2011 12:19:32 +0300 Subject: move diagram into docs dir --- docs/keystone_compat_flows.sdx | 99 ++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 99 insertions(+) create mode 100644 docs/keystone_compat_flows.sdx (limited to 'docs') diff --git a/docs/keystone_compat_flows.sdx b/docs/keystone_compat_flows.sdx new file mode 100644 index 00000000..f1fcc5f0 --- /dev/null +++ b/docs/keystone_compat_flows.sdx @@ -0,0 +1,99 @@ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + -- cgit From a84930a8265b8e917e75fe4814be706721596253 Mon Sep 17 00:00:00 2001 From: termie Date: Mon, 9 Jan 2012 13:25:20 -0800 Subject: add basic sphinx doc bits --- docs/Makefile | 158 +++++++++++++ docs/source/conf.py | 247 +++++++++++++++++++++ docs/source/index.rst | 22 ++ docs/source/keystone.backends.rst | 42 ++++ docs/source/keystone.backends.sql.migrate_repo.rst | 18 ++ ...keystone.backends.sql.migrate_repo.versions.rst | 11 + docs/source/keystone.backends.sql.rst | 42 ++++ docs/source/keystone.rst | 130 +++++++++++ docs/source/modules.rst | 9 + 9 files changed, 679 insertions(+) create mode 100644 docs/Makefile create mode 100644 docs/source/conf.py create mode 100644 docs/source/index.rst create mode 100644 docs/source/keystone.backends.rst create mode 100644 docs/source/keystone.backends.sql.migrate_repo.rst create mode 100644 docs/source/keystone.backends.sql.migrate_repo.versions.rst create mode 100644 docs/source/keystone.backends.sql.rst create mode 100644 docs/source/keystone.rst create mode 100644 docs/source/modules.rst (limited to 'docs') diff --git a/docs/Makefile b/docs/Makefile new file mode 100644 index 00000000..5083ea0d --- /dev/null +++ b/docs/Makefile @@ -0,0 +1,158 @@ +# Makefile for Sphinx documentation +# + +# You can set these variables from the command line. +SPHINXOPTS = +SPHINXBUILD = sphinx-build +PAPER = +BUILDDIR = build +SOURCEDIR = source +SPHINXAPIDOC = sphinx-apidoc + +# Internal variables. +PAPEROPT_a4 = -D latex_paper_size=a4 +PAPEROPT_letter = -D latex_paper_size=letter +ALLSPHINXOPTS = -d $(BUILDDIR)/doctrees $(PAPEROPT_$(PAPER)) $(SPHINXOPTS) source +# the i18n builder cannot share the environment and doctrees with the others +I18NSPHINXOPTS = $(PAPEROPT_$(PAPER)) $(SPHINXOPTS) source + +.PHONY: help clean html dirhtml singlehtml pickle json htmlhelp qthelp devhelp epub latex latexpdf text man changes linkcheck doctest gettext + +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 " singlehtml to make a single large HTML file" + @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 " devhelp to make HTML files and a Devhelp project" + @echo " epub to make an epub" + @echo " latex to make LaTeX files, you can set PAPER=a4 or PAPER=letter" + @echo " latexpdf to make LaTeX files and run them through pdflatex" + @echo " text to make text files" + @echo " man to make manual pages" + @echo " texinfo to make Texinfo files" + @echo " info to make Texinfo files and run them through makeinfo" + @echo " gettext to make PO message catalogs" + @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)/* + +apidoc: + $(SPHINXAPIDOC) -o $(SOURCEDIR) ../keystone + +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." + +singlehtml: + $(SPHINXBUILD) -b singlehtml $(ALLSPHINXOPTS) $(BUILDDIR)/singlehtml + @echo + @echo "Build finished. The HTML page is in $(BUILDDIR)/singlehtml." + +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/keystone.qhcp" + @echo "To view the help file:" + @echo "# assistant -collectionFile $(BUILDDIR)/qthelp/keystone.qhc" + +devhelp: + $(SPHINXBUILD) -b devhelp $(ALLSPHINXOPTS) $(BUILDDIR)/devhelp + @echo + @echo "Build finished." + @echo "To view the help file:" + @echo "# mkdir -p $$HOME/.local/share/devhelp/keystone" + @echo "# ln -s $(BUILDDIR)/devhelp $$HOME/.local/share/devhelp/keystone" + @echo "# devhelp" + +epub: + $(SPHINXBUILD) -b epub $(ALLSPHINXOPTS) $(BUILDDIR)/epub + @echo + @echo "Build finished. The epub file is in $(BUILDDIR)/epub." + +latex: + $(SPHINXBUILD) -b latex $(ALLSPHINXOPTS) $(BUILDDIR)/latex + @echo + @echo "Build finished; the LaTeX files are in $(BUILDDIR)/latex." + @echo "Run \`make' in that directory to run these through (pdf)latex" \ + "(use \`make latexpdf' here to do that automatically)." + +latexpdf: + $(SPHINXBUILD) -b latex $(ALLSPHINXOPTS) $(BUILDDIR)/latex + @echo "Running LaTeX files through pdflatex..." + $(MAKE) -C $(BUILDDIR)/latex all-pdf + @echo "pdflatex finished; the PDF files are in $(BUILDDIR)/latex." + +text: + $(SPHINXBUILD) -b text $(ALLSPHINXOPTS) $(BUILDDIR)/text + @echo + @echo "Build finished. The text files are in $(BUILDDIR)/text." + +man: + $(SPHINXBUILD) -b man $(ALLSPHINXOPTS) $(BUILDDIR)/man + @echo + @echo "Build finished. The manual pages are in $(BUILDDIR)/man." + +texinfo: + $(SPHINXBUILD) -b texinfo $(ALLSPHINXOPTS) $(BUILDDIR)/texinfo + @echo + @echo "Build finished. The Texinfo files are in $(BUILDDIR)/texinfo." + @echo "Run \`make' in that directory to run these through makeinfo" \ + "(use \`make info' here to do that automatically)." + +info: + $(SPHINXBUILD) -b texinfo $(ALLSPHINXOPTS) $(BUILDDIR)/texinfo + @echo "Running Texinfo files through makeinfo..." + make -C $(BUILDDIR)/texinfo info + @echo "makeinfo finished; the Info files are in $(BUILDDIR)/texinfo." + +gettext: + $(SPHINXBUILD) -b gettext $(I18NSPHINXOPTS) $(BUILDDIR)/locale + @echo + @echo "Build finished. The message catalogs are in $(BUILDDIR)/locale." + +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/docs/source/conf.py b/docs/source/conf.py new file mode 100644 index 00000000..1f7785ef --- /dev/null +++ b/docs/source/conf.py @@ -0,0 +1,247 @@ +# -*- coding: utf-8 -*- +# +# keystone documentation build configuration file, created by +# sphinx-quickstart on Mon Jan 9 12:02:59 2012. +# +# This file is execfile()d with the current directory set to its containing dir. +# +# Note that not all possible configuration values are present in this +# autogenerated file. +# +# All configuration values have a default; values that are commented out +# serve to show the default. + +import sys, os + +# If extensions (or modules to document with autodoc) are in another directory, +# add these directories to sys.path here. If the directory is relative to the +# documentation root, use os.path.abspath to make it absolute, like shown here. +sys.path.insert(0, os.path.abspath('..')) + +# -- General configuration ----------------------------------------------------- + +# If your documentation needs a minimal Sphinx version, state it here. +#needs_sphinx = '1.0' + +# Add any Sphinx extension module names here, as strings. They can be extensions +# coming with Sphinx (named 'sphinx.ext.*') or your custom ones. +#extensions = ['sphinx.ext.autodoc', 'sphinx.ext.intersphinx', 'sphinx.ext.todo', 'sphinx.ext.coverage'] +extensions = ['sphinx.ext.autodoc', 'sphinx.ext.todo', 'sphinx.ext.coverage'] + +# 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-sig' + +# The master toctree document. +master_doc = 'index' + +# General information about the project. +project = u'keystone' +copyright = u'2012, termie' + +# The version info for the project you're documenting, acts as replacement for +# |version| and |release|, also used in various other places throughout the +# built documents. +# +# The short X.Y version. +version = '2012.1' +# The full version, including alpha/beta/rc tags. +release = '2012.1-dev' + +# The language for content autogenerated by Sphinx. Refer to documentation +# for a list of supported languages. +#language = None + +# There are two options for replacing |today|: either, you set today to some +# non-false value, then it is used: +#today = '' +# Else, today_fmt is used as the format for a strftime call. +#today_fmt = '%B %d, %Y' + +# List of patterns, relative to source directory, that match files and +# directories to ignore when looking for source files. +exclude_patterns = [] + +# The reST default role (used for this markup: `text`) to use for all documents. +#default_role = None + +# If true, '()' will be appended to :func: etc. cross-reference text. +#add_function_parentheses = True + +# If true, the current module name will be prepended to all description +# unit titles (such as .. function::). +#add_module_names = True + +# If true, sectionauthor and moduleauthor directives will be shown in the +# output. They are ignored by default. +#show_authors = 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. See the documentation for +# a list of builtin themes. +html_theme = 'default' + +# 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_domain_indices = True + +# If false, no index is generated. +#html_use_index = True + +# If true, the index is split into individual pages for each letter. +#html_split_index = False + +# If true, links to the reST sources are added to the pages. +#html_show_sourcelink = True + +# If true, "Created using Sphinx" is shown in the HTML footer. Default is True. +#html_show_sphinx = True + +# If true, "(C) Copyright ..." is shown in the HTML footer. Default is True. +#html_show_copyright = True + +# If true, an OpenSearch description file will be output, and all pages will +# contain a tag referring to it. The value of this option must be the +# base URL from which the finished HTML is served. +#html_use_opensearch = '' + +# This is the file name suffix for HTML files (e.g. ".xhtml"). +#html_file_suffix = None + +# Output file base name for HTML help builder. +htmlhelp_basename = 'keystonedoc' + + +# -- Options for LaTeX output -------------------------------------------------- + +latex_elements = { +# The paper size ('letterpaper' or 'a4paper'). +#'papersize': 'letterpaper', + +# The font size ('10pt', '11pt' or '12pt'). +#'pointsize': '10pt', + +# Additional stuff for the LaTeX preamble. +#'preamble': '', +} + +# Grouping the document tree into LaTeX files. List of tuples +# (source start file, target name, title, author, documentclass [howto/manual]). +latex_documents = [ + ('index', 'keystone.tex', u'keystone Documentation', + u'termie', 'manual'), +] + +# The name of an image file (relative to this directory) to place at the top of +# the title page. +#latex_logo = None + +# For "manual" documents, if this is true, then toplevel headings are parts, +# not chapters. +#latex_use_parts = False + +# If true, show page references after internal links. +#latex_show_pagerefs = False + +# If true, show URL addresses after external links. +#latex_show_urls = False + +# Documents to append as an appendix to all manuals. +#latex_appendices = [] + +# If false, no module index is generated. +#latex_domain_indices = True + + +# -- Options for manual page output -------------------------------------------- + +# One entry per manual page. List of tuples +# (source start file, name, description, authors, manual section). +man_pages = [ + ('index', 'keystone', u'keystone Documentation', + [u'termie'], 1) +] + +# If true, show URL addresses after external links. +#man_show_urls = False + + +# -- Options for Texinfo output ------------------------------------------------ + +# Grouping the document tree into Texinfo files. List of tuples +# (source start file, target name, title, author, +# dir menu entry, description, category) +texinfo_documents = [ + ('index', 'keystone', u'keystone Documentation', + u'termie', 'keystone', 'One line description of project.', + 'Miscellaneous'), +] + +# Documents to append as an appendix to all manuals. +#texinfo_appendices = [] + +# If false, no module index is generated. +#texinfo_domain_indices = True + +# How to display URL addresses: 'footnote', 'no', or 'inline'. +#texinfo_show_urls = 'footnote' + + +# Example configuration for intersphinx: refer to the Python standard library. +#intersphinx_mapping = {'http://docs.python.org/': None} diff --git a/docs/source/index.rst b/docs/source/index.rst new file mode 100644 index 00000000..cd7c96a8 --- /dev/null +++ b/docs/source/index.rst @@ -0,0 +1,22 @@ +.. keystone documentation master file, created by + sphinx-quickstart on Mon Jan 9 12:02:59 2012. + You can adapt this file completely to your liking, but it should at least + contain the root `toctree` directive. + +Welcome to keystone's documentation! +==================================== + +Contents: + +.. toctree:: + :maxdepth: 2 + + + +Indices and tables +================== + +* :ref:`genindex` +* :ref:`modindex` +* :ref:`search` + diff --git a/docs/source/keystone.backends.rst b/docs/source/keystone.backends.rst new file mode 100644 index 00000000..8641ad9e --- /dev/null +++ b/docs/source/keystone.backends.rst @@ -0,0 +1,42 @@ +backends Package +================ + +:mod:`kvs` Module +----------------- + +.. automodule:: keystone.backends.kvs + :members: + :undoc-members: + :show-inheritance: + +:mod:`pam` Module +----------------- + +.. automodule:: keystone.backends.pam + :members: + :undoc-members: + :show-inheritance: + +:mod:`policy` Module +-------------------- + +.. automodule:: keystone.backends.policy + :members: + :undoc-members: + :show-inheritance: + +:mod:`templated` Module +----------------------- + +.. automodule:: keystone.backends.templated + :members: + :undoc-members: + :show-inheritance: + +Subpackages +----------- + +.. toctree:: + + keystone.backends.sql + diff --git a/docs/source/keystone.backends.sql.migrate_repo.rst b/docs/source/keystone.backends.sql.migrate_repo.rst new file mode 100644 index 00000000..d47a101e --- /dev/null +++ b/docs/source/keystone.backends.sql.migrate_repo.rst @@ -0,0 +1,18 @@ +migrate_repo Package +==================== + +:mod:`manage` Module +-------------------- + +.. automodule:: keystone.backends.sql.migrate_repo.manage + :members: + :undoc-members: + :show-inheritance: + +Subpackages +----------- + +.. toctree:: + + keystone.backends.sql.migrate_repo.versions + diff --git a/docs/source/keystone.backends.sql.migrate_repo.versions.rst b/docs/source/keystone.backends.sql.migrate_repo.versions.rst new file mode 100644 index 00000000..85e1ce86 --- /dev/null +++ b/docs/source/keystone.backends.sql.migrate_repo.versions.rst @@ -0,0 +1,11 @@ +versions Package +================ + +:mod:`001_add_initial_tables` Module +------------------------------------ + +.. automodule:: keystone.backends.sql.migrate_repo.versions.001_add_initial_tables + :members: + :undoc-members: + :show-inheritance: + diff --git a/docs/source/keystone.backends.sql.rst b/docs/source/keystone.backends.sql.rst new file mode 100644 index 00000000..91c9f735 --- /dev/null +++ b/docs/source/keystone.backends.sql.rst @@ -0,0 +1,42 @@ +sql Package +=========== + +:mod:`sql` Package +------------------ + +.. automodule:: keystone.backends.sql + :members: + :undoc-members: + :show-inheritance: + +:mod:`core` Module +------------------ + +.. automodule:: keystone.backends.sql.core + :members: + :undoc-members: + :show-inheritance: + +:mod:`migration` Module +----------------------- + +.. automodule:: keystone.backends.sql.migration + :members: + :undoc-members: + :show-inheritance: + +:mod:`util` Module +------------------ + +.. automodule:: keystone.backends.sql.util + :members: + :undoc-members: + :show-inheritance: + +Subpackages +----------- + +.. toctree:: + + keystone.backends.sql.migrate_repo + diff --git a/docs/source/keystone.rst b/docs/source/keystone.rst new file mode 100644 index 00000000..d4737f06 --- /dev/null +++ b/docs/source/keystone.rst @@ -0,0 +1,130 @@ +keystone Package +================ + +:mod:`catalog` Module +--------------------- + +.. automodule:: keystone.catalog + :members: + :undoc-members: + :show-inheritance: + +:mod:`cfg` Module +----------------- + +.. automodule:: keystone.cfg + :members: + :undoc-members: + :show-inheritance: + +:mod:`client` Module +-------------------- + +.. automodule:: keystone.client + :members: + :undoc-members: + :show-inheritance: + +:mod:`config` Module +-------------------- + +.. automodule:: keystone.config + :members: + :undoc-members: + :show-inheritance: + +:mod:`identity` Module +---------------------- + +.. automodule:: keystone.identity + :members: + :undoc-members: + :show-inheritance: + +:mod:`keystone_compat` Module +----------------------------- + +.. automodule:: keystone.keystone_compat + :members: + :undoc-members: + :show-inheritance: + +:mod:`logging` Module +--------------------- + +.. automodule:: keystone.logging + :members: + :undoc-members: + :show-inheritance: + +:mod:`middleware` Module +------------------------ + +.. automodule:: keystone.middleware + :members: + :undoc-members: + :show-inheritance: + +:mod:`models` Module +-------------------- + +.. automodule:: keystone.models + :members: + :undoc-members: + :show-inheritance: + +:mod:`policy` Module +-------------------- + +.. automodule:: keystone.policy + :members: + :undoc-members: + :show-inheritance: + +:mod:`service` Module +--------------------- + +.. automodule:: keystone.service + :members: + :undoc-members: + :show-inheritance: + +:mod:`test` Module +------------------ + +.. automodule:: keystone.test + :members: + :undoc-members: + :show-inheritance: + +:mod:`token` Module +------------------- + +.. automodule:: keystone.token + :members: + :undoc-members: + :show-inheritance: + +:mod:`utils` Module +------------------- + +.. automodule:: keystone.utils + :members: + :undoc-members: + :show-inheritance: + +:mod:`wsgi` Module +------------------ + +.. automodule:: keystone.wsgi + :members: + :undoc-members: + :show-inheritance: + +Subpackages +----------- + +.. toctree:: + + keystone.backends + diff --git a/docs/source/modules.rst b/docs/source/modules.rst new file mode 100644 index 00000000..e071e108 --- /dev/null +++ b/docs/source/modules.rst @@ -0,0 +1,9 @@ +.. +== + +.. toctree:: + :maxdepth: 4 + + keystone + run_tests + setup -- cgit From 9d04ee987bff0bcf7587b632fdea86518c4adc9a Mon Sep 17 00:00:00 2001 From: termie Date: Tue, 17 Jan 2012 13:29:10 -0800 Subject: rename apidoc to autodoc --- docs/Makefile | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) (limited to 'docs') diff --git a/docs/Makefile b/docs/Makefile index 5083ea0d..e0366c85 100644 --- a/docs/Makefile +++ b/docs/Makefile @@ -20,6 +20,7 @@ I18NSPHINXOPTS = $(PAPEROPT_$(PAPER)) $(SPHINXOPTS) source help: @echo "Please use \`make ' where is one of" + @echo " autodoc generate the autodoc templates" @echo " html to make standalone HTML files" @echo " dirhtml to make HTML files named index.html in directories" @echo " singlehtml to make a single large HTML file" @@ -43,7 +44,7 @@ help: clean: -rm -rf $(BUILDDIR)/* -apidoc: +autodoc: $(SPHINXAPIDOC) -o $(SOURCEDIR) ../keystone html: -- cgit From e129d5f402255bd10e2bd2f8a80284b7b38ab749 Mon Sep 17 00:00:00 2001 From: termie Date: Wed, 18 Jan 2012 10:54:33 -0800 Subject: fix sphinx --- docs/Makefile | 2 +- docs/source/conf.py | 2 +- 2 files changed, 2 insertions(+), 2 deletions(-) (limited to 'docs') diff --git a/docs/Makefile b/docs/Makefile index e0366c85..03e3ef3b 100644 --- a/docs/Makefile +++ b/docs/Makefile @@ -45,7 +45,7 @@ clean: -rm -rf $(BUILDDIR)/* autodoc: - $(SPHINXAPIDOC) -o $(SOURCEDIR) ../keystone + $(SPHINXAPIDOC) -f -o $(SOURCEDIR) ../keystone html: $(SPHINXBUILD) -b html $(ALLSPHINXOPTS) $(BUILDDIR)/html diff --git a/docs/source/conf.py b/docs/source/conf.py index 1f7785ef..9c18c5ff 100644 --- a/docs/source/conf.py +++ b/docs/source/conf.py @@ -16,7 +16,7 @@ import sys, os # If extensions (or modules to document with autodoc) are in another directory, # add these directories to sys.path here. If the directory is relative to the # documentation root, use os.path.abspath to make it absolute, like shown here. -sys.path.insert(0, os.path.abspath('..')) +sys.path.insert(0, os.path.abspath('../..')) # -- General configuration ----------------------------------------------------- -- cgit From 94f78a3082efb7a73a8670701e9c037b7ffde581 Mon Sep 17 00:00:00 2001 From: termie Date: Wed, 18 Jan 2012 11:36:02 -0800 Subject: expect sphinx sources to be autogenned --- docs/source/keystone.backends.rst | 42 ------- docs/source/keystone.backends.sql.migrate_repo.rst | 18 --- ...keystone.backends.sql.migrate_repo.versions.rst | 11 -- docs/source/keystone.backends.sql.rst | 42 ------- docs/source/keystone.rst | 130 --------------------- docs/source/modules.rst | 9 -- 6 files changed, 252 deletions(-) delete mode 100644 docs/source/keystone.backends.rst delete mode 100644 docs/source/keystone.backends.sql.migrate_repo.rst delete mode 100644 docs/source/keystone.backends.sql.migrate_repo.versions.rst delete mode 100644 docs/source/keystone.backends.sql.rst delete mode 100644 docs/source/keystone.rst delete mode 100644 docs/source/modules.rst (limited to 'docs') diff --git a/docs/source/keystone.backends.rst b/docs/source/keystone.backends.rst deleted file mode 100644 index 8641ad9e..00000000 --- a/docs/source/keystone.backends.rst +++ /dev/null @@ -1,42 +0,0 @@ -backends Package -================ - -:mod:`kvs` Module ------------------ - -.. automodule:: keystone.backends.kvs - :members: - :undoc-members: - :show-inheritance: - -:mod:`pam` Module ------------------ - -.. automodule:: keystone.backends.pam - :members: - :undoc-members: - :show-inheritance: - -:mod:`policy` Module --------------------- - -.. automodule:: keystone.backends.policy - :members: - :undoc-members: - :show-inheritance: - -:mod:`templated` Module ------------------------ - -.. automodule:: keystone.backends.templated - :members: - :undoc-members: - :show-inheritance: - -Subpackages ------------ - -.. toctree:: - - keystone.backends.sql - diff --git a/docs/source/keystone.backends.sql.migrate_repo.rst b/docs/source/keystone.backends.sql.migrate_repo.rst deleted file mode 100644 index d47a101e..00000000 --- a/docs/source/keystone.backends.sql.migrate_repo.rst +++ /dev/null @@ -1,18 +0,0 @@ -migrate_repo Package -==================== - -:mod:`manage` Module --------------------- - -.. automodule:: keystone.backends.sql.migrate_repo.manage - :members: - :undoc-members: - :show-inheritance: - -Subpackages ------------ - -.. toctree:: - - keystone.backends.sql.migrate_repo.versions - diff --git a/docs/source/keystone.backends.sql.migrate_repo.versions.rst b/docs/source/keystone.backends.sql.migrate_repo.versions.rst deleted file mode 100644 index 85e1ce86..00000000 --- a/docs/source/keystone.backends.sql.migrate_repo.versions.rst +++ /dev/null @@ -1,11 +0,0 @@ -versions Package -================ - -:mod:`001_add_initial_tables` Module ------------------------------------- - -.. automodule:: keystone.backends.sql.migrate_repo.versions.001_add_initial_tables - :members: - :undoc-members: - :show-inheritance: - diff --git a/docs/source/keystone.backends.sql.rst b/docs/source/keystone.backends.sql.rst deleted file mode 100644 index 91c9f735..00000000 --- a/docs/source/keystone.backends.sql.rst +++ /dev/null @@ -1,42 +0,0 @@ -sql Package -=========== - -:mod:`sql` Package ------------------- - -.. automodule:: keystone.backends.sql - :members: - :undoc-members: - :show-inheritance: - -:mod:`core` Module ------------------- - -.. automodule:: keystone.backends.sql.core - :members: - :undoc-members: - :show-inheritance: - -:mod:`migration` Module ------------------------ - -.. automodule:: keystone.backends.sql.migration - :members: - :undoc-members: - :show-inheritance: - -:mod:`util` Module ------------------- - -.. automodule:: keystone.backends.sql.util - :members: - :undoc-members: - :show-inheritance: - -Subpackages ------------ - -.. toctree:: - - keystone.backends.sql.migrate_repo - diff --git a/docs/source/keystone.rst b/docs/source/keystone.rst deleted file mode 100644 index d4737f06..00000000 --- a/docs/source/keystone.rst +++ /dev/null @@ -1,130 +0,0 @@ -keystone Package -================ - -:mod:`catalog` Module ---------------------- - -.. automodule:: keystone.catalog - :members: - :undoc-members: - :show-inheritance: - -:mod:`cfg` Module ------------------ - -.. automodule:: keystone.cfg - :members: - :undoc-members: - :show-inheritance: - -:mod:`client` Module --------------------- - -.. automodule:: keystone.client - :members: - :undoc-members: - :show-inheritance: - -:mod:`config` Module --------------------- - -.. automodule:: keystone.config - :members: - :undoc-members: - :show-inheritance: - -:mod:`identity` Module ----------------------- - -.. automodule:: keystone.identity - :members: - :undoc-members: - :show-inheritance: - -:mod:`keystone_compat` Module ------------------------------ - -.. automodule:: keystone.keystone_compat - :members: - :undoc-members: - :show-inheritance: - -:mod:`logging` Module ---------------------- - -.. automodule:: keystone.logging - :members: - :undoc-members: - :show-inheritance: - -:mod:`middleware` Module ------------------------- - -.. automodule:: keystone.middleware - :members: - :undoc-members: - :show-inheritance: - -:mod:`models` Module --------------------- - -.. automodule:: keystone.models - :members: - :undoc-members: - :show-inheritance: - -:mod:`policy` Module --------------------- - -.. automodule:: keystone.policy - :members: - :undoc-members: - :show-inheritance: - -:mod:`service` Module ---------------------- - -.. automodule:: keystone.service - :members: - :undoc-members: - :show-inheritance: - -:mod:`test` Module ------------------- - -.. automodule:: keystone.test - :members: - :undoc-members: - :show-inheritance: - -:mod:`token` Module -------------------- - -.. automodule:: keystone.token - :members: - :undoc-members: - :show-inheritance: - -:mod:`utils` Module -------------------- - -.. automodule:: keystone.utils - :members: - :undoc-members: - :show-inheritance: - -:mod:`wsgi` Module ------------------- - -.. automodule:: keystone.wsgi - :members: - :undoc-members: - :show-inheritance: - -Subpackages ------------ - -.. toctree:: - - keystone.backends - diff --git a/docs/source/modules.rst b/docs/source/modules.rst deleted file mode 100644 index e071e108..00000000 --- a/docs/source/modules.rst +++ /dev/null @@ -1,9 +0,0 @@ -.. -== - -.. toctree:: - :maxdepth: 4 - - keystone - run_tests - setup -- cgit From ffeb0e558ca1108df02c53c9170e73020e57e67c Mon Sep 17 00:00:00 2001 From: Joe Heck Date: Thu, 19 Jan 2012 01:52:44 +0000 Subject: doctry --- docs/source/conf.py | 29 ++++++++++++++++++++++------- 1 file changed, 22 insertions(+), 7 deletions(-) (limited to 'docs') diff --git a/docs/source/conf.py b/docs/source/conf.py index 9c18c5ff..11c8adb0 100644 --- a/docs/source/conf.py +++ b/docs/source/conf.py @@ -11,7 +11,8 @@ # All configuration values have a default; values that are commented out # serve to show the default. -import sys, os +import sys +import os # If extensions (or modules to document with autodoc) are in another directory, # add these directories to sys.path here. If the directory is relative to the @@ -26,10 +27,19 @@ sys.path.insert(0, os.path.abspath('../..')) # Add any Sphinx extension module names here, as strings. They can be extensions # coming with Sphinx (named 'sphinx.ext.*') or your custom ones. #extensions = ['sphinx.ext.autodoc', 'sphinx.ext.intersphinx', 'sphinx.ext.todo', 'sphinx.ext.coverage'] -extensions = ['sphinx.ext.autodoc', 'sphinx.ext.todo', 'sphinx.ext.coverage'] +extensions = ['sphinx.ext.autodoc', + 'sphinx.ext.todo', +# 'sphinx.ect.intersphinx', + 'sphinx.ext.coverage'] + +todo_include_todos = True # Add any paths that contain templates here, relative to this directory. -templates_path = ['_templates'] +templates_path = [] +if os.getenv('HUDSON_PUBLISH_DOCS'): + templates_path = ['_ga', '_templates'] +else: + templates_path = ['_templates'] # The suffix of source filenames. source_suffix = '.rst' @@ -79,20 +89,21 @@ exclude_patterns = [] # If true, sectionauthor and moduleauthor directives will be shown in the # output. They are ignored by default. -#show_authors = False +show_authors = True # The name of the Pygments (syntax highlighting) style to use. pygments_style = 'sphinx' # A list of ignored prefixes for module index sorting. -#modindex_common_prefix = [] +modindex_common_prefix = ['keystone.'] # -- Options for HTML output --------------------------------------------------- # The theme to use for HTML and HTML Help pages. See the documentation for # a list of builtin themes. -html_theme = 'default' +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 @@ -121,7 +132,7 @@ html_theme = 'default' # 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', 'images'] # If not '', a 'Last updated on:' timestamp is inserted at every page bottom, # using the given strftime format. @@ -245,3 +256,7 @@ texinfo_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)} -- cgit From f40198dece0b3729e6eb70abaa972bd73ee827da Mon Sep 17 00:00:00 2001 From: Joe Heck Date: Thu, 19 Jan 2012 17:30:27 -0800 Subject: shimming in basics from original keystone --- docs/generate_autodoc_index.py | 76 +++++++ docs/source/_static/basic.css | 416 ++++++++++++++++++++++++++++++++++++ docs/source/_static/default.css | 230 ++++++++++++++++++++ docs/source/_static/jquery.tweet.js | 154 +++++++++++++ docs/source/_static/tweaks.css | 65 ++++++ docs/source/_templates/.placeholder | 0 docs/source/_theme/layout.html | 86 ++++++++ docs/source/_theme/theme.conf | 5 + docs/source/community.rst | 93 ++++++++ docs/source/conf.py | 12 ++ docs/source/developing.rst | 135 ++++++++++++ docs/source/index.rst | 58 ++++- docs/source/man/keystone-manage.rst | 192 +++++++++++++++++ docs/source/man/keystone.rst | 90 ++++++++ docs/source/setup.rst | 151 +++++++++++++ docs/source/testing.rst | 77 +++++++ 16 files changed, 1832 insertions(+), 8 deletions(-) create mode 100755 docs/generate_autodoc_index.py create mode 100644 docs/source/_static/basic.css create mode 100644 docs/source/_static/default.css create mode 100644 docs/source/_static/jquery.tweet.js create mode 100644 docs/source/_static/tweaks.css create mode 100644 docs/source/_templates/.placeholder create mode 100644 docs/source/_theme/layout.html create mode 100644 docs/source/_theme/theme.conf create mode 100644 docs/source/community.rst create mode 100644 docs/source/developing.rst create mode 100644 docs/source/man/keystone-manage.rst create mode 100644 docs/source/man/keystone.rst create mode 100644 docs/source/setup.rst create mode 100644 docs/source/testing.rst (limited to 'docs') diff --git a/docs/generate_autodoc_index.py b/docs/generate_autodoc_index.py new file mode 100755 index 00000000..993369b0 --- /dev/null +++ b/docs/generate_autodoc_index.py @@ -0,0 +1,76 @@ +#!/usr/bin/env python +"""Generates files for sphinx documentation using a simple Autodoc based +template. + +To use, just run as a script: + $ python doc/generate_autodoc_index.py +""" + +import os + + +base_dir = os.path.dirname(os.path.abspath(__file__)) +RSTDIR=os.path.join(base_dir, "source", "sourcecode") +SOURCEDIR=os.path.join(base_dir, "..") + +# Exclude these modules from the autodoc results +EXCLUDE_MODULES = ['keystone.backends.sqlalchemy.migrate_repo'] + +def in_exclude_list(module_name): + """Compares a module to the list of excluded modules + + Returns true if the provided module resides in or matches + an excluded module, false otherwise. + """ + for excluded_module in EXCLUDE_MODULES: + if module_name.startswith(excluded_module): + return True + return False + +def find_autodoc_modules(module_name, sourcedir): + """returns a list of modules in the SOURCE directory""" + modlist = [] + os.chdir(os.path.join(sourcedir, module_name)) + for root, dirs, files in os.walk("."): + for filename in files: + if filename.endswith(".py"): + # root = ./keystone/test/unit + # filename = base.py + elements = root.split(os.path.sep) + # replace the leading "." with the module name + elements[0] = module_name + # and get the base module name + base, extension = os.path.splitext(filename) + if not (base == "__init__"): + elements.append(base) + result = (".".join(elements)) + if not in_exclude_list(result): + modlist.append(result) + return modlist + +if not(os.path.exists(RSTDIR)): + os.mkdir(RSTDIR) + +INDEXOUT = open("%s/autoindex.rst" % RSTDIR, "w") +INDEXOUT.write("Source Code Index\n") +INDEXOUT.write("=================\n") +INDEXOUT.write(".. toctree::\n") +INDEXOUT.write(" :maxdepth: 1\n") +INDEXOUT.write("\n") + +for module in find_autodoc_modules('keystone', SOURCEDIR): + generated_file = "%s/%s.rst" % (RSTDIR, module) + + INDEXOUT.write(" %s\n" % module) + FILEOUT = open(generated_file, "w") + FILEOUT.write("The :mod:`%s` Module\n" % module) + FILEOUT.write("==============================" + "==============================" + "==============================\n") + FILEOUT.write(".. automodule:: %s\n" % module) + FILEOUT.write(" :members:\n") + FILEOUT.write(" :undoc-members:\n") + FILEOUT.write(" :show-inheritance:\n") + FILEOUT.close() + +INDEXOUT.close() diff --git a/docs/source/_static/basic.css b/docs/source/_static/basic.css new file mode 100644 index 00000000..d909ce37 --- /dev/null +++ b/docs/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/docs/source/_static/default.css b/docs/source/_static/default.css new file mode 100644 index 00000000..c8091ecb --- /dev/null +++ b/docs/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/docs/source/_static/jquery.tweet.js b/docs/source/_static/jquery.tweet.js new file mode 100644 index 00000000..c93fea87 --- /dev/null +++ b/docs/source/_static/jquery.tweet.js @@ -0,0 +1,154 @@ +(function($) { + + $.fn.tweet = function(o){ + var s = { + username: ["seaofclouds"], // [string] required, unless you want to display our tweets. :) it can be an array, just do ["username1","username2","etc"] + list: null, //[string] optional name of list belonging to username + avatar_size: null, // [integer] height and width of avatar if displayed (48px max) + count: 3, // [integer] how many tweets to display? + intro_text: null, // [string] do you want text BEFORE your your tweets? + outro_text: null, // [string] do you want text AFTER your tweets? + join_text: null, // [string] optional text in between date and tweet, try setting to "auto" + auto_join_text_default: "i said,", // [string] auto text for non verb: "i said" bullocks + auto_join_text_ed: "i", // [string] auto text for past tense: "i" surfed + auto_join_text_ing: "i am", // [string] auto tense for present tense: "i was" surfing + auto_join_text_reply: "i replied to", // [string] auto tense for replies: "i replied to" @someone "with" + auto_join_text_url: "i was looking at", // [string] auto tense for urls: "i was looking at" http:... + loading_text: null, // [string] optional loading text, displayed while tweets load + query: null // [string] optional search query + }; + + if(o) $.extend(s, o); + + $.fn.extend({ + linkUrl: function() { + var returning = []; + var regexp = /((ftp|http|https):\/\/(\w+:{0,1}\w*@)?(\S+)(:[0-9]+)?(\/|\/([\w#!:.?+=&%@!\-\/]))?)/gi; + this.each(function() { + returning.push(this.replace(regexp,"$1")); + }); + return $(returning); + }, + linkUser: function() { + var returning = []; + var regexp = /[\@]+([A-Za-z0-9-_]+)/gi; + this.each(function() { + returning.push(this.replace(regexp,"@$1")); + }); + return $(returning); + }, + linkHash: function() { + var returning = []; + var regexp = / [\#]+([A-Za-z0-9-_]+)/gi; + this.each(function() { + returning.push(this.replace(regexp, ' #$1')); + }); + return $(returning); + }, + capAwesome: function() { + var returning = []; + this.each(function() { + returning.push(this.replace(/\b(awesome)\b/gi, '$1')); + }); + return $(returning); + }, + capEpic: function() { + var returning = []; + this.each(function() { + returning.push(this.replace(/\b(epic)\b/gi, '$1')); + }); + return $(returning); + }, + makeHeart: function() { + var returning = []; + this.each(function() { + returning.push(this.replace(/(<)+[3]/gi, "♥")); + }); + return $(returning); + } + }); + + function relative_time(time_value) { + var parsed_date = Date.parse(time_value); + var relative_to = (arguments.length > 1) ? arguments[1] : new Date(); + var delta = parseInt((relative_to.getTime() - parsed_date) / 1000); + var pluralize = function (singular, n) { + return '' + n + ' ' + singular + (n == 1 ? '' : 's'); + }; + if(delta < 60) { + return 'less than a minute ago'; + } else if(delta < (45*60)) { + return 'about ' + pluralize("minute", parseInt(delta / 60)) + ' ago'; + } else if(delta < (24*60*60)) { + return 'about ' + pluralize("hour", parseInt(delta / 3600)) + ' ago'; + } else { + return 'about ' + pluralize("day", parseInt(delta / 86400)) + ' ago'; + } + } + + function build_url() { + var proto = ('https:' == document.location.protocol ? 'https:' : 'http:'); + if (s.list) { + return proto+"//api.twitter.com/1/"+s.username[0]+"/lists/"+s.list+"/statuses.json?per_page="+s.count+"&callback=?"; + } else if (s.query == null && s.username.length == 1) { + return proto+'//twitter.com/status/user_timeline/'+s.username[0]+'.json?count='+s.count+'&callback=?'; + } else { + var query = (s.query || 'from:'+s.username.join('%20OR%20from:')); + return proto+'//search.twitter.com/search.json?&q='+query+'&rpp='+s.count+'&callback=?'; + } + } + + return this.each(function(){ + var list = $('
    ').appendTo(this); + var intro = '

    '+s.intro_text+'

    '; + var outro = '

    '+s.outro_text+'

    '; + var loading = $('

    '+s.loading_text+'

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

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

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

    {{ _('Previous topic') }}

    +

    {{ prev.title }}

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

    {{ _('Next topic') }}

    +

    {{ next.title }}

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

    {{ _('This Page') }}

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

    {{ _('Twitter Feed') }}

    + + {%- endif %} + + + {%- endblock %} +
    +
    + {%- endif %}{% endif %} +{%- endmacro %} diff --git a/docs/source/_theme/theme.conf b/docs/source/_theme/theme.conf new file mode 100644 index 00000000..e039fe01 --- /dev/null +++ b/docs/source/_theme/theme.conf @@ -0,0 +1,5 @@ +[theme] +inherit = sphinxdoc +stylesheet = sphinxdoc.css +pygments_style = friendly + diff --git a/docs/source/community.rst b/docs/source/community.rst new file mode 100644 index 00000000..bbad2421 --- /dev/null +++ b/docs/source/community.rst @@ -0,0 +1,93 @@ +.. + Copyright 2011 OpenStack, LLC + All Rights Reserved. + + Licensed under the Apache License, Version 2.0 (the "License"); you may + not use this file except in compliance with the License. You may obtain + a copy of the License at + + http://www.apache.org/licenses/LICENSE-2.0 + + Unless required by applicable law or agreed to in writing, software + distributed under the License is distributed on an "AS IS" BASIS, WITHOUT + WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the + License for the specific language governing permissions and limitations + under the License. + +================ +Getting Involved +================ + +The OpenStack community is a very friendly group and there are places online to join in with the +community. Feel free to ask questions. This document points you to some of the places where you can +communicate with people. + +How to Join the Community +========================= + +Our community welcomes all people interested in open source cloud computing, and there are no formal +membership requirements. The best way to join the community is to talk with others online or at a meetup +and offer contributions through Launchpad_, the wiki_, or blogs. We welcome all types of contributions, +from blueprint designs to documentation to testing to deployment scripts. + +.. _Launchpad: https://launchpad.net/keystone +.. _wiki: http://wiki.openstack.org/ + + + +Contributing Code +----------------- + +To contribute code, sign up for a Launchpad account and sign a contributor license agreement, +available on the ``_. Once the CLA is signed you +can contribute code through the Gerrit version control system which is related to your Launchpad account. + +To contribute tests, docs, code, etc, refer to our `Gerrit-Jenkins-Github Workflow`_. + +.. _`Gerrit-Jenkins-Github Workflow`: http://wiki.openstack.org/GerritJenkinsGithub + + +#openstack on Freenode IRC Network +---------------------------------- + +There is a very active chat channel at ``_. This +is usually the best place to ask questions and find your way around. IRC stands for Internet Relay +Chat and it is a way to chat online in real time. You can also ask a question and come back to the +log files to read the answer later. Logs for the #openstack IRC channel are stored at +``_. + +OpenStack Wiki +-------------- + +The wiki is a living source of knowledge. It is edited by the community, and +has collections of links and other sources of information. Typically the pages are a good place +to write drafts for specs or documentation, describe a blueprint, or collaborate with others. + +`OpenStack Wiki `_ + +Keystone on Launchpad +--------------------- + +Launchpad is a code hosting service that hosts the Keystone source code. From +Launchpad you can report bugs, ask questions, and register blueprints (feature requests). + +* `Launchpad Keystone Page `_ + +OpenStack Blog +-------------- + +The OpenStack blog includes a weekly newsletter that aggregates OpenStack news +from around the internet, as well as providing inside information on upcoming +events and posts from OpenStack contributors. + +`OpenStack Blog `_ + +See also: `Planet OpenStack `_, aggregating blogs +about OpenStack from around the internet into a single feed. If you'd like to contribute to this blog +aggregation with your blog posts, there are instructions for `adding your blog `_. + +Twitter +------- + +Because all the cool kids do it: `@openstack `_. Also follow the +`#openstack `_ tag for relevant tweets. diff --git a/docs/source/conf.py b/docs/source/conf.py index 11c8adb0..63515726 100644 --- a/docs/source/conf.py +++ b/docs/source/conf.py @@ -97,6 +97,18 @@ pygments_style = 'sphinx' # A list of ignored prefixes for module index sorting. modindex_common_prefix = ['keystone.'] +# -- Options for man page output -------------------------------------------- + +# Grouping the document tree for man pages. +# List of tuples 'sourcefile', 'target', u'title', u'Authors name', 'manual' + +man_pages = [ + ('man/keystone-manage', 'keystone-manage', u'Keystone Management Utility', + [u'OpenStack'], 1), + ('man/keystone', 'keystone', u'Keystone Startup Command', + [u'OpenStack'], 1), + ] + # -- Options for HTML output --------------------------------------------------- diff --git a/docs/source/developing.rst b/docs/source/developing.rst new file mode 100644 index 00000000..acd22730 --- /dev/null +++ b/docs/source/developing.rst @@ -0,0 +1,135 @@ +.. + Copyright 2011 OpenStack, LLC + All Rights Reserved. + + Licensed under the Apache License, Version 2.0 (the "License"); you may + not use this file except in compliance with the License. You may obtain + a copy of the License at + + http://www.apache.org/licenses/LICENSE-2.0 + + Unless required by applicable law or agreed to in writing, software + distributed under the License is distributed on an "AS IS" BASIS, WITHOUT + WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the + License for the specific language governing permissions and limitations + under the License. + +======================== +Developing with Keystone +======================== + +Get your development environment set up according to :doc:`setup`. + +Running a development instance +============================== + +Setting up a virtualenv +----------------------- + +We recommend establishing a virtualenv to run keystone within. To establish +this environment, use the command:: + + $ python tools/install_venv.py + +This will create a local virtual environment in the directory ``.venv``. +Once created, you can activate this virtualenv for your current shell using:: + + $ source .venv/bin/activate + +The virtual environment can be disabled using the command:: + + $ deactivate + +You can also use ``tools\with_venv.sh`` to prefix commands so that they run +within the virtual environment. For more information on virtual environments, +see virtualenv_. + +.. _virtualenv: http://www.virtualenv.org/ + +Running Keystone +---------------- + +To run the keystone Admin and API server instances, use:: + + $ tools/with_venv.sh bin/keystone + +Running a demo service that uses Keystone +----------------------------------------- + +To run client demo (with all auth middleware running locally on sample service):: + + $ tools/with_venv.sh examples/echo/bin/echod + +which spins up a simple "echo" service on port 8090. To use a simple echo client:: + + $ python examples/echo/echo_client.py + +Interacting with Keystone +========================= + +You can interact with Keystone through the command line using :doc:`man/keystone-manage` +which allows you to establish tenants, users, etc. + +You can also interact with Keystone through it's REST API. There is a python +keystone client library python-keystoneclient_ which interacts exclusively through +the REST API. + +.. _python-keystoneclient: https://github.com/4P/python-keystoneclient + +The easiest way to establish some base information in Keystone to interact with is +to invoke:: + + $ tools/with_venv.sh bin/sampledata + +You can see the details of what that creates in ``keystone/test/sampledata.py`` + +Enabling debugging middleware +----------------------------- + +You can enable a huge amount of additional data (debugging information) about +the request and repsonse objects flowing through Keystone using the debugging +WSGI middleware. + +To enable this, just modify the pipelines in ``etc/keystone.conf``, from:: + + [pipeline:admin] + pipeline = + urlnormalizer + admin_api + + [pipeline:keystone-legacy-auth] + pipeline = + urlnormalizer + legacy_auth + d5_compat + service_api + +... to:: + + [pipeline:admin] + pipeline = + debug + urlnormalizer + d5_compat + admin_api + + [pipeline:keystone-legacy-auth] + pipeline = + debug + urlnormalizer + legacy_auth + d5_compat + service_api + +Two simple and easy debugging tools are using the ``-d`` when you start keystone:: + + $ ./keystone -d + +and the `--trace-calls` flag:: + + $ ./keystone -trace-calls + +The ``-d`` flag outputs debug information to the console. The ``--trace-calls`` flag +outputs extensive, nested trace calls to the console and highlights any errors +in red. + diff --git a/docs/source/index.rst b/docs/source/index.rst index cd7c96a8..4270033a 100644 --- a/docs/source/index.rst +++ b/docs/source/index.rst @@ -1,17 +1,59 @@ -.. keystone documentation master file, created by - sphinx-quickstart on Mon Jan 9 12:02:59 2012. - You can adapt this file completely to your liking, but it should at least - contain the root `toctree` directive. +.. + Copyright 2011 OpenStack, LLC + All Rights Reserved. -Welcome to keystone's documentation! -==================================== + 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 -Contents: + http://www.apache.org/licenses/LICENSE-2.0 + + Unless required by applicable law or agreed to in writing, software + distributed under the License is distributed on an "AS IS" BASIS, WITHOUT + WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the + License for the specific language governing permissions and limitations + under the License. + +==================================================== +Welcome to Keystone, the OpenStack Identity Service! +==================================================== + +Keystone is a cloud identity service written in Python, which provides +authentication, authorization, and an OpenStack service catalog. It +implements `OpenStack's Identity API`_. + +This document describes Keystone for contributors of the project, and assumes +that you are already familiar with Keystone from an `end-user perspective`_. + +.. _`OpenStack's Identity API`: http://docs.openstack.org/api/openstack-identity-service/2.0/content/ +.. _`end-user perspective`: http://docs.openstack.org/ + +This documentation is generated by the Sphinx toolkit and lives in the source +tree. Additional documentation on Keystone and other components of OpenStack can +be found on the `OpenStack wiki`_. Also see the :doc:`community` page for +other ways to interact with the community. + +.. _`OpenStack wiki`: http://wiki.openstack.org + +Getting Started +=============== .. toctree:: - :maxdepth: 2 + :maxdepth: 1 + + setup + community + testing +Developers Documentation +======================== +.. toctree:: + :maxdepth: 1 + + developing + architecture + sourcecode/autoindex Indices and tables ================== diff --git a/docs/source/man/keystone-manage.rst b/docs/source/man/keystone-manage.rst new file mode 100644 index 00000000..9e9304f0 --- /dev/null +++ b/docs/source/man/keystone-manage.rst @@ -0,0 +1,192 @@ +=============== +keystone-manage +=============== + +--------------------------- +Keystone Management Utility +--------------------------- + +:Author: keystone@lists.launchpad.net +:Date: 2010-11-16 +:Copyright: OpenStack LLC +:Version: 0.1.2 +:Manual section: 1 +:Manual group: cloud computing + +SYNOPSIS +======== + + keystone-manage [options] + +DESCRIPTION +=========== + +keystone-manage is the command line tool that interacts with the keystone +service to configure Keystone + +USAGE +===== + + ``keystone-manage [options] type action [additional args]`` + +user +---- + +* **user add** [username] [password] + + adds a user to Keystone's data store + +* **user list** + + lists all users + +* **user disable** [username] + + disables the user *username* + +tenant +------ + +* **tenant add** [tenant_name] + + adds a tenant to Keystone's data store + +* **tenant list** + + lists all users + +* **tenant disable** [tenant_name] + +role +---- + +Roles are used to associated users to tenants. Two roles are defined related +to the Keystone service in it's configuration file :doc:`../keystone.conf` + +* **role add** [role_name] + + adds a role + +* **role list** ([tenant_name]) + + lists all roles, or all roles for tenant, if tenant_name is provided + +* **role grant** [role_name] [username] ([tenant]) + + grants a role to a specific user. Granted globally if tenant_name is not + provided or granted for a specific tenant if tenant_name is provided. + +service +------- + +* **service add** [name] [type] [description] [owner_id] + + adds a service + +* **service list** + + lists all services with id, name, and type + +endpointTemplate +---------------- + +* **endpointTemplate add** [region] [service_name] [public_url] [admin_url] [internal_url] [enabled] [is_global] + + Add a service endpoint for keystone. + + example:: + + keystone-manage endpointTemplates add RegionOne \ + keystone \ + http://keystone_host:5000/v2.0 \ + http://keystone_host:35357/v2.0 \ + http://keystone_host:5000/v2.0 \ + 1 1 + +* **endpointTemplate list** ([tenant_name]) + + lists endpoint templates with service, region, and public_url. Restricted to + tenant endpoints if tenant_name is provided. + +token +----- + +* **token add** [token] [username] [tenant] [expiration] + + adds a token for a given user and tenant with an expiration + +* **token list** + + lists all tokens + +* **token delete** [token] + + deletes the identified token + +endpoint +-------- + +* **endpoint add** [tenant_name] [endpoint_template] + + adds a tenant-specific endpoint + +credentials +----------- + +* **credentials add** [username] [type] [key] [password] ([tenant_name]) + +OPTIONS +======= + + --version show program's version number and exit + -h, --help show this help message and exit + -v, --verbose Print more verbose output + -d, --debug Print debugging output to console + -c PATH, --config-file=PATH Path to the config file to use. When not + specified (the default), we generally look at + the first argument specified to be a config + file, and if that is also missing, we search + standard directories for a config file. + -p BIND_PORT, --port=BIND_PORT, --bind-port=BIND_PORT + specifies port to listen on (default is 5000) + --host=BIND_HOST, --bind-host=BIND_HOST + specifies host address to listen on (default + is all or 0.0.0.0) + -t, --trace-calls Turns on call tracing for troubleshooting + -a PORT, --admin-port=PORT Specifies port for Admin API to listen on + (default is 35357) + +Logging Options: +================ + +The following configuration options are specific to logging +functionality for this program. + + --log-config=PATH If this option is specified, the logging + configuration file specified is used and + overrides any other logging options specified. + Please see the Python logging module + documentation for details on logging + configuration files. + --log-date-format=FORMAT Format string for %(asctime)s in log records. + Default: %Y-%m-%d %H:%M:%S + --log-file=PATH (Optional) Name of log file to output to. If + not set, logging will go to stdout. + --log-dir=LOG_DIR (Optional) The directory to keep log files in + (will be prepended to --logfile) + +FILES +===== + +None + +SEE ALSO +======== + +* `Keystone `__ + +SOURCE +====== + +* Keystone is sourced in GitHub `Keystone `__ +* Keystone bugs are managed at Launchpad `Launchpad Keystone `__ diff --git a/docs/source/man/keystone.rst b/docs/source/man/keystone.rst new file mode 100644 index 00000000..48e062e4 --- /dev/null +++ b/docs/source/man/keystone.rst @@ -0,0 +1,90 @@ +======== +keystone +======== + +--------------------------- +Keystone Management Utility +--------------------------- + +:Author: keystone@lists.launchpad.net +:Date: 2010-11-16 +:Copyright: OpenStack LLC +:Version: 0.1.2 +:Manual section: 1 +:Manual group: cloud computing + +SYNOPSIS +======== + + keystone [options] + +DESCRIPTION +=========== + +keystone starts both the service and administrative API servers for Keystone. +Use :doc:`keystone-control` to stop/start/restart and manage those services +once started. + +USAGE +===== + + keystone ``keystone [options]`` + +Common Options: +^^^^^^^^^^^^^^^ + --version show program's version number and exit + -h, --help show this help message and exit + +The following configuration options are common to all keystone +programs.:: + + -v, --verbose Print more verbose output + -d, --debug Print debugging output to console + -c PATH, --config-file=PATH Path to the config file to use. When not + specified (the default), we generally look at + the first argument specified to be a config + file, and if that is also missing, we search + standard directories for a config file. + -p BIND_PORT, --port=BIND_PORT, --bind-port=BIND_PORT + specifies port to listen on (default is 5000) + --host=BIND_HOST, --bind-host=BIND_HOST + specifies host address to listen on (default + is all or 0.0.0.0) + -t, --trace-calls Turns on call tracing for troubleshooting + -a PORT, --admin-port=PORT Specifies port for Admin API to listen on + (default is 35357) + +Logging Options: +^^^^^^^^^^^^^^^^ + +The following configuration options are specific to logging +functionality for this program.:: + + --log-config=PATH If this option is specified, the logging + configuration file specified is used and + overrides any other logging options specified. + Please see the Python logging module + documentation for details on logging + configuration files. + --log-date-format=FORMAT Format string for %(asctime)s in log records. + Default: %Y-%m-%d %H:%M:%S + --log-file=PATH (Optional) Name of log file to output to. If + not set, logging will go to stdout. + --log-dir=LOG_DIR (Optional) The directory to keep log files in + (will be prepended to --logfile) + +FILES +===== + +None + +SEE ALSO +======== + +* `Keystone `__ + +SOURCE +====== + +* Keystone is sourced in GitHub `Keystone `__ +* Keystone bugs are managed at Launchpad `Launchpad Keystone `__ diff --git a/docs/source/setup.rst b/docs/source/setup.rst new file mode 100644 index 00000000..e608f09e --- /dev/null +++ b/docs/source/setup.rst @@ -0,0 +1,151 @@ +.. + Copyright 2011 OpenStack, LLC + All Rights Reserved. + + Licensed under the Apache License, Version 2.0 (the "License"); you may + not use this file except in compliance with the License. You may obtain + a copy of the License at + + http://www.apache.org/licenses/LICENSE-2.0 + + Unless required by applicable law or agreed to in writing, software + distributed under the License is distributed on an "AS IS" BASIS, WITHOUT + WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the + License for the specific language governing permissions and limitations + under the License. + +============================================= +Setting up a Keystone development environment +============================================= + +This document describes setting up keystone directly from GitHub_ +for development purposes. + +To install keystone from packaging, refer instead to Keystone's `User Documentation`_. + +.. _GitHub: http://github.com/openstack/keystone +.. _`User Documentation`: http://docs.openstack.org/ + +Prerequisites +============= + +This document assumes you are using: + +- Ubuntu 11.10, Fedora 15, or Mac OS X Lion +- `Python 2.7`_ + +.. _`Python 2.7`: http://www.python.org/ + +And that you have the following tools available on your system: + +- git_ +- setuptools_ +- pip_ + +**Reminder**: If you're successfully using a different platform, or a +different version of the above, please document your configuration here! + +.. _git: http://git-scm.com/ +.. _setuptools: http://pypi.python.org/pypi/setuptools + +Getting the latest code +======================= + +You can clone our latest code from our `Github repository`:: + + $ git clone https://github.com/openstack/keystone.git + +When that is complete, you can:: + + $ cd keystone + +.. _`Github repository`: https://github.com/openstack/keystone + +Installing dependencies +======================= + +Keystone maintains a list of PyPi_ dependencies, designed for use by +pip_. + +.. _PyPi: http://pypi.python.org/ +.. _pip: http://pypi.python.org/pypi/pip + +However, your system *may* need additional dependencies that `pip` (and by +extension, PyPi) cannot satisfy. These dependencies should be installed +prior to using `pip`, and the installation method may vary depending on +your platform. + +Ubuntu 11.10:: + + $ sudo apt-get install python-dev libxml2-dev libxslt1-dev libsasl2-dev libsqlite3-dev libssl-dev libldap2-dev + +Fedora 15:: + + $ sudo yum install python-sqlite2 python-lxml python-greenlet-devel python-ldap + +Mac OS X Lion (requires MacPorts_):: + + $ sudo port install py-ldap + +.. _MacPorts: http://www.macports.org/ + +PyPi Packages +------------- + +Assuming you have any necessary binary packages & header files available +on your system, you can then install PyPi dependencies. + +You may also need to prefix `pip install` with `sudo`, depending on your +environment:: + + # Describe dependencies (including non-PyPi dependencies) + $ cat tools/pip-requires + + # Install all PyPi dependencies (for production, testing, and development) + $ pip install -r tools/pip-requires + +Updating your PYTHONPATH +======================== + +There are a number of methods for getting Keystone into your PYTHON PATH, +the easiest of which is:: + + # Fake-install the project by symlinking Keystone into your Python site-packages + $ python setup.py develop + +You should then be able to `import keystone` from your Python shell +without issue:: + + >>> import keystone.version + >>> + +If you want to check the version of Keystone you are running: + + >>> print keystone.version.version() + 2012.1-dev + + +If you can import keystone successfully, you should be ready to move on to :doc:`testing`. + +Troubleshooting +=============== + +Eventlet segfaults on RedHat / Fedora +------------------------------------- + +[*If this is no longer an issue, please remove this section, thanks!*] + +On some OSes, specifically Fedora 15, the current versions of +greenlet/eventlet segfault when running keystone. To fix this, install +the development versions of greenlet and eventlet:: + + $ pip uninstall greenlet eventlet + $ cd + $ hg clone https://bitbucket.org/ambroff/greenlet + $ cd greenlet + $ sudo python setup.py install + + $ cd + $ hg clone https://bitbucket.org/which_linden/eventlet + $ cd greenlet + $ sudo python setup.py install diff --git a/docs/source/testing.rst b/docs/source/testing.rst new file mode 100644 index 00000000..82a33604 --- /dev/null +++ b/docs/source/testing.rst @@ -0,0 +1,77 @@ +================ +Testing Keystone +================ + +Keystone uses a number of testing methodologies to ensure correctness. + +Running Built-In Tests +====================== + +To run the full suites of tests maintained within Keystone, run:: + + $ ./run_tests.sh --with-progress + +This shows realtime feedback during test execution, and iterates over +multiple configuration variations. + +This differs from how tests are executed from the continuous integration +environment. Specifically, Jenkins doesn't care about realtime progress, +and aborts after the first test failure (a fail-fast behavior):: + + $ ./run_tests.sh + +Testing Schema Migrations +========================= + +The application of schema migrations can be tested using SQLAlchemy Migrate’s built-in test runner, one migration at a time. + +.. WARNING:: + + This may leave your database in an inconsistent state; attempt this in non-production environments only! + +This is useful for testing the *next* migration in sequence (both forward & backward) in a database under version control:: + + $ python keystone/backends/sqlalchemy/migrate_repo/manage.py test --url=sqlite:///test.db --repository=keystone/backends/sqlalchemy/migrate_repo/ + +This command refers to a SQLite database used for testing purposes. Depending on the migration, this command alone does not make assertions as to the integrity of your data during migration. + +Writing Tests +============= + +Tests are maintained in the ``keystone.test`` module. Unit tests are +isolated from functional tests. + +Functional Tests +---------------- + +The ``keystone.test.functional.common`` module provides a ``unittest``-based +``httplib`` client which you can extend and use for your own tests. +Generally, functional tests should serve to illustrate intended use cases +and API behaviors. To help make your tests easier to read, the test client: + +- Authenticates with a known user name and password combination +- Asserts 2xx HTTP status codes (unless told otherwise) +- Abstracts keystone REST verbs & resources into single function calls + +Testing Multiple Configurations +------------------------------- + +Several variations of the default configuration are iterated over to +ensure test coverage of mutually exclusive featuresets, such as the +various backend options. + +These configuration templates are maintained in ``keystone/test/etc`` and +are iterated over by ``run_tests.py``. + +Further Testing +=============== + +devstack_ is the *best* way to quickly deploy keystone with the rest of the +OpenStack universe and should be critical step in your development workflow! + +You may also be interested in either the `OpenStack Continuous Integration Project`_ +or the `OpenStack Integration Testing Project`_. + +.. _devstack: http://devstack.org/ +.. _OpenStack Continuous Integration Project: https://github.com/openstack/openstack-ci +.. _OpenStack Integration Testing Project: https://github.com/openstack/openstack-integration-tests -- cgit From d8ddc074f026a2b7c72cdb2107ed8ff790a4bb5f Mon Sep 17 00:00:00 2001 From: termie Date: Thu, 19 Jan 2012 20:36:06 -0800 Subject: get docs working --- docs/Makefile | 2 +- docs/generate_autodoc_index.py | 76 ------------------------------------------ 2 files changed, 1 insertion(+), 77 deletions(-) delete mode 100755 docs/generate_autodoc_index.py (limited to 'docs') diff --git a/docs/Makefile b/docs/Makefile index 03e3ef3b..79861705 100644 --- a/docs/Makefile +++ b/docs/Makefile @@ -47,7 +47,7 @@ clean: autodoc: $(SPHINXAPIDOC) -f -o $(SOURCEDIR) ../keystone -html: +html: autodoc $(SPHINXBUILD) -b html $(ALLSPHINXOPTS) $(BUILDDIR)/html @echo @echo "Build finished. The HTML pages are in $(BUILDDIR)/html." diff --git a/docs/generate_autodoc_index.py b/docs/generate_autodoc_index.py deleted file mode 100755 index 993369b0..00000000 --- a/docs/generate_autodoc_index.py +++ /dev/null @@ -1,76 +0,0 @@ -#!/usr/bin/env python -"""Generates files for sphinx documentation using a simple Autodoc based -template. - -To use, just run as a script: - $ python doc/generate_autodoc_index.py -""" - -import os - - -base_dir = os.path.dirname(os.path.abspath(__file__)) -RSTDIR=os.path.join(base_dir, "source", "sourcecode") -SOURCEDIR=os.path.join(base_dir, "..") - -# Exclude these modules from the autodoc results -EXCLUDE_MODULES = ['keystone.backends.sqlalchemy.migrate_repo'] - -def in_exclude_list(module_name): - """Compares a module to the list of excluded modules - - Returns true if the provided module resides in or matches - an excluded module, false otherwise. - """ - for excluded_module in EXCLUDE_MODULES: - if module_name.startswith(excluded_module): - return True - return False - -def find_autodoc_modules(module_name, sourcedir): - """returns a list of modules in the SOURCE directory""" - modlist = [] - os.chdir(os.path.join(sourcedir, module_name)) - for root, dirs, files in os.walk("."): - for filename in files: - if filename.endswith(".py"): - # root = ./keystone/test/unit - # filename = base.py - elements = root.split(os.path.sep) - # replace the leading "." with the module name - elements[0] = module_name - # and get the base module name - base, extension = os.path.splitext(filename) - if not (base == "__init__"): - elements.append(base) - result = (".".join(elements)) - if not in_exclude_list(result): - modlist.append(result) - return modlist - -if not(os.path.exists(RSTDIR)): - os.mkdir(RSTDIR) - -INDEXOUT = open("%s/autoindex.rst" % RSTDIR, "w") -INDEXOUT.write("Source Code Index\n") -INDEXOUT.write("=================\n") -INDEXOUT.write(".. toctree::\n") -INDEXOUT.write(" :maxdepth: 1\n") -INDEXOUT.write("\n") - -for module in find_autodoc_modules('keystone', SOURCEDIR): - generated_file = "%s/%s.rst" % (RSTDIR, module) - - INDEXOUT.write(" %s\n" % module) - FILEOUT = open(generated_file, "w") - FILEOUT.write("The :mod:`%s` Module\n" % module) - FILEOUT.write("==============================" - "==============================" - "==============================\n") - FILEOUT.write(".. automodule:: %s\n" % module) - FILEOUT.write(" :members:\n") - FILEOUT.write(" :undoc-members:\n") - FILEOUT.write(" :show-inheritance:\n") - FILEOUT.close() - -INDEXOUT.close() -- cgit From 6b38e3ceb62515f1d28078d2f36b72548023521c Mon Sep 17 00:00:00 2001 From: Joe Heck Date: Tue, 24 Jan 2012 09:43:06 -0800 Subject: moving in all the original docs from keystone --- docs/source/adminAPI_curl_examples.rst | 387 +++++++++++++++ docs/source/architecture.rst | 97 ++++ docs/source/backends.rst | 188 ++++++++ docs/source/configuration.rst | 100 ++++ docs/source/configuringservices.rst | 333 +++++++++++++ docs/source/controllingservers.rst | 288 +++++++++++ docs/source/endpoints.rst | 430 +++++++++++++++++ docs/source/extensions.rst | 183 +++++++ docs/source/images/305.svg | 158 ++++++ docs/source/images/authComp.svg | 174 +++++++ docs/source/images/both.svg | 135 ++++++ docs/source/images/graphs_305.svg | 41 ++ docs/source/images/graphs_authComp.svg | 48 ++ docs/source/images/graphs_authCompDelegate.svg | 53 +++ docs/source/images/graphs_both.svg | 36 ++ docs/source/images/graphs_delegate_accept.svg | 52 ++ .../images/graphs_delegate_forbiden_basic.svg | 53 +++ .../images/graphs_delegate_forbiden_proxy.svg | 52 ++ .../source/images/graphs_delegate_reject_basic.svg | 55 +++ .../source/images/graphs_delegate_reject_oauth.svg | 56 +++ .../images/graphs_delegate_unimplemented.svg | 53 +++ docs/source/images/graphs_mapper.svg | 73 +++ docs/source/images/graphs_proxyAuth.svg | 51 ++ docs/source/images/graphs_separate.svg | 30 ++ docs/source/images/graphs_standard_accept.svg | 51 ++ docs/source/images/graphs_standard_reject.svg | 39 ++ docs/source/images/graphs_together.svg | 24 + docs/source/images/images_layouts.svg | 200 ++++++++ docs/source/images/layouts.svg | 215 +++++++++ docs/source/images/mapper.svg | 237 +++++++++ docs/source/images/proxyAuth.svg | 238 +++++++++ docs/source/middleware.rst | 169 +++++++ docs/source/middleware_architecture.rst | 529 +++++++++++++++++++++ docs/source/migration.rst | 126 +++++ docs/source/nova-api-paste.rst | 142 ++++++ docs/source/releases.rst | 36 ++ docs/source/serviceAPI_curl_examples.rst | 69 +++ docs/source/services.rst | 92 ++++ docs/source/ssl.rst | 118 +++++ docs/source/usingkeystone.rst | 28 ++ 40 files changed, 5439 insertions(+) create mode 100644 docs/source/adminAPI_curl_examples.rst create mode 100644 docs/source/architecture.rst create mode 100644 docs/source/backends.rst create mode 100644 docs/source/configuration.rst create mode 100644 docs/source/configuringservices.rst create mode 100644 docs/source/controllingservers.rst create mode 100644 docs/source/endpoints.rst create mode 100644 docs/source/extensions.rst create mode 100644 docs/source/images/305.svg create mode 100644 docs/source/images/authComp.svg create mode 100644 docs/source/images/both.svg create mode 100644 docs/source/images/graphs_305.svg create mode 100644 docs/source/images/graphs_authComp.svg create mode 100644 docs/source/images/graphs_authCompDelegate.svg create mode 100644 docs/source/images/graphs_both.svg create mode 100644 docs/source/images/graphs_delegate_accept.svg create mode 100644 docs/source/images/graphs_delegate_forbiden_basic.svg create mode 100644 docs/source/images/graphs_delegate_forbiden_proxy.svg create mode 100644 docs/source/images/graphs_delegate_reject_basic.svg create mode 100644 docs/source/images/graphs_delegate_reject_oauth.svg create mode 100644 docs/source/images/graphs_delegate_unimplemented.svg create mode 100644 docs/source/images/graphs_mapper.svg create mode 100644 docs/source/images/graphs_proxyAuth.svg create mode 100644 docs/source/images/graphs_separate.svg create mode 100644 docs/source/images/graphs_standard_accept.svg create mode 100644 docs/source/images/graphs_standard_reject.svg create mode 100644 docs/source/images/graphs_together.svg create mode 100644 docs/source/images/images_layouts.svg create mode 100644 docs/source/images/layouts.svg create mode 100644 docs/source/images/mapper.svg create mode 100644 docs/source/images/proxyAuth.svg create mode 100644 docs/source/middleware.rst create mode 100644 docs/source/middleware_architecture.rst create mode 100644 docs/source/migration.rst create mode 100644 docs/source/nova-api-paste.rst create mode 100644 docs/source/releases.rst create mode 100644 docs/source/serviceAPI_curl_examples.rst create mode 100644 docs/source/services.rst create mode 100644 docs/source/ssl.rst create mode 100644 docs/source/usingkeystone.rst (limited to 'docs') diff --git a/docs/source/adminAPI_curl_examples.rst b/docs/source/adminAPI_curl_examples.rst new file mode 100644 index 00000000..81f96c36 --- /dev/null +++ b/docs/source/adminAPI_curl_examples.rst @@ -0,0 +1,387 @@ +.. + Copyright 2011 OpenStack, LLC + All Rights Reserved. + + Licensed under the Apache License, Version 2.0 (the "License"); you may + not use this file except in compliance with the License. You may obtain + a copy of the License at + + http://www.apache.org/licenses/LICENSE-2.0 + + Unless required by applicable law or agreed to in writing, software + distributed under the License is distributed on an "AS IS" BASIS, WITHOUT + WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the + License for the specific language governing permissions and limitations + under the License. + +============================= +Admin API Examples Using Curl +============================= + +These examples assume a default port value of 35357, and depend on the +``sampledata`` bundled with keystone. + +GET / +===== + +Disover API version information, links to documentation (PDF, HTML, WADL), +and supported media types:: + + $ curl http://0.0.0.0:35357 + +or:: + + $ curl http://0.0.0.0:35357/v2.0/ + +Returns:: + + { + "version":{ + "id":"v2.0", + "status":"beta", + "updated":"2011-11-19T00:00:00Z", + "links":[ + { + "rel":"self", + "href":"http://127.0.0.1:35357/v2.0/" + }, + { + "rel":"describedby", + "type":"text/html", + "href":"http://docs.openstack.org/api/openstack-identity-service/2.0/content/" + }, + { + "rel":"describedby", + "type":"application/pdf", + "href":"http://docs.openstack.org/api/openstack-identity-service/2.0/identity-dev-guide-2.0.pdf" + }, + { + "rel":"describedby", + "type":"application/vnd.sun.wadl+xml", + "href":"http://127.0.0.1:35357/v2.0/identity-admin.wadl" + } + ], + "media-types":[ + { + "base":"application/xml", + "type":"application/vnd.openstack.identity-v2.0+xml" + }, + { + "base":"application/json", + "type":"application/vnd.openstack.identity-v2.0+json" + } + ] + } + } + +GET /extensions +=============== + +Discover the API extensions enabled at the endpoint:: + + $ curl http://0.0.0.0:35357/extensions + +Returns:: + + { + "extensions":{ + "values":[] + } + } + +POST /tokens +============ + +Authenticate by exchanging credentials for an access token:: + + $ curl -d '{"auth":{"passwordCredentials":{"username": "joeuser", "password": "secrete"}}}' -H "Content-type: application/json" http://localhost:35357/v2.0/tokens + +Returns:: + + { + "access":{ + "token":{ + "expires":"2012-02-05T00:00:00", + "id":"887665443383838", + "tenant":{ + "id":"1", + "name":"customer-x" + } + }, + "serviceCatalog":[ + { + "endpoints":[ + { + "adminURL":"http://swift.admin-nets.local:8080/", + "region":"RegionOne", + "internalURL":"http://127.0.0.1:8080/v1/AUTH_1", + "publicURL":"http://swift.publicinternets.com/v1/AUTH_1" + } + ], + "type":"object-store", + "name":"swift" + }, + { + "endpoints":[ + { + "adminURL":"http://cdn.admin-nets.local/v1.1/1", + "region":"RegionOne", + "internalURL":"http://127.0.0.1:7777/v1.1/1", + "publicURL":"http://cdn.publicinternets.com/v1.1/1" + } + ], + "type":"object-store", + "name":"cdn" + } + ], + "user":{ + "id":"1", + "roles":[ + { + "tenantId":"1", + "id":"3", + "name":"Member" + } + ], + "name":"joeuser" + } + } + } + +.. note:: + + Take note of the value ['access']['token']['id'] value produced here (``887665443383838``, above), as you can use it in the calls below. + +GET /tokens/{token_id} +====================== + +.. note:: + + This call refers to a token known to be valid, ``887665443383838`` in this case. + +Validate a token:: + + $ curl -H "X-Auth-Token:999888777666" http://localhost:35357/v2.0/tokens/887665443383838 + +If the token is valid, returns:: + + { + "access":{ + "token":{ + "expires":"2012-02-05T00:00:00", + "id":"887665443383838", + "tenant":{ + "id":"1", + "name":"customer-x" + } + }, + "user":{ + "name":"joeuser", + "tenantName":"customer-x", + "id":"1", + "roles":[ + { + "serviceId":"1", + "id":"3", + "name":"Member" + } + ], + "tenantId":"1" + } + } + } + +HEAD /tokens/{token_id} +======================= + +This is a high-performance variant of the GET call documented above, which +by definition, returns no response body:: + + $ curl -I -H "X-Auth-Token:999888777666" http://localhost:35357/v2.0/tokens/887665443383838 + +... which returns ``200``, indicating the token is valid:: + + HTTP/1.1 200 OK + Content-Length: 0 + Content-Type: None + Date: Tue, 08 Nov 2011 23:07:44 GMT + +GET /tokens/{token_id}/endpoints +================================ + +List all endpoints for a token:: + + $ curl -H "X-Auth-Token:999888777666" http://localhost:35357/v2.0/tokens/887665443383838/endpoints + +Returns:: + + { + "endpoints_links": [ + { + "href": "http://127.0.0.1:35357/tokens/887665443383838/endpoints?'marker=5&limit=10'", + "rel": "next" + } + ], + "endpoints": [ + { + "internalURL": "http://127.0.0.1:8080/v1/AUTH_1", + "name": "swift", + "adminURL": "http://swift.admin-nets.local:8080/", + "region": "RegionOne", + "tenantId": 1, + "type": "object-store", + "id": 1, + "publicURL": "http://swift.publicinternets.com/v1/AUTH_1" + }, + { + "internalURL": "http://localhost:8774/v1.0", + "name": "nova_compat", + "adminURL": "http://127.0.0.1:8774/v1.0", + "region": "RegionOne", + "tenantId": 1, + "type": "compute", + "id": 2, + "publicURL": "http://nova.publicinternets.com/v1.0/" + }, + { + "internalURL": "http://localhost:8774/v1.1", + "name": "nova", + "adminURL": "http://127.0.0.1:8774/v1.1", + "region": "RegionOne", + "tenantId": 1, + "type": "compute", + "id": 3, + "publicURL": "http://nova.publicinternets.com/v1.1/ + }, + { + "internalURL": "http://127.0.0.1:9292/v1.1/", + "name": "glance", + "adminURL": "http://nova.admin-nets.local/v1.1/", + "region": "RegionOne", + "tenantId": 1, + "type": "image", + "id": 4, + "publicURL": "http://glance.publicinternets.com/v1.1/" + }, + { + "internalURL": "http://127.0.0.1:7777/v1.1/1", + "name": "cdn", + "adminURL": "http://cdn.admin-nets.local/v1.1/1", + "region": "RegionOne", + "tenantId": 1, + "versionId": "1.1", + "versionList": "http://127.0.0.1:7777/", + "versionInfo": "http://127.0.0.1:7777/v1.1", + "type": "object-store", + "id": 5, + "publicURL": "http://cdn.publicinternets.com/v1.1/1" + } + ] + } + +GET /tenants +============ + +List all of the tenants in the system (requires an Admin ``X-Auth-Token``):: + + $ curl -H "X-Auth-Token:999888777666" http://localhost:35357/v2.0/tenants + +Returns:: + + { + "tenants_links": [], + "tenants": [ + { + "enabled": false, + "description": "None", + "name": "project-y", + "id": "3" + }, + { + "enabled": true, + "description": "None", + "name": "ANOTHER:TENANT", + "id": "2" + }, + { + "enabled": true, + "description": "None", + "name": "customer-x", + "id": "1" + } + ] + } + +GET /tenants/{tenant_id} +======================== + +Retrieve information about a tenant, by tenant ID:: + + $ curl -H "X-Auth-Token:999888777666" http://localhost:35357/v2.0/tenants/1 + +Returns:: + + { + "tenant":{ + "enabled":true, + "description":"None", + "name":"customer-x", + "id":"1" + } + } + +GET /tenants/{tenant_id}/users/{user_id}/roles +============================================== + +List the roles a user has been granted on a tenant:: + + $ curl -H "X-Auth-Token:999888777666" http://localhost:35357/v2.0/tenants/1/users/1/roles + +Returns:: + + { + "roles_links":[], + "roles":[ + { + "id":"3", + "name":"Member" + } + ] + } + +GET /users/{user_id} +==================== + +Retrieve information about a user, by user ID:: + + $ curl -H "X-Auth-Token:999888777666" http://localhost:35357/v2.0/users/1 + +Returns:: + + { + "user":{ + "tenantId":"1", + "enabled":true, + "id":"1", + "name":"joeuser" + } + } + +GET /users/{user_id}/roles +========================== + +Retrieve the roles granted to a user, given a user ID:: + + $ curl -H "X-Auth-Token:999888777666" http://localhost:35357/v2.0/users/4/roles + +Returns:: + + { + "roles_links":[], + "roles":[ + { + "id":"2", + "name":"KeystoneServiceAdmin" + } + ] + } diff --git a/docs/source/architecture.rst b/docs/source/architecture.rst new file mode 100644 index 00000000..8de45502 --- /dev/null +++ b/docs/source/architecture.rst @@ -0,0 +1,97 @@ +.. + Copyright 2011 OpenStack, LLC + All Rights Reserved. + + Licensed under the Apache License, Version 2.0 (the "License"); you may + not use this file except in compliance with the License. You may obtain + a copy of the License at + + http://www.apache.org/licenses/LICENSE-2.0 + + Unless required by applicable law or agreed to in writing, software + distributed under the License is distributed on an "AS IS" BASIS, WITHOUT + WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the + License for the specific language governing permissions and limitations + under the License. + +Keystone Architecture +===================== + +Keystone has two major components: Authentication and a Service Catalog. + +Authentication +-------------- + +In providing a token-based authentication service for OpenStack, keystone +has several major concepts: + +Tenant + A grouping used in OpenStack to contain relevant OpenStack services. A + tenant maps to a Nova "project-id", and in object storage, a tenant can + have multiple containers. Depending on the installation, a tenant can + represent a customer, account, organization, or project. + +User + Represents an individual within OpenStack for the purposes of + authenticating them to OpenStack services. Users have credentials, and may + be assigned to one or more tenants. When authenticated, a token is + provided that is specific to a single tenant. + +Credentials + Password or other information that uniquely identifies a User to Keystone + for the purposes of providing a token. + +Token + A token is an arbitrary bit of text that is used to share authentication + with other OpenStack services so that Keystone can provide a central + location for authenticating users for access to OpenStack services. A + token may be "scoped" or "unscoped". A scoped token represents a user + authenticated to a Tenant, where an unscoped token represents just the + user. + + Tokens are valid for a limited amount of time and may be revoked at any + time. + +Role + A role is a set of permissions to access and use specific operations for + a given user when applied to a tenant. Roles are logical groupings of + those permissions to enable common permissions to be easily grouped and + bound to users associated with a given tenant. + +Service Catalog +--------------- + +Keystone also provides a list of REST API endpoints as a definitive list for +an OpenStack installation. Key concepts include: + +Service + An OpenStack service such as nova, swift, glance, or keystone. A service + may have one of more endpoints through which users can interact with + OpenStack services and resources. + +Endpoint + A network accessible address (typically a URL) that represents the API + interface to an OpenStack service. Endpoints may also be grouped into + templates which represent a group of consumable OpenStack services + available across regions. + +Template + A collection of endpoints representing a set of consumable OpenStack + service endpoints. + +Components of Keystone +---------------------- + +Keystone includes a command-line interface which interacts with the Keystone +API for administrating keystone and related services. + +* keystone - runs both keystone-admin and keystone-service +* keystone-admin - the administrative API for manipulating keystone +* keystone-service - the user oriented API for authentication +* keystone-manage - the command line interface to manipulate keystone + +Keystone also includes WSGI middelware to provide authentication support +for Nova and Swift. + +Keystone uses a built-in SQLite datastore - and may use an external LDAP +service to authenticate users instead of using stored credentials. diff --git a/docs/source/backends.rst b/docs/source/backends.rst new file mode 100644 index 00000000..b3fc2d91 --- /dev/null +++ b/docs/source/backends.rst @@ -0,0 +1,188 @@ +.. + Copyright 2011 OpenStack, LLC + All Rights Reserved. + + Licensed under the Apache License, Version 2.0 (the "License"); you may + not use this file except in compliance with the License. You may obtain + a copy of the License at + + http://www.apache.org/licenses/LICENSE-2.0 + + Unless required by applicable law or agreed to in writing, software + distributed under the License is distributed on an "AS IS" BASIS, WITHOUT + WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the + License for the specific language governing permissions and limitations + under the License. + +======== +Backends +======== + +Keystone supports multiple types of data stores for things like users, tenants, and +tokens, including SQL, LDAP, and memcache. + +SQL +=== + +In the default backend configuration (SQL-only), Keystone depends on the following database tables. + +``users`` +--------- + +``id`` + Auto-incremented primary key. +``name`` + Unqiue username used for authentication via ``passwordCredentials``. +``password`` + Password used for authentication via ``passwordCredentials``. + + Salted and hashed using ``passlib``. +``email`` + Email address (uniqueness is expected, but not enforced). +``enabled`` + If false, the user is unable to authenticate and the user's tokens will fail validation. +``tenant_id`` + Default tenant for the user. + +``tokens`` +---------- + +``id`` + The actual token provided after successful authentication (*plaintext*). +``user_id`` + References the user who owns the token. +``tenant_id`` + (*optional*) References the tenant the token is scoped to. +``expires`` + Indicates the expiration date of the token, after which the token can no longer be validated successfully. + +``tenants`` +----------- + +``id`` + Auto-incremented primary key. +``name`` + Unique string identifying the tenant. +``desc`` + Description of the tenant. +``enabled`` + If false, users are unable to scope to the tenant. + +``roles`` +--------- + +``id`` + Auto-incremented primary key. +``name`` + Name of the role. + + If the role is owned by a service, the role name **must** follow the convention:: + + serviceName:roleName +``desc`` + Description of the role. +``service_id`` + (*optional*) References the service that owns the role. + +``user_roles`` +-------------- + +Maps users to the roles that have been granted to them (*optionally*, within the scope of a tenant). + +``id`` + Auto-incremented primary key. +``user_id`` + References the user the role is granted to. +``role_id`` + References the granted role. +``tenant_id`` + (*optional*) References a tenant upon which this grant is applies. + +``services`` +------------ + +``id`` + Auto-incremented primary key. +``name`` + Unique name of the service. +``type`` + Indicates the type of service (e.g. ``compute``, ``object``, ``identity``, etc). + + This can also be extended to support non-core services. Extended services + follow the naming convention ``extension:type`` (e.g. ``dnsextension:dns``). +``desc`` + Describes the service. +``owner_id`` + (*optional*) References the user who owns the service. + +``credentials`` +--------------- + +Currently only used for Amazon EC2 credential storage, this table is designed to support multiple +types of credentials in the future. + +``id`` + Auto-incremented primary key. +``user_id`` + References the user who owns the credential. +``tenant_id`` + References the tenant upon which the credential is valid. +``types`` + Indicates the type of credential (e.g. ``Password``, ``APIKey``, ``EC2``). +``key`` + Amazon EC2 access key. +``secret`` + Amazon EC2 secret key. + +``endpoints`` +------------- + +Tenant-specific endpoints map endpoint templates to specific tenants. +The ``tenant_id`` which appears here replaces the +``%tenant_id%`` template variable in the specified endpoint template. + +``id`` + Auto-incremented primary key. +``tenant_id`` + References the tenant this endpoint applies to. +``endpoint_template_id`` + The endpoint template to appear in the user's service catalog. + +``endpoint_templates`` +---------------------- + +A multi-purpose model for the service catalog which can be: + +- Provided to users of a specific tenants via ``endpoints``, when ``is_global`` is false. +- Provided to all users as-is, when ``is_global`` is true. + +``id`` + Auto-incremented primary key. +``region`` + Identifies the geographic region the endpoint is physically located within. +``service_id`` + TODO: References the service which owns the endpoints? +``public_url`` + Appears in the service catalog [#first]_. + + Represents an endpoint available on the public Internet. +``admin_url`` + Appears in the service catalog [#first]_. + + Users of this endpoint must have an Admin or ServiceAdmin role. +``internal_url`` + Appears in the service catalog [#first]_. + + Represents an endpoint on an internal, unmetered network. +``enabled`` + If false, this endpoint template will not appear in the service catalog. +``is_global`` + If true, this endpoint can not be mapped to tenant-specific endpoints, and ``%tenant_id%`` will not be substituted in endpoint URL's. Additionally, this endpoint will appear for all users. +``version_id`` + Identifies the version of the API contract that endpoint supports. +``version_list`` + A URL which lists versions supported by the endpoint. +``version_info`` + A URL which provides detailed version info regarding the service. + +.. [#first] ``%tenant_id%`` may be replaced by actual tenant references, depending on the value of ``is_global`` and the existence of a corresponding ``endpoints`` record. diff --git a/docs/source/configuration.rst b/docs/source/configuration.rst new file mode 100644 index 00000000..a98d92f8 --- /dev/null +++ b/docs/source/configuration.rst @@ -0,0 +1,100 @@ +.. + Copyright 2011 OpenStack, LLC + All Rights Reserved. + + Licensed under the Apache License, Version 2.0 (the "License"); you may + not use this file except in compliance with the License. You may obtain + a copy of the License at + + http://www.apache.org/licenses/LICENSE-2.0 + + Unless required by applicable law or agreed to in writing, software + distributed under the License is distributed on an "AS IS" BASIS, WITHOUT + WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the + License for the specific language governing permissions and limitations + under the License. + +==================== +Configuring Keystone +==================== + +.. toctree:: + :maxdepth: 1 + + keystone.conf + man/keystone-manage + +Once Keystone is installed, there are a number of configuration options +available and potentially some initial data to create and set up. + +Sample data / Quick Setup +========================= + +Default sampledata is provided for easy setup and testing in bin/sampeldata. To +set up the sample data run the following command while Keystone is running:: + + $ ./bin/sampledata + +The sample data created comes from the file :doc:`sourcecode/keystone.test.sampledata` + + +Keystone Configuration File +=========================== + +Most configuration is done via configuration files. The default files are +in ``/etc/keystone.conf`` + +When starting up a Keystone server, you can specify the configuration file to +use (see :doc:`controllingservers`). +If you do **not** specify a configuration file, keystone will look in the following +directories for a configuration file, in order: + +* ``~/.keystone`` +* ``~/`` +* ``/etc/keystone`` +* ``/etc`` + +The keystone configuration file should be named ``keystone.conf``. +If you installed keystone via your operating system's +package management system, it is likely that you will have sample +configuration files installed in ``/etc/keystone``. + +In addition to this documentation page, you can check the +``etc/keystone.conf`` sample configuration +files distributed with keystone for example configuration files for each server +application with detailed comments on what each options does. + +Sample Configuration Files +-------------------------- + +Keystone ships with sample configuration files in keystone/etc. These files are: + +1. keystone.conf + + A standard configuration file for running keystone in stand-alone mode. + It has a set of default extensions loaded to support administering Keystone + over REST. It uses a local SQLite database. + +2. memcache.conf + + A configuration that uses memcached for storing tokens (but still SQLite for all + other entities). This requires memcached running. + +3. ssl.conf + + A configuration that runs Keystone with SSL (so all URLs are accessed over HTTPS). + +To run any of these configurations, use the `-c` option:: + + ./keystone -c ../etc/ssl.conf + + + +Usefule Links +------------- + +For a sample configuration file with explanations of the settings, see :doc:`keystone.conf` + +For configuring an LDAP backend, see http://mirantis.blogspot.com/2011/08/ldap-identity-store-for-openstack.html + +For configuration settings of middleware components, see :doc:`middleware` \ No newline at end of file diff --git a/docs/source/configuringservices.rst b/docs/source/configuringservices.rst new file mode 100644 index 00000000..083c3ec5 --- /dev/null +++ b/docs/source/configuringservices.rst @@ -0,0 +1,333 @@ +.. + Copyright 2011 OpenStack, LLC + All Rights Reserved. + + Licensed under the Apache License, Version 2.0 (the "License"); you may + not use this file except in compliance with the License. You may obtain + a copy of the License at + + http://www.apache.org/licenses/LICENSE-2.0 + + Unless required by applicable law or agreed to in writing, software + distributed under the License is distributed on an "AS IS" BASIS, WITHOUT + WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the + License for the specific language governing permissions and limitations + under the License. + +========================================== +Configuring Services to work with Keystone +========================================== + +.. toctree:: + :maxdepth: 1 + +Once Keystone is installed and running, services need to be configured to work +with it. These are the steps to configure a service to work with Keystone: + +1. Create or get credentials for the service to use + + A set of credentials are needed for each service (they may be + shared if you chose to). Depending on the service, these credentials are + either a username and password or a long-lived token.. + +2. Register the service, endpoints, roles and other entities + + In order for a service to have it's endpoints and roles show in the service + catalog returned by Keystone, a service record needs to be added for the + service. Endpoints and roles associated with that service can then be created. + + This can be done through the REST interface (using the OS-KSCATALOG extension) + or using keystone-manage. + +3. Install and configure middleware for the service to handle authentication + + Clients making calls to the service will pass in an authentication token. The + Keystone middleware will look for and validate that token, taking the + appropriate action. It will also retrive additional information from the token + such as user name, id, tenant name, id, roles, etc... + + The middleware will pass those data down to the service as headers. The + detailed description of this architecture is available here :doc:`middleware_architecture` + +Setting up credentials +====================== + +First admin user - bootstrapping +-------------------------------- + +For a default installation of Keystone, before you can use the REST API, you +need to create your first initial user and grant that user the right to +administer Keystone. + +For the keystone service itself, two +Roles are pre-defined in the keystone configuration file +(:doc:`keystone.conf`). + + #Role that allows admin operations (access to all operations) + keystone-admin-role = Admin + + #Role that allows acting as service (validate tokens, register service, + etc...) + keystone-service-admin-role = KeystoneServiceAdmin + +In order to create your first user, once Keystone is running use +the `keystone-manage` command: + + $ keystone-manage user add admin secrete + $ keystone-manage role add Admin + $ keystone-manage role add KeystoneServiceAdmin + $ keystone-manage role grant Admin admin + $ keystone-manage role grant KeystoneServiceAdmin admin + +This creates the `admin` user (with a password of `secrete`), creates +two roles (`Admin` and `KeystoneServiceAdmin`), and assigns those roles to +the `admin` user. From here, you should now have the choice of using the +administrative API (as well as the :doc:`man/keystone-manage` commands) to +further configure keystone. There are a number of examples of how to use +that API at :doc:`adminAPI_curl_examples`. + + +Setting up services +=================== + +Defining Services and Service Endpoints +--------------------------------------- + +Keystone also acts as a service catalog to let other OpenStack systems know +where relevant API endpoints exist for OpenStack Services. The OpenStack +Dashboard, in particular, uses this heavily - and this **must** be configured +for the OpenStack Dashboard to properly function. + +Here's how we define the services:: + + $ keystone-manage service add nova compute "Nova Compute Service" + $ keystone-manage service add glance image "Glance Image Service" + $ keystone-manage service add swift storage "Swift Object Storage Service" + $ keystone-manage service add keystone identity "Keystone Identity Service" + +Once the services are defined, we create endpoints for them. Each service +has three relevant URL's associated with it that are used in the command: + +* the public API URL +* an administrative API URL +* an internal URL + +The "internal URL" is an endpoint the generally offers the same API as the +public URL, but over a high-bandwidth, low-latency, unmetered (free) network. +You would use that to transfer images from nova to glance for example, and +not the Public URL which would go over the internet and be potentially chargeable. + +The "admin URL" is for administering the services and is not exposed or accessible +to customers without the apporpriate privileges. + +An example of setting up the endpoint for Nova:: + + $ keystone-manage endpointTemplates add RegionOne nova \ + http://nova-api.mydomain:8774/v1.1/%tenant_id% \ + http://nova-api.mydomain:8774/v1.1/%tenant_id% \ + http://nova-api.mydomain:8774/v1.1/%tenant_id% \ + 1 1 + +Glance:: + + $ keystone-manage endpointTemplates add RegionOne glance \ + http://glance.mydomain:9292/v1 \ + http://glance.mydomain:9292/v1 \ + http://glance.mydomain:9292/v1 \ + 1 1 + +Swift:: + + $ keystone-manage endpointTemplates add RegionOne swift \ + http://swift.mydomain:8080/v1/AUTH_%tenant_id% \ + http://swift.mydomain:8080/v1.0/ \ + http://swift.mydomain:8080/v1/AUTH_%tenant_id% \ + 1 1 + +And setting up an endpoint for Keystone:: + + $ keystone-manage endpointTemplates add RegionOne keystone \ + http://keystone.mydomain:5000/v2.0 \ + http://keystone.mydomain:35357/v2.0 \ + http://keystone.mydomain:5000/v2.0 \ + 1 1 + + +Defining an Administrative Service Token +---------------------------------------- + +An Administrative Service Token is a bit of arbitrary text which is configured +in Keystone and used (typically configured into) Nova, Swift, Glance, and any +other OpenStack projects, to be able to use Keystone services. + +This token is an arbitrary text string, but must be identical between Keystone +and the services using Keystone. This token is bound to a user and tenant as +well, so those also need to be created prior to setting it up. + +The *admin* user was set up above, but we haven't created a tenant for that +user yet:: + + $ keystone-manage tenant add admin + +and while we're here, let's grant the admin user the 'Admin' role to the +'admin' tenant:: + + $ keystone-manage role add Admin + $ keystone-manage role grant Admin admin admin + +Now we can create a service token:: + + $ keystone-manage token add 999888777666 admin admin 2015-02-05T00:00 + +This creates a service token of '999888777666' associated to the admin user, +admin tenant, and expires on February 5th, 2015. This token will be used when +configuring Nova, Glance, or other OpenStack services. + +Securing Communications with SSL +-------------------------------- + +To encrypt traffic between services and Keystone, see :doc:`ssl` + + +Setting up OpenStack users +========================== + +Creating Tenants, Users, and Roles +---------------------------------- + +Let's set up a 'demo' tenant:: + + $ keystone-manage tenant add demo + +And add a 'demo' user with the password 'guest':: + + $ keystone-manage user add demo guest + +Now let's add a role of "Member" and grant 'demo' user that role +as it pertains to the tenant 'demo':: + + $ keystone-manage role add Member + $ keystone-manage role grant Member demo demo + +Let's also add the admin user as an Admin role to the demo tenant:: + + $ keystone-manage role grant Admin admin demo + +Creating EC2 credentials +------------------------ + +To add EC2 credentials for the `admin` and `demo` accounts:: + + $ keystone-manage credentials add admin EC2 'admin' 'secretpassword' + $ keystone-manage credentials add admin EC2 'demo' 'secretpassword' + +If you have a large number of credentials to create, you can put them all +into a single large file and import them using :doc:`man/keystone-import`. The +format of the document looks like:: + + credentials add admin EC2 'username' 'password' + credentials add admin EC2 'username' 'password' + +Then use:: + + $ keystone-import `filename` + + +Setting Up Middleware +===================== + +Keystone Auth-Token Middleware +-------------------------------- + +The Keystone auth_token middleware is a WSGI component that can be inserted in +the WSGI pipeline to handle authenticating tokens with Keystone. See :doc:`middleware` +for details on middleware and configuration parameters. + + +Configuring Nova to use Keystone +-------------------------------- + +To configure Nova to use Keystone for authentication, the Nova API service +can be run against the api-paste file provided by Keystone. This is most +easily accomplished by setting the `--api_paste_config` flag in nova.conf to +point to `examples/paste/nova-api-paste.ini` from Keystone. This paste file +included references to the WSGI authentication middleware provided with the +keystone installation. + +When configuring Nova, it is important to create a admin service token for +the service (from the Configuration step above) and include that as the key +'admin_token' in the nova-api-paste.ini. See the documented +:doc:`nova-api-paste` file for references. + +Configuring Swift to use Keystone +--------------------------------- + +Similar to Nova, swift can be configured to use Keystone for authentication +rather than it's built in 'tempauth'. + +1. Add a service endpoint for Swift to Keystone + +2. Configure the paste file for swift-proxy (`/etc/swift/swift-proxy.conf`) + +3. Reconfigure Swift's proxy server to use Keystone instead of TempAuth. + Here's an example `/etc/swift/proxy-server.conf`:: + + [DEFAULT] + bind_port = 8888 + user = + + [pipeline:main] + pipeline = catch_errors cache keystone proxy-server + + [app:proxy-server] + use = egg:swift#proxy + account_autocreate = true + + [filter:keystone] + use = egg:keystone#tokenauth + auth_protocol = http + auth_host = 127.0.0.1 + auth_port = 35357 + admin_token = 999888777666 + delay_auth_decision = 0 + service_protocol = http + service_host = 127.0.0.1 + service_port = 8100 + service_pass = dTpw + cache = swift.cache + + [filter:cache] + use = egg:swift#memcache + set log_name = cache + + [filter:catch_errors] + use = egg:swift#catch_errors + + Note that the optional "cache" property in the keystone filter allows any + service (not just Swift) to register its memcache client in the WSGI + environment. If such a cache exists, Keystone middleware will utilize it + to store validated token information, which could result in better overall + performance. + +4. Restart swift + +5. Verify that keystone is providing authentication to Swift + +Use `swift` to check everything works (note: you currently have to create a +container or upload something as your first action to have the account +created; there's a Swift bug to be fixed soon):: + + $ swift -A http://127.0.0.1:5000/v1.0 -U joeuser -K secrete post container + $ swift -A http://127.0.0.1:5000/v1.0 -U joeuser -K secrete stat -v + StorageURL: http://127.0.0.1:8888/v1/AUTH_1234 + Auth Token: 74ce1b05-e839-43b7-bd76-85ef178726c3 + Account: AUTH_1234 + Containers: 1 + Objects: 0 + Bytes: 0 + Accept-Ranges: bytes + X-Trans-Id: tx25c1a6969d8f4372b63912f411de3c3b + +.. WARNING:: + Keystone currently allows any valid token to do anything with any account. + diff --git a/docs/source/controllingservers.rst b/docs/source/controllingservers.rst new file mode 100644 index 00000000..ba8bfc06 --- /dev/null +++ b/docs/source/controllingservers.rst @@ -0,0 +1,288 @@ +.. + Copyright 2011 OpenStack, LLC + All Rights Reserved. + + Licensed under the Apache License, Version 2.0 (the "License"); you may + not use this file except in compliance with the License. You may obtain + a copy of the License at + + http://www.apache.org/licenses/LICENSE-2.0 + + Unless required by applicable law or agreed to in writing, software + distributed under the License is distributed on an "AS IS" BASIS, WITHOUT + WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the + License for the specific language governing permissions and limitations + under the License. + +============================ +Controlling Keystone Servers +============================ + +This section describes the ways to start, stop, and reload the Keystone +services. + +Keystone Services +----------------- + +Keystone can serve a number of REST APIs and extensions on different TCP/IP +ports. + +The Service API +~~~~~~~~~~~~~~~~ + +The core Keystone +API is primarily a read-only API (the only write operation being POST /tokens +which authenticates a client, and returns a generated token). +This API is sufficient to use OpenStack if all users, roles, endpoints already +exist. This is often the case if Keystone is using an enterprise backend +and the backend is managed through other entperrise tools and business +processes. This core API is called the Service API and can be started +separately from the more complete Admin API. By default, Keystone runs +this API on port 5000. This is not an IANA assigned port and should not +be relied upon (instead, use the Admin API on port 35357 to look for +this endpoint - more on this later) + +The Service API is started using this command in the /bin directory:: + + $ ./keystone-auth + +The Admin API +~~~~~~~~~~~~~ + +Inn order for Keystone to be a fully functional service out of the box, +API extensions that provide full CRUD operations is included with Keystone. +This full set of API calls includes the OS-KSCATALOG, OS-KSADM, and OS-KSEC2 +extensions. These extensions provide a full set of create, read, update, delete +(CRUD) operations that can be used to manage Keystone objects through REST +calls. By default Keystone runs this full REST API on TCP/IP port 35357 +(assigned by IANA to Keystone). + +The Admin API is started using this command in the /bin directory:: + + $ ./keystone-admin + + +Both APIs can be loaded simultaneously (on different ports) using this command:: + + $ ./keystone + +Starting a server +----------------- + +There are two ways to start a Keystone service (either the Service API server +or the Admin API server): + +- Manually calling the server program +- Using the ``keystone-control`` server daemon wrapper program + +We recommend using the second way in production and the first for development +and debugging. + +Manually starting the server +~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +The first is by directly calling the server program, passing in command-line +options and a single argument for a ``paste.deploy`` configuration file to +use when configuring the server application. + +.. note:: + + Keystone ships with an ``etc/`` directory that contains a sample ``paste.deploy`` + configuration files that you can copy to a standard configuration directory and + adapt for your own uses. + +If you do `not` specify a configuration file on the command line, Keystone will +do its best to locate a configuration file in one of the +following directories, stopping at the first config file it finds: + +- ``$CWD`` +- ``~/.keystone`` +- ``~/`` +- ``/etc/keystone`` +- ``/etc`` + +The filename that is searched for is ``keystone.conf`` by default. + +If no configuration file is found, you will see an error, like:: + + $ keystone + ERROR: Unable to locate any configuration file. Cannot load application keystone + +Here is an example showing how you can manually start the ``keystone-auth`` server and ``keystone-registry`` in a shell:: + + $ ./keystone -d + keystone-legacy-auth: INFO ************************************************** + keystone-legacy-auth: INFO Configuration options gathered from config file: + keystone-legacy-auth: INFO /Users/ziadsawalha/Documents/Code/keystone/etc/keystone.conf + keystone-legacy-auth: INFO ================================================ + keystone-legacy-auth: INFO admin_host 0.0.0.0 + keystone-legacy-auth: INFO admin_port 35357 + keystone-legacy-auth: INFO admin_ssl False + keystone-legacy-auth: INFO backends keystone.backends.sqlalchemy + keystone-legacy-auth: INFO ca_certs /etc/keystone/ssl/certs/ca.pem + keystone-legacy-auth: INFO cert_required True + keystone-legacy-auth: INFO certfile /etc/keystone/ssl/certs/keystone.pem + keystone-legacy-auth: INFO debug True + keystone-legacy-auth: INFO default_store sqlite + keystone-legacy-auth: INFO extensions osksadm,oskscatalog,hpidm + keystone-legacy-auth: INFO hash-password True + keystone-legacy-auth: INFO keyfile /etc/keystone/ssl/private/keystonekey.pem + keystone-legacy-auth: INFO keystone-admin-role Admin + keystone-legacy-auth: INFO keystone-service-admin-role KeystoneServiceAdmin + keystone-legacy-auth: INFO log_dir . + keystone-legacy-auth: INFO log_file keystone.log + keystone-legacy-auth: INFO service-header-mappings { + 'nova' : 'X-Server-Management-Url', + 'swift' : 'X-Storage-Url', + 'cdn' : 'X-CDN-Management-Url'} + keystone-legacy-auth: INFO service_host 0.0.0.0 + keystone-legacy-auth: INFO service_port 5000 + keystone-legacy-auth: INFO service_ssl False + keystone-legacy-auth: INFO verbose False + keystone-legacy-auth: INFO ************************************************** + passlib.registry: INFO registered crypt handler 'sha512_crypt': + Starting the RAX-KEY extension + Starting the Legacy Authentication component + admin : INFO ************************************************** + admin : INFO Configuration options gathered from config file: + admin : INFO /Users/ziadsawalha/Documents/Code/keystone/etc/keystone.conf + admin : INFO ================================================ + admin : INFO admin_host 0.0.0.0 + admin : INFO admin_port 35357 + admin : INFO admin_ssl False + admin : INFO backends keystone.backends.sqlalchemy + admin : INFO ca_certs /etc/keystone/ssl/certs/ca.pem + admin : INFO cert_required True + admin : INFO certfile /etc/keystone/ssl/certs/keystone.pem + admin : INFO debug True + admin : INFO default_store sqlite + admin : INFO extensions osksadm,oskscatalog,hpidm + admin : INFO hash-password True + admin : INFO keyfile /etc/keystone/ssl/private/keystonekey.pem + admin : INFO keystone-admin-role Admin + admin : INFO keystone-service-admin-role KeystoneServiceAdmin + admin : INFO log_dir . + admin : INFO log_file keystone.log + admin : INFO service-header-mappings { + 'nova' : 'X-Server-Management-Url', + 'swift' : 'X-Storage-Url', + 'cdn' : 'X-CDN-Management-Url'} + admin : INFO service_host 0.0.0.0 + admin : INFO service_port 5000 + admin : INFO service_ssl False + admin : INFO verbose False + admin : INFO ************************************************** + Using config file: /Users/ziadsawalha/Documents/Code/keystone/etc/keystone.conf + Service API (ssl=False) listening on 0.0.0.0:5000 + Admin API (ssl=False) listening on 0.0.0.0:35357 + eventlet.wsgi.server: DEBUG (77128) wsgi starting up on http://0.0.0.0:5000/ + eventlet.wsgi.server: DEBUG (77128) wsgi starting up on http://0.0.0.0:35357/ + + $ sudo keystone-registry keystone-registry.conf & + jsuh@mc-ats1:~$ 2011-04-13 14:51:16 INFO [sqlalchemy.engine.base.Engine.0x...feac] PRAGMA table_info("images") + 2011-04-13 14:51:16 INFO [sqlalchemy.engine.base.Engine.0x...feac] () + 2011-04-13 14:51:16 DEBUG [sqlalchemy.engine.base.Engine.0x...feac] Col ('cid', 'name', 'type', 'notnull', 'dflt_value', 'pk') + 2011-04-13 14:51:16 DEBUG [sqlalchemy.engine.base.Engine.0x...feac] Row (0, u'created_at', u'DATETIME', 1, None, 0) + 2011-04-13 14:51:16 DEBUG [sqlalchemy.engine.base.Engine.0x...feac] Row (1, u'updated_at', u'DATETIME', 0, None, 0) + 2011-04-13 14:51:16 DEBUG [sqlalchemy.engine.base.Engine.0x...feac] Row (2, u'deleted_at', u'DATETIME', 0, None, 0) + 2011-04-13 14:51:16 DEBUG [sqlalchemy.engine.base.Engine.0x...feac] Row (3, u'deleted', u'BOOLEAN', 1, None, 0) + 2011-04-13 14:51:16 DEBUG [sqlalchemy.engine.base.Engine.0x...feac] Row (4, u'id', u'INTEGER', 1, None, 1) + 2011-04-13 14:51:16 DEBUG [sqlalchemy.engine.base.Engine.0x...feac] Row (5, u'name', u'VARCHAR(255)', 0, None, 0) + 2011-04-13 14:51:16 DEBUG [sqlalchemy.engine.base.Engine.0x...feac] Row (6, u'disk_format', u'VARCHAR(20)', 0, None, 0) + 2011-04-13 14:51:16 DEBUG [sqlalchemy.engine.base.Engine.0x...feac] Row (7, u'container_format', u'VARCHAR(20)', 0, None, 0) + 2011-04-13 14:51:16 DEBUG [sqlalchemy.engine.base.Engine.0x...feac] Row (8, u'size', u'INTEGER', 0, None, 0) + 2011-04-13 14:51:16 DEBUG [sqlalchemy.engine.base.Engine.0x...feac] Row (9, u'status', u'VARCHAR(30)', 1, None, 0) + 2011-04-13 14:51:16 DEBUG [sqlalchemy.engine.base.Engine.0x...feac] Row (10, u'is_public', u'BOOLEAN', 1, None, 0) + 2011-04-13 14:51:16 DEBUG [sqlalchemy.engine.base.Engine.0x...feac] Row (11, u'location', u'TEXT', 0, None, 0) + 2011-04-13 14:51:16 INFO [sqlalchemy.engine.base.Engine.0x...feac] PRAGMA table_info("image_properties") + 2011-04-13 14:51:16 INFO [sqlalchemy.engine.base.Engine.0x...feac] () + 2011-04-13 14:51:16 DEBUG [sqlalchemy.engine.base.Engine.0x...feac] Col ('cid', 'name', 'type', 'notnull', 'dflt_value', 'pk') + 2011-04-13 14:51:16 DEBUG [sqlalchemy.engine.base.Engine.0x...feac] Row (0, u'created_at', u'DATETIME', 1, None, 0) + 2011-04-13 14:51:16 DEBUG [sqlalchemy.engine.base.Engine.0x...feac] Row (1, u'updated_at', u'DATETIME', 0, None, 0) + 2011-04-13 14:51:16 DEBUG [sqlalchemy.engine.base.Engine.0x...feac] Row (2, u'deleted_at', u'DATETIME', 0, None, 0) + 2011-04-13 14:51:16 DEBUG [sqlalchemy.engine.base.Engine.0x...feac] Row (3, u'deleted', u'BOOLEAN', 1, None, 0) + 2011-04-13 14:51:16 DEBUG [sqlalchemy.engine.base.Engine.0x...feac] Row (4, u'id', u'INTEGER', 1, None, 1) + 2011-04-13 14:51:16 DEBUG [sqlalchemy.engine.base.Engine.0x...feac] Row (5, u'image_id', u'INTEGER', 1, None, 0) + 2011-04-13 14:51:16 DEBUG [sqlalchemy.engine.base.Engine.0x...feac] Row (6, u'key', u'VARCHAR(255)', 1, None, 0) + 2011-04-13 14:51:16 DEBUG [sqlalchemy.engine.base.Engine.0x...feac] Row (7, u'value', u'TEXT', 0, None, 0) + + $ ps aux | grep keystone + myuser 77148 0.0 0.0 2434892 472 s012 U+ 11:50AM 0:00.01 grep keystone + myuser 77128 0.0 0.6 2459356 25360 s011 S+ 11:48AM 0:00.82 python ./keystone -d + +Simply supply the configuration file as the first argument +and then any common options +you want to use (``-d`` was used above to show some of the debugging +output that the server shows when starting up. Call the server program +with ``--help`` to see all available options you can specify on the +command line.) + +Using ``--trace-calls`` is useful for showing a trace of calls (errors in red) +for debugging. + +For more information on configuring the server via the ``paste.deploy`` +configuration files, see the section entitled +:doc:`Configuring Keystone ` + +Note that the server `daemonizes` itself by using the standard +shell backgrounding indicator, ``&``, in the previous example. For most use cases, we recommend +using the ``keystone-control`` server daemon wrapper for daemonizing. See below +for more details on daemonization with ``keystone-control``. + +Using ``keystone-control`` to start the server +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +The second way to start up a Keystone server is to use the ``keystone-control`` +program. ``keystone-control`` is a wrapper script that allows the user to +start, stop, restart, and reload the other Keystone server programs in +a fashion that is more conducive to automation and scripting. + +Servers started via the ``keystone-control`` program are always `daemonized`, +meaning that the server program process runs in the background. + +To start a Keystone server with ``keystone-control``, simply call +``keystone-control`` with a server and the word "start", followed by +any command-line options you wish to provide. Start the server with ``keystone-control`` +in the following way:: + + $ sudo keystone-control start [CONFPATH] + +.. note:: + + You must use the ``sudo`` program to run ``keystone-control`` currently, as the + pid files for the server programs are written to /var/run/keystone/ + +Start the ``keystone-admin`` server using ``keystone-control``:: + + $ sudo keystone-control admin start + Starting keystone-admin with /etc/keystone.conf + +The same ``paste.deploy`` configuration files are used by ``keystone-control`` +to start the Keystone server programs, and you can specify (as the example above +shows) a configuration file when starting the server. + +Stopping a server +----------------- + +If you started a Keystone server manually and did not use the ``&`` backgrounding +function, simply send a terminate signal to the server process by typing +``Ctrl-C`` + +If you started the Keystone server using ``keystone-control``, you can +use the ``keystone-control`` program to stop it:: + + $ sudo keystone-control stop + +For example:: + + $ sudo keystone-control auth stop + Stopping keystone-auth pid: 77401 signal: 15 + +Restarting a server +------------------- + +Restart the Keystone server using ``keystone-control``:: + + $ sudo keystone-control admin restart /etc/keystone.conf + Stopping keystone-admin pid: 77401 signal: 15 + Starting keystone-admin with /etc/keystone.conf diff --git a/docs/source/endpoints.rst b/docs/source/endpoints.rst new file mode 100644 index 00000000..84a42e09 --- /dev/null +++ b/docs/source/endpoints.rst @@ -0,0 +1,430 @@ +.. + Copyright 2011 OpenStack, LLC + All Rights Reserved. + + Licensed under the Apache License, Version 2.0 (the "License"); you may + not use this file except in compliance with the License. You may obtain + a copy of the License at + + http://www.apache.org/licenses/LICENSE-2.0 + + Unless required by applicable law or agreed to in writing, software + distributed under the License is distributed on an "AS IS" BASIS, WITHOUT + WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the + License for the specific language governing permissions and limitations + under the License. + +================================ +Endpoints and Endpoint Templates +================================ + +.. toctree:: + :maxdepth: 1 + +What are Endpoints? +------------------- + +Simply, endpoints are URLs that point to OpenStack services. When you +authenticate to Keystone you get back a token which has a service catalog in +it. The service catalog is basically a list of the OpenStack services that +you have access to and the URLs you can use to get to them; their endpoints. + +Here is an example response from Keystone when you authenticate:: + + { + "access":{ + "token":{ + "id":"ab48a9efdfedb23ty3494", + "expires":"2010-11-01T03:32:15-05:00", + "tenant":{ + "id": "t1000", + "name": "My Project" + } + }, + "user":{ + "id":"u123", + "name":"jqsmith", + "roles":[{ + "id":"100", + "name":"compute:admin" + }, + { + "id":"101", + "name":"object-store:admin", + "tenantId":"t1000" + } + ], + "roles_links":[] + }, + "serviceCatalog":[{ + "name":"Nova", + "type":"compute", + "endpoints":[{ + "tenantId":"t1000", + "publicURL":"https://compute.north.host.com/v1/t1000", + "internalURL":"https://compute.north.internal/v1/t1000", + "region":"North", + "versionId":"1", + "versionInfo":"https://compute.north.host.com/v1/", + "versionList":"https://compute.north.host.com/" + }, + { + "tenantId":"t1000", + "publicURL":"https://compute.north.host.com/v1.1/t1000", + "internalURL":"https://compute.north.internal/v1.1/t1000", + "region":"North", + "versionId":"1.1", + "versionInfo":"https://compute.north.host.com/v1.1/", + "versionList":"https://compute.north.host.com/" + } + ], + "endpoints_links":[] + }, + { + "name":"Swift", + "type":"object-store", + "endpoints":[{ + "tenantId":"t1000", + "publicURL":"https://storage.north.host.com/v1/t1000", + "internalURL":"https://storage.north.internal/v1/t1000", + "region":"North", + "versionId":"1", + "versionInfo":"https://storage.north.host.com/v1/", + "versionList":"https://storage.north.host.com/" + }, + { + "tenantId":"t1000", + "publicURL":"https://storage.south.host.com/v1/t1000", + "internalURL":"https://storage.south.internal/v1/t1000", + "region":"South", + "versionId":"1", + "versionInfo":"https://storage.south.host.com/v1/", + "versionList":"https://storage.south.host.com/" + } + ] + }, + { + "name":"DNS-as-a-Service", + "type":"dnsextension:dns", + "endpoints":[{ + "tenantId":"t1000", + "publicURL":"https://dns.host.com/v2.0/t1000", + "versionId":"2.0", + "versionInfo":"https://dns.host.com/v2.0/", + "versionList":"https://dns.host.com/" + } + ] + } + ] + } + } + +Note the following about this response: + +#. There are two endpoints given to the Nova compute service. The only + difference between them is the version (1.0 vs. 1.1). This allows for code + written to look for the version 1.0 endpoint to still work even after the 1.1 + version is released. + +#. There are two endpoints for the Swift object-store service. The difference + between them is they are in different regions (North and South). + +#. Note the DNS service is global; it does not have a Region. Also, since DNS + is not a core OpenStack service, the endpoint type is "dnsextension:dns" + showing it is coming from an extension to the Keystone service. + +#. The Region, Tenant, and versionId are listed under the endpoint. You do not + (and should not) have to parse those out of the URL. In fact, they may not be + embedded in the URL if the service developer so chooses. + + +What do the fields in an Endpoint mean? +--------------------------------------- + +The schema definition for an endpoint is in endpoints.xsd under +keystone/content/common/xsd in the Keystone code repo. The fields are: + +id + A unique ID for the endpoint. + +type + The OpenStack-registered type (ex. 'compute', 'object-store', 'image service') + This can also be extended using the OpenStack Extension mechanism to support + non-core services. Extended services will be in the form ``extension:type`` + (e.g. ``dnsextension:dns``) + +name + This can be anything that the operator of OpenStack chooses. It could be a + brand or marketing name (ex. Rackspace Cloud Servers). + +region + This is a string that identifies the region where this endpoint exists. + Examples are 'North America', 'Europe', 'Asia'. Or 'North' and 'South'. Or + 'Data Center 1', 'Data Center 2'. + The list of regions and what a region means is decided by the operator. The + spec treats them as opaque strings. + +publicURL + This is the URL to use to access that endpoint over the internet. + +internalURL + This is the URL to use to communicate between services. This is genenrally + a way to communicate between services over a high bandwidth, low latency, + unmetered (free, no bandwidth charges) network. An example would be if you + want to access a swift cluster from inside your Nova VMs and want to make + sure the communication stays local and does not go over a public network + and rack up your bandwidth charges. + +adminURL + This is the URL to use to administer the service. In Keystone, this URL + is only shown to users with the appropriate rights. + +tenantId + If an endpoint is specific to a tenant, the tenantId field identifies the + tenant that URL applies to. Some operators include the tenant in the + URLs for a service, while others may provide one endpoint and use some + other mechanism to identify the tenant. This field is therefore optional. + Having this field also means you do not have to parse the URL to identify + a tenant if the operator includes it in the URL. + +versionId + This identifies the version of the API contract that endpoint supports. + While many APIs include the version in the URL (ex: https://compute.host/v1), + this field allows you to identify the version without parsing the URL. It + therefore also allows operators and service developers to publish endpoints + that do not have versions embedded in the URL. + +versionInfo + This is the URL to call to get some information on the version. This returns + information in this format:: + + { + "version": { + "id": "v2.0", + "status": "CURRENT", + "updated": "2011-01-21T11:33:21-06:00", + "links": [ + { + "rel": "self", + "href": "http://identity.api.openstack.org/v2.0/" + }, { + "rel": "describedby", + "type": "application/pdf", + "href": "http://docs.openstack.org/identity/api/v2.0/identity-latest.pdf" + }, { + "rel": "describedby", + "type": "application/vnd.sun.wadl+xml", + "href": "http://docs.openstack.org/identity/api/v2.0/identity.wadl" + } + ], + "media-types": [ + { + "base": "application/xml", + "type": "application/vnd.openstack.identity+xml;version=2.0" + }, { + "base": "application/json", + "type": "application/vnd.openstack.identity+json;version=2.0" + } + ] + } + } + +versionList + + This is the URL to call to find out which versions are supported at that + endpoint. The response is in this format:: + + { + "versions":[{ + "id":"v1.0", + "status":"DEPRECATED", + "updated":"2009-10-09T11:30:00Z", + "links":[{ + "rel":"self", + "href":"http://identity.api.openstack.org/v1.0/" + } + ] + }, + { + "id":"v1.1", + "status":"CURRENT", + "updated":"2010-12-12T18:30:02.25Z", + "links":[{ + "rel":"self", + "href":"http://identity.api.openstack.org/v1.1/" + } + ] + }, + { + "id":"v2.0", + "status":"BETA", + "updated":"2011-05-27T20:22:02.25Z", + "links":[{ + "rel":"self", + "href":"http://identity.api.openstack.org/v2.0/" + } + ] + } + ], + "versions_links":[] + } + + Here, the response shows that the endpoint supports version 1.0, 1.1, and 2.0. + It also shows that 1.0 is in DEPRECTAED status and 2.0 is in BETA. + +What are Endpoint Templates? +---------------------------- + +Endpoint Templates are a way for an administrator to manage endpoints en masse. +They provide a way to define Endpoints that apply to many or all tenants +without having to a create each endpoint on each tenant manually. Without +Endpoint Templates, if I wanted to create Endpoints for each tenant in my +OpenStack deployment, I'd have to manually create a bunch of endpoints on +each tenant (probably when I created the tenant). And then I'd have to go change +them all whenever a service changed versions or I added a new service. + +To provide a simpler mechanism to manage endpoints on tenants, Keystone uses +Endpoint Templates. I can, for example, define a template with parametrized URLs +and set it's `global` to true and that will show up as an endpoint on all the tenants +I have. Here is an example: + +Define a global Endpoint Template:: + + $ ./keystone-manage endpointTemplates add North nova https://compute.north.example.com/v1/%tenant_id%/ https://compute.north.example.corp/v1/ https://compute.north.example.local/v1/%tenant_id%/ 1 1 + + The arguments are: object_type action 'region' 'service_name' 'publicURL' 'adminURL' 'internalURL' 'enabled' 'global' + +This creates a global endpoint (global means it gets applied to all tenants automatically). + +Now, when a user authenticates, they get that endpoint in their service catalog. Here's an example +authentication request for use against tenant 1:: + + $ curl -H "Content-type: application/json" -d '{"auth":{"passwordCredentials":{"username":"joeuser","password":"secrete"}, "tenantId": "1"}}' http://localhost:5000/v2.0/tokens + +The response is:: + + { + "access": { + "serviceCatalog": [ + { + "endpoints": [ + { + "internalURL": "https://compute.north.example.local", + "publicURL": "https://compute.north.example.com/v1/1/", + "region": "North" + } + ], + "name": "nova", + "type": "compute" + } + ], + "token": { + "expires": "2012-02-05T00:00:00", + "id": "887665443383838", + "tenant": { + "id": "1", + "name": "customer-x" + } + }, + "user": { + "id": "1", + "name": "joeuser", + "roles": [ + { + "id": "3", + "name": "Member", + "tenantId": "1" + } + ] + } + } + } + +Notice the adminURL is not showing (this user is a regular user and does not +have rights to see the adminURL) and the tenant ID has been substituted in the +URL:: + + "publicURL": "https://compute.north.example.com/v1/1/", + +This endpoint will show up for all tenants. The OpenStack administrator does +not need to create the endpoint manually. + +.. note:: Endpoint Templates are not part of the core Keystone API (but Endpoints are). + + +What parameters can I use in a Template URL +------------------------------------------- + +Currently the only parameterization available is %tenant_id% which gets +substituted by the Tenant ID. + + +Endpoint Template Types: Global or not +-------------------------------------- + +When the global flag is set to true on an Endpoint Template, it means it should +be available to all tenants. Whenever someone authenticates to a tenant, they +will see the Endpoint generated by that template. + +When the global flag is not set, the template only shows up when it is added to +a tenant manually. To add an endpoint to a tenant manually, you must create +the Endpoint and supply the Endpoint Template ID: + +Create the Endpoint Template:: + + $ ./keystone-manage endpointTemplates add West nova https://compute.west.example.com/v1/%tenant_id%/ https://compute.west.example.corp https://compute.west.example.local 1 0 + + Note the 0 at the end - this Endpoint Template is not global. So it will not show up for users authenticating. + +Find the Endpoint Template ID:: + + $ ./keystone-manage endpointTemplates list + + All EndpointTemplates + id service type region enabled is_global Public URL Admin URL + ------------------------------------------------------------------------------- + 15 nova compute North True True https://compute.north.example.com/v1/%tenant_id%/ https://compute.north.example.corp + 16 nova compute West True False https://compute.west.example.com/v1/%tenant_id%/ https://compute.west.example.corp + +Add the Endpoint to the tenant:: + + $ ./keystone-manage endpoint add customer-x 16 + +Now, when the user authenticates, they get the endpoint:: + + { + "internalURL": "https://compute.west.example.local", + "publicURL": "https://compute.west.example.com/v1/1/", + "region": "West" + } + +Who can see the AdminURL? +------------------------- + +Users who have the Keystone `Admin` or `Service Admin` roles will see the +AdminURL when they authenticate or when they retrieve token information: + +Using an administrator token to authenticate, GET a client token's endpoints:: + + $ curl -H "X-Auth-Token: 999888777666" http://localhost:35357/v2.0/tokens/887665443383838/endpoints + + { + "endpoints": [ + { + "adminURL": "https://compute.west.example.corp", + "id": 6, + "internalURL": "https://compute.west.example.local", + "name": "nova", + "publicURL": "https://compute.west.example.com/v1/1/", + "region": "West", + "tenantId": 1, + "type": "compute" + } + ], + "endpoints_links": [ + { + "href": "http://127.0.0.1:35357/tokens/887665443383838/endpoints?marker=6&limit=10", + "rel": "next" + } + ] + } diff --git a/docs/source/extensions.rst b/docs/source/extensions.rst new file mode 100644 index 00000000..539bef39 --- /dev/null +++ b/docs/source/extensions.rst @@ -0,0 +1,183 @@ +.. + Copyright 2011 OpenStack, LLC + All Rights Reserved. + + Licensed under the Apache License, Version 2.0 (the "License"); you may + not use this file except in compliance with the License. You may obtain + a copy of the License at + + http://www.apache.org/licenses/LICENSE-2.0 + + Unless required by applicable law or agreed to in writing, software + distributed under the License is distributed on an "AS IS" BASIS, WITHOUT + WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the + License for the specific language governing permissions and limitations + under the License. + +========== +Extensions +========== + +Extensions support adding features and functions to OpenStack APIs at any time, without prior +approval or waiting for a new API and release cycles. + +The extension framework is in development and documented in extensions_ and extensionspresentation_. + +This document describes the extensions included with Keystone, how to enable and disable them, +and briefly touches on how to write your own extensions. + +.. _extensions: http://docs.openstack.org/trunk/openstack-compute/developer/openstack-api-extensions/content/ch02s01.html +.. _extensionspresentation: http://www.slideshare.net/RackerWilliams/openstack-extensions + +Built-in Extensions +------------------- + +Keystone ships with a number of extensions found under the +``keystone/contib/extensions`` folder. + +The following built-in extensions are included: + +OS-KSADM + + This is an extensions that supports managing users, tenants, and roles + through the API. Without this extensions, the ony way to manage those + objects is through keystone-manage or directly in the underlying database. + + This is an Admin API extension only. + +OS-KSCATALOG + + This extensions supports managing Endpoints and prrovides the Endpoint + Template mechanism for managing bulk endpoints. + + This is an Admin API extension only. + +OS-EC2 + + This extension adds support for EC2 credentials. + + This is an Admin and Service API extension. + +RAX-GRP + + This extension adds functionality the enables groups. + + This is an Admin and Service API extension. + +RAX-KEY + + This extensions adds support for authentication with an API Key (the core + Keystone API only supports username/password credentials) + + This is an Admin and Service API extension. + +HP-IDM + + This extension adds capability to filter roles with optional service IDs + for token validation to mitigate security risks with role name conflicts. + See https://bugs.launchpad.net/keystone/+bug/890411 for more details. + + This is an Admin API extension. Applicable to validate token (GET) + and check token (HEAD) APIs only. + +OS-KSVALIDATE + + This extensions supports admin calls to /tokens without having to specify + the token ID in the URL. Instead, the ID is supplied in a header called + X-Subject-Token. This is provided as an alternative to address any security + concerns that arise when token IDs are passed as part of the URL which is + often (and by default) logged to insecure media. + + This is an Admin API extension only. + +.. note:: + + The included extensions are in the process of being rewritten. Currently + osksadm, oskscatalog, hpidm, and osksvalidate work with this new + extensions design. + + +Enabling & Disabling Extensions +------------------------------- + +The Keystone conf file has a property called extensions. This property holds +the list of supported extensions that you want enabled. If you want to +add/remove an extension from being supported, add/remove the extension key +from this property. The key is the name of the folder of the extension +under the keystone/contrib/extensions folder. + +.. note:: + + If you want to load different extensions in the service API than the Admin API + you need to use different config files. + +Creating New Extensions +----------------------- + +#. **Adopt a unique organization abbreviation.** + + This prefix should uniquely identify your organization within the community. + The goal is to avoid schema and resource collisions with similiar extensions. + (e.g. ``OS`` for OpenStack, ``RAX`` for Rackspace, or ``HP`` for Hewlett-Packard) + +#. **Adopt a unique extension abbreviation.** + + Select an abbreviation to identify your extension, and append to + your organization prefix using a hyphen (``-``), by convention + (e.g. ``OS-KSADM`` (for OpenStack's Keystone Administration extension). + + This combination is referred to as your extension's prefix. + +#. **Determine the scope of your extension.** + + Extensions can enhance the Admin API, Service API or both. + +#. **Create a new module.** + + Create a module to isolate your namespace based on the extension prefix + you selected:: + + keystone/contrib/extensions/admin + + ... and/or:: + + keystone/contrib/extensions/service/ + + ... based on which API you are enhancing. + + .. note:: + + In the future, we will support loading external extensions. + +#. Add static extension files for JSON (``*.json``) and XML + (``*.xml``) to the new extension module. + + Refer to `Service Guide `_ + `Sample extension XML `_ + `Sample extension JSON `_ for the the content and structure. + +#. If your extension is adding additional methods override the base class + ``BaseExtensionHandler``, name it ``ExtensionHandler``, and add your methods. + +#. **Document your work.** + + Provide documentation to support your extension. + + Extensions documentation, WADL, and XSD files can be stored in the + ``keystone/content`` folder. + +#. Add your extension name to the list of supported extensions in The + ``keystone.conf`` file. + +Which extensions are enabled? +----------------------------- + +Discover which extensions are available (service API):: + + curl http://localhost:5000/v2.0/extensions + +... or (admin API):: + + curl http://localhost:35357/v2.0/extensions + +The response will list the extensions available. diff --git a/docs/source/images/305.svg b/docs/source/images/305.svg new file mode 100644 index 00000000..7d79464e --- /dev/null +++ b/docs/source/images/305.svg @@ -0,0 +1,158 @@ + + + + + + + + + + image/svg+xml + + + + + + + + Request + service directly + + + Auth + Component + 305 + Use proxy to + redirect to Auth + + + + + + + OpenStack + Service + + + diff --git a/docs/source/images/authComp.svg b/docs/source/images/authComp.svg new file mode 100644 index 00000000..d344b871 --- /dev/null +++ b/docs/source/images/authComp.svg @@ -0,0 +1,174 @@ + + + + + + + + + + image/svg+xml + + + + + + + + + + Auth + Component + + + OpenStack + Service + + + + + + + Reject + unauthenticated + requests + Forward + authenticated + requests + + + diff --git a/docs/source/images/both.svg b/docs/source/images/both.svg new file mode 100644 index 00000000..d29872a4 --- /dev/null +++ b/docs/source/images/both.svg @@ -0,0 +1,135 @@ + + + + + + + + + + image/svg+xml + + + + + + + + + + Auth + Component + + Auth + Component + + + OpenStack + Service + + + + + diff --git a/docs/source/images/graphs_305.svg b/docs/source/images/graphs_305.svg new file mode 100644 index 00000000..1dff61a6 --- /dev/null +++ b/docs/source/images/graphs_305.svg @@ -0,0 +1,41 @@ + + + + + + +Handle305 + + +AuthComp + +Auth +Component + + +Service + +OpenStack +Service + + + +Service:n->AuthComp:n + + +305 Use Proxy +To Redirect to Auth + + + +Start:sw->Service + + +Request +Service Directly + + + diff --git a/docs/source/images/graphs_authComp.svg b/docs/source/images/graphs_authComp.svg new file mode 100644 index 00000000..6be629c1 --- /dev/null +++ b/docs/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/docs/source/images/graphs_authCompDelegate.svg b/docs/source/images/graphs_authCompDelegate.svg new file mode 100644 index 00000000..4788829a --- /dev/null +++ b/docs/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/docs/source/images/graphs_both.svg b/docs/source/images/graphs_both.svg new file mode 100644 index 00000000..6aa87612 --- /dev/null +++ b/docs/source/images/graphs_both.svg @@ -0,0 +1,36 @@ + + + + + + +Both + + +AuthComp + +Auth +Component + + +Together + + + +Auth +Component + + +OpenStack +Service + + +AuthComp->Together:OStack:n + + + + + diff --git a/docs/source/images/graphs_delegate_accept.svg b/docs/source/images/graphs_delegate_accept.svg new file mode 100644 index 00000000..1d86cadf --- /dev/null +++ b/docs/source/images/graphs_delegate_accept.svg @@ -0,0 +1,52 @@ + + + + + + +DelegateAcceptAuth + + + +AuthComp + +Auth +Component + + +Start->AuthComp + + +Authorization: Basic VTpQ + + +AuthComp->Start + + +200 Okay + + +Service + +OpenStack +Service + + +AuthComp->Service + + +Authorization: Basic dTpw +X-Authorization: Proxy U +X-Identity-Status: Confirmed + + +Service->AuthComp + + +200 Okay + + + diff --git a/docs/source/images/graphs_delegate_forbiden_basic.svg b/docs/source/images/graphs_delegate_forbiden_basic.svg new file mode 100644 index 00000000..dcd62b77 --- /dev/null +++ b/docs/source/images/graphs_delegate_forbiden_basic.svg @@ -0,0 +1,53 @@ + + + + + + +DelegateRejectForbidden + + + +AuthComp + +Auth +Component + + +Start->AuthComp + + +Authorization: Basic VTpQ + + +AuthComp->Start + + +403 Forbidden + + +Service + +OpenStack +Service + + +AuthComp->Service + + +Authorization: Basic dTpw +X-Authorization: Proxy U +X-Identity-Status: Confirmed + + +Service->AuthComp + + +403 Forbidden +WWW-Authenticate: Delegated + + + diff --git a/docs/source/images/graphs_delegate_forbiden_proxy.svg b/docs/source/images/graphs_delegate_forbiden_proxy.svg new file mode 100644 index 00000000..df53212b --- /dev/null +++ b/docs/source/images/graphs_delegate_forbiden_proxy.svg @@ -0,0 +1,52 @@ + + + + + + +DelegateForbiddnProxy + + + +AuthComp + +Auth +Component + + +Start->AuthComp + + +Authorization: Basic VTpQ + + +AuthComp->Start + + +500 Internal Error + + +Service + +OpenStack +Service + + +AuthComp->Service + + +Authorization: Basic dTpw +X-Authorization: Proxy U +X-Identity-Status: Confirmed + + +Service->AuthComp + + +403 Forbidden + + + diff --git a/docs/source/images/graphs_delegate_reject_basic.svg b/docs/source/images/graphs_delegate_reject_basic.svg new file mode 100644 index 00000000..a33ea095 --- /dev/null +++ b/docs/source/images/graphs_delegate_reject_basic.svg @@ -0,0 +1,55 @@ + + + + + + +DelegateRejectAuthBasic + + + +AuthComp + +Auth +Component + + +Start->AuthComp + + +Authorization: Basic Yjpw + + +AuthComp->Start + + +401 Unauthorized +WWW-Authenticate: Basic +Realm="API Realm" + + +Service + +OpenStack +Service + + +AuthComp->Service + + +Authorization: Basic dTpw +X-Authorization: Proxy b +X-Identity-Status: Indeterminate + + +Service->AuthComp + + +401 Unauthorized +WWW-Authenticate: Delegated + + + diff --git a/docs/source/images/graphs_delegate_reject_oauth.svg b/docs/source/images/graphs_delegate_reject_oauth.svg new file mode 100644 index 00000000..760adeb6 --- /dev/null +++ b/docs/source/images/graphs_delegate_reject_oauth.svg @@ -0,0 +1,56 @@ + + + + + + +DelegateRejectAuthOAuth + + + +AuthComp + +Auth +Component + + +Start->AuthComp + + +Authorization: OAuth 000-999-222 + + +AuthComp->Start + + +401 Unauthorized +WWW-Authenticate: OAuth +Realm=’API Realm’, +Error=’invalid-token’ + + +Service + +OpenStack +Service + + +AuthComp->Service + + +Authorization: Basic dTpw +X-Authorization: Proxy +X-Identity-Status: Indeterminate + + +Service->AuthComp + + +401 Unauthorized +WWW-Authenticate: Delegated + + + diff --git a/docs/source/images/graphs_delegate_unimplemented.svg b/docs/source/images/graphs_delegate_unimplemented.svg new file mode 100644 index 00000000..8c4fdc6b --- /dev/null +++ b/docs/source/images/graphs_delegate_unimplemented.svg @@ -0,0 +1,53 @@ + + + + + + +DelegateUnimplemented + + + +AuthComp + +Auth +Component + + +Start->AuthComp + + +Authorization: Basic VTpQ + + +AuthComp->Start + + +500 Internal Error + + +Service + +OpenStack +Service + + +AuthComp->Service + + +Authorization: Basic dTpw +X-Authorization: Proxy U +X-Identity-Status: Confirmed + + +Service->AuthComp + + +501 Unimplemented +WWW-Authenticate: Delegated + + + diff --git a/docs/source/images/graphs_mapper.svg b/docs/source/images/graphs_mapper.svg new file mode 100644 index 00000000..52c6c55b --- /dev/null +++ b/docs/source/images/graphs_mapper.svg @@ -0,0 +1,73 @@ + + + + + + +Mapper + + + +Mapper + +Mapper + + +Start->Mapper + + + + +Auths + + + +Auth1 + + +Auth2 + + +Auth3 + + +Mapper:sw->Auths:auth1 + + + + +Mapper:s->Auths:auth2 + + + + +Mapper:se->Auths:auth3 + + + + +Service + +OpenStack +Service + + +Auths:auth1->Service + + + + +Auths:auth2->Service + + + + +Auths:auth3->Service + + + + + diff --git a/docs/source/images/graphs_proxyAuth.svg b/docs/source/images/graphs_proxyAuth.svg new file mode 100644 index 00000000..7b94b077 --- /dev/null +++ b/docs/source/images/graphs_proxyAuth.svg @@ -0,0 +1,51 @@ + + + + + + +ProxyAuth + + + +AuthComp + +Auth +Component + + +Start->AuthComp + + +Authorization: Basic VTpQ + + +AuthComp:w->Start + + +500 Internal Error + + +Service + +OpenStack +Service + + +AuthComp->Service + + +Authorization: Basic dTpw +X-Authorization: Proxy U + + +Service:w->AuthComp + + +403 Forbidden + + + diff --git a/docs/source/images/graphs_separate.svg b/docs/source/images/graphs_separate.svg new file mode 100644 index 00000000..376e5988 --- /dev/null +++ b/docs/source/images/graphs_separate.svg @@ -0,0 +1,30 @@ + + + + + + +Seperate + + +AuthComp + +Auth +Component + + +Service + +OpenStack +Service + + +AuthComp->Service + + + + + diff --git a/docs/source/images/graphs_standard_accept.svg b/docs/source/images/graphs_standard_accept.svg new file mode 100644 index 00000000..bddf4b5f --- /dev/null +++ b/docs/source/images/graphs_standard_accept.svg @@ -0,0 +1,51 @@ + + + + + + +StandardAcceptAuth + + + +AuthComp + +Auth +Component + + +Start->AuthComp + + +Authorization: Basic VTpQ + + +AuthComp->Start + + +200 Okay + + +Service + +OpenStack +Service + + +AuthComp->Service + + +Authorization: Basic dTpw +X-Authorization: Proxy U + + +Service->AuthComp + + +200 Okay + + + diff --git a/docs/source/images/graphs_standard_reject.svg b/docs/source/images/graphs_standard_reject.svg new file mode 100644 index 00000000..6020ad67 --- /dev/null +++ b/docs/source/images/graphs_standard_reject.svg @@ -0,0 +1,39 @@ + + + + + + +StandardRejectAuth + + + +AuthComp + +Auth +Component + + +Start->AuthComp + + +Authorization: Basic Yjpw + + +AuthComp->Start + + +401 Unauthorized +WWW-Authenticate: Basic Realm="API Realm" + + +Service + +OpenStack +Service + + + diff --git a/docs/source/images/graphs_together.svg b/docs/source/images/graphs_together.svg new file mode 100644 index 00000000..1425a28b --- /dev/null +++ b/docs/source/images/graphs_together.svg @@ -0,0 +1,24 @@ + + + + + + +Together + + +Together + + +Auth +Component + + +OpenStack +Service + + + diff --git a/docs/source/images/images_layouts.svg b/docs/source/images/images_layouts.svg new file mode 100644 index 00000000..e7fe7a95 --- /dev/null +++ b/docs/source/images/images_layouts.svg @@ -0,0 +1,200 @@ + + + + + + image/svg+xml + + + + + + + + Auth Layouts + (a) + (b) + + + Together + + + + Together + + + Auth + Component + + + OpenStack + Service + + + + Seperate + + + + AuthComp + + Auth + Component + + + + Service + + OpenStack + Service + + + + AuthComp->Service + + + + + diff --git a/docs/source/images/layouts.svg b/docs/source/images/layouts.svg new file mode 100644 index 00000000..fdf61b7d --- /dev/null +++ b/docs/source/images/layouts.svg @@ -0,0 +1,215 @@ + + + + + + + + + + image/svg+xml + + + + + + + + + + Auth + Component + + + OpenStack + Service + + + Option + ( + b + ) + + + Auth + Component + + + OpenStack + Service + Option + ( + a + ) + + + + diff --git a/docs/source/images/mapper.svg b/docs/source/images/mapper.svg new file mode 100644 index 00000000..b5a2b7b1 --- /dev/null +++ b/docs/source/images/mapper.svg @@ -0,0 +1,237 @@ + + + + + + + + + + image/svg+xml + + + + + + + + + + OpenStack + Service + + + + + + + + + + + + + + + Mapper + + + Auth + 1 + + + Auth + 2 + + + Auth + 3 + + + + + diff --git a/docs/source/images/proxyAuth.svg b/docs/source/images/proxyAuth.svg new file mode 100644 index 00000000..f60b40d8 --- /dev/null +++ b/docs/source/images/proxyAuth.svg @@ -0,0 +1,238 @@ + + + + + + + + + + image/svg+xml + + + + + + + + Authorization + : + Basic dTpw + X + - + Authorization + : + Proxy U + Authorization + : + Basic VTpQ + 500 + Internal Error + 403 + Proxy Unauthorized + + + + + Auth + Component + + + + + OpenStack + Service + + + + + + + diff --git a/docs/source/middleware.rst b/docs/source/middleware.rst new file mode 100644 index 00000000..69506ee2 --- /dev/null +++ b/docs/source/middleware.rst @@ -0,0 +1,169 @@ +.. + Copyright 2011 OpenStack, LLC + All Rights Reserved. + + Licensed under the Apache License, Version 2.0 (the "License"); you may + not use this file except in compliance with the License. You may obtain + a copy of the License at + + http://www.apache.org/licenses/LICENSE-2.0 + + Unless required by applicable law or agreed to in writing, software + distributed under the License is distributed on an "AS IS" BASIS, WITHOUT + WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the + License for the specific language governing permissions and limitations + under the License. + +========== +Middleware +========== + +The Keystone middleware sits in front of an OpenStack service and handles authenticating +incoming requests. The middleware was designed according to `this spec`. + +The middleware is found in source under Keystone/middleware. + +The middleware supports two interfaces; WSGI and REST/HTTP. + +.. _`this spec`: http://wiki.openstack.org/openstack-authn + +REST & HTTP API +=============== + +If an unauthenticated call comes in, the middleware will respond with a 401 Unauthorized error. As per +HTTP standards, it will also return a WWW-Authenticate header informing the caller +of what protocols are supported. For Keystone authentication, the response syntax will be:: + + WWW-Authenticate: Keystone uri="url to Keystone server" + +The client can then make the necessary calls to the Keystone server, obtain a token, and retry the call with the token. + +The token is passed in using ther X-Auth-Token header. + +WSGI API (Headers) +================== + +Upon successful authentication the middleware sends the following +headers to the downstream WSGI app: + +X-Identity-Status + Provides information on whether the request was authenticated or not. + +X-Tenant + Provides the tenant ID (as it appears in the URL in Keystone). This is to support any legacy implementations before Keystone switched to an ID/Name schema for tenants. + +X-Tenant-Id + The unique, immutable tenant Id + +X-Tenant-Name + The unique, but mutable (it can change) tenant name. + +X-User-Id + The user id of the user used to log in + +X-User-Name + The username used to log in + +X-User + The username used to log in. This is to support any legacy implementations before Keystone switched to an ID/Name schema for tenants. + +X-Roles + The roles associated with that user + + +Configuration +============= + +The middleware is configured within the config file of the main application as +a WSGI component. Example for the auth_token middleware:: + + [app:myService] + paste.app_factory = myService:app_factory + + [pipeline:main] + pipeline = + tokenauth + myService + + [filter:tokenauth] + paste.filter_factory = keystone.middleware.auth_token:filter_factory + auth_host = 127.0.0.1 + auth_port = 35357 + auth_protocol = http + auth_uri = http://127.0.0.1:5000/ + admin_token = 999888777666 + ;Uncomment next line and check ip:port to use memcached to cache token requests + ;memcache_hosts = 127.0.0.1:11211 + +*The required configuration entries are:* + +auth_host + The IP address or DNS name of the Keystone server + +auth_port + The TCP/IP port of the Keystone server + +auth_protocol + The protocol of the Keystone server ('http' or 'https') + +auth_uri + The externally accessible URL of the Keystone server. This will be where unauthenticated + clients are redirected to. This is in the form of a URL. For example, if they make an + unauthenticated call, they get this response:: + + HTTP/1.1 401 Unauthorized + Www-Authenticate: Keystone uri='https://auth.example.com/' + Content-Length: 381 + + In this case, the auth_uri setting is set to https://auth.example.com/ + +admin_token + This is the long-lived token issued to the service to authenticate itself when calling + Keystone. See :doc:`configuration` for more information on setting this up. + + +*Optional parameters are:* + +delay_auth_decision + Whether the middleware should reject invalid or unauthenticated calls directly or not. If not, + it will send all calls down to the service to decide, but it will set the HTTP-X-IDENTITY-STATUS + header appropriately (set to'Confirmed' or 'Indeterminate' based on validation) and the + service can then decide if it wants to honor the call or not. This is useful if the service offers + some resources publicly, for example. + +auth_timeout + The amount of time to wait before timing out a call to Keystone (in seconds) + +memcache_hosts + This is used to point to a memcached server (in ip:port format). If supplied, + the middleware will cache tokens and data retrieved from Keystone in memcached + to minimize calls made to Keystone and optimize performance. + +.. warning:: + Tokens are cached for the duration of their validity. If they are revoked eariler in Keystone, + the service will not know and will continue to honor the token as it has them stored in memcached. + Also note that tokens and data stored in memcached are not encrypted. The memcached server must + be trusted and on a secure network. + + +*Parameters needed in a distributed topology.* In this configuration, the middleware is running +on a separate machine or cluster than the protected service (not common - see :doc:`middleware_architecture` +for details on different deployment topologies): + +service_host + The IP address or DNS name of the location of the service (since it is remote + and not automatically down the WSGI chain) + +service_port + The TCP/IP port of the remote service. + +service_protocol + The protocol of the service ('http' or 'https') + +service_pass + The basic auth password used to authenticate to the service (so the service + knows the call is coming from a server that has validated the token and not from + an untrusted source or spoofer) + +service_timeout + The amount of time to wait for the service to respond before timing out. diff --git a/docs/source/middleware_architecture.rst b/docs/source/middleware_architecture.rst new file mode 100644 index 00000000..a8c38f3c --- /dev/null +++ b/docs/source/middleware_architecture.rst @@ -0,0 +1,529 @@ +.. + Copyright 2011 OpenStack, LLC + All Rights Reserved. + + Licensed under the Apache License, Version 2.0 (the "License"); you may + not use this file except in compliance with the License. You may obtain + a copy of the License at + + http://www.apache.org/licenses/LICENSE-2.0 + + Unless required by applicable law or agreed to in writing, software + distributed under the License is distributed on an "AS IS" BASIS, WITHOUT + WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the + License for the specific language governing permissions and limitations + under the License. + +======================= +Middleware Architecture +======================= + +Abstract +======== + +The Keystone middleware architecture supports multiple authentication protocols +in a pluggable manner in OpenStack. By providing support for authentication via +pluggable authentication components, this architecture allows OpenStack +services to be integrated easily into existing deployment environments. It also +provides a path by which to implement support for emerging authentication +standards such as OAUTH. + +Rationale and Goals +=================== + +Keystone is the Identity service for OpenStack. To support the easy integrating +of OpenStack with existing authentication and identity management systems, +Keystone supports talking to multiple backends like LDAP. +And to support different deployment needs, it can support multiple +authentication protocols via pluggable 'authentication components' implemented +as WSGI middleware. + +In this document, we describe the responsibilities of the authentication +middleware. We describe how these interact with underlying OpenStack services +and how existing services can be modified to take advantage of pluggable +authentication. The goal is to allow OpenStack services to be integrated easily +into existing deployment environments and to provide a path by which to +implement support for emerging authentication standards such as OAUTH. + +Specification Overview +====================== + +'Authentication' is the process of determining that users are who they say they +are. Typically, 'authentication protocols' such as HTTP Basic Auth, Digest +Access, public key, token, etc, are used to verify a user's identity. In this +document, we define an ''authentication component'' as a software module that +implements an authentication protocol for an OpenStack service. + +At a high level, an authentication component is simply a reverse proxy that +intercepts HTTP calls from clients. Once it has verified a user's identity, the +authentication component extends the call with information about the current +user and forwards the request to the OpenStack service. Otherwise, if a user's +identity is not verified, the message is rejected before it gets to the +service. This is illustrated in :ref:`authComponent`. + +.. _authComponent: + +Authentication Component +------------------------ + +Figure 1. Authentication Component + +.. image:: images/graphs_authComp.svg + :width: 100% + :height: 180 + :alt: An Authentication Component + +Authentication components may operate in 'delegated mode'. In this mode, the +decision reject an unauthenticated client is delegated to the OpenStack +service. Delegated mode is illustrated in :ref:`authComponentDelegated`. + +Here, requests are forwarded to the OpenStack service with an identity status +message that indicates whether the client's identity has been confirmed or is +indeterminate. It is the OpenStack service that decides whether or not a reject +message should be sent to the client. Note that it is always the responsibility +of the Authentication Component to transmit reject messages to the client. + +.. _authComponentDelegated: + +Authentication Component (Delegated Mode) +----------------------------------------- + +Figure 2. Authentication Component (Delegated Mode) + +.. image:: images/graphs_authCompDelegate.svg + :width: 100% + :height: 180 + :alt: An Authentication Component (Delegated Mode) + +In this architecture, we define interactions between the authentication component +and the OpenStack service. Interactions between the client and the +authentication component are defined only for exceptional cases. For example, +we define the message that should be returned when the OpenStack service is +down. Other interactions, however, are defined by the underlying authentication +protocol and the OpenStack service and are considered out of scope. + +.. _deployStrategies: + +Deployment Strategies +===================== + +An authentication component may be integrated directly into the service +implementation, or it may be deployed separately as an HTTP reverse proxy. This +is illustrated in :ref:`deployment`, showing both approaches to +authentication, labeled Option (a) and Option (b). + +.. _deployment: + +Authentication Component Deployments Options +-------------------------------------------- + +Figure 3. Authentication Component Deployments Options + +.. image:: images/images_layouts.svg + :width: 100% + :height: 180 + :alt: Authentication Component Deployments Options + +In Option (a), the component is integrated into the service implementation. In +this case, communication between the authentication component and the service +can be efficiently implemented via a method call. In Option (b), the component +is deployed separately and communication between the service and the component +involves an HTTP request. In both cases, unauthenticated requests are filtered +before they reach the service. + +Each approach offers some benefits. Option (a) offers low latency and ease of +initial implementation, making it possibly most appropriate as a starting point +for simple configurations. Option (b) offers several key advantages that may be +of particular value in complex and dynamic configurations. It offers the +ability to scale horizontally in cases where authentication is computationally +expensive, such as when verifying digital signatures. Option (b) also allows +authentication components to be written in different programming languages. +Finally, Option (b) allows multiple authentication components to be deployed in +front of the same service. + +OpenStack services can support both embedded (Option (a)) and external (Option +(b)) deployment strategies. Individual authentication components should support +either strategy or they |may| support both strategies. In order to support +option (a), authentication components written in the Python programming +language should be written as WSGI middleware components (in accordance with +the Web Server Gateway Interface (WSGI) standard [PEP-333]_. + +Additionally, services should support the ability to swap between different +embedded or external authentication components via configuration options. + +Exchanging User Information +=========================== + +If a request is successfully authenticated, the authentication component must +extend the request by adding an ``X-Authorization`` header. The header |must| +be formatted as illustrated in :ref:`xAuthHeader`. + +.. _xAuthHeader: + +X-Authorization Header +---------------------- + +Example 1. X-Authorization Header:: + + X-Authorization: Proxy JoeUser + +Here, `Proxy` denotes that the authentication occurred via a proxy (in this +case authentication component) and ''JoeUser'' is the name of the user who +issued the request. + +.. note: + + We considered using an ``Authorization`` header rather than an + ``X-Authorization``, thereby following normal HTTP semantics. There are some + cases, however, where multiple ``Authorization`` headers need to be transmitted + in a single request. We want to assure ourselves that this will not break + common clients before we recommend the approach. + +Authentication components |may| extend the request with additional +information. For example, an authentication system may add additional headers +or modify the target URI to pass authentication information to the back-end +service. Additionally, an authentication component |may| strip sensitive +information — a plain text password, for example — from the request. That said, +an authentication component |should| pass the majority of the request +unmodified. + +Reverse Proxy Authentication +---------------------------- + +An OpenStack service |should| verify that it is receiving requests from a +trusted authentication component. This is particularly important in cases where +the authentication component and the OpenStack service are deployed separately. +In order to trust incoming requests, the OpenStack service should therefore +authenticate the authentication component. To avoid confusion, we call this +'reverse proxy authentication', since in this case the authentication +component is acting as an HTTP reverse proxy. + +Any HTTP-based authentication scheme may be used for reverse proxy +authentication; however, all OpenStack services and all authentication +components |must| support HTTP Basic Authentication as defined in +[RFC-2617]_. + +Whether or not reverse proxy authentication is required is strictly a +deployment concern. For example, an operations team may opt to utilize firewall +rules instead of an authentication protocol to verify the integrity of incoming +request. Because of this, both OpenStack services and authentication components +|must| also allow for unauthenticated communication. + +In cases where reverse proxy authentication is used, the authorization +component may receive an HTTP 401 authentication error or an HTTP 403 +authorization error. These errors indicate that the component does not have +access to the underlying OpenStack service. The authentication component +|must not| return these errors to the client application. Instead, the +component |must| return a 500 internal error. This is illustrated in +:ref:`proxyAuth` and :ref:`proxyAuthDelegated` below. The component +|should| format the errors in a manner that does not break the service +contract defined by the OpenStack service. :ref:`proxyAuthDelegated` +illustrates proxy authorization in delegated mode. Delegated mode is discussed +in detail in the next section. + +.. _proxyAuth: + +Reverse Proxy Authentication +---------------------------- + +Figure 4. Reverse Proxy Authentication + +.. image:: images/graphs_proxyAuth.svg + :width: 100% + :height: 180 + :alt: Reverse Proxy Authentication + +.. _proxyAuthDelegated: + +Reverse Proxy Authentication (Delegated Mode) +--------------------------------------------- + +Figure 5. Reverse Proxy Authentication (Delegated Mode) + +.. image:: images/graphs_delegate_forbiden_proxy.svg + :width: 100% + :height: 180 + :alt: Reverse Proxy Authentication (Delegated Mode) + +Delegated Mode +============== +In some cases, the decision to reject an unauthenticated request should be +delegated to the OpenStack service. An unauthenticated request may be +appropriate in cases when anonymous access is allowed. In order to support +these cases, an authentication component may be placed in Delegated Mode. In +this mode, the component forwards requests to the OpenStack service when the +client's identity has been confirmed or is indeterminate — that is when +credentials are missing. The authentication component directly rejects requests +with invalid credentials. Authentication components |must| extend the +request by adding an `X-Identity-Status` header. The identity status header +|must| contain one of the following values: + +Identity Status Values +---------------------- + +Confirmed + A `confirmed` value indicates that valid credentials were sent and identity + has been confirmed. The service can trust that the request has been sent on + behalf of the user specified in the `X-Authorization` header. + +Indeterminate + An `indeterminate` value indicates that no credentials were sent and + identity has not been confirmed. In this case, the service will receive an + `X-Authorization` header with no user entry as illustrated in + :ref:`xauth-header-indeterminate`. + +.. _xauth-header-indeterminate: + +Indeterminate Identity Headers +------------------------------ + +Example 2. Indeterminate Identity Headers:: + + X-Identity-Status: Indeterminate + X-Authorization: Proxy + +Services |may| reject a delegated request by issuing an HTTP 401 +authentication error or an HTTP 403 authorization error. These responses +|must| contain an ``WWW-Authenticate`` header with a value of ``Delegated`` as +illustrated in :ref:`unauthHeaders`. + +X-Identity-Status + Provides information on whether the request was authenticated or not. + +X-Tenant + Provides the tenant ID (as it appears in the URL in Keystone). This is to support any legacy implementations before Keystone switched to an ID/Name schema for tenants. + +X-Tenant-Id + The unique, immutable tenant Id + +X-Tenant-Name + The unique, but mutable (it can change) tenant name. + +X-User-Id + The user id of the user used to log in + +X-User-Name + The username used to log in + +X-User + The username used to log in. This is to support any legacy implementations before Keystone switched to an ID/Name schema for tenants. + +X-Roles + The roles associated with that user + +.. _unauthHeaders: + +Delegated WWW-Authenticate Header +--------------------------------- + +:: + + WWW-Authenticate: Delegated + +It is important to note that the actual reject message will likely be modified +by the authentication component in order to comply with the authentication +scheme it is implementing. This is illustrated in :ref:`delegateRejectBasic` and +:ref:`delegateRejectOAuth` below. + +.. _delegateRejectBasic: + +Delegated Reject Basic Auth +--------------------------- + +.. image:: images/graphs_delegate_reject_basic.svg + :width: 100% + :height: 180 + :alt: Delegated Reject Basic Auth + +.. _delegateRejectOAuth: + +Delegated Reject OAuth +---------------------- + +.. image:: images/graphs_delegate_reject_oauth.svg + :width: 100% + :height: 180 + :alt: Delegated Reject OAuth + +The presence of the `WWW-Authenticate` header with a value of `Delegated` +distinguishes a client authentication/authorization failure from a component +failure. For example, compare :ref:`delegateForbidden` with :ref:`proxyAuthDelegated`. In +:ref:`delegateForbidden`, the client is not allowed to access the OpenStack service. +In :ref:`proxyAuthDelegated`, it is the authentication component itself which is +unauthorized. + +.. _delegateForbidden: + +Delegated Reject Forbidden +-------------------------- + +Figure 8. Delegated Reject Forbidden + +.. image:: images/graphs_delegate_forbiden_basic.svg + :width: 100% + :height: 180 + :alt: Delegated Reject Forbidden + +Authentication components |must| support both delegated and undelegated +(standard) modes. Delegated mode |should| be configured via a configuration +option. Delegated mode |should| be disabled by default. + +OpenStack services are not required to support delegated mode. If a service +does not support delegated mode, it |must| respond with a 501 not implemented +error and an `WWW-Authenticate` header with a value of `Delegated`. The +authentication component |must not| return the error to the client +application. Instead, the component |must| return a 500 internal error; this is +illustrated in :ref:`delegateUnimplemented`. The component |should| +format the error in a manner that does not break the service contract defined +by the OpenStack service. The component should also log the error such that it +that will inform operators of the misconfiguration. + +.. _delegateUnimplemented: + +Unimplemented Delegated Mode +---------------------------- + +.. image:: images/graphs_delegate_unimplemented.svg + :width: 100% + :height: 180 + :alt: Unimplemented Delegated Mode + +Handling Direct Client Connections +================================== + +Requests from the authentication component to an OpenStack service |must| +contain an ``X-Authorization`` header. If the header is missing, and reverse +proxy authentication fails or is switched off, the OpenStack service |may| +assume that the request is coming directly from a client application. In this +case, the OpenStack service |must| redirect the request to the authentication +component by issuing an HTTP 305 User Proxy redirect. This is illustrated in +:ref:`redirect`. Note that the redirect response |must| include a ``Location`` header +specifying the authentication component's URL as shown in :ref:`redirect-response`. + +.. _redirect: + +Auth Component Redirect +----------------------- + +.. image:: images/graphs_305.svg + :width: 100% + :height: 280 + :alt: Auth Component Redirect + +.. _redirect-response: + +Auth Component Redirect Response +-------------------------------- + +:: + + HTTP/1.1 305 Use Proxy + Date: Thu, 28 Oct 2011 07:41:16 GMT + Location: http://sample.auth.openstack.com/path/to/resource + +Using Multiple Authentication Components +======================================== + +There are some use cases when a service provider might want to consider using +multiple authentication components for different purposes. For instance, a +service provider may have one authentication scheme to authenticate the users +of the service and another one to authenticate the administrators or operations +personnel that maintain the service. For such scenarios, we propose using a +mapper as illustrated in :ref:`multiAuth`. + +.. _multiAuth: + +Multiple Authentication Components +---------------------------------- + +.. image:: images/graphs_mapper.svg + :width: 100% + :height: 320 + :alt: Multiple Authentication Components + +At a high level, a mapper is a simple reverse proxy that intercepts HTTP calls +from clients and routes the request to the appropriate authentication +component. A mapper can make the routing decisions based on a number of routing +rules that map a resource to a specific authentication component. For example, +a request URI may determine whether a call should be authenticated via one +authentication component or another. + +Note that neither the authentication component nor the OpenStack service need +be aware of the mapper. Any external authentication component can be used +alongside others. Mappers may provide a means by which to offer support for +anonymous or guest access to a subset of service resources. A mapper may be +implemented via a traditional reverse proxy server such as Pound or Zeus. + +The Default Component +===================== + +Individual services |must| be distributed with a simple integrated +authentication component by default. Providing such a component lowers barriers +to the deployment of individual services. This is especially important to] +developers who may want to deploy OpenStack services on their own machines. +Also, since there is no direct dependency on an external authentication system, +OpenStack services can be deployed individually, without the need to stand up +and configure additional services. Finally, having a standard authentication +component that all services share promotes a separation of concerns. That is, +as a community we are explicitly stating that services should not develop their +own authentication mechanisms. Additional authentication components may be +developed, of course, but these components should not be intimately coupled to +any one particular service. + +As discussed in :ref:`deployStrategies`, an authentication component may be +integrated directly into the service implementation (Option (a)), or it may be +deployed separately as an HTTP reverse proxy (Option (b)). The default +component should be implemented to support Option (a) and services should +maintain support for Option (b). One way to achieve this is to provide a +method that allows the disabling of the default authentication component via +configuration. This is illustrated in :ref:`both`. Here, requests are +sent directly to the OpenStack service when the default authentication +component is disabled. + +We will discuss the design of the default component in an upcoming blueprint. + +.. _both: + +Disabled Embedded Component +--------------------------- + +.. image:: images/graphs_both.svg + :width: 100% + :height: 250 + :alt: Disabled Embedded Component + +Questions and Answers +===================== + +#. Why do authentication components send reject messages? Why not have + OpenStack services reject requests themselves? + + The content and format of an authentication failed message is determined by + the authentication scheme (or protocol). For the service to respond + appropriately, it would have to be aware of the authentication scheme in + which it participates; this defeats the purpose of pluggable authentication + components. + +#. Why require support for deploying authentication components in separate + nodes? + + The deployment strategy is very flexible. It allows for authentication + components to be horizontally scalable. It allows for components to be written + in different languages. Finally, it allows different authentication components + to be deployed simultaneously as described above. + +References +========== + +.. [PEP-333] pep0333 Phillip J Eby. 'Python Web Server Gateway Interface + v1.0.'' http://www.python.org/dev/peps/pep-0333/. + +.. [RFC-2617] rfc2617 J Franks. P Hallam-Baker. J Hostetler. S Lawrence. + P Leach. A Luotonen. L Stewart. ''HTTP Authentication: Basic and Digest + Access Authentication.'' http://tools.ietf.org/html/rfc2617. + +.. |must| replace:: must must +.. |should| replace:: should should +.. |may| replace:: may may +.. |must not| replace:: "must not" "must not" + diff --git a/docs/source/migration.rst b/docs/source/migration.rst new file mode 100644 index 00000000..460d980b --- /dev/null +++ b/docs/source/migration.rst @@ -0,0 +1,126 @@ +=================== +Database Migrations +=================== + +Keystone uses SQLAlchemy Migrate (``sqlalchemy-migrate``) to manage +migrations. + +Migrations are tracked using a metadata table (``migrate_version``), which +allows keystone to compare the state of your database to the state it +expects, and to move between versions. + +.. WARNING:: + + Backup your database before applying migrations. Migrations may + attempt to modify both your schema and data, and could result in data + loss. + + Always review the behavior of migrations in a staging environment + before applying them in production. + +Getting Started +=============== + +Your initial approach to migrations should depend on whether you have an +empty database or a schema full of data. + +Starting with an empty database +------------------------------- + +If you have an empty database for keystone to work with, you can simply +run:: + + $ ./bin/keystone-manage database sync + +This command will initialize your metadata table, and run through all the +schema & data migrations necessary to bring your database in sync with +keystone. That's it! + +Starting with an existing database +---------------------------------- + +Place an existing database under version control to enable migration +support:: + + $ ./bin/keystone-manage database version_control + +This command simply creates a ``migrate_version`` table, set at +``version_number`` 0, which indicates that no migrations have been applied. + +If you are starting with an existing schema, you can jump to a specific +schema version without performing migrations using the ``database goto`` +command. For example, if you're starting from a diablo-compatible +database, set your current database ``version_number`` to ``1`` using:: + + $ ./bin/keystone-manage database goto + +Determine your appropriate database ``version_number`` by referencing the +following table: + + +------------+-------------+ + | Release | ``version`` | + +============+=============+ + | pre-diablo | (see below) | + +------------+-------------+ + | diablo | 1 | + +------------+-------------+ + | essex-m1 | 3 | + +------------+-------------+ + | essex-m2 | 4 | + +------------+-------------+ + +From there, you can upgrade normally (see :ref:`upgrading`). + +Starting with a pre-diablo database (cactus) +-------------------------------------------- + +You'll need to manually migrate your database to a diablo-compatible +schema, and continue forward from there (if desired) using migrations. + +.. _upgrading: + +Upgrading & Downgrading +======================= + +.. note:: + + Attempting to start keystone with an outdated schema will cause + keystone to abort, to avoid corrupting your data. + +Upgrade to the latest version automatically:: + + $ ./bin/keystone-manage database sync + +Check your current schema version:: + + $ ./bin/keystone-manage database version + +Jump to a specific version without performing migrations:: + + $ ./bin/keystone-manage database goto + +Upgrade to a specific version:: + + $ ./bin/keystone-manage database upgrade + +Downgrade to a specific version (will likely result in data loss!):: + + $ ./bin/keystone-manage database downgrade + +Opting Out of Migrations +======================== + +If you don't want to use migrations (e.g. if you want to manage your +schema manually), keystone will complain in your logs on startup, but +won't actually stop you from doing so. + +It's recommended that you use migrations to get up and running, but if +you want to manage migrations manually after that, simply drop the +``migrate_version`` table:: + + DROP TABLE migrate_version; + +Useful Links +============ + +Principles to follow when developing migrations `OpenStack Deployability `_ diff --git a/docs/source/nova-api-paste.rst b/docs/source/nova-api-paste.rst new file mode 100644 index 00000000..586bac72 --- /dev/null +++ b/docs/source/nova-api-paste.rst @@ -0,0 +1,142 @@ +.. + Copyright 2011 OpenStack, LLC + All Rights Reserved. + + Licensed under the Apache License, Version 2.0 (the "License"); you may + not use this file except in compliance with the License. You may obtain + a copy of the License at + + http://www.apache.org/licenses/LICENSE-2.0 + + Unless required by applicable law or agreed to in writing, software + distributed under the License is distributed on an "AS IS" BASIS, WITHOUT + WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the + License for the specific language governing permissions and limitations + under the License. + +nova-api-paste example +====================== +:: + + ####### + # EC2 # + ####### + + [composite:ec2] + use = egg:Paste#urlmap + /: ec2versions + /services/Cloud: ec2cloud + /services/Admin: ec2admin + /latest: ec2metadata + /2007-01-19: ec2metadata + /2007-03-01: ec2metadata + /2007-08-29: ec2metadata + /2007-10-10: ec2metadata + /2007-12-15: ec2metadata + /2008-02-01: ec2metadata + /2008-09-01: ec2metadata + /2009-04-04: ec2metadata + /1.0: ec2metadata + + [pipeline:ec2cloud] + pipeline = logrequest totoken authtoken keystonecontext cloudrequest authorizer ec2executor + + [pipeline:ec2admin] + pipeline = logrequest totoken authtoken keystonecontext adminrequest authorizer ec2executor + + [pipeline:ec2metadata] + pipeline = logrequest ec2md + + [pipeline:ec2versions] + pipeline = logrequest ec2ver + + [filter:logrequest] + paste.filter_factory = nova.api.ec2:RequestLogging.factory + + [filter:ec2lockout] + paste.filter_factory = nova.api.ec2:Lockout.factory + + [filter:totoken] + paste.filter_factory = keystone.middleware.ec2_token:EC2Token.factory + + [filter:ec2noauth] + paste.filter_factory = nova.api.ec2:NoAuth.factory + + [filter:authenticate] + paste.filter_factory = nova.api.ec2:Authenticate.factory + + [filter:cloudrequest] + controller = nova.api.ec2.cloud.CloudController + paste.filter_factory = nova.api.ec2:Requestify.factory + + [filter:adminrequest] + controller = nova.api.ec2.admin.AdminController + paste.filter_factory = nova.api.ec2:Requestify.factory + + [filter:authorizer] + paste.filter_factory = nova.api.ec2:Authorizer.factory + + [app:ec2executor] + paste.app_factory = nova.api.ec2:Executor.factory + + [app:ec2ver] + paste.app_factory = nova.api.ec2:Versions.factory + + [app:ec2md] + paste.app_factory = nova.api.ec2.metadatarequesthandler:MetadataRequestHandler.factory + + ############# + # Openstack # + ############# + + [composite:osapi] + use = egg:Paste#urlmap + /: osversions + /v1.1: openstackapi + + [pipeline:openstackapi] + pipeline = faultwrap authtoken keystonecontext ratelimit extensions osapiapp + + [filter:faultwrap] + paste.filter_factory = nova.api.openstack:FaultWrapper.factory + + [filter:auth] + paste.filter_factory = nova.api.openstack.auth:AuthMiddleware.factory + + [filter:noauth] + paste.filter_factory = nova.api.openstack.auth:NoAuthMiddleware.factory + + [filter:ratelimit] + paste.filter_factory = nova.api.openstack.limits:RateLimitingMiddleware.factory + + [filter:extensions] + paste.filter_factory = nova.api.openstack.extensions:ExtensionMiddleware.factory + + [app:osapiapp] + paste.app_factory = nova.api.openstack:APIRouter.factory + + [pipeline:osversions] + pipeline = faultwrap osversionapp + + [app:osversionapp] + paste.app_factory = nova.api.openstack.versions:Versions.factory + + ########## + # Shared # + ########## + + [filter:keystonecontext] + paste.filter_factory = keystone.middleware.nova_keystone_context:NovaKeystoneContext.factory + + [filter:authtoken] + paste.filter_factory = keystone.middleware.auth_token:filter_factory + service_protocol = http + service_host = 127.0.0.1 + service_port = 5000 + auth_host = 127.0.0.1 + auth_port = 35357 + auth_protocol = http + auth_uri = http://127.0.0.1:5000/ + admin_token = 999888777666 + ;Uncomment next line and check ip:port to use memcached to cache token requests + ;memcache_hosts = 127.0.0.1:11211 diff --git a/docs/source/releases.rst b/docs/source/releases.rst new file mode 100644 index 00000000..a4b698d7 --- /dev/null +++ b/docs/source/releases.rst @@ -0,0 +1,36 @@ +============= +Release notes +============= + + +E3 (January 26, 2012) +========================================== +* Contract compliance: version response and ATOM, 300 multiple choice +* Global endpoints returned for unscoped calls +* adminUrl only shown to admin clients +* Endpoints have unique ID +* Auth-N/Auth-Z for S3 API (OS-KSS3 extension) +* Default tenant scope optionally returned when authenticating +* Vary header returned for caching proxies + +* Portable identifiers: modifiable, string identifiers in database backend +* Much improved keystone-manage command (see --help and docs) +* OS-KSVALIDATE extension to support not passing tokens in URL +* OS-KSEC2 and OS-KSS3 extensions respond on /tokens +* HP-IDM extension to filter roles to a given service ID +* Additional caching options in middleware (memcache and swift cache) + +* Enhanced configuration management (in line with other OpenStack projects) +* Additional logging +* Enhanced tracer tool (-t or --trace-calls) + +See comprehensive list here https://launchpad.net/keystone/+milestone/essex-3 + + +E2 (December 15, 2011) +======================== +* D5 compatibility middleware +* Database versioning +* Much more documentation: http://keystone.openstack.org + +See https://launchpad.net/keystone/+milestone/essex-2 diff --git a/docs/source/serviceAPI_curl_examples.rst b/docs/source/serviceAPI_curl_examples.rst new file mode 100644 index 00000000..d05afc9f --- /dev/null +++ b/docs/source/serviceAPI_curl_examples.rst @@ -0,0 +1,69 @@ +.. + Copyright 2011 OpenStack, LLC + All Rights Reserved. + + Licensed under the Apache License, Version 2.0 (the "License"); you may + not use this file except in compliance with the License. You may obtain + a copy of the License at + + http://www.apache.org/licenses/LICENSE-2.0 + + Unless required by applicable law or agreed to in writing, software + distributed under the License is distributed on an "AS IS" BASIS, WITHOUT + WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the + License for the specific language governing permissions and limitations + under the License. + +=============================== +Service API Examples Using Curl +=============================== + +The service API is defined to be a subset of the Admin API and, by +default, runs on port 5000. + +GET / +===== + +This call is identical to that documented for the Admin API, except +that it uses port 5000, instead of port 35357, by default:: + + $ curl http://0.0.0.0:5000 + +or:: + + $ curl http://0.0.0.0:5000/v2.0/ + +See the `Admin API Examples Using Curl`_ for more info. + +.. _`Admin API Examples Using Curl`: adminAPI_curl_examples.html + +GET /extensions +=============== + +This call is identical to that documented for the Admin API. + +POST /tokens +============ + +This call is identical to that documented for the Admin API. + +GET /tenants +============ + +List all of the tenants your token can access:: + + $ curl -H "X-Auth-Token:887665443383838" http://localhost:5000/v2.0/tenants + +Returns:: + + { + "tenants_links": [], + "tenants": [ + { + "enabled": true, + "description": "None", + "name": "customer-x", + "id": "1" + } + ] + } diff --git a/docs/source/services.rst b/docs/source/services.rst new file mode 100644 index 00000000..d1c33381 --- /dev/null +++ b/docs/source/services.rst @@ -0,0 +1,92 @@ +.. + Copyright 2011 OpenStack, LLC + All Rights Reserved. + + Licensed under the Apache License, Version 2.0 (the "License"); you may + not use this file except in compliance with the License. You may obtain + a copy of the License at + + http://www.apache.org/licenses/LICENSE-2.0 + + Unless required by applicable law or agreed to in writing, software + distributed under the License is distributed on an "AS IS" BASIS, WITHOUT + WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the + License for the specific language governing permissions and limitations + under the License. + +================ +Services +================ + +.. toctree:: + :maxdepth: 1 + + +What are services? +================== + +Keystone includes service registry and service catalog functionality which it +uses to respond to client authentication requests with information useful to +clients in locating the list of available services they can access. + +The Service entity in Keystone represents an OpenStack service that is integrated +with Keystone. The Service entity is also used as a reference from roles, endpoints, +and endpoint templates. + +Keystone also includes an authorization mechanism to allow a service to own +its own roles and endpoints and prevent other services from changing or +modifying them. + +Who can create services? +======================== + +Any user with the Admin or Service Admin roles in Keystone may create services. + +How are services created? +========================= + +Services can be created using ``keystone-manage`` or through the REST API using +the OS-KSADM extension calls. + +Using ``keystone-manage`` (see :doc:`man/keystone-manage` for details):: + + $ keystone-manage add service compute nova 'This is a sample compute service' + +Using the REST API (see `extensions dev guide `_ for details):: + + $ curl -H "Content-type: application/json" -X POST -d '{ + "OS-KSADM:service": { + "name": "nova", + "type": "compute", + "description": "This is a sample compute service" + } + }' -H "X-Auth-Token: 999888777666" http://localhost:35357/v2.0/OS-KSADM/services/ + +How is service ownership determined? +==================================== + +Currently, the way to assign ownership to a service is to provide the owner's +user id in the keystone-manage add command:: + + $ keystone-manage add service nova compute 'This is a sample compute service' joeuser + +This will assign ownership to the new service to joeuser. + +When a service has an owner, then only that owner (or a global Admin) can create and manage +roles that start with that service name (ex: "nova:admin") and manage endpoints +and endpoint templates associated with that service. + +Listing services +================ + +Using ``keystone-manage``, the list of services and their owners can be listed:: + + $ keystone-manage service list + + id name type owner_id description + ------------------------------------------------------------------------------- + 1 compute nova joeuser This is a sample compute service + +Using the REST API, call ``GET /v2.0/OS-KSADM/services`` + +.. note: The rest API does not yet support service ownership diff --git a/docs/source/ssl.rst b/docs/source/ssl.rst new file mode 100644 index 00000000..839e951e --- /dev/null +++ b/docs/source/ssl.rst @@ -0,0 +1,118 @@ +.. + Copyright 2011 OpenStack, LLC + All Rights Reserved. + + Licensed under the Apache License, Version 2.0 (the "License"); you may + not use this file except in compliance with the License. You may obtain + a copy of the License at + + http://www.apache.org/licenses/LICENSE-2.0 + + Unless required by applicable law or agreed to in writing, software + distributed under the License is distributed on an "AS IS" BASIS, WITHOUT + WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the + License for the specific language governing permissions and limitations + under the License. + +=========================== +x.509 Client Authentication +=========================== + +Purpose +======= + +Allows the Keystone middleware to authenticate itself with the Keystone server +via an x.509 client certificate. Both Service API and Admin API may be secured +with this feature. + +Certificates +============ + +The following types of certificates are required. A set of certficates is provided +in the examples/ssl directory with the Keystone distribution for testing. Here +is the description of each of them and their purpose: + +ca.pem + Certificate Authority chain to validate against. + +keystone.pem + Public certificate for Keystone server. + +middleware-key.pem + Public and private certificate for Keystone middleware. + +cakey.pem + Private key for the CA. + +keystonekey.pem + Private key for the Keystone server. + +Note that you may choose whatever names you want for these certificates, or combine +the public/private keys in the same file if you wish. These certificates are just +provided as an example. + +Configuration +============= + +By default, the Keystone server does not use SSL. To enable SSL with client authentication, +modify the etc/keystone.conf file accordingly: + +1. To enable SSL for Service API:: + + service_ssl = True + +2. To enable SSL for Admin API:: + + admin_ssl = True + +3. To enable SSL client authentication:: + + cert_required = True + +4. Set the location of the Keystone certificate file (example):: + + certfile = /etc/keystone/ca/certs/keystone.pem + +5. Set the location of the Keystone private file (example):: + + keyfile = /etc/keystone/ca/private/keystonekey.pem + +6. Set the location of the CA chain:: + + ca_certs = /etc/keystone/ca/certs/ca.pem + +Middleware +========== + +Add the following to your middleware configuration to support x.509 client authentication. +If ``cert_required`` is set to ``False`` on the keystone server, the certfile and keyfile parameters +in steps 3) and 4) may be commented out. + +1. Specify 'https' as the auth_protocol:: + + auth_protocol = https + +2. Modify the protocol in 'auth_uri' to be 'https' as well, if the service API is configured + for SSL:: + + auth_uri = https://localhost:5000/ + +3. Set the location of the middleware certificate file (example):: + + certfile = /etc/keystone/ca/certs/middleware-key.pem + +4. Set the location of the Keystone private file (example):: + + keyfile = /etc/keystone/ca/certs/middleware-key.pem + +For an example, take a look at the ``echo.ini`` middleware configuration for the 'echo' example +service in the examples/echo directory. + +Testing +======= + +You can test out how it works by using the ``echo`` example service in the ``examples/echo`` directory +and the certficates included in the ``examples/ssl`` directory. Invoke the ``echo_client.py`` with +the path to the client certificate:: + + python echo_client.py -s diff --git a/docs/source/usingkeystone.rst b/docs/source/usingkeystone.rst new file mode 100644 index 00000000..bb52a94d --- /dev/null +++ b/docs/source/usingkeystone.rst @@ -0,0 +1,28 @@ +.. + Copyright 2011 OpenStack, LLC + All Rights Reserved. + + Licensed under the Apache License, Version 2.0 (the "License"); you may + not use this file except in compliance with the License. You may obtain + a copy of the License at + + http://www.apache.org/licenses/LICENSE-2.0 + + Unless required by applicable law or agreed to in writing, software + distributed under the License is distributed on an "AS IS" BASIS, WITHOUT + WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the + License for the specific language governing permissions and limitations + under the License. + +============== +Using Keystone +============== + +Curl examples +------------- + +.. toctree:: + :maxdepth: 1 + + adminAPI_curl_examples + serviceAPI_curl_examples -- cgit From e643f239816bae29e8206407db3d5eabdd2ea4b0 Mon Sep 17 00:00:00 2001 From: Joe Heck Date: Sun, 29 Jan 2012 10:57:02 -0800 Subject: doc updates --- docs/source/api_curl_examples.rst | 442 ++++++++++++++++++++++++++++++++++++ docs/source/architecture.rst | 4 + docs/source/community.rst | 26 +-- docs/source/configuration.rst | 224 ++++++++++++++---- docs/source/developing.rst | 130 +++++------ docs/source/index.rst | 20 +- docs/source/man/keystone-manage.rst | 241 ++++++++++++-------- docs/source/man/keystone.rst | 69 +++--- docs/source/setup.rst | 71 ++++-- docs/source/testing.rst | 77 ------- 10 files changed, 918 insertions(+), 386 deletions(-) create mode 100644 docs/source/api_curl_examples.rst delete mode 100644 docs/source/testing.rst (limited to 'docs') diff --git a/docs/source/api_curl_examples.rst b/docs/source/api_curl_examples.rst new file mode 100644 index 00000000..686e8bd5 --- /dev/null +++ b/docs/source/api_curl_examples.rst @@ -0,0 +1,442 @@ +.. + Copyright 2011 OpenStack, LLC + All Rights Reserved. + + Licensed under the Apache License, Version 2.0 (the "License"); you may + not use this file except in compliance with the License. You may obtain + a copy of the License at + + http://www.apache.org/licenses/LICENSE-2.0 + + Unless required by applicable law or agreed to in writing, software + distributed under the License is distributed on an "AS IS" BASIS, WITHOUT + WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the + License for the specific language governing permissions and limitations + under the License. + + +=============================== +Service API Examples Using Curl +=============================== + +The service API is defined to be a subset of the Admin API and, by +default, runs on port 5000. + +GET / +===== + +This call is identical to that documented for the Admin API, except +that it uses port 5000, instead of port 35357, by default:: + + $ curl http://0.0.0.0:5000 + +or:: + + $ curl http://0.0.0.0:5000/v2.0/ + +See the `Admin API Examples Using Curl`_ for more info. + +.. _`Admin API Examples Using Curl`: adminAPI_curl_examples.html + +GET /extensions +=============== + +This call is identical to that documented for the Admin API. + +POST /tokens +============ + +This call is identical to that documented for the Admin API. + +GET /tenants +============ + +List all of the tenants your token can access:: + + $ curl -H "X-Auth-Token:887665443383838" http://localhost:5000/v2.0/tenants + +Returns:: + + { + "tenants_links": [], + "tenants": [ + { + "enabled": true, + "description": "None", + "name": "customer-x", + "id": "1" + } + ] + } + +============================= +Admin API Examples Using Curl +============================= + +These examples assume a default port value of 35357, and depend on the +``sampledata`` bundled with keystone. + +GET / +===== + +Disover API version information, links to documentation (PDF, HTML, WADL), +and supported media types:: + + $ curl http://0.0.0.0:35357 + +or:: + + $ curl http://0.0.0.0:35357/v2.0/ + +Returns:: + + { + "version":{ + "id":"v2.0", + "status":"beta", + "updated":"2011-11-19T00:00:00Z", + "links":[ + { + "rel":"self", + "href":"http://127.0.0.1:35357/v2.0/" + }, + { + "rel":"describedby", + "type":"text/html", + "href":"http://docs.openstack.org/api/openstack-identity-service/2.0/content/" + }, + { + "rel":"describedby", + "type":"application/pdf", + "href":"http://docs.openstack.org/api/openstack-identity-service/2.0/identity-dev-guide-2.0.pdf" + }, + { + "rel":"describedby", + "type":"application/vnd.sun.wadl+xml", + "href":"http://127.0.0.1:35357/v2.0/identity-admin.wadl" + } + ], + "media-types":[ + { + "base":"application/xml", + "type":"application/vnd.openstack.identity-v2.0+xml" + }, + { + "base":"application/json", + "type":"application/vnd.openstack.identity-v2.0+json" + } + ] + } + } + +GET /extensions +=============== + +Discover the API extensions enabled at the endpoint:: + + $ curl http://0.0.0.0:35357/extensions + +Returns:: + + { + "extensions":{ + "values":[] + } + } + +POST /tokens +============ + +Authenticate by exchanging credentials for an access token:: + + $ curl -d '{"auth":{"passwordCredentials":{"username": "joeuser", "password": "secrete"}}}' -H "Content-type: application/json" http://localhost:35357/v2.0/tokens + +Returns:: + + { + "access":{ + "token":{ + "expires":"2012-02-05T00:00:00", + "id":"887665443383838", + "tenant":{ + "id":"1", + "name":"customer-x" + } + }, + "serviceCatalog":[ + { + "endpoints":[ + { + "adminURL":"http://swift.admin-nets.local:8080/", + "region":"RegionOne", + "internalURL":"http://127.0.0.1:8080/v1/AUTH_1", + "publicURL":"http://swift.publicinternets.com/v1/AUTH_1" + } + ], + "type":"object-store", + "name":"swift" + }, + { + "endpoints":[ + { + "adminURL":"http://cdn.admin-nets.local/v1.1/1", + "region":"RegionOne", + "internalURL":"http://127.0.0.1:7777/v1.1/1", + "publicURL":"http://cdn.publicinternets.com/v1.1/1" + } + ], + "type":"object-store", + "name":"cdn" + } + ], + "user":{ + "id":"1", + "roles":[ + { + "tenantId":"1", + "id":"3", + "name":"Member" + } + ], + "name":"joeuser" + } + } + } + +.. note:: + + Take note of the value ['access']['token']['id'] value produced here (``887665443383838``, above), as you can use it in the calls below. + +GET /tokens/{token_id} +====================== + +.. note:: + + This call refers to a token known to be valid, ``887665443383838`` in this case. + +Validate a token:: + + $ curl -H "X-Auth-Token:999888777666" http://localhost:35357/v2.0/tokens/887665443383838 + +If the token is valid, returns:: + + { + "access":{ + "token":{ + "expires":"2012-02-05T00:00:00", + "id":"887665443383838", + "tenant":{ + "id":"1", + "name":"customer-x" + } + }, + "user":{ + "name":"joeuser", + "tenantName":"customer-x", + "id":"1", + "roles":[ + { + "serviceId":"1", + "id":"3", + "name":"Member" + } + ], + "tenantId":"1" + } + } + } + +HEAD /tokens/{token_id} +======================= + +This is a high-performance variant of the GET call documented above, which +by definition, returns no response body:: + + $ curl -I -H "X-Auth-Token:999888777666" http://localhost:35357/v2.0/tokens/887665443383838 + +... which returns ``200``, indicating the token is valid:: + + HTTP/1.1 200 OK + Content-Length: 0 + Content-Type: None + Date: Tue, 08 Nov 2011 23:07:44 GMT + +GET /tokens/{token_id}/endpoints +================================ + +List all endpoints for a token:: + + $ curl -H "X-Auth-Token:999888777666" http://localhost:35357/v2.0/tokens/887665443383838/endpoints + +Returns:: + + { + "endpoints_links": [ + { + "href": "http://127.0.0.1:35357/tokens/887665443383838/endpoints?'marker=5&limit=10'", + "rel": "next" + } + ], + "endpoints": [ + { + "internalURL": "http://127.0.0.1:8080/v1/AUTH_1", + "name": "swift", + "adminURL": "http://swift.admin-nets.local:8080/", + "region": "RegionOne", + "tenantId": 1, + "type": "object-store", + "id": 1, + "publicURL": "http://swift.publicinternets.com/v1/AUTH_1" + }, + { + "internalURL": "http://localhost:8774/v1.0", + "name": "nova_compat", + "adminURL": "http://127.0.0.1:8774/v1.0", + "region": "RegionOne", + "tenantId": 1, + "type": "compute", + "id": 2, + "publicURL": "http://nova.publicinternets.com/v1.0/" + }, + { + "internalURL": "http://localhost:8774/v1.1", + "name": "nova", + "adminURL": "http://127.0.0.1:8774/v1.1", + "region": "RegionOne", + "tenantId": 1, + "type": "compute", + "id": 3, + "publicURL": "http://nova.publicinternets.com/v1.1/ + }, + { + "internalURL": "http://127.0.0.1:9292/v1.1/", + "name": "glance", + "adminURL": "http://nova.admin-nets.local/v1.1/", + "region": "RegionOne", + "tenantId": 1, + "type": "image", + "id": 4, + "publicURL": "http://glance.publicinternets.com/v1.1/" + }, + { + "internalURL": "http://127.0.0.1:7777/v1.1/1", + "name": "cdn", + "adminURL": "http://cdn.admin-nets.local/v1.1/1", + "region": "RegionOne", + "tenantId": 1, + "versionId": "1.1", + "versionList": "http://127.0.0.1:7777/", + "versionInfo": "http://127.0.0.1:7777/v1.1", + "type": "object-store", + "id": 5, + "publicURL": "http://cdn.publicinternets.com/v1.1/1" + } + ] + } + +GET /tenants +============ + +List all of the tenants in the system (requires an Admin ``X-Auth-Token``):: + + $ curl -H "X-Auth-Token:999888777666" http://localhost:35357/v2.0/tenants + +Returns:: + + { + "tenants_links": [], + "tenants": [ + { + "enabled": false, + "description": "None", + "name": "project-y", + "id": "3" + }, + { + "enabled": true, + "description": "None", + "name": "ANOTHER:TENANT", + "id": "2" + }, + { + "enabled": true, + "description": "None", + "name": "customer-x", + "id": "1" + } + ] + } + +GET /tenants/{tenant_id} +======================== + +Retrieve information about a tenant, by tenant ID:: + + $ curl -H "X-Auth-Token:999888777666" http://localhost:35357/v2.0/tenants/1 + +Returns:: + + { + "tenant":{ + "enabled":true, + "description":"None", + "name":"customer-x", + "id":"1" + } + } + +GET /tenants/{tenant_id}/users/{user_id}/roles +============================================== + +List the roles a user has been granted on a tenant:: + + $ curl -H "X-Auth-Token:999888777666" http://localhost:35357/v2.0/tenants/1/users/1/roles + +Returns:: + + { + "roles_links":[], + "roles":[ + { + "id":"3", + "name":"Member" + } + ] + } + +GET /users/{user_id} +==================== + +Retrieve information about a user, by user ID:: + + $ curl -H "X-Auth-Token:999888777666" http://localhost:35357/v2.0/users/1 + +Returns:: + + { + "user":{ + "tenantId":"1", + "enabled":true, + "id":"1", + "name":"joeuser" + } + } + +GET /users/{user_id}/roles +========================== + +Retrieve the roles granted to a user, given a user ID:: + + $ curl -H "X-Auth-Token:999888777666" http://localhost:35357/v2.0/users/4/roles + +Returns:: + + { + "roles_links":[], + "roles":[ + { + "id":"2", + "name":"KeystoneServiceAdmin" + } + ] + } diff --git a/docs/source/architecture.rst b/docs/source/architecture.rst index 8de45502..21d9b895 100644 --- a/docs/source/architecture.rst +++ b/docs/source/architecture.rst @@ -17,6 +17,10 @@ Keystone Architecture ===================== +Much of the design is precipitated from the expectation that the auth backends +for most deployments will actually be shims in front of existing user systems. + +.........JOEEDIT.......... Keystone has two major components: Authentication and a Service Catalog. Authentication diff --git a/docs/source/community.rst b/docs/source/community.rst index bbad2421..d3e32178 100644 --- a/docs/source/community.rst +++ b/docs/source/community.rst @@ -33,20 +33,6 @@ from blueprint designs to documentation to testing to deployment scripts. .. _Launchpad: https://launchpad.net/keystone .. _wiki: http://wiki.openstack.org/ - - -Contributing Code ------------------ - -To contribute code, sign up for a Launchpad account and sign a contributor license agreement, -available on the ``_. Once the CLA is signed you -can contribute code through the Gerrit version control system which is related to your Launchpad account. - -To contribute tests, docs, code, etc, refer to our `Gerrit-Jenkins-Github Workflow`_. - -.. _`Gerrit-Jenkins-Github Workflow`: http://wiki.openstack.org/GerritJenkinsGithub - - #openstack on Freenode IRC Network ---------------------------------- @@ -68,10 +54,10 @@ to write drafts for specs or documentation, describe a blueprint, or collaborate Keystone on Launchpad --------------------- -Launchpad is a code hosting service that hosts the Keystone source code. From -Launchpad you can report bugs, ask questions, and register blueprints (feature requests). +Launchpad is a code hosting that OpenStack is using to track bugs, feature work, and releases of OpenStack. Like other OpenStack projects, Keystone source code is hosted on GitHub -* `Launchpad Keystone Page `_ +* `Keystone Project Page on Launchpad `_ +* `Keystone Source Repository on GitHub `_ OpenStack Blog -------------- @@ -82,9 +68,9 @@ events and posts from OpenStack contributors. `OpenStack Blog `_ -See also: `Planet OpenStack `_, aggregating blogs -about OpenStack from around the internet into a single feed. If you'd like to contribute to this blog -aggregation with your blog posts, there are instructions for `adding your blog `_. +See also: `Planet OpenStack `_, an aggregation of blogs +about OpenStack from around the internet, combined into a web site and RSS feed. If you'd like to +contribute with your blog posts, there are instructions for `adding your blog `_. Twitter ------- diff --git a/docs/source/configuration.rst b/docs/source/configuration.rst index a98d92f8..02fbd4b4 100644 --- a/docs/source/configuration.rst +++ b/docs/source/configuration.rst @@ -21,80 +21,214 @@ Configuring Keystone .. toctree:: :maxdepth: 1 - keystone.conf man/keystone-manage -Once Keystone is installed, there are a number of configuration options -available and potentially some initial data to create and set up. - -Sample data / Quick Setup -========================= - -Default sampledata is provided for easy setup and testing in bin/sampeldata. To -set up the sample data run the following command while Keystone is running:: - - $ ./bin/sampledata - -The sample data created comes from the file :doc:`sourcecode/keystone.test.sampledata` +Once Keystone is installed, it is configured via a primary configuration file +(:doc:`keystone.conf`), possibly a separate logging configuration file, and +initializing data into keystone using the command line client. Keystone Configuration File =========================== -Most configuration is done via configuration files. The default files are -in ``/etc/keystone.conf`` - -When starting up a Keystone server, you can specify the configuration file to -use (see :doc:`controllingservers`). -If you do **not** specify a configuration file, keystone will look in the following -directories for a configuration file, in order: +The keystone configuration file is an 'ini' file format with sections, +extended from Paste_, a common system used to configure python WSGI based +applications. In addition to the paste config entries, general configuration +values are stored under [DEFAULT] and [sql], and then drivers for the various +backend components are included under their individual sections. + +The driver sections include: +* ``[identity]`` - the python module that backends the identity system +* ``[catalog]`` - the python module that backends the service catalog +* ``[token]`` - the python module that backends the token providing mechanisms +* ``[policy]`` - the python module that drives the policy system for RBAC +* ``[ec2]`` - the python module providing the EC2 translations for OpenStack + +The keystone configuration file is expected to be named ``keystone.conf``. +When starting up Keystone, you can specify a different configuration file to +use with ``--config-file``. If you do **not** specify a configuration file, +keystone will look in the following directories for a configuration file, in +order: * ``~/.keystone`` * ``~/`` * ``/etc/keystone`` * ``/etc`` -The keystone configuration file should be named ``keystone.conf``. -If you installed keystone via your operating system's -package management system, it is likely that you will have sample -configuration files installed in ``/etc/keystone``. +Logging is configured externally to the rest of keystone, the file specifying +the logging configuration is in the [DEFAULT] section of the keystone conf +file under ``log_config``. If you wish to route all your logging through +syslog, there is a ``use_syslog`` option also in the [DEFAULT] section that +easy. -In addition to this documentation page, you can check the -``etc/keystone.conf`` sample configuration -files distributed with keystone for example configuration files for each server -application with detailed comments on what each options does. +A sample logging file is available with the project in the directory ``etc/logging.conf.sample``. Like other OpenStack projects, keystone uses the +`python logging module`, which includes extensive configuration options for +choosing the output levels and formats. + +In addition to this documentation page, you can check the ``etc/keystone.conf`` +sample configuration files distributed with keystone for example configuration +files for each server application. + +.. _Paste: http://pythonpaste.org/ +.. _`python logging module`: http://docs.python.org/library/logging.html Sample Configuration Files -------------------------- -Keystone ships with sample configuration files in keystone/etc. These files are: +* ``etc/keystone.conf`` +* ``etc/logging.conf.sample`` + +Initializing Keystone +===================== + +Keystone must be running in order to initialize data within it. This is because +the keystone-manage commands are all used the same REST API that other +OpenStack systems utilize. + +General keystone-manage options: +-------------------------------- + +* ``--id-only`` : causes ``keystone-manage`` to return only the UUID result +from the API call. +* ``--endpoint`` : allows you to specify the keystone endpoint to communicate with. The default endpoint is http://localhost:35357/v2.0' +* ``--auth-token`` : provides the authorization token + +``keystone-manage`` is set up to expect commands in the general form of ``keystone-manage`` ``command`` ``subcommand``, with keyword arguments to provide additional information to the command. For example, the command +``tenant`` has the subcommand ``create``, which takes the required keyword ``tenant_name``:: + + keystone-manage tenant create tenant_name=example_tenant + +Invoking keystone-manage by itself will give you some usage information. + +Available keystone-manage commands: + db_sync: Sync the database. + ec2: no docs + role: Role CRUD functions. + service: Service CRUD functions. + tenant: Tenant CRUD functions. + token: Token CRUD functions. + user: User CRUD functions. + +Tenants +------- + +Tenants are the high level grouping within Keystone that represent groups of +users. A tenant is the grouping that owns virtual machines within Nova, or +containers within Swift. A tenant can have zero or more users, Users can be assocaited with more than one tenant, and each tenant - user pairing can have a role associated with it. + +* tenant create + + keyword arguments + * tenant_name + * id (optional) + +example:: + keystone-manage --id-only tenant create tenant_name=admin + +creates a tenant named "admin". + +* tenant delete + + keyword arguments + * tenant_id + +example:: + keystone-manage tenant delete tenant_id=f2b7b39c860840dfa47d9ee4adffa0b3 + +* tenant update + + keyword arguments + * description + * name + * tenant_id + +example:: + keystone-manage tenant update \ + tenant_id=f2b7b39c860840dfa47d9ee4adffa0b3 \ + description="those other guys" \ + name=tog + +Users +----- + +* user create + + keyword arguments + * name + * password + * email + +example:: + keystone-manage user --ks-id-only create \ + name=admin \ + password=secrete \ + email=admin@example.com + +* user delete + + keyword arguments + +* user list + + keyword arguments + +* user update_email + + keyword arguments + +* user update_enabled + + keyword arguments + +* user update_password + + keyword arguments -1. keystone.conf +* user update_tenant - A standard configuration file for running keystone in stand-alone mode. - It has a set of default extensions loaded to support administering Keystone - over REST. It uses a local SQLite database. + keyword arguments -2. memcache.conf +Roles +----- - A configuration that uses memcached for storing tokens (but still SQLite for all - other entities). This requires memcached running. +* role create -3. ssl.conf + keyword arguments + * name - A configuration that runs Keystone with SSL (so all URLs are accessed over HTTPS). +exmaple:: + keystone-manage role --ks-id-only create name=Admin + +* role add_user_to_tenant -To run any of these configurations, use the `-c` option:: + keyword arguments + * role_id + * user_id + * tenant_id - ./keystone -c ../etc/ssl.conf +example:: + keystone-manage role add_user_to_tenant \ + role_id=19d1d3344873464d819c45f521ff9890 \ + user_id=08741d8ed88242ca88d1f61484a0fe3b \ + tenant_id=20601a7f1d94447daa4dff438cb1c209 + +* role remove_user_from_tenant +* role get_user_role_refs -Usefule Links -------------- +Services +-------- -For a sample configuration file with explanations of the settings, see :doc:`keystone.conf` +* service create -For configuring an LDAP backend, see http://mirantis.blogspot.com/2011/08/ldap-identity-store-for-openstack.html + keyword arguments + * name + * service_type + * description -For configuration settings of middleware components, see :doc:`middleware` \ No newline at end of file +example:: + keystone-manage service create \ + name=nova \ + service_type=compute \ + description="Nova Compute Service" diff --git a/docs/source/developing.rst b/docs/source/developing.rst index acd22730..b19fec24 100644 --- a/docs/source/developing.rst +++ b/docs/source/developing.rst @@ -18,33 +18,22 @@ Developing with Keystone ======================== -Get your development environment set up according to :doc:`setup`. +Contributing Code +================= -Running a development instance -============================== +To contribute code, sign up for a Launchpad account and sign a contributor license agreement, +available on the ``_. Once the CLA is signed you +can contribute code through the Gerrit version control system which is related to your Launchpad account. -Setting up a virtualenv ------------------------ +To contribute tests, docs, code, etc, refer to our `Gerrit-Jenkins-Github Workflow`_. -We recommend establishing a virtualenv to run keystone within. To establish -this environment, use the command:: +.. _`Gerrit-Jenkins-Github Workflow`: http://wiki.openstack.org/GerritJenkinsGithub - $ python tools/install_venv.py +Setup +----- -This will create a local virtual environment in the directory ``.venv``. -Once created, you can activate this virtualenv for your current shell using:: - - $ source .venv/bin/activate - -The virtual environment can be disabled using the command:: - - $ deactivate - -You can also use ``tools\with_venv.sh`` to prefix commands so that they run -within the virtual environment. For more information on virtual environments, -see virtualenv_. - -.. _virtualenv: http://www.virtualenv.org/ +Get your development environment set up according to :doc:`setup`. The instructions from here will +assume that you have installed keystone into a virtualenv. If you chose not to, simply exclude "tools/with_venv.sh" from the example commands below. Running Keystone ---------------- @@ -52,84 +41,69 @@ Running Keystone To run the keystone Admin and API server instances, use:: $ tools/with_venv.sh bin/keystone - -Running a demo service that uses Keystone ------------------------------------------ - -To run client demo (with all auth middleware running locally on sample service):: - - $ tools/with_venv.sh examples/echo/bin/echod - -which spins up a simple "echo" service on port 8090. To use a simple echo client:: - - $ python examples/echo/echo_client.py + +this runs keystone with the configuration the etc/ directory of the project. See :doc:`configuration` for details on how Keystone is configured. Interacting with Keystone -========================= +------------------------- You can interact with Keystone through the command line using :doc:`man/keystone-manage` which allows you to establish tenants, users, etc. You can also interact with Keystone through it's REST API. There is a python -keystone client library python-keystoneclient_ which interacts exclusively through -the REST API. +keystone client library `python-keystoneclient`_ which interacts exclusively through +the REST API, and which keystone itself uses to provide it's command-line interface. + +.. _`python-keystoneclient`: https://github.com/openstack/python-keystoneclient + +Running Tests +============= + +To run the full suites of tests maintained within Keystone, run:: -.. _python-keystoneclient: https://github.com/4P/python-keystoneclient + $ ./run_tests.sh -The easiest way to establish some base information in Keystone to interact with is -to invoke:: +This shows realtime feedback during test execution, iterates over +multiple configuration variations, and uses external projects to do +light integration testing to verify the keystone API against other projects. - $ tools/with_venv.sh bin/sampledata +Test Structure +-------------- -You can see the details of what that creates in ``keystone/test/sampledata.py`` +UPDATE THIS... -Enabling debugging middleware ------------------------------ +Testing Schema Migrations +------------------------- -You can enable a huge amount of additional data (debugging information) about -the request and repsonse objects flowing through Keystone using the debugging -WSGI middleware. +The application of schema migrations can be tested using SQLAlchemy Migrate’s built-in test runner, one migration at a time. -To enable this, just modify the pipelines in ``etc/keystone.conf``, from:: +.. WARNING:: - [pipeline:admin] - pipeline = - urlnormalizer - admin_api + This may leave your database in an inconsistent state; attempt this in non-production environments only! - [pipeline:keystone-legacy-auth] - pipeline = - urlnormalizer - legacy_auth - d5_compat - service_api +This is useful for testing the *next* migration in sequence (both forward & backward) in a database under version control:: -... to:: + python keystone/common/sql/migrate_repo/manage.py test \ + --url=sqlite:///test.db \ + --repository=keystone/common/sql/migrate_repo/ - [pipeline:admin] - pipeline = - debug - urlnormalizer - d5_compat - admin_api +This command references to a SQLite database (test.db) to be used. Depending on the migration, this command alone does not make assertions as to the integrity of your data during migration. - [pipeline:keystone-legacy-auth] - pipeline = - debug - urlnormalizer - legacy_auth - d5_compat - service_api +Writing Tests +------------- -Two simple and easy debugging tools are using the ``-d`` when you start keystone:: +UPDATE THIS... - $ ./keystone -d -and the `--trace-calls` flag:: +Further Testing +--------------- - $ ./keystone -trace-calls +devstack_ is the *best* way to quickly deploy keystone with the rest of the +OpenStack universe and should be critical step in your development workflow! -The ``-d`` flag outputs debug information to the console. The ``--trace-calls`` flag -outputs extensive, nested trace calls to the console and highlights any errors -in red. +You may also be interested in either the `OpenStack Continuous Integration Project`_ +or the `OpenStack Integration Testing Project`_. +.. _devstack: http://devstack.org/ +.. _OpenStack Continuous Integration Project: https://github.com/openstack/openstack-ci +.. _OpenStack Integration Testing Project: https://github.com/openstack/tempest diff --git a/docs/source/index.rst b/docs/source/index.rst index 4270033a..427414d4 100644 --- a/docs/source/index.rst +++ b/docs/source/index.rst @@ -18,9 +18,9 @@ Welcome to Keystone, the OpenStack Identity Service! ==================================================== -Keystone is a cloud identity service written in Python, which provides -authentication, authorization, and an OpenStack service catalog. It -implements `OpenStack's Identity API`_. +Keystone is an OpenStack project that provides Identity, Token, Catalog and +Policy services for use specifically by projects in the OpenStack family. +It implements `OpenStack's Identity API`_. This document describes Keystone for contributors of the project, and assumes that you are already familiar with Keystone from an `end-user perspective`_. @@ -42,9 +42,18 @@ Getting Started :maxdepth: 1 setup + configuration + configuringservices community - testing +Man Pages +--------- + +.. toctree:: + :maxdepth: 1 + + man/keystone + man/keystone-manage Developers Documentation ======================== @@ -53,7 +62,8 @@ Developers Documentation developing architecture - sourcecode/autoindex + api_curl_examples + modules Indices and tables ================== diff --git a/docs/source/man/keystone-manage.rst b/docs/source/man/keystone-manage.rst index 9e9304f0..da5fc941 100644 --- a/docs/source/man/keystone-manage.rst +++ b/docs/source/man/keystone-manage.rst @@ -22,159 +22,202 @@ DESCRIPTION =========== keystone-manage is the command line tool that interacts with the keystone -service to configure Keystone +service to initialize and update data within Keystone. Keystone *must* be +opertional for the keystone-manage commands to function correctly. USAGE ===== ``keystone-manage [options] type action [additional args]`` -user ----- -* **user add** [username] [password] +General keystone-manage options: +-------------------------------- - adds a user to Keystone's data store +* ``--id-only`` : causes ``keystone-manage`` to return only the UUID result +from the API call. +* ``--endpoint`` : allows you to specify the keystone endpoint to communicate with. The default endpoint is http://localhost:35357/v2.0' +* ``--auth-token`` : provides the authorization token -* **user list** +``keystone-manage`` is set up to expect commands in the general form of ``keystone-manage`` ``command`` ``subcommand``, with keyword arguments to provide additional information to the command. For example, the command +``tenant`` has the subcommand ``create``, which takes the required keyword ``tenant_name``:: - lists all users + keystone-manage tenant create tenant_name=example_tenant -* **user disable** [username] +Invoking keystone-manage by itself will give you some usage information. - disables the user *username* +Available keystone-manage commands: + db_sync: Sync the database. + ec2: no docs + role: Role CRUD functions. + service: Service CRUD functions. + tenant: Tenant CRUD functions. + token: Token CRUD functions. + user: User CRUD functions. -tenant ------- - -* **tenant add** [tenant_name] +Tenants +------- - adds a tenant to Keystone's data store +Tenants are the high level grouping within Keystone that represent groups of +users. A tenant is the grouping that owns virtual machines within Nova, or +containers within Swift. A tenant can have zero or more users, Users can be assocaited with more than one tenant, and each tenant - user pairing can have a role associated with it. -* **tenant list** +* tenant create - lists all users + keyword arguments + * tenant_name + * id (optional) -* **tenant disable** [tenant_name] +example:: + keystone-manage --id-only tenant create tenant_name=admin -role ----- +creates a tenant named "admin". -Roles are used to associated users to tenants. Two roles are defined related -to the Keystone service in it's configuration file :doc:`../keystone.conf` +* tenant delete -* **role add** [role_name] + keyword arguments + * tenant_id + +example:: + keystone-manage tenant delete tenant_id=f2b7b39c860840dfa47d9ee4adffa0b3 - adds a role +* tenant update -* **role list** ([tenant_name]) + keyword arguments + * description + * name + * tenant_id - lists all roles, or all roles for tenant, if tenant_name is provided +example:: + keystone-manage tenant update \ + tenant_id=f2b7b39c860840dfa47d9ee4adffa0b3 \ + description="those other guys" \ + name=tog -* **role grant** [role_name] [username] ([tenant]) +Users +----- - grants a role to a specific user. Granted globally if tenant_name is not - provided or granted for a specific tenant if tenant_name is provided. +* user create -service -------- + keyword arguments + * name + * password + * email + +example:: + keystone-manage user --ks-id-only create \ + name=admin \ + password=secrete \ + email=admin@example.com + +* user delete -* **service add** [name] [type] [description] [owner_id] + keyword arguments - adds a service +* user list -* **service list** + keyword arguments - lists all services with id, name, and type +* user update_email -endpointTemplate ----------------- + keyword arguments -* **endpointTemplate add** [region] [service_name] [public_url] [admin_url] [internal_url] [enabled] [is_global] +* user update_enabled - Add a service endpoint for keystone. + keyword arguments - example:: +* user update_password + + keyword arguments - keystone-manage endpointTemplates add RegionOne \ - keystone \ - http://keystone_host:5000/v2.0 \ - http://keystone_host:35357/v2.0 \ - http://keystone_host:5000/v2.0 \ - 1 1 +* user update_tenant -* **endpointTemplate list** ([tenant_name]) + keyword arguments - lists endpoint templates with service, region, and public_url. Restricted to - tenant endpoints if tenant_name is provided. - -token +Roles ----- -* **token add** [token] [username] [tenant] [expiration] +* role create + + keyword arguments + * name - adds a token for a given user and tenant with an expiration +exmaple:: + keystone-manage role --ks-id-only create name=Admin + +* role add_user_to_tenant -* **token list** + keyword arguments + * role_id + * user_id + * tenant_id - lists all tokens +example:: -* **token delete** [token] + keystone-manage role add_user_to_tenant \ + role_id=19d1d3344873464d819c45f521ff9890 \ + user_id=08741d8ed88242ca88d1f61484a0fe3b \ + tenant_id=20601a7f1d94447daa4dff438cb1c209 + +* role remove_user_from_tenant - deletes the identified token +* role get_user_role_refs -endpoint +Services -------- -* **endpoint add** [tenant_name] [endpoint_template] +* service create - adds a tenant-specific endpoint + keyword arguments + * name + * service_type + * description -credentials ------------ +example:: + keystone-manage service create \ + name=nova \ + service_type=compute \ + description="Nova Compute Service" -* **credentials add** [username] [type] [key] [password] ([tenant_name]) OPTIONS ======= - --version show program's version number and exit - -h, --help show this help message and exit - -v, --verbose Print more verbose output - -d, --debug Print debugging output to console - -c PATH, --config-file=PATH Path to the config file to use. When not - specified (the default), we generally look at - the first argument specified to be a config - file, and if that is also missing, we search - standard directories for a config file. - -p BIND_PORT, --port=BIND_PORT, --bind-port=BIND_PORT - specifies port to listen on (default is 5000) - --host=BIND_HOST, --bind-host=BIND_HOST - specifies host address to listen on (default - is all or 0.0.0.0) - -t, --trace-calls Turns on call tracing for troubleshooting - -a PORT, --admin-port=PORT Specifies port for Admin API to listen on - (default is 35357) - -Logging Options: -================ - -The following configuration options are specific to logging -functionality for this program. - - --log-config=PATH If this option is specified, the logging - configuration file specified is used and - overrides any other logging options specified. - Please see the Python logging module - documentation for details on logging - configuration files. - --log-date-format=FORMAT Format string for %(asctime)s in log records. - Default: %Y-%m-%d %H:%M:%S - --log-file=PATH (Optional) Name of log file to output to. If - not set, logging will go to stdout. - --log-dir=LOG_DIR (Optional) The directory to keep log files in - (will be prepended to --logfile) - +Options: + -h, --help show this help message and exit + --config-file=PATH Path to a config file to use. Multiple config files + can be specified, with values in later files taking + precedence. The default files used are: [] + -d, --debug Print debugging output + --nodebug Print debugging output + -v, --verbose Print more verbose output + --noverbose Print more verbose output + --log-config=PATH If this option is specified, the logging configuration + file specified is used and overrides any other logging + options specified. Please see the Python logging + module documentation for details on logging + configuration files. + --log-format=FORMAT A logging.Formatter log message format string which + may use any of the available logging.LogRecord + attributes. Default: none + --log-date-format=DATE_FORMAT + Format string for %(asctime)s in log records. Default: + none + --log-file=PATH (Optional) Name of log file to output to. If not set, + logging will go to stdout. + --log-dir=LOG_DIR (Optional) The directory to keep log files in (will be + prepended to --logfile) + --syslog-log-facility=SYSLOG_LOG_FACILITY + (Optional) The syslog facility to use when logging to + syslog (defaults to LOG_USER) + --use-syslog Use syslog for logging. + --nouse-syslog Use syslog for logging. + --endpoint=ENDPOINT + --auth-token=AUTH_TOKEN + authorization token + --id-only + --noid-only + FILES ===== diff --git a/docs/source/man/keystone.rst b/docs/source/man/keystone.rst index 48e062e4..74d0bb69 100644 --- a/docs/source/man/keystone.rst +++ b/docs/source/man/keystone.rst @@ -21,9 +21,7 @@ SYNOPSIS DESCRIPTION =========== -keystone starts both the service and administrative API servers for Keystone. -Use :doc:`keystone-control` to stop/start/restart and manage those services -once started. +keystone starts both the service and administrative APIs for Keystone. USAGE ===== @@ -32,47 +30,40 @@ USAGE Common Options: ^^^^^^^^^^^^^^^ - --version show program's version number and exit -h, --help show this help message and exit The following configuration options are common to all keystone programs.:: - -v, --verbose Print more verbose output - -d, --debug Print debugging output to console - -c PATH, --config-file=PATH Path to the config file to use. When not - specified (the default), we generally look at - the first argument specified to be a config - file, and if that is also missing, we search - standard directories for a config file. - -p BIND_PORT, --port=BIND_PORT, --bind-port=BIND_PORT - specifies port to listen on (default is 5000) - --host=BIND_HOST, --bind-host=BIND_HOST - specifies host address to listen on (default - is all or 0.0.0.0) - -t, --trace-calls Turns on call tracing for troubleshooting - -a PORT, --admin-port=PORT Specifies port for Admin API to listen on - (default is 35357) - -Logging Options: -^^^^^^^^^^^^^^^^ - -The following configuration options are specific to logging -functionality for this program.:: - - --log-config=PATH If this option is specified, the logging - configuration file specified is used and - overrides any other logging options specified. - Please see the Python logging module - documentation for details on logging - configuration files. - --log-date-format=FORMAT Format string for %(asctime)s in log records. - Default: %Y-%m-%d %H:%M:%S - --log-file=PATH (Optional) Name of log file to output to. If - not set, logging will go to stdout. - --log-dir=LOG_DIR (Optional) The directory to keep log files in - (will be prepended to --logfile) - + -h, --help show this help message and exit + --config-file=PATH Path to a config file to use. Multiple config files + can be specified, with values in later files taking + precedence. The default files used are: [] + -d, --debug Print debugging output + --nodebug Print debugging output + -v, --verbose Print more verbose output + --noverbose Print more verbose output + --log-config=PATH If this option is specified, the logging configuration + file specified is used and overrides any other logging + options specified. Please see the Python logging + module documentation for details on logging + configuration files. + --log-format=FORMAT A logging.Formatter log message format string which + may use any of the available logging.LogRecord + attributes. Default: none + --log-date-format=DATE_FORMAT + Format string for %(asctime)s in log records. Default: + none + --log-file=PATH (Optional) Name of log file to output to. If not set, + logging will go to stdout. + --log-dir=LOG_DIR (Optional) The directory to keep log files in (will be + prepended to --logfile) + --syslog-log-facility=SYSLOG_LOG_FACILITY + (Optional) The syslog facility to use when logging to + syslog (defaults to LOG_USER) + --use-syslog Use syslog for logging. + --nouse-syslog Use syslog for logging. + FILES ===== diff --git a/docs/source/setup.rst b/docs/source/setup.rst index e608f09e..25a43655 100644 --- a/docs/source/setup.rst +++ b/docs/source/setup.rst @@ -18,12 +18,12 @@ Setting up a Keystone development environment ============================================= -This document describes setting up keystone directly from GitHub_ +This document describes getting the source from keystone's `GitHub repository`_ for development purposes. To install keystone from packaging, refer instead to Keystone's `User Documentation`_. -.. _GitHub: http://github.com/openstack/keystone +.. _`GitHub Repository`: http://github.com/openstack/keystone .. _`User Documentation`: http://docs.openstack.org/ Prerequisites @@ -51,7 +51,7 @@ different version of the above, please document your configuration here! Getting the latest code ======================= -You can clone our latest code from our `Github repository`:: +Make a clone of the code from our `Github repository`:: $ git clone https://github.com/openstack/keystone.git @@ -59,13 +59,17 @@ When that is complete, you can:: $ cd keystone -.. _`Github repository`: https://github.com/openstack/keystone - Installing dependencies ======================= -Keystone maintains a list of PyPi_ dependencies, designed for use by -pip_. +Keystone maintains two lists of dependencies: + + tools/pip-requires + tools/pip-requires-test + +The first is the list of dependencies needed for running keystone, the second list includes dependencies used for active development and testing of keystone itself. + +These depdendencies can be installed from PyPi_ using the python tool pip_. .. _PyPi: http://pypi.python.org/ .. _pip: http://pypi.python.org/pypi/pip @@ -89,29 +93,51 @@ Mac OS X Lion (requires MacPorts_):: .. _MacPorts: http://www.macports.org/ -PyPi Packages -------------- +PyPi Packages and VirtualEnv +---------------------------- -Assuming you have any necessary binary packages & header files available -on your system, you can then install PyPi dependencies. +We recommend establishing a virtualenv to run keystone within. Virtualenv limits the python environment +to just what you're installing as depdendencies, useful to keep a clean environment for working on +Keystone. The tools directory in keystone has a script already created to make this very simple:: -You may also need to prefix `pip install` with `sudo`, depending on your -environment:: + $ python tools/install_venv.py - # Describe dependencies (including non-PyPi dependencies) - $ cat tools/pip-requires +This will create a local virtual environment in the directory ``.venv``. +Once created, you can activate this virtualenv for your current shell using:: - # Install all PyPi dependencies (for production, testing, and development) - $ pip install -r tools/pip-requires + $ source .venv/bin/activate + +The virtual environment can be disabled using the command:: + + $ deactivate -Updating your PYTHONPATH -======================== +You can also use ``tools\with_venv.sh`` to prefix commands so that they run +within the virtual environment. For more information on virtual environments, +see virtualenv_. -There are a number of methods for getting Keystone into your PYTHON PATH, -the easiest of which is:: +.. _virtualenv: http://www.virtualenv.org/ +If you want to run keystone outside of a virtualenv, you can install the dependencies directly +into your system from the requires files:: + + # Install the dependencies for running keystone + $ pip install -r tools/pip-requires + + # Install the dependencies for developing, testing, and running keystone + $ pip install -r tools/pip-requires-test + # Fake-install the project by symlinking Keystone into your Python site-packages $ python setup.py develop + + +Verifying Keystone is set up +============================ + +Once set up, either directly or within a virtualenv, you should be able to invoke python and import +the libraries. If you're using a virtualenv, don't forget to activate it:: + + $ source .venv/bin/activate + $ python You should then be able to `import keystone` from your Python shell without issue:: @@ -124,8 +150,7 @@ If you want to check the version of Keystone you are running: >>> print keystone.version.version() 2012.1-dev - -If you can import keystone successfully, you should be ready to move on to :doc:`testing`. +If you can import keystone successfully, you should be ready to move on to :doc:`testing` and :doc:`developing` Troubleshooting =============== diff --git a/docs/source/testing.rst b/docs/source/testing.rst deleted file mode 100644 index 82a33604..00000000 --- a/docs/source/testing.rst +++ /dev/null @@ -1,77 +0,0 @@ -================ -Testing Keystone -================ - -Keystone uses a number of testing methodologies to ensure correctness. - -Running Built-In Tests -====================== - -To run the full suites of tests maintained within Keystone, run:: - - $ ./run_tests.sh --with-progress - -This shows realtime feedback during test execution, and iterates over -multiple configuration variations. - -This differs from how tests are executed from the continuous integration -environment. Specifically, Jenkins doesn't care about realtime progress, -and aborts after the first test failure (a fail-fast behavior):: - - $ ./run_tests.sh - -Testing Schema Migrations -========================= - -The application of schema migrations can be tested using SQLAlchemy Migrate’s built-in test runner, one migration at a time. - -.. WARNING:: - - This may leave your database in an inconsistent state; attempt this in non-production environments only! - -This is useful for testing the *next* migration in sequence (both forward & backward) in a database under version control:: - - $ python keystone/backends/sqlalchemy/migrate_repo/manage.py test --url=sqlite:///test.db --repository=keystone/backends/sqlalchemy/migrate_repo/ - -This command refers to a SQLite database used for testing purposes. Depending on the migration, this command alone does not make assertions as to the integrity of your data during migration. - -Writing Tests -============= - -Tests are maintained in the ``keystone.test`` module. Unit tests are -isolated from functional tests. - -Functional Tests ----------------- - -The ``keystone.test.functional.common`` module provides a ``unittest``-based -``httplib`` client which you can extend and use for your own tests. -Generally, functional tests should serve to illustrate intended use cases -and API behaviors. To help make your tests easier to read, the test client: - -- Authenticates with a known user name and password combination -- Asserts 2xx HTTP status codes (unless told otherwise) -- Abstracts keystone REST verbs & resources into single function calls - -Testing Multiple Configurations -------------------------------- - -Several variations of the default configuration are iterated over to -ensure test coverage of mutually exclusive featuresets, such as the -various backend options. - -These configuration templates are maintained in ``keystone/test/etc`` and -are iterated over by ``run_tests.py``. - -Further Testing -=============== - -devstack_ is the *best* way to quickly deploy keystone with the rest of the -OpenStack universe and should be critical step in your development workflow! - -You may also be interested in either the `OpenStack Continuous Integration Project`_ -or the `OpenStack Integration Testing Project`_. - -.. _devstack: http://devstack.org/ -.. _OpenStack Continuous Integration Project: https://github.com/openstack/openstack-ci -.. _OpenStack Integration Testing Project: https://github.com/openstack/openstack-integration-tests -- cgit From fec7598a07b4beca78fe31a549e5d3beb6c0dc5d Mon Sep 17 00:00:00 2001 From: Joe Heck Date: Sun, 29 Jan 2012 13:24:38 -0800 Subject: shifting older docs into old/ directory --- docs/source/adminAPI_curl_examples.rst | 387 -------------------- docs/source/configuration.rst | 2 +- docs/source/configuringservices.rst | 333 ----------------- docs/source/controllingservers.rst | 288 --------------- docs/source/endpoints.rst | 430 ---------------------- docs/source/extensions.rst | 183 ---------- docs/source/index.rst | 6 +- docs/source/middleware.rst | 169 --------- docs/source/middleware_architecture.rst | 529 ---------------------------- docs/source/migration.rst | 126 ------- docs/source/nova-api-paste.rst | 142 -------- docs/source/old/configuringservices.rst | 333 +++++++++++++++++ docs/source/old/controllingservers.rst | 288 +++++++++++++++ docs/source/old/endpoints.rst | 430 ++++++++++++++++++++++ docs/source/old/extensions.rst | 183 ++++++++++ docs/source/old/middleware.rst | 169 +++++++++ docs/source/old/middleware_architecture.rst | 529 ++++++++++++++++++++++++++++ docs/source/old/migration.rst | 126 +++++++ docs/source/old/nova-api-paste.rst | 142 ++++++++ docs/source/old/releases.rst | 36 ++ docs/source/old/services.rst | 92 +++++ docs/source/old/ssl.rst | 118 +++++++ docs/source/releases.rst | 36 -- docs/source/serviceAPI_curl_examples.rst | 69 ---- docs/source/services.rst | 92 ----- docs/source/ssl.rst | 118 ------- docs/source/usingkeystone.rst | 28 -- 27 files changed, 2450 insertions(+), 2934 deletions(-) delete mode 100644 docs/source/adminAPI_curl_examples.rst delete mode 100644 docs/source/configuringservices.rst delete mode 100644 docs/source/controllingservers.rst delete mode 100644 docs/source/endpoints.rst delete mode 100644 docs/source/extensions.rst delete mode 100644 docs/source/middleware.rst delete mode 100644 docs/source/middleware_architecture.rst delete mode 100644 docs/source/migration.rst delete mode 100644 docs/source/nova-api-paste.rst create mode 100644 docs/source/old/configuringservices.rst create mode 100644 docs/source/old/controllingservers.rst create mode 100644 docs/source/old/endpoints.rst create mode 100644 docs/source/old/extensions.rst create mode 100644 docs/source/old/middleware.rst create mode 100644 docs/source/old/middleware_architecture.rst create mode 100644 docs/source/old/migration.rst create mode 100644 docs/source/old/nova-api-paste.rst create mode 100644 docs/source/old/releases.rst create mode 100644 docs/source/old/services.rst create mode 100644 docs/source/old/ssl.rst delete mode 100644 docs/source/releases.rst delete mode 100644 docs/source/serviceAPI_curl_examples.rst delete mode 100644 docs/source/services.rst delete mode 100644 docs/source/ssl.rst delete mode 100644 docs/source/usingkeystone.rst (limited to 'docs') diff --git a/docs/source/adminAPI_curl_examples.rst b/docs/source/adminAPI_curl_examples.rst deleted file mode 100644 index 81f96c36..00000000 --- a/docs/source/adminAPI_curl_examples.rst +++ /dev/null @@ -1,387 +0,0 @@ -.. - Copyright 2011 OpenStack, LLC - All Rights Reserved. - - Licensed under the Apache License, Version 2.0 (the "License"); you may - not use this file except in compliance with the License. You may obtain - a copy of the License at - - http://www.apache.org/licenses/LICENSE-2.0 - - Unless required by applicable law or agreed to in writing, software - distributed under the License is distributed on an "AS IS" BASIS, WITHOUT - WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the - License for the specific language governing permissions and limitations - under the License. - -============================= -Admin API Examples Using Curl -============================= - -These examples assume a default port value of 35357, and depend on the -``sampledata`` bundled with keystone. - -GET / -===== - -Disover API version information, links to documentation (PDF, HTML, WADL), -and supported media types:: - - $ curl http://0.0.0.0:35357 - -or:: - - $ curl http://0.0.0.0:35357/v2.0/ - -Returns:: - - { - "version":{ - "id":"v2.0", - "status":"beta", - "updated":"2011-11-19T00:00:00Z", - "links":[ - { - "rel":"self", - "href":"http://127.0.0.1:35357/v2.0/" - }, - { - "rel":"describedby", - "type":"text/html", - "href":"http://docs.openstack.org/api/openstack-identity-service/2.0/content/" - }, - { - "rel":"describedby", - "type":"application/pdf", - "href":"http://docs.openstack.org/api/openstack-identity-service/2.0/identity-dev-guide-2.0.pdf" - }, - { - "rel":"describedby", - "type":"application/vnd.sun.wadl+xml", - "href":"http://127.0.0.1:35357/v2.0/identity-admin.wadl" - } - ], - "media-types":[ - { - "base":"application/xml", - "type":"application/vnd.openstack.identity-v2.0+xml" - }, - { - "base":"application/json", - "type":"application/vnd.openstack.identity-v2.0+json" - } - ] - } - } - -GET /extensions -=============== - -Discover the API extensions enabled at the endpoint:: - - $ curl http://0.0.0.0:35357/extensions - -Returns:: - - { - "extensions":{ - "values":[] - } - } - -POST /tokens -============ - -Authenticate by exchanging credentials for an access token:: - - $ curl -d '{"auth":{"passwordCredentials":{"username": "joeuser", "password": "secrete"}}}' -H "Content-type: application/json" http://localhost:35357/v2.0/tokens - -Returns:: - - { - "access":{ - "token":{ - "expires":"2012-02-05T00:00:00", - "id":"887665443383838", - "tenant":{ - "id":"1", - "name":"customer-x" - } - }, - "serviceCatalog":[ - { - "endpoints":[ - { - "adminURL":"http://swift.admin-nets.local:8080/", - "region":"RegionOne", - "internalURL":"http://127.0.0.1:8080/v1/AUTH_1", - "publicURL":"http://swift.publicinternets.com/v1/AUTH_1" - } - ], - "type":"object-store", - "name":"swift" - }, - { - "endpoints":[ - { - "adminURL":"http://cdn.admin-nets.local/v1.1/1", - "region":"RegionOne", - "internalURL":"http://127.0.0.1:7777/v1.1/1", - "publicURL":"http://cdn.publicinternets.com/v1.1/1" - } - ], - "type":"object-store", - "name":"cdn" - } - ], - "user":{ - "id":"1", - "roles":[ - { - "tenantId":"1", - "id":"3", - "name":"Member" - } - ], - "name":"joeuser" - } - } - } - -.. note:: - - Take note of the value ['access']['token']['id'] value produced here (``887665443383838``, above), as you can use it in the calls below. - -GET /tokens/{token_id} -====================== - -.. note:: - - This call refers to a token known to be valid, ``887665443383838`` in this case. - -Validate a token:: - - $ curl -H "X-Auth-Token:999888777666" http://localhost:35357/v2.0/tokens/887665443383838 - -If the token is valid, returns:: - - { - "access":{ - "token":{ - "expires":"2012-02-05T00:00:00", - "id":"887665443383838", - "tenant":{ - "id":"1", - "name":"customer-x" - } - }, - "user":{ - "name":"joeuser", - "tenantName":"customer-x", - "id":"1", - "roles":[ - { - "serviceId":"1", - "id":"3", - "name":"Member" - } - ], - "tenantId":"1" - } - } - } - -HEAD /tokens/{token_id} -======================= - -This is a high-performance variant of the GET call documented above, which -by definition, returns no response body:: - - $ curl -I -H "X-Auth-Token:999888777666" http://localhost:35357/v2.0/tokens/887665443383838 - -... which returns ``200``, indicating the token is valid:: - - HTTP/1.1 200 OK - Content-Length: 0 - Content-Type: None - Date: Tue, 08 Nov 2011 23:07:44 GMT - -GET /tokens/{token_id}/endpoints -================================ - -List all endpoints for a token:: - - $ curl -H "X-Auth-Token:999888777666" http://localhost:35357/v2.0/tokens/887665443383838/endpoints - -Returns:: - - { - "endpoints_links": [ - { - "href": "http://127.0.0.1:35357/tokens/887665443383838/endpoints?'marker=5&limit=10'", - "rel": "next" - } - ], - "endpoints": [ - { - "internalURL": "http://127.0.0.1:8080/v1/AUTH_1", - "name": "swift", - "adminURL": "http://swift.admin-nets.local:8080/", - "region": "RegionOne", - "tenantId": 1, - "type": "object-store", - "id": 1, - "publicURL": "http://swift.publicinternets.com/v1/AUTH_1" - }, - { - "internalURL": "http://localhost:8774/v1.0", - "name": "nova_compat", - "adminURL": "http://127.0.0.1:8774/v1.0", - "region": "RegionOne", - "tenantId": 1, - "type": "compute", - "id": 2, - "publicURL": "http://nova.publicinternets.com/v1.0/" - }, - { - "internalURL": "http://localhost:8774/v1.1", - "name": "nova", - "adminURL": "http://127.0.0.1:8774/v1.1", - "region": "RegionOne", - "tenantId": 1, - "type": "compute", - "id": 3, - "publicURL": "http://nova.publicinternets.com/v1.1/ - }, - { - "internalURL": "http://127.0.0.1:9292/v1.1/", - "name": "glance", - "adminURL": "http://nova.admin-nets.local/v1.1/", - "region": "RegionOne", - "tenantId": 1, - "type": "image", - "id": 4, - "publicURL": "http://glance.publicinternets.com/v1.1/" - }, - { - "internalURL": "http://127.0.0.1:7777/v1.1/1", - "name": "cdn", - "adminURL": "http://cdn.admin-nets.local/v1.1/1", - "region": "RegionOne", - "tenantId": 1, - "versionId": "1.1", - "versionList": "http://127.0.0.1:7777/", - "versionInfo": "http://127.0.0.1:7777/v1.1", - "type": "object-store", - "id": 5, - "publicURL": "http://cdn.publicinternets.com/v1.1/1" - } - ] - } - -GET /tenants -============ - -List all of the tenants in the system (requires an Admin ``X-Auth-Token``):: - - $ curl -H "X-Auth-Token:999888777666" http://localhost:35357/v2.0/tenants - -Returns:: - - { - "tenants_links": [], - "tenants": [ - { - "enabled": false, - "description": "None", - "name": "project-y", - "id": "3" - }, - { - "enabled": true, - "description": "None", - "name": "ANOTHER:TENANT", - "id": "2" - }, - { - "enabled": true, - "description": "None", - "name": "customer-x", - "id": "1" - } - ] - } - -GET /tenants/{tenant_id} -======================== - -Retrieve information about a tenant, by tenant ID:: - - $ curl -H "X-Auth-Token:999888777666" http://localhost:35357/v2.0/tenants/1 - -Returns:: - - { - "tenant":{ - "enabled":true, - "description":"None", - "name":"customer-x", - "id":"1" - } - } - -GET /tenants/{tenant_id}/users/{user_id}/roles -============================================== - -List the roles a user has been granted on a tenant:: - - $ curl -H "X-Auth-Token:999888777666" http://localhost:35357/v2.0/tenants/1/users/1/roles - -Returns:: - - { - "roles_links":[], - "roles":[ - { - "id":"3", - "name":"Member" - } - ] - } - -GET /users/{user_id} -==================== - -Retrieve information about a user, by user ID:: - - $ curl -H "X-Auth-Token:999888777666" http://localhost:35357/v2.0/users/1 - -Returns:: - - { - "user":{ - "tenantId":"1", - "enabled":true, - "id":"1", - "name":"joeuser" - } - } - -GET /users/{user_id}/roles -========================== - -Retrieve the roles granted to a user, given a user ID:: - - $ curl -H "X-Auth-Token:999888777666" http://localhost:35357/v2.0/users/4/roles - -Returns:: - - { - "roles_links":[], - "roles":[ - { - "id":"2", - "name":"KeystoneServiceAdmin" - } - ] - } diff --git a/docs/source/configuration.rst b/docs/source/configuration.rst index 02fbd4b4..e16d1892 100644 --- a/docs/source/configuration.rst +++ b/docs/source/configuration.rst @@ -24,7 +24,7 @@ Configuring Keystone man/keystone-manage Once Keystone is installed, it is configured via a primary configuration file -(:doc:`keystone.conf`), possibly a separate logging configuration file, and +(``etc/keystone.conf``), possibly a separate logging configuration file, and initializing data into keystone using the command line client. diff --git a/docs/source/configuringservices.rst b/docs/source/configuringservices.rst deleted file mode 100644 index 083c3ec5..00000000 --- a/docs/source/configuringservices.rst +++ /dev/null @@ -1,333 +0,0 @@ -.. - Copyright 2011 OpenStack, LLC - All Rights Reserved. - - Licensed under the Apache License, Version 2.0 (the "License"); you may - not use this file except in compliance with the License. You may obtain - a copy of the License at - - http://www.apache.org/licenses/LICENSE-2.0 - - Unless required by applicable law or agreed to in writing, software - distributed under the License is distributed on an "AS IS" BASIS, WITHOUT - WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the - License for the specific language governing permissions and limitations - under the License. - -========================================== -Configuring Services to work with Keystone -========================================== - -.. toctree:: - :maxdepth: 1 - -Once Keystone is installed and running, services need to be configured to work -with it. These are the steps to configure a service to work with Keystone: - -1. Create or get credentials for the service to use - - A set of credentials are needed for each service (they may be - shared if you chose to). Depending on the service, these credentials are - either a username and password or a long-lived token.. - -2. Register the service, endpoints, roles and other entities - - In order for a service to have it's endpoints and roles show in the service - catalog returned by Keystone, a service record needs to be added for the - service. Endpoints and roles associated with that service can then be created. - - This can be done through the REST interface (using the OS-KSCATALOG extension) - or using keystone-manage. - -3. Install and configure middleware for the service to handle authentication - - Clients making calls to the service will pass in an authentication token. The - Keystone middleware will look for and validate that token, taking the - appropriate action. It will also retrive additional information from the token - such as user name, id, tenant name, id, roles, etc... - - The middleware will pass those data down to the service as headers. The - detailed description of this architecture is available here :doc:`middleware_architecture` - -Setting up credentials -====================== - -First admin user - bootstrapping --------------------------------- - -For a default installation of Keystone, before you can use the REST API, you -need to create your first initial user and grant that user the right to -administer Keystone. - -For the keystone service itself, two -Roles are pre-defined in the keystone configuration file -(:doc:`keystone.conf`). - - #Role that allows admin operations (access to all operations) - keystone-admin-role = Admin - - #Role that allows acting as service (validate tokens, register service, - etc...) - keystone-service-admin-role = KeystoneServiceAdmin - -In order to create your first user, once Keystone is running use -the `keystone-manage` command: - - $ keystone-manage user add admin secrete - $ keystone-manage role add Admin - $ keystone-manage role add KeystoneServiceAdmin - $ keystone-manage role grant Admin admin - $ keystone-manage role grant KeystoneServiceAdmin admin - -This creates the `admin` user (with a password of `secrete`), creates -two roles (`Admin` and `KeystoneServiceAdmin`), and assigns those roles to -the `admin` user. From here, you should now have the choice of using the -administrative API (as well as the :doc:`man/keystone-manage` commands) to -further configure keystone. There are a number of examples of how to use -that API at :doc:`adminAPI_curl_examples`. - - -Setting up services -=================== - -Defining Services and Service Endpoints ---------------------------------------- - -Keystone also acts as a service catalog to let other OpenStack systems know -where relevant API endpoints exist for OpenStack Services. The OpenStack -Dashboard, in particular, uses this heavily - and this **must** be configured -for the OpenStack Dashboard to properly function. - -Here's how we define the services:: - - $ keystone-manage service add nova compute "Nova Compute Service" - $ keystone-manage service add glance image "Glance Image Service" - $ keystone-manage service add swift storage "Swift Object Storage Service" - $ keystone-manage service add keystone identity "Keystone Identity Service" - -Once the services are defined, we create endpoints for them. Each service -has three relevant URL's associated with it that are used in the command: - -* the public API URL -* an administrative API URL -* an internal URL - -The "internal URL" is an endpoint the generally offers the same API as the -public URL, but over a high-bandwidth, low-latency, unmetered (free) network. -You would use that to transfer images from nova to glance for example, and -not the Public URL which would go over the internet and be potentially chargeable. - -The "admin URL" is for administering the services and is not exposed or accessible -to customers without the apporpriate privileges. - -An example of setting up the endpoint for Nova:: - - $ keystone-manage endpointTemplates add RegionOne nova \ - http://nova-api.mydomain:8774/v1.1/%tenant_id% \ - http://nova-api.mydomain:8774/v1.1/%tenant_id% \ - http://nova-api.mydomain:8774/v1.1/%tenant_id% \ - 1 1 - -Glance:: - - $ keystone-manage endpointTemplates add RegionOne glance \ - http://glance.mydomain:9292/v1 \ - http://glance.mydomain:9292/v1 \ - http://glance.mydomain:9292/v1 \ - 1 1 - -Swift:: - - $ keystone-manage endpointTemplates add RegionOne swift \ - http://swift.mydomain:8080/v1/AUTH_%tenant_id% \ - http://swift.mydomain:8080/v1.0/ \ - http://swift.mydomain:8080/v1/AUTH_%tenant_id% \ - 1 1 - -And setting up an endpoint for Keystone:: - - $ keystone-manage endpointTemplates add RegionOne keystone \ - http://keystone.mydomain:5000/v2.0 \ - http://keystone.mydomain:35357/v2.0 \ - http://keystone.mydomain:5000/v2.0 \ - 1 1 - - -Defining an Administrative Service Token ----------------------------------------- - -An Administrative Service Token is a bit of arbitrary text which is configured -in Keystone and used (typically configured into) Nova, Swift, Glance, and any -other OpenStack projects, to be able to use Keystone services. - -This token is an arbitrary text string, but must be identical between Keystone -and the services using Keystone. This token is bound to a user and tenant as -well, so those also need to be created prior to setting it up. - -The *admin* user was set up above, but we haven't created a tenant for that -user yet:: - - $ keystone-manage tenant add admin - -and while we're here, let's grant the admin user the 'Admin' role to the -'admin' tenant:: - - $ keystone-manage role add Admin - $ keystone-manage role grant Admin admin admin - -Now we can create a service token:: - - $ keystone-manage token add 999888777666 admin admin 2015-02-05T00:00 - -This creates a service token of '999888777666' associated to the admin user, -admin tenant, and expires on February 5th, 2015. This token will be used when -configuring Nova, Glance, or other OpenStack services. - -Securing Communications with SSL --------------------------------- - -To encrypt traffic between services and Keystone, see :doc:`ssl` - - -Setting up OpenStack users -========================== - -Creating Tenants, Users, and Roles ----------------------------------- - -Let's set up a 'demo' tenant:: - - $ keystone-manage tenant add demo - -And add a 'demo' user with the password 'guest':: - - $ keystone-manage user add demo guest - -Now let's add a role of "Member" and grant 'demo' user that role -as it pertains to the tenant 'demo':: - - $ keystone-manage role add Member - $ keystone-manage role grant Member demo demo - -Let's also add the admin user as an Admin role to the demo tenant:: - - $ keystone-manage role grant Admin admin demo - -Creating EC2 credentials ------------------------- - -To add EC2 credentials for the `admin` and `demo` accounts:: - - $ keystone-manage credentials add admin EC2 'admin' 'secretpassword' - $ keystone-manage credentials add admin EC2 'demo' 'secretpassword' - -If you have a large number of credentials to create, you can put them all -into a single large file and import them using :doc:`man/keystone-import`. The -format of the document looks like:: - - credentials add admin EC2 'username' 'password' - credentials add admin EC2 'username' 'password' - -Then use:: - - $ keystone-import `filename` - - -Setting Up Middleware -===================== - -Keystone Auth-Token Middleware --------------------------------- - -The Keystone auth_token middleware is a WSGI component that can be inserted in -the WSGI pipeline to handle authenticating tokens with Keystone. See :doc:`middleware` -for details on middleware and configuration parameters. - - -Configuring Nova to use Keystone --------------------------------- - -To configure Nova to use Keystone for authentication, the Nova API service -can be run against the api-paste file provided by Keystone. This is most -easily accomplished by setting the `--api_paste_config` flag in nova.conf to -point to `examples/paste/nova-api-paste.ini` from Keystone. This paste file -included references to the WSGI authentication middleware provided with the -keystone installation. - -When configuring Nova, it is important to create a admin service token for -the service (from the Configuration step above) and include that as the key -'admin_token' in the nova-api-paste.ini. See the documented -:doc:`nova-api-paste` file for references. - -Configuring Swift to use Keystone ---------------------------------- - -Similar to Nova, swift can be configured to use Keystone for authentication -rather than it's built in 'tempauth'. - -1. Add a service endpoint for Swift to Keystone - -2. Configure the paste file for swift-proxy (`/etc/swift/swift-proxy.conf`) - -3. Reconfigure Swift's proxy server to use Keystone instead of TempAuth. - Here's an example `/etc/swift/proxy-server.conf`:: - - [DEFAULT] - bind_port = 8888 - user = - - [pipeline:main] - pipeline = catch_errors cache keystone proxy-server - - [app:proxy-server] - use = egg:swift#proxy - account_autocreate = true - - [filter:keystone] - use = egg:keystone#tokenauth - auth_protocol = http - auth_host = 127.0.0.1 - auth_port = 35357 - admin_token = 999888777666 - delay_auth_decision = 0 - service_protocol = http - service_host = 127.0.0.1 - service_port = 8100 - service_pass = dTpw - cache = swift.cache - - [filter:cache] - use = egg:swift#memcache - set log_name = cache - - [filter:catch_errors] - use = egg:swift#catch_errors - - Note that the optional "cache" property in the keystone filter allows any - service (not just Swift) to register its memcache client in the WSGI - environment. If such a cache exists, Keystone middleware will utilize it - to store validated token information, which could result in better overall - performance. - -4. Restart swift - -5. Verify that keystone is providing authentication to Swift - -Use `swift` to check everything works (note: you currently have to create a -container or upload something as your first action to have the account -created; there's a Swift bug to be fixed soon):: - - $ swift -A http://127.0.0.1:5000/v1.0 -U joeuser -K secrete post container - $ swift -A http://127.0.0.1:5000/v1.0 -U joeuser -K secrete stat -v - StorageURL: http://127.0.0.1:8888/v1/AUTH_1234 - Auth Token: 74ce1b05-e839-43b7-bd76-85ef178726c3 - Account: AUTH_1234 - Containers: 1 - Objects: 0 - Bytes: 0 - Accept-Ranges: bytes - X-Trans-Id: tx25c1a6969d8f4372b63912f411de3c3b - -.. WARNING:: - Keystone currently allows any valid token to do anything with any account. - diff --git a/docs/source/controllingservers.rst b/docs/source/controllingservers.rst deleted file mode 100644 index ba8bfc06..00000000 --- a/docs/source/controllingservers.rst +++ /dev/null @@ -1,288 +0,0 @@ -.. - Copyright 2011 OpenStack, LLC - All Rights Reserved. - - Licensed under the Apache License, Version 2.0 (the "License"); you may - not use this file except in compliance with the License. You may obtain - a copy of the License at - - http://www.apache.org/licenses/LICENSE-2.0 - - Unless required by applicable law or agreed to in writing, software - distributed under the License is distributed on an "AS IS" BASIS, WITHOUT - WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the - License for the specific language governing permissions and limitations - under the License. - -============================ -Controlling Keystone Servers -============================ - -This section describes the ways to start, stop, and reload the Keystone -services. - -Keystone Services ------------------ - -Keystone can serve a number of REST APIs and extensions on different TCP/IP -ports. - -The Service API -~~~~~~~~~~~~~~~~ - -The core Keystone -API is primarily a read-only API (the only write operation being POST /tokens -which authenticates a client, and returns a generated token). -This API is sufficient to use OpenStack if all users, roles, endpoints already -exist. This is often the case if Keystone is using an enterprise backend -and the backend is managed through other entperrise tools and business -processes. This core API is called the Service API and can be started -separately from the more complete Admin API. By default, Keystone runs -this API on port 5000. This is not an IANA assigned port and should not -be relied upon (instead, use the Admin API on port 35357 to look for -this endpoint - more on this later) - -The Service API is started using this command in the /bin directory:: - - $ ./keystone-auth - -The Admin API -~~~~~~~~~~~~~ - -Inn order for Keystone to be a fully functional service out of the box, -API extensions that provide full CRUD operations is included with Keystone. -This full set of API calls includes the OS-KSCATALOG, OS-KSADM, and OS-KSEC2 -extensions. These extensions provide a full set of create, read, update, delete -(CRUD) operations that can be used to manage Keystone objects through REST -calls. By default Keystone runs this full REST API on TCP/IP port 35357 -(assigned by IANA to Keystone). - -The Admin API is started using this command in the /bin directory:: - - $ ./keystone-admin - - -Both APIs can be loaded simultaneously (on different ports) using this command:: - - $ ./keystone - -Starting a server ------------------ - -There are two ways to start a Keystone service (either the Service API server -or the Admin API server): - -- Manually calling the server program -- Using the ``keystone-control`` server daemon wrapper program - -We recommend using the second way in production and the first for development -and debugging. - -Manually starting the server -~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -The first is by directly calling the server program, passing in command-line -options and a single argument for a ``paste.deploy`` configuration file to -use when configuring the server application. - -.. note:: - - Keystone ships with an ``etc/`` directory that contains a sample ``paste.deploy`` - configuration files that you can copy to a standard configuration directory and - adapt for your own uses. - -If you do `not` specify a configuration file on the command line, Keystone will -do its best to locate a configuration file in one of the -following directories, stopping at the first config file it finds: - -- ``$CWD`` -- ``~/.keystone`` -- ``~/`` -- ``/etc/keystone`` -- ``/etc`` - -The filename that is searched for is ``keystone.conf`` by default. - -If no configuration file is found, you will see an error, like:: - - $ keystone - ERROR: Unable to locate any configuration file. Cannot load application keystone - -Here is an example showing how you can manually start the ``keystone-auth`` server and ``keystone-registry`` in a shell:: - - $ ./keystone -d - keystone-legacy-auth: INFO ************************************************** - keystone-legacy-auth: INFO Configuration options gathered from config file: - keystone-legacy-auth: INFO /Users/ziadsawalha/Documents/Code/keystone/etc/keystone.conf - keystone-legacy-auth: INFO ================================================ - keystone-legacy-auth: INFO admin_host 0.0.0.0 - keystone-legacy-auth: INFO admin_port 35357 - keystone-legacy-auth: INFO admin_ssl False - keystone-legacy-auth: INFO backends keystone.backends.sqlalchemy - keystone-legacy-auth: INFO ca_certs /etc/keystone/ssl/certs/ca.pem - keystone-legacy-auth: INFO cert_required True - keystone-legacy-auth: INFO certfile /etc/keystone/ssl/certs/keystone.pem - keystone-legacy-auth: INFO debug True - keystone-legacy-auth: INFO default_store sqlite - keystone-legacy-auth: INFO extensions osksadm,oskscatalog,hpidm - keystone-legacy-auth: INFO hash-password True - keystone-legacy-auth: INFO keyfile /etc/keystone/ssl/private/keystonekey.pem - keystone-legacy-auth: INFO keystone-admin-role Admin - keystone-legacy-auth: INFO keystone-service-admin-role KeystoneServiceAdmin - keystone-legacy-auth: INFO log_dir . - keystone-legacy-auth: INFO log_file keystone.log - keystone-legacy-auth: INFO service-header-mappings { - 'nova' : 'X-Server-Management-Url', - 'swift' : 'X-Storage-Url', - 'cdn' : 'X-CDN-Management-Url'} - keystone-legacy-auth: INFO service_host 0.0.0.0 - keystone-legacy-auth: INFO service_port 5000 - keystone-legacy-auth: INFO service_ssl False - keystone-legacy-auth: INFO verbose False - keystone-legacy-auth: INFO ************************************************** - passlib.registry: INFO registered crypt handler 'sha512_crypt': - Starting the RAX-KEY extension - Starting the Legacy Authentication component - admin : INFO ************************************************** - admin : INFO Configuration options gathered from config file: - admin : INFO /Users/ziadsawalha/Documents/Code/keystone/etc/keystone.conf - admin : INFO ================================================ - admin : INFO admin_host 0.0.0.0 - admin : INFO admin_port 35357 - admin : INFO admin_ssl False - admin : INFO backends keystone.backends.sqlalchemy - admin : INFO ca_certs /etc/keystone/ssl/certs/ca.pem - admin : INFO cert_required True - admin : INFO certfile /etc/keystone/ssl/certs/keystone.pem - admin : INFO debug True - admin : INFO default_store sqlite - admin : INFO extensions osksadm,oskscatalog,hpidm - admin : INFO hash-password True - admin : INFO keyfile /etc/keystone/ssl/private/keystonekey.pem - admin : INFO keystone-admin-role Admin - admin : INFO keystone-service-admin-role KeystoneServiceAdmin - admin : INFO log_dir . - admin : INFO log_file keystone.log - admin : INFO service-header-mappings { - 'nova' : 'X-Server-Management-Url', - 'swift' : 'X-Storage-Url', - 'cdn' : 'X-CDN-Management-Url'} - admin : INFO service_host 0.0.0.0 - admin : INFO service_port 5000 - admin : INFO service_ssl False - admin : INFO verbose False - admin : INFO ************************************************** - Using config file: /Users/ziadsawalha/Documents/Code/keystone/etc/keystone.conf - Service API (ssl=False) listening on 0.0.0.0:5000 - Admin API (ssl=False) listening on 0.0.0.0:35357 - eventlet.wsgi.server: DEBUG (77128) wsgi starting up on http://0.0.0.0:5000/ - eventlet.wsgi.server: DEBUG (77128) wsgi starting up on http://0.0.0.0:35357/ - - $ sudo keystone-registry keystone-registry.conf & - jsuh@mc-ats1:~$ 2011-04-13 14:51:16 INFO [sqlalchemy.engine.base.Engine.0x...feac] PRAGMA table_info("images") - 2011-04-13 14:51:16 INFO [sqlalchemy.engine.base.Engine.0x...feac] () - 2011-04-13 14:51:16 DEBUG [sqlalchemy.engine.base.Engine.0x...feac] Col ('cid', 'name', 'type', 'notnull', 'dflt_value', 'pk') - 2011-04-13 14:51:16 DEBUG [sqlalchemy.engine.base.Engine.0x...feac] Row (0, u'created_at', u'DATETIME', 1, None, 0) - 2011-04-13 14:51:16 DEBUG [sqlalchemy.engine.base.Engine.0x...feac] Row (1, u'updated_at', u'DATETIME', 0, None, 0) - 2011-04-13 14:51:16 DEBUG [sqlalchemy.engine.base.Engine.0x...feac] Row (2, u'deleted_at', u'DATETIME', 0, None, 0) - 2011-04-13 14:51:16 DEBUG [sqlalchemy.engine.base.Engine.0x...feac] Row (3, u'deleted', u'BOOLEAN', 1, None, 0) - 2011-04-13 14:51:16 DEBUG [sqlalchemy.engine.base.Engine.0x...feac] Row (4, u'id', u'INTEGER', 1, None, 1) - 2011-04-13 14:51:16 DEBUG [sqlalchemy.engine.base.Engine.0x...feac] Row (5, u'name', u'VARCHAR(255)', 0, None, 0) - 2011-04-13 14:51:16 DEBUG [sqlalchemy.engine.base.Engine.0x...feac] Row (6, u'disk_format', u'VARCHAR(20)', 0, None, 0) - 2011-04-13 14:51:16 DEBUG [sqlalchemy.engine.base.Engine.0x...feac] Row (7, u'container_format', u'VARCHAR(20)', 0, None, 0) - 2011-04-13 14:51:16 DEBUG [sqlalchemy.engine.base.Engine.0x...feac] Row (8, u'size', u'INTEGER', 0, None, 0) - 2011-04-13 14:51:16 DEBUG [sqlalchemy.engine.base.Engine.0x...feac] Row (9, u'status', u'VARCHAR(30)', 1, None, 0) - 2011-04-13 14:51:16 DEBUG [sqlalchemy.engine.base.Engine.0x...feac] Row (10, u'is_public', u'BOOLEAN', 1, None, 0) - 2011-04-13 14:51:16 DEBUG [sqlalchemy.engine.base.Engine.0x...feac] Row (11, u'location', u'TEXT', 0, None, 0) - 2011-04-13 14:51:16 INFO [sqlalchemy.engine.base.Engine.0x...feac] PRAGMA table_info("image_properties") - 2011-04-13 14:51:16 INFO [sqlalchemy.engine.base.Engine.0x...feac] () - 2011-04-13 14:51:16 DEBUG [sqlalchemy.engine.base.Engine.0x...feac] Col ('cid', 'name', 'type', 'notnull', 'dflt_value', 'pk') - 2011-04-13 14:51:16 DEBUG [sqlalchemy.engine.base.Engine.0x...feac] Row (0, u'created_at', u'DATETIME', 1, None, 0) - 2011-04-13 14:51:16 DEBUG [sqlalchemy.engine.base.Engine.0x...feac] Row (1, u'updated_at', u'DATETIME', 0, None, 0) - 2011-04-13 14:51:16 DEBUG [sqlalchemy.engine.base.Engine.0x...feac] Row (2, u'deleted_at', u'DATETIME', 0, None, 0) - 2011-04-13 14:51:16 DEBUG [sqlalchemy.engine.base.Engine.0x...feac] Row (3, u'deleted', u'BOOLEAN', 1, None, 0) - 2011-04-13 14:51:16 DEBUG [sqlalchemy.engine.base.Engine.0x...feac] Row (4, u'id', u'INTEGER', 1, None, 1) - 2011-04-13 14:51:16 DEBUG [sqlalchemy.engine.base.Engine.0x...feac] Row (5, u'image_id', u'INTEGER', 1, None, 0) - 2011-04-13 14:51:16 DEBUG [sqlalchemy.engine.base.Engine.0x...feac] Row (6, u'key', u'VARCHAR(255)', 1, None, 0) - 2011-04-13 14:51:16 DEBUG [sqlalchemy.engine.base.Engine.0x...feac] Row (7, u'value', u'TEXT', 0, None, 0) - - $ ps aux | grep keystone - myuser 77148 0.0 0.0 2434892 472 s012 U+ 11:50AM 0:00.01 grep keystone - myuser 77128 0.0 0.6 2459356 25360 s011 S+ 11:48AM 0:00.82 python ./keystone -d - -Simply supply the configuration file as the first argument -and then any common options -you want to use (``-d`` was used above to show some of the debugging -output that the server shows when starting up. Call the server program -with ``--help`` to see all available options you can specify on the -command line.) - -Using ``--trace-calls`` is useful for showing a trace of calls (errors in red) -for debugging. - -For more information on configuring the server via the ``paste.deploy`` -configuration files, see the section entitled -:doc:`Configuring Keystone ` - -Note that the server `daemonizes` itself by using the standard -shell backgrounding indicator, ``&``, in the previous example. For most use cases, we recommend -using the ``keystone-control`` server daemon wrapper for daemonizing. See below -for more details on daemonization with ``keystone-control``. - -Using ``keystone-control`` to start the server -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -The second way to start up a Keystone server is to use the ``keystone-control`` -program. ``keystone-control`` is a wrapper script that allows the user to -start, stop, restart, and reload the other Keystone server programs in -a fashion that is more conducive to automation and scripting. - -Servers started via the ``keystone-control`` program are always `daemonized`, -meaning that the server program process runs in the background. - -To start a Keystone server with ``keystone-control``, simply call -``keystone-control`` with a server and the word "start", followed by -any command-line options you wish to provide. Start the server with ``keystone-control`` -in the following way:: - - $ sudo keystone-control start [CONFPATH] - -.. note:: - - You must use the ``sudo`` program to run ``keystone-control`` currently, as the - pid files for the server programs are written to /var/run/keystone/ - -Start the ``keystone-admin`` server using ``keystone-control``:: - - $ sudo keystone-control admin start - Starting keystone-admin with /etc/keystone.conf - -The same ``paste.deploy`` configuration files are used by ``keystone-control`` -to start the Keystone server programs, and you can specify (as the example above -shows) a configuration file when starting the server. - -Stopping a server ------------------ - -If you started a Keystone server manually and did not use the ``&`` backgrounding -function, simply send a terminate signal to the server process by typing -``Ctrl-C`` - -If you started the Keystone server using ``keystone-control``, you can -use the ``keystone-control`` program to stop it:: - - $ sudo keystone-control stop - -For example:: - - $ sudo keystone-control auth stop - Stopping keystone-auth pid: 77401 signal: 15 - -Restarting a server -------------------- - -Restart the Keystone server using ``keystone-control``:: - - $ sudo keystone-control admin restart /etc/keystone.conf - Stopping keystone-admin pid: 77401 signal: 15 - Starting keystone-admin with /etc/keystone.conf diff --git a/docs/source/endpoints.rst b/docs/source/endpoints.rst deleted file mode 100644 index 84a42e09..00000000 --- a/docs/source/endpoints.rst +++ /dev/null @@ -1,430 +0,0 @@ -.. - Copyright 2011 OpenStack, LLC - All Rights Reserved. - - Licensed under the Apache License, Version 2.0 (the "License"); you may - not use this file except in compliance with the License. You may obtain - a copy of the License at - - http://www.apache.org/licenses/LICENSE-2.0 - - Unless required by applicable law or agreed to in writing, software - distributed under the License is distributed on an "AS IS" BASIS, WITHOUT - WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the - License for the specific language governing permissions and limitations - under the License. - -================================ -Endpoints and Endpoint Templates -================================ - -.. toctree:: - :maxdepth: 1 - -What are Endpoints? -------------------- - -Simply, endpoints are URLs that point to OpenStack services. When you -authenticate to Keystone you get back a token which has a service catalog in -it. The service catalog is basically a list of the OpenStack services that -you have access to and the URLs you can use to get to them; their endpoints. - -Here is an example response from Keystone when you authenticate:: - - { - "access":{ - "token":{ - "id":"ab48a9efdfedb23ty3494", - "expires":"2010-11-01T03:32:15-05:00", - "tenant":{ - "id": "t1000", - "name": "My Project" - } - }, - "user":{ - "id":"u123", - "name":"jqsmith", - "roles":[{ - "id":"100", - "name":"compute:admin" - }, - { - "id":"101", - "name":"object-store:admin", - "tenantId":"t1000" - } - ], - "roles_links":[] - }, - "serviceCatalog":[{ - "name":"Nova", - "type":"compute", - "endpoints":[{ - "tenantId":"t1000", - "publicURL":"https://compute.north.host.com/v1/t1000", - "internalURL":"https://compute.north.internal/v1/t1000", - "region":"North", - "versionId":"1", - "versionInfo":"https://compute.north.host.com/v1/", - "versionList":"https://compute.north.host.com/" - }, - { - "tenantId":"t1000", - "publicURL":"https://compute.north.host.com/v1.1/t1000", - "internalURL":"https://compute.north.internal/v1.1/t1000", - "region":"North", - "versionId":"1.1", - "versionInfo":"https://compute.north.host.com/v1.1/", - "versionList":"https://compute.north.host.com/" - } - ], - "endpoints_links":[] - }, - { - "name":"Swift", - "type":"object-store", - "endpoints":[{ - "tenantId":"t1000", - "publicURL":"https://storage.north.host.com/v1/t1000", - "internalURL":"https://storage.north.internal/v1/t1000", - "region":"North", - "versionId":"1", - "versionInfo":"https://storage.north.host.com/v1/", - "versionList":"https://storage.north.host.com/" - }, - { - "tenantId":"t1000", - "publicURL":"https://storage.south.host.com/v1/t1000", - "internalURL":"https://storage.south.internal/v1/t1000", - "region":"South", - "versionId":"1", - "versionInfo":"https://storage.south.host.com/v1/", - "versionList":"https://storage.south.host.com/" - } - ] - }, - { - "name":"DNS-as-a-Service", - "type":"dnsextension:dns", - "endpoints":[{ - "tenantId":"t1000", - "publicURL":"https://dns.host.com/v2.0/t1000", - "versionId":"2.0", - "versionInfo":"https://dns.host.com/v2.0/", - "versionList":"https://dns.host.com/" - } - ] - } - ] - } - } - -Note the following about this response: - -#. There are two endpoints given to the Nova compute service. The only - difference between them is the version (1.0 vs. 1.1). This allows for code - written to look for the version 1.0 endpoint to still work even after the 1.1 - version is released. - -#. There are two endpoints for the Swift object-store service. The difference - between them is they are in different regions (North and South). - -#. Note the DNS service is global; it does not have a Region. Also, since DNS - is not a core OpenStack service, the endpoint type is "dnsextension:dns" - showing it is coming from an extension to the Keystone service. - -#. The Region, Tenant, and versionId are listed under the endpoint. You do not - (and should not) have to parse those out of the URL. In fact, they may not be - embedded in the URL if the service developer so chooses. - - -What do the fields in an Endpoint mean? ---------------------------------------- - -The schema definition for an endpoint is in endpoints.xsd under -keystone/content/common/xsd in the Keystone code repo. The fields are: - -id - A unique ID for the endpoint. - -type - The OpenStack-registered type (ex. 'compute', 'object-store', 'image service') - This can also be extended using the OpenStack Extension mechanism to support - non-core services. Extended services will be in the form ``extension:type`` - (e.g. ``dnsextension:dns``) - -name - This can be anything that the operator of OpenStack chooses. It could be a - brand or marketing name (ex. Rackspace Cloud Servers). - -region - This is a string that identifies the region where this endpoint exists. - Examples are 'North America', 'Europe', 'Asia'. Or 'North' and 'South'. Or - 'Data Center 1', 'Data Center 2'. - The list of regions and what a region means is decided by the operator. The - spec treats them as opaque strings. - -publicURL - This is the URL to use to access that endpoint over the internet. - -internalURL - This is the URL to use to communicate between services. This is genenrally - a way to communicate between services over a high bandwidth, low latency, - unmetered (free, no bandwidth charges) network. An example would be if you - want to access a swift cluster from inside your Nova VMs and want to make - sure the communication stays local and does not go over a public network - and rack up your bandwidth charges. - -adminURL - This is the URL to use to administer the service. In Keystone, this URL - is only shown to users with the appropriate rights. - -tenantId - If an endpoint is specific to a tenant, the tenantId field identifies the - tenant that URL applies to. Some operators include the tenant in the - URLs for a service, while others may provide one endpoint and use some - other mechanism to identify the tenant. This field is therefore optional. - Having this field also means you do not have to parse the URL to identify - a tenant if the operator includes it in the URL. - -versionId - This identifies the version of the API contract that endpoint supports. - While many APIs include the version in the URL (ex: https://compute.host/v1), - this field allows you to identify the version without parsing the URL. It - therefore also allows operators and service developers to publish endpoints - that do not have versions embedded in the URL. - -versionInfo - This is the URL to call to get some information on the version. This returns - information in this format:: - - { - "version": { - "id": "v2.0", - "status": "CURRENT", - "updated": "2011-01-21T11:33:21-06:00", - "links": [ - { - "rel": "self", - "href": "http://identity.api.openstack.org/v2.0/" - }, { - "rel": "describedby", - "type": "application/pdf", - "href": "http://docs.openstack.org/identity/api/v2.0/identity-latest.pdf" - }, { - "rel": "describedby", - "type": "application/vnd.sun.wadl+xml", - "href": "http://docs.openstack.org/identity/api/v2.0/identity.wadl" - } - ], - "media-types": [ - { - "base": "application/xml", - "type": "application/vnd.openstack.identity+xml;version=2.0" - }, { - "base": "application/json", - "type": "application/vnd.openstack.identity+json;version=2.0" - } - ] - } - } - -versionList - - This is the URL to call to find out which versions are supported at that - endpoint. The response is in this format:: - - { - "versions":[{ - "id":"v1.0", - "status":"DEPRECATED", - "updated":"2009-10-09T11:30:00Z", - "links":[{ - "rel":"self", - "href":"http://identity.api.openstack.org/v1.0/" - } - ] - }, - { - "id":"v1.1", - "status":"CURRENT", - "updated":"2010-12-12T18:30:02.25Z", - "links":[{ - "rel":"self", - "href":"http://identity.api.openstack.org/v1.1/" - } - ] - }, - { - "id":"v2.0", - "status":"BETA", - "updated":"2011-05-27T20:22:02.25Z", - "links":[{ - "rel":"self", - "href":"http://identity.api.openstack.org/v2.0/" - } - ] - } - ], - "versions_links":[] - } - - Here, the response shows that the endpoint supports version 1.0, 1.1, and 2.0. - It also shows that 1.0 is in DEPRECTAED status and 2.0 is in BETA. - -What are Endpoint Templates? ----------------------------- - -Endpoint Templates are a way for an administrator to manage endpoints en masse. -They provide a way to define Endpoints that apply to many or all tenants -without having to a create each endpoint on each tenant manually. Without -Endpoint Templates, if I wanted to create Endpoints for each tenant in my -OpenStack deployment, I'd have to manually create a bunch of endpoints on -each tenant (probably when I created the tenant). And then I'd have to go change -them all whenever a service changed versions or I added a new service. - -To provide a simpler mechanism to manage endpoints on tenants, Keystone uses -Endpoint Templates. I can, for example, define a template with parametrized URLs -and set it's `global` to true and that will show up as an endpoint on all the tenants -I have. Here is an example: - -Define a global Endpoint Template:: - - $ ./keystone-manage endpointTemplates add North nova https://compute.north.example.com/v1/%tenant_id%/ https://compute.north.example.corp/v1/ https://compute.north.example.local/v1/%tenant_id%/ 1 1 - - The arguments are: object_type action 'region' 'service_name' 'publicURL' 'adminURL' 'internalURL' 'enabled' 'global' - -This creates a global endpoint (global means it gets applied to all tenants automatically). - -Now, when a user authenticates, they get that endpoint in their service catalog. Here's an example -authentication request for use against tenant 1:: - - $ curl -H "Content-type: application/json" -d '{"auth":{"passwordCredentials":{"username":"joeuser","password":"secrete"}, "tenantId": "1"}}' http://localhost:5000/v2.0/tokens - -The response is:: - - { - "access": { - "serviceCatalog": [ - { - "endpoints": [ - { - "internalURL": "https://compute.north.example.local", - "publicURL": "https://compute.north.example.com/v1/1/", - "region": "North" - } - ], - "name": "nova", - "type": "compute" - } - ], - "token": { - "expires": "2012-02-05T00:00:00", - "id": "887665443383838", - "tenant": { - "id": "1", - "name": "customer-x" - } - }, - "user": { - "id": "1", - "name": "joeuser", - "roles": [ - { - "id": "3", - "name": "Member", - "tenantId": "1" - } - ] - } - } - } - -Notice the adminURL is not showing (this user is a regular user and does not -have rights to see the adminURL) and the tenant ID has been substituted in the -URL:: - - "publicURL": "https://compute.north.example.com/v1/1/", - -This endpoint will show up for all tenants. The OpenStack administrator does -not need to create the endpoint manually. - -.. note:: Endpoint Templates are not part of the core Keystone API (but Endpoints are). - - -What parameters can I use in a Template URL -------------------------------------------- - -Currently the only parameterization available is %tenant_id% which gets -substituted by the Tenant ID. - - -Endpoint Template Types: Global or not --------------------------------------- - -When the global flag is set to true on an Endpoint Template, it means it should -be available to all tenants. Whenever someone authenticates to a tenant, they -will see the Endpoint generated by that template. - -When the global flag is not set, the template only shows up when it is added to -a tenant manually. To add an endpoint to a tenant manually, you must create -the Endpoint and supply the Endpoint Template ID: - -Create the Endpoint Template:: - - $ ./keystone-manage endpointTemplates add West nova https://compute.west.example.com/v1/%tenant_id%/ https://compute.west.example.corp https://compute.west.example.local 1 0 - - Note the 0 at the end - this Endpoint Template is not global. So it will not show up for users authenticating. - -Find the Endpoint Template ID:: - - $ ./keystone-manage endpointTemplates list - - All EndpointTemplates - id service type region enabled is_global Public URL Admin URL - ------------------------------------------------------------------------------- - 15 nova compute North True True https://compute.north.example.com/v1/%tenant_id%/ https://compute.north.example.corp - 16 nova compute West True False https://compute.west.example.com/v1/%tenant_id%/ https://compute.west.example.corp - -Add the Endpoint to the tenant:: - - $ ./keystone-manage endpoint add customer-x 16 - -Now, when the user authenticates, they get the endpoint:: - - { - "internalURL": "https://compute.west.example.local", - "publicURL": "https://compute.west.example.com/v1/1/", - "region": "West" - } - -Who can see the AdminURL? -------------------------- - -Users who have the Keystone `Admin` or `Service Admin` roles will see the -AdminURL when they authenticate or when they retrieve token information: - -Using an administrator token to authenticate, GET a client token's endpoints:: - - $ curl -H "X-Auth-Token: 999888777666" http://localhost:35357/v2.0/tokens/887665443383838/endpoints - - { - "endpoints": [ - { - "adminURL": "https://compute.west.example.corp", - "id": 6, - "internalURL": "https://compute.west.example.local", - "name": "nova", - "publicURL": "https://compute.west.example.com/v1/1/", - "region": "West", - "tenantId": 1, - "type": "compute" - } - ], - "endpoints_links": [ - { - "href": "http://127.0.0.1:35357/tokens/887665443383838/endpoints?marker=6&limit=10", - "rel": "next" - } - ] - } diff --git a/docs/source/extensions.rst b/docs/source/extensions.rst deleted file mode 100644 index 539bef39..00000000 --- a/docs/source/extensions.rst +++ /dev/null @@ -1,183 +0,0 @@ -.. - Copyright 2011 OpenStack, LLC - All Rights Reserved. - - Licensed under the Apache License, Version 2.0 (the "License"); you may - not use this file except in compliance with the License. You may obtain - a copy of the License at - - http://www.apache.org/licenses/LICENSE-2.0 - - Unless required by applicable law or agreed to in writing, software - distributed under the License is distributed on an "AS IS" BASIS, WITHOUT - WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the - License for the specific language governing permissions and limitations - under the License. - -========== -Extensions -========== - -Extensions support adding features and functions to OpenStack APIs at any time, without prior -approval or waiting for a new API and release cycles. - -The extension framework is in development and documented in extensions_ and extensionspresentation_. - -This document describes the extensions included with Keystone, how to enable and disable them, -and briefly touches on how to write your own extensions. - -.. _extensions: http://docs.openstack.org/trunk/openstack-compute/developer/openstack-api-extensions/content/ch02s01.html -.. _extensionspresentation: http://www.slideshare.net/RackerWilliams/openstack-extensions - -Built-in Extensions -------------------- - -Keystone ships with a number of extensions found under the -``keystone/contib/extensions`` folder. - -The following built-in extensions are included: - -OS-KSADM - - This is an extensions that supports managing users, tenants, and roles - through the API. Without this extensions, the ony way to manage those - objects is through keystone-manage or directly in the underlying database. - - This is an Admin API extension only. - -OS-KSCATALOG - - This extensions supports managing Endpoints and prrovides the Endpoint - Template mechanism for managing bulk endpoints. - - This is an Admin API extension only. - -OS-EC2 - - This extension adds support for EC2 credentials. - - This is an Admin and Service API extension. - -RAX-GRP - - This extension adds functionality the enables groups. - - This is an Admin and Service API extension. - -RAX-KEY - - This extensions adds support for authentication with an API Key (the core - Keystone API only supports username/password credentials) - - This is an Admin and Service API extension. - -HP-IDM - - This extension adds capability to filter roles with optional service IDs - for token validation to mitigate security risks with role name conflicts. - See https://bugs.launchpad.net/keystone/+bug/890411 for more details. - - This is an Admin API extension. Applicable to validate token (GET) - and check token (HEAD) APIs only. - -OS-KSVALIDATE - - This extensions supports admin calls to /tokens without having to specify - the token ID in the URL. Instead, the ID is supplied in a header called - X-Subject-Token. This is provided as an alternative to address any security - concerns that arise when token IDs are passed as part of the URL which is - often (and by default) logged to insecure media. - - This is an Admin API extension only. - -.. note:: - - The included extensions are in the process of being rewritten. Currently - osksadm, oskscatalog, hpidm, and osksvalidate work with this new - extensions design. - - -Enabling & Disabling Extensions -------------------------------- - -The Keystone conf file has a property called extensions. This property holds -the list of supported extensions that you want enabled. If you want to -add/remove an extension from being supported, add/remove the extension key -from this property. The key is the name of the folder of the extension -under the keystone/contrib/extensions folder. - -.. note:: - - If you want to load different extensions in the service API than the Admin API - you need to use different config files. - -Creating New Extensions ------------------------ - -#. **Adopt a unique organization abbreviation.** - - This prefix should uniquely identify your organization within the community. - The goal is to avoid schema and resource collisions with similiar extensions. - (e.g. ``OS`` for OpenStack, ``RAX`` for Rackspace, or ``HP`` for Hewlett-Packard) - -#. **Adopt a unique extension abbreviation.** - - Select an abbreviation to identify your extension, and append to - your organization prefix using a hyphen (``-``), by convention - (e.g. ``OS-KSADM`` (for OpenStack's Keystone Administration extension). - - This combination is referred to as your extension's prefix. - -#. **Determine the scope of your extension.** - - Extensions can enhance the Admin API, Service API or both. - -#. **Create a new module.** - - Create a module to isolate your namespace based on the extension prefix - you selected:: - - keystone/contrib/extensions/admin - - ... and/or:: - - keystone/contrib/extensions/service/ - - ... based on which API you are enhancing. - - .. note:: - - In the future, we will support loading external extensions. - -#. Add static extension files for JSON (``*.json``) and XML - (``*.xml``) to the new extension module. - - Refer to `Service Guide `_ - `Sample extension XML `_ - `Sample extension JSON `_ for the the content and structure. - -#. If your extension is adding additional methods override the base class - ``BaseExtensionHandler``, name it ``ExtensionHandler``, and add your methods. - -#. **Document your work.** - - Provide documentation to support your extension. - - Extensions documentation, WADL, and XSD files can be stored in the - ``keystone/content`` folder. - -#. Add your extension name to the list of supported extensions in The - ``keystone.conf`` file. - -Which extensions are enabled? ------------------------------ - -Discover which extensions are available (service API):: - - curl http://localhost:5000/v2.0/extensions - -... or (admin API):: - - curl http://localhost:35357/v2.0/extensions - -The response will list the extensions available. diff --git a/docs/source/index.rst b/docs/source/index.rst index 427414d4..8b12ff93 100644 --- a/docs/source/index.rst +++ b/docs/source/index.rst @@ -42,8 +42,8 @@ Getting Started :maxdepth: 1 setup - configuration - configuringservices + configuration + configuringservices community Man Pages @@ -53,7 +53,7 @@ Man Pages :maxdepth: 1 man/keystone - man/keystone-manage + man/keystone-manage Developers Documentation ======================== diff --git a/docs/source/middleware.rst b/docs/source/middleware.rst deleted file mode 100644 index 69506ee2..00000000 --- a/docs/source/middleware.rst +++ /dev/null @@ -1,169 +0,0 @@ -.. - Copyright 2011 OpenStack, LLC - All Rights Reserved. - - Licensed under the Apache License, Version 2.0 (the "License"); you may - not use this file except in compliance with the License. You may obtain - a copy of the License at - - http://www.apache.org/licenses/LICENSE-2.0 - - Unless required by applicable law or agreed to in writing, software - distributed under the License is distributed on an "AS IS" BASIS, WITHOUT - WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the - License for the specific language governing permissions and limitations - under the License. - -========== -Middleware -========== - -The Keystone middleware sits in front of an OpenStack service and handles authenticating -incoming requests. The middleware was designed according to `this spec`. - -The middleware is found in source under Keystone/middleware. - -The middleware supports two interfaces; WSGI and REST/HTTP. - -.. _`this spec`: http://wiki.openstack.org/openstack-authn - -REST & HTTP API -=============== - -If an unauthenticated call comes in, the middleware will respond with a 401 Unauthorized error. As per -HTTP standards, it will also return a WWW-Authenticate header informing the caller -of what protocols are supported. For Keystone authentication, the response syntax will be:: - - WWW-Authenticate: Keystone uri="url to Keystone server" - -The client can then make the necessary calls to the Keystone server, obtain a token, and retry the call with the token. - -The token is passed in using ther X-Auth-Token header. - -WSGI API (Headers) -================== - -Upon successful authentication the middleware sends the following -headers to the downstream WSGI app: - -X-Identity-Status - Provides information on whether the request was authenticated or not. - -X-Tenant - Provides the tenant ID (as it appears in the URL in Keystone). This is to support any legacy implementations before Keystone switched to an ID/Name schema for tenants. - -X-Tenant-Id - The unique, immutable tenant Id - -X-Tenant-Name - The unique, but mutable (it can change) tenant name. - -X-User-Id - The user id of the user used to log in - -X-User-Name - The username used to log in - -X-User - The username used to log in. This is to support any legacy implementations before Keystone switched to an ID/Name schema for tenants. - -X-Roles - The roles associated with that user - - -Configuration -============= - -The middleware is configured within the config file of the main application as -a WSGI component. Example for the auth_token middleware:: - - [app:myService] - paste.app_factory = myService:app_factory - - [pipeline:main] - pipeline = - tokenauth - myService - - [filter:tokenauth] - paste.filter_factory = keystone.middleware.auth_token:filter_factory - auth_host = 127.0.0.1 - auth_port = 35357 - auth_protocol = http - auth_uri = http://127.0.0.1:5000/ - admin_token = 999888777666 - ;Uncomment next line and check ip:port to use memcached to cache token requests - ;memcache_hosts = 127.0.0.1:11211 - -*The required configuration entries are:* - -auth_host - The IP address or DNS name of the Keystone server - -auth_port - The TCP/IP port of the Keystone server - -auth_protocol - The protocol of the Keystone server ('http' or 'https') - -auth_uri - The externally accessible URL of the Keystone server. This will be where unauthenticated - clients are redirected to. This is in the form of a URL. For example, if they make an - unauthenticated call, they get this response:: - - HTTP/1.1 401 Unauthorized - Www-Authenticate: Keystone uri='https://auth.example.com/' - Content-Length: 381 - - In this case, the auth_uri setting is set to https://auth.example.com/ - -admin_token - This is the long-lived token issued to the service to authenticate itself when calling - Keystone. See :doc:`configuration` for more information on setting this up. - - -*Optional parameters are:* - -delay_auth_decision - Whether the middleware should reject invalid or unauthenticated calls directly or not. If not, - it will send all calls down to the service to decide, but it will set the HTTP-X-IDENTITY-STATUS - header appropriately (set to'Confirmed' or 'Indeterminate' based on validation) and the - service can then decide if it wants to honor the call or not. This is useful if the service offers - some resources publicly, for example. - -auth_timeout - The amount of time to wait before timing out a call to Keystone (in seconds) - -memcache_hosts - This is used to point to a memcached server (in ip:port format). If supplied, - the middleware will cache tokens and data retrieved from Keystone in memcached - to minimize calls made to Keystone and optimize performance. - -.. warning:: - Tokens are cached for the duration of their validity. If they are revoked eariler in Keystone, - the service will not know and will continue to honor the token as it has them stored in memcached. - Also note that tokens and data stored in memcached are not encrypted. The memcached server must - be trusted and on a secure network. - - -*Parameters needed in a distributed topology.* In this configuration, the middleware is running -on a separate machine or cluster than the protected service (not common - see :doc:`middleware_architecture` -for details on different deployment topologies): - -service_host - The IP address or DNS name of the location of the service (since it is remote - and not automatically down the WSGI chain) - -service_port - The TCP/IP port of the remote service. - -service_protocol - The protocol of the service ('http' or 'https') - -service_pass - The basic auth password used to authenticate to the service (so the service - knows the call is coming from a server that has validated the token and not from - an untrusted source or spoofer) - -service_timeout - The amount of time to wait for the service to respond before timing out. diff --git a/docs/source/middleware_architecture.rst b/docs/source/middleware_architecture.rst deleted file mode 100644 index a8c38f3c..00000000 --- a/docs/source/middleware_architecture.rst +++ /dev/null @@ -1,529 +0,0 @@ -.. - Copyright 2011 OpenStack, LLC - All Rights Reserved. - - Licensed under the Apache License, Version 2.0 (the "License"); you may - not use this file except in compliance with the License. You may obtain - a copy of the License at - - http://www.apache.org/licenses/LICENSE-2.0 - - Unless required by applicable law or agreed to in writing, software - distributed under the License is distributed on an "AS IS" BASIS, WITHOUT - WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the - License for the specific language governing permissions and limitations - under the License. - -======================= -Middleware Architecture -======================= - -Abstract -======== - -The Keystone middleware architecture supports multiple authentication protocols -in a pluggable manner in OpenStack. By providing support for authentication via -pluggable authentication components, this architecture allows OpenStack -services to be integrated easily into existing deployment environments. It also -provides a path by which to implement support for emerging authentication -standards such as OAUTH. - -Rationale and Goals -=================== - -Keystone is the Identity service for OpenStack. To support the easy integrating -of OpenStack with existing authentication and identity management systems, -Keystone supports talking to multiple backends like LDAP. -And to support different deployment needs, it can support multiple -authentication protocols via pluggable 'authentication components' implemented -as WSGI middleware. - -In this document, we describe the responsibilities of the authentication -middleware. We describe how these interact with underlying OpenStack services -and how existing services can be modified to take advantage of pluggable -authentication. The goal is to allow OpenStack services to be integrated easily -into existing deployment environments and to provide a path by which to -implement support for emerging authentication standards such as OAUTH. - -Specification Overview -====================== - -'Authentication' is the process of determining that users are who they say they -are. Typically, 'authentication protocols' such as HTTP Basic Auth, Digest -Access, public key, token, etc, are used to verify a user's identity. In this -document, we define an ''authentication component'' as a software module that -implements an authentication protocol for an OpenStack service. - -At a high level, an authentication component is simply a reverse proxy that -intercepts HTTP calls from clients. Once it has verified a user's identity, the -authentication component extends the call with information about the current -user and forwards the request to the OpenStack service. Otherwise, if a user's -identity is not verified, the message is rejected before it gets to the -service. This is illustrated in :ref:`authComponent`. - -.. _authComponent: - -Authentication Component ------------------------- - -Figure 1. Authentication Component - -.. image:: images/graphs_authComp.svg - :width: 100% - :height: 180 - :alt: An Authentication Component - -Authentication components may operate in 'delegated mode'. In this mode, the -decision reject an unauthenticated client is delegated to the OpenStack -service. Delegated mode is illustrated in :ref:`authComponentDelegated`. - -Here, requests are forwarded to the OpenStack service with an identity status -message that indicates whether the client's identity has been confirmed or is -indeterminate. It is the OpenStack service that decides whether or not a reject -message should be sent to the client. Note that it is always the responsibility -of the Authentication Component to transmit reject messages to the client. - -.. _authComponentDelegated: - -Authentication Component (Delegated Mode) ------------------------------------------ - -Figure 2. Authentication Component (Delegated Mode) - -.. image:: images/graphs_authCompDelegate.svg - :width: 100% - :height: 180 - :alt: An Authentication Component (Delegated Mode) - -In this architecture, we define interactions between the authentication component -and the OpenStack service. Interactions between the client and the -authentication component are defined only for exceptional cases. For example, -we define the message that should be returned when the OpenStack service is -down. Other interactions, however, are defined by the underlying authentication -protocol and the OpenStack service and are considered out of scope. - -.. _deployStrategies: - -Deployment Strategies -===================== - -An authentication component may be integrated directly into the service -implementation, or it may be deployed separately as an HTTP reverse proxy. This -is illustrated in :ref:`deployment`, showing both approaches to -authentication, labeled Option (a) and Option (b). - -.. _deployment: - -Authentication Component Deployments Options --------------------------------------------- - -Figure 3. Authentication Component Deployments Options - -.. image:: images/images_layouts.svg - :width: 100% - :height: 180 - :alt: Authentication Component Deployments Options - -In Option (a), the component is integrated into the service implementation. In -this case, communication between the authentication component and the service -can be efficiently implemented via a method call. In Option (b), the component -is deployed separately and communication between the service and the component -involves an HTTP request. In both cases, unauthenticated requests are filtered -before they reach the service. - -Each approach offers some benefits. Option (a) offers low latency and ease of -initial implementation, making it possibly most appropriate as a starting point -for simple configurations. Option (b) offers several key advantages that may be -of particular value in complex and dynamic configurations. It offers the -ability to scale horizontally in cases where authentication is computationally -expensive, such as when verifying digital signatures. Option (b) also allows -authentication components to be written in different programming languages. -Finally, Option (b) allows multiple authentication components to be deployed in -front of the same service. - -OpenStack services can support both embedded (Option (a)) and external (Option -(b)) deployment strategies. Individual authentication components should support -either strategy or they |may| support both strategies. In order to support -option (a), authentication components written in the Python programming -language should be written as WSGI middleware components (in accordance with -the Web Server Gateway Interface (WSGI) standard [PEP-333]_. - -Additionally, services should support the ability to swap between different -embedded or external authentication components via configuration options. - -Exchanging User Information -=========================== - -If a request is successfully authenticated, the authentication component must -extend the request by adding an ``X-Authorization`` header. The header |must| -be formatted as illustrated in :ref:`xAuthHeader`. - -.. _xAuthHeader: - -X-Authorization Header ----------------------- - -Example 1. X-Authorization Header:: - - X-Authorization: Proxy JoeUser - -Here, `Proxy` denotes that the authentication occurred via a proxy (in this -case authentication component) and ''JoeUser'' is the name of the user who -issued the request. - -.. note: - - We considered using an ``Authorization`` header rather than an - ``X-Authorization``, thereby following normal HTTP semantics. There are some - cases, however, where multiple ``Authorization`` headers need to be transmitted - in a single request. We want to assure ourselves that this will not break - common clients before we recommend the approach. - -Authentication components |may| extend the request with additional -information. For example, an authentication system may add additional headers -or modify the target URI to pass authentication information to the back-end -service. Additionally, an authentication component |may| strip sensitive -information — a plain text password, for example — from the request. That said, -an authentication component |should| pass the majority of the request -unmodified. - -Reverse Proxy Authentication ----------------------------- - -An OpenStack service |should| verify that it is receiving requests from a -trusted authentication component. This is particularly important in cases where -the authentication component and the OpenStack service are deployed separately. -In order to trust incoming requests, the OpenStack service should therefore -authenticate the authentication component. To avoid confusion, we call this -'reverse proxy authentication', since in this case the authentication -component is acting as an HTTP reverse proxy. - -Any HTTP-based authentication scheme may be used for reverse proxy -authentication; however, all OpenStack services and all authentication -components |must| support HTTP Basic Authentication as defined in -[RFC-2617]_. - -Whether or not reverse proxy authentication is required is strictly a -deployment concern. For example, an operations team may opt to utilize firewall -rules instead of an authentication protocol to verify the integrity of incoming -request. Because of this, both OpenStack services and authentication components -|must| also allow for unauthenticated communication. - -In cases where reverse proxy authentication is used, the authorization -component may receive an HTTP 401 authentication error or an HTTP 403 -authorization error. These errors indicate that the component does not have -access to the underlying OpenStack service. The authentication component -|must not| return these errors to the client application. Instead, the -component |must| return a 500 internal error. This is illustrated in -:ref:`proxyAuth` and :ref:`proxyAuthDelegated` below. The component -|should| format the errors in a manner that does not break the service -contract defined by the OpenStack service. :ref:`proxyAuthDelegated` -illustrates proxy authorization in delegated mode. Delegated mode is discussed -in detail in the next section. - -.. _proxyAuth: - -Reverse Proxy Authentication ----------------------------- - -Figure 4. Reverse Proxy Authentication - -.. image:: images/graphs_proxyAuth.svg - :width: 100% - :height: 180 - :alt: Reverse Proxy Authentication - -.. _proxyAuthDelegated: - -Reverse Proxy Authentication (Delegated Mode) ---------------------------------------------- - -Figure 5. Reverse Proxy Authentication (Delegated Mode) - -.. image:: images/graphs_delegate_forbiden_proxy.svg - :width: 100% - :height: 180 - :alt: Reverse Proxy Authentication (Delegated Mode) - -Delegated Mode -============== -In some cases, the decision to reject an unauthenticated request should be -delegated to the OpenStack service. An unauthenticated request may be -appropriate in cases when anonymous access is allowed. In order to support -these cases, an authentication component may be placed in Delegated Mode. In -this mode, the component forwards requests to the OpenStack service when the -client's identity has been confirmed or is indeterminate — that is when -credentials are missing. The authentication component directly rejects requests -with invalid credentials. Authentication components |must| extend the -request by adding an `X-Identity-Status` header. The identity status header -|must| contain one of the following values: - -Identity Status Values ----------------------- - -Confirmed - A `confirmed` value indicates that valid credentials were sent and identity - has been confirmed. The service can trust that the request has been sent on - behalf of the user specified in the `X-Authorization` header. - -Indeterminate - An `indeterminate` value indicates that no credentials were sent and - identity has not been confirmed. In this case, the service will receive an - `X-Authorization` header with no user entry as illustrated in - :ref:`xauth-header-indeterminate`. - -.. _xauth-header-indeterminate: - -Indeterminate Identity Headers ------------------------------- - -Example 2. Indeterminate Identity Headers:: - - X-Identity-Status: Indeterminate - X-Authorization: Proxy - -Services |may| reject a delegated request by issuing an HTTP 401 -authentication error or an HTTP 403 authorization error. These responses -|must| contain an ``WWW-Authenticate`` header with a value of ``Delegated`` as -illustrated in :ref:`unauthHeaders`. - -X-Identity-Status - Provides information on whether the request was authenticated or not. - -X-Tenant - Provides the tenant ID (as it appears in the URL in Keystone). This is to support any legacy implementations before Keystone switched to an ID/Name schema for tenants. - -X-Tenant-Id - The unique, immutable tenant Id - -X-Tenant-Name - The unique, but mutable (it can change) tenant name. - -X-User-Id - The user id of the user used to log in - -X-User-Name - The username used to log in - -X-User - The username used to log in. This is to support any legacy implementations before Keystone switched to an ID/Name schema for tenants. - -X-Roles - The roles associated with that user - -.. _unauthHeaders: - -Delegated WWW-Authenticate Header ---------------------------------- - -:: - - WWW-Authenticate: Delegated - -It is important to note that the actual reject message will likely be modified -by the authentication component in order to comply with the authentication -scheme it is implementing. This is illustrated in :ref:`delegateRejectBasic` and -:ref:`delegateRejectOAuth` below. - -.. _delegateRejectBasic: - -Delegated Reject Basic Auth ---------------------------- - -.. image:: images/graphs_delegate_reject_basic.svg - :width: 100% - :height: 180 - :alt: Delegated Reject Basic Auth - -.. _delegateRejectOAuth: - -Delegated Reject OAuth ----------------------- - -.. image:: images/graphs_delegate_reject_oauth.svg - :width: 100% - :height: 180 - :alt: Delegated Reject OAuth - -The presence of the `WWW-Authenticate` header with a value of `Delegated` -distinguishes a client authentication/authorization failure from a component -failure. For example, compare :ref:`delegateForbidden` with :ref:`proxyAuthDelegated`. In -:ref:`delegateForbidden`, the client is not allowed to access the OpenStack service. -In :ref:`proxyAuthDelegated`, it is the authentication component itself which is -unauthorized. - -.. _delegateForbidden: - -Delegated Reject Forbidden --------------------------- - -Figure 8. Delegated Reject Forbidden - -.. image:: images/graphs_delegate_forbiden_basic.svg - :width: 100% - :height: 180 - :alt: Delegated Reject Forbidden - -Authentication components |must| support both delegated and undelegated -(standard) modes. Delegated mode |should| be configured via a configuration -option. Delegated mode |should| be disabled by default. - -OpenStack services are not required to support delegated mode. If a service -does not support delegated mode, it |must| respond with a 501 not implemented -error and an `WWW-Authenticate` header with a value of `Delegated`. The -authentication component |must not| return the error to the client -application. Instead, the component |must| return a 500 internal error; this is -illustrated in :ref:`delegateUnimplemented`. The component |should| -format the error in a manner that does not break the service contract defined -by the OpenStack service. The component should also log the error such that it -that will inform operators of the misconfiguration. - -.. _delegateUnimplemented: - -Unimplemented Delegated Mode ----------------------------- - -.. image:: images/graphs_delegate_unimplemented.svg - :width: 100% - :height: 180 - :alt: Unimplemented Delegated Mode - -Handling Direct Client Connections -================================== - -Requests from the authentication component to an OpenStack service |must| -contain an ``X-Authorization`` header. If the header is missing, and reverse -proxy authentication fails or is switched off, the OpenStack service |may| -assume that the request is coming directly from a client application. In this -case, the OpenStack service |must| redirect the request to the authentication -component by issuing an HTTP 305 User Proxy redirect. This is illustrated in -:ref:`redirect`. Note that the redirect response |must| include a ``Location`` header -specifying the authentication component's URL as shown in :ref:`redirect-response`. - -.. _redirect: - -Auth Component Redirect ------------------------ - -.. image:: images/graphs_305.svg - :width: 100% - :height: 280 - :alt: Auth Component Redirect - -.. _redirect-response: - -Auth Component Redirect Response --------------------------------- - -:: - - HTTP/1.1 305 Use Proxy - Date: Thu, 28 Oct 2011 07:41:16 GMT - Location: http://sample.auth.openstack.com/path/to/resource - -Using Multiple Authentication Components -======================================== - -There are some use cases when a service provider might want to consider using -multiple authentication components for different purposes. For instance, a -service provider may have one authentication scheme to authenticate the users -of the service and another one to authenticate the administrators or operations -personnel that maintain the service. For such scenarios, we propose using a -mapper as illustrated in :ref:`multiAuth`. - -.. _multiAuth: - -Multiple Authentication Components ----------------------------------- - -.. image:: images/graphs_mapper.svg - :width: 100% - :height: 320 - :alt: Multiple Authentication Components - -At a high level, a mapper is a simple reverse proxy that intercepts HTTP calls -from clients and routes the request to the appropriate authentication -component. A mapper can make the routing decisions based on a number of routing -rules that map a resource to a specific authentication component. For example, -a request URI may determine whether a call should be authenticated via one -authentication component or another. - -Note that neither the authentication component nor the OpenStack service need -be aware of the mapper. Any external authentication component can be used -alongside others. Mappers may provide a means by which to offer support for -anonymous or guest access to a subset of service resources. A mapper may be -implemented via a traditional reverse proxy server such as Pound or Zeus. - -The Default Component -===================== - -Individual services |must| be distributed with a simple integrated -authentication component by default. Providing such a component lowers barriers -to the deployment of individual services. This is especially important to] -developers who may want to deploy OpenStack services on their own machines. -Also, since there is no direct dependency on an external authentication system, -OpenStack services can be deployed individually, without the need to stand up -and configure additional services. Finally, having a standard authentication -component that all services share promotes a separation of concerns. That is, -as a community we are explicitly stating that services should not develop their -own authentication mechanisms. Additional authentication components may be -developed, of course, but these components should not be intimately coupled to -any one particular service. - -As discussed in :ref:`deployStrategies`, an authentication component may be -integrated directly into the service implementation (Option (a)), or it may be -deployed separately as an HTTP reverse proxy (Option (b)). The default -component should be implemented to support Option (a) and services should -maintain support for Option (b). One way to achieve this is to provide a -method that allows the disabling of the default authentication component via -configuration. This is illustrated in :ref:`both`. Here, requests are -sent directly to the OpenStack service when the default authentication -component is disabled. - -We will discuss the design of the default component in an upcoming blueprint. - -.. _both: - -Disabled Embedded Component ---------------------------- - -.. image:: images/graphs_both.svg - :width: 100% - :height: 250 - :alt: Disabled Embedded Component - -Questions and Answers -===================== - -#. Why do authentication components send reject messages? Why not have - OpenStack services reject requests themselves? - - The content and format of an authentication failed message is determined by - the authentication scheme (or protocol). For the service to respond - appropriately, it would have to be aware of the authentication scheme in - which it participates; this defeats the purpose of pluggable authentication - components. - -#. Why require support for deploying authentication components in separate - nodes? - - The deployment strategy is very flexible. It allows for authentication - components to be horizontally scalable. It allows for components to be written - in different languages. Finally, it allows different authentication components - to be deployed simultaneously as described above. - -References -========== - -.. [PEP-333] pep0333 Phillip J Eby. 'Python Web Server Gateway Interface - v1.0.'' http://www.python.org/dev/peps/pep-0333/. - -.. [RFC-2617] rfc2617 J Franks. P Hallam-Baker. J Hostetler. S Lawrence. - P Leach. A Luotonen. L Stewart. ''HTTP Authentication: Basic and Digest - Access Authentication.'' http://tools.ietf.org/html/rfc2617. - -.. |must| replace:: must must -.. |should| replace:: should should -.. |may| replace:: may may -.. |must not| replace:: "must not" "must not" - diff --git a/docs/source/migration.rst b/docs/source/migration.rst deleted file mode 100644 index 460d980b..00000000 --- a/docs/source/migration.rst +++ /dev/null @@ -1,126 +0,0 @@ -=================== -Database Migrations -=================== - -Keystone uses SQLAlchemy Migrate (``sqlalchemy-migrate``) to manage -migrations. - -Migrations are tracked using a metadata table (``migrate_version``), which -allows keystone to compare the state of your database to the state it -expects, and to move between versions. - -.. WARNING:: - - Backup your database before applying migrations. Migrations may - attempt to modify both your schema and data, and could result in data - loss. - - Always review the behavior of migrations in a staging environment - before applying them in production. - -Getting Started -=============== - -Your initial approach to migrations should depend on whether you have an -empty database or a schema full of data. - -Starting with an empty database -------------------------------- - -If you have an empty database for keystone to work with, you can simply -run:: - - $ ./bin/keystone-manage database sync - -This command will initialize your metadata table, and run through all the -schema & data migrations necessary to bring your database in sync with -keystone. That's it! - -Starting with an existing database ----------------------------------- - -Place an existing database under version control to enable migration -support:: - - $ ./bin/keystone-manage database version_control - -This command simply creates a ``migrate_version`` table, set at -``version_number`` 0, which indicates that no migrations have been applied. - -If you are starting with an existing schema, you can jump to a specific -schema version without performing migrations using the ``database goto`` -command. For example, if you're starting from a diablo-compatible -database, set your current database ``version_number`` to ``1`` using:: - - $ ./bin/keystone-manage database goto - -Determine your appropriate database ``version_number`` by referencing the -following table: - - +------------+-------------+ - | Release | ``version`` | - +============+=============+ - | pre-diablo | (see below) | - +------------+-------------+ - | diablo | 1 | - +------------+-------------+ - | essex-m1 | 3 | - +------------+-------------+ - | essex-m2 | 4 | - +------------+-------------+ - -From there, you can upgrade normally (see :ref:`upgrading`). - -Starting with a pre-diablo database (cactus) --------------------------------------------- - -You'll need to manually migrate your database to a diablo-compatible -schema, and continue forward from there (if desired) using migrations. - -.. _upgrading: - -Upgrading & Downgrading -======================= - -.. note:: - - Attempting to start keystone with an outdated schema will cause - keystone to abort, to avoid corrupting your data. - -Upgrade to the latest version automatically:: - - $ ./bin/keystone-manage database sync - -Check your current schema version:: - - $ ./bin/keystone-manage database version - -Jump to a specific version without performing migrations:: - - $ ./bin/keystone-manage database goto - -Upgrade to a specific version:: - - $ ./bin/keystone-manage database upgrade - -Downgrade to a specific version (will likely result in data loss!):: - - $ ./bin/keystone-manage database downgrade - -Opting Out of Migrations -======================== - -If you don't want to use migrations (e.g. if you want to manage your -schema manually), keystone will complain in your logs on startup, but -won't actually stop you from doing so. - -It's recommended that you use migrations to get up and running, but if -you want to manage migrations manually after that, simply drop the -``migrate_version`` table:: - - DROP TABLE migrate_version; - -Useful Links -============ - -Principles to follow when developing migrations `OpenStack Deployability `_ diff --git a/docs/source/nova-api-paste.rst b/docs/source/nova-api-paste.rst deleted file mode 100644 index 586bac72..00000000 --- a/docs/source/nova-api-paste.rst +++ /dev/null @@ -1,142 +0,0 @@ -.. - Copyright 2011 OpenStack, LLC - All Rights Reserved. - - Licensed under the Apache License, Version 2.0 (the "License"); you may - not use this file except in compliance with the License. You may obtain - a copy of the License at - - http://www.apache.org/licenses/LICENSE-2.0 - - Unless required by applicable law or agreed to in writing, software - distributed under the License is distributed on an "AS IS" BASIS, WITHOUT - WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the - License for the specific language governing permissions and limitations - under the License. - -nova-api-paste example -====================== -:: - - ####### - # EC2 # - ####### - - [composite:ec2] - use = egg:Paste#urlmap - /: ec2versions - /services/Cloud: ec2cloud - /services/Admin: ec2admin - /latest: ec2metadata - /2007-01-19: ec2metadata - /2007-03-01: ec2metadata - /2007-08-29: ec2metadata - /2007-10-10: ec2metadata - /2007-12-15: ec2metadata - /2008-02-01: ec2metadata - /2008-09-01: ec2metadata - /2009-04-04: ec2metadata - /1.0: ec2metadata - - [pipeline:ec2cloud] - pipeline = logrequest totoken authtoken keystonecontext cloudrequest authorizer ec2executor - - [pipeline:ec2admin] - pipeline = logrequest totoken authtoken keystonecontext adminrequest authorizer ec2executor - - [pipeline:ec2metadata] - pipeline = logrequest ec2md - - [pipeline:ec2versions] - pipeline = logrequest ec2ver - - [filter:logrequest] - paste.filter_factory = nova.api.ec2:RequestLogging.factory - - [filter:ec2lockout] - paste.filter_factory = nova.api.ec2:Lockout.factory - - [filter:totoken] - paste.filter_factory = keystone.middleware.ec2_token:EC2Token.factory - - [filter:ec2noauth] - paste.filter_factory = nova.api.ec2:NoAuth.factory - - [filter:authenticate] - paste.filter_factory = nova.api.ec2:Authenticate.factory - - [filter:cloudrequest] - controller = nova.api.ec2.cloud.CloudController - paste.filter_factory = nova.api.ec2:Requestify.factory - - [filter:adminrequest] - controller = nova.api.ec2.admin.AdminController - paste.filter_factory = nova.api.ec2:Requestify.factory - - [filter:authorizer] - paste.filter_factory = nova.api.ec2:Authorizer.factory - - [app:ec2executor] - paste.app_factory = nova.api.ec2:Executor.factory - - [app:ec2ver] - paste.app_factory = nova.api.ec2:Versions.factory - - [app:ec2md] - paste.app_factory = nova.api.ec2.metadatarequesthandler:MetadataRequestHandler.factory - - ############# - # Openstack # - ############# - - [composite:osapi] - use = egg:Paste#urlmap - /: osversions - /v1.1: openstackapi - - [pipeline:openstackapi] - pipeline = faultwrap authtoken keystonecontext ratelimit extensions osapiapp - - [filter:faultwrap] - paste.filter_factory = nova.api.openstack:FaultWrapper.factory - - [filter:auth] - paste.filter_factory = nova.api.openstack.auth:AuthMiddleware.factory - - [filter:noauth] - paste.filter_factory = nova.api.openstack.auth:NoAuthMiddleware.factory - - [filter:ratelimit] - paste.filter_factory = nova.api.openstack.limits:RateLimitingMiddleware.factory - - [filter:extensions] - paste.filter_factory = nova.api.openstack.extensions:ExtensionMiddleware.factory - - [app:osapiapp] - paste.app_factory = nova.api.openstack:APIRouter.factory - - [pipeline:osversions] - pipeline = faultwrap osversionapp - - [app:osversionapp] - paste.app_factory = nova.api.openstack.versions:Versions.factory - - ########## - # Shared # - ########## - - [filter:keystonecontext] - paste.filter_factory = keystone.middleware.nova_keystone_context:NovaKeystoneContext.factory - - [filter:authtoken] - paste.filter_factory = keystone.middleware.auth_token:filter_factory - service_protocol = http - service_host = 127.0.0.1 - service_port = 5000 - auth_host = 127.0.0.1 - auth_port = 35357 - auth_protocol = http - auth_uri = http://127.0.0.1:5000/ - admin_token = 999888777666 - ;Uncomment next line and check ip:port to use memcached to cache token requests - ;memcache_hosts = 127.0.0.1:11211 diff --git a/docs/source/old/configuringservices.rst b/docs/source/old/configuringservices.rst new file mode 100644 index 00000000..083c3ec5 --- /dev/null +++ b/docs/source/old/configuringservices.rst @@ -0,0 +1,333 @@ +.. + Copyright 2011 OpenStack, LLC + All Rights Reserved. + + Licensed under the Apache License, Version 2.0 (the "License"); you may + not use this file except in compliance with the License. You may obtain + a copy of the License at + + http://www.apache.org/licenses/LICENSE-2.0 + + Unless required by applicable law or agreed to in writing, software + distributed under the License is distributed on an "AS IS" BASIS, WITHOUT + WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the + License for the specific language governing permissions and limitations + under the License. + +========================================== +Configuring Services to work with Keystone +========================================== + +.. toctree:: + :maxdepth: 1 + +Once Keystone is installed and running, services need to be configured to work +with it. These are the steps to configure a service to work with Keystone: + +1. Create or get credentials for the service to use + + A set of credentials are needed for each service (they may be + shared if you chose to). Depending on the service, these credentials are + either a username and password or a long-lived token.. + +2. Register the service, endpoints, roles and other entities + + In order for a service to have it's endpoints and roles show in the service + catalog returned by Keystone, a service record needs to be added for the + service. Endpoints and roles associated with that service can then be created. + + This can be done through the REST interface (using the OS-KSCATALOG extension) + or using keystone-manage. + +3. Install and configure middleware for the service to handle authentication + + Clients making calls to the service will pass in an authentication token. The + Keystone middleware will look for and validate that token, taking the + appropriate action. It will also retrive additional information from the token + such as user name, id, tenant name, id, roles, etc... + + The middleware will pass those data down to the service as headers. The + detailed description of this architecture is available here :doc:`middleware_architecture` + +Setting up credentials +====================== + +First admin user - bootstrapping +-------------------------------- + +For a default installation of Keystone, before you can use the REST API, you +need to create your first initial user and grant that user the right to +administer Keystone. + +For the keystone service itself, two +Roles are pre-defined in the keystone configuration file +(:doc:`keystone.conf`). + + #Role that allows admin operations (access to all operations) + keystone-admin-role = Admin + + #Role that allows acting as service (validate tokens, register service, + etc...) + keystone-service-admin-role = KeystoneServiceAdmin + +In order to create your first user, once Keystone is running use +the `keystone-manage` command: + + $ keystone-manage user add admin secrete + $ keystone-manage role add Admin + $ keystone-manage role add KeystoneServiceAdmin + $ keystone-manage role grant Admin admin + $ keystone-manage role grant KeystoneServiceAdmin admin + +This creates the `admin` user (with a password of `secrete`), creates +two roles (`Admin` and `KeystoneServiceAdmin`), and assigns those roles to +the `admin` user. From here, you should now have the choice of using the +administrative API (as well as the :doc:`man/keystone-manage` commands) to +further configure keystone. There are a number of examples of how to use +that API at :doc:`adminAPI_curl_examples`. + + +Setting up services +=================== + +Defining Services and Service Endpoints +--------------------------------------- + +Keystone also acts as a service catalog to let other OpenStack systems know +where relevant API endpoints exist for OpenStack Services. The OpenStack +Dashboard, in particular, uses this heavily - and this **must** be configured +for the OpenStack Dashboard to properly function. + +Here's how we define the services:: + + $ keystone-manage service add nova compute "Nova Compute Service" + $ keystone-manage service add glance image "Glance Image Service" + $ keystone-manage service add swift storage "Swift Object Storage Service" + $ keystone-manage service add keystone identity "Keystone Identity Service" + +Once the services are defined, we create endpoints for them. Each service +has three relevant URL's associated with it that are used in the command: + +* the public API URL +* an administrative API URL +* an internal URL + +The "internal URL" is an endpoint the generally offers the same API as the +public URL, but over a high-bandwidth, low-latency, unmetered (free) network. +You would use that to transfer images from nova to glance for example, and +not the Public URL which would go over the internet and be potentially chargeable. + +The "admin URL" is for administering the services and is not exposed or accessible +to customers without the apporpriate privileges. + +An example of setting up the endpoint for Nova:: + + $ keystone-manage endpointTemplates add RegionOne nova \ + http://nova-api.mydomain:8774/v1.1/%tenant_id% \ + http://nova-api.mydomain:8774/v1.1/%tenant_id% \ + http://nova-api.mydomain:8774/v1.1/%tenant_id% \ + 1 1 + +Glance:: + + $ keystone-manage endpointTemplates add RegionOne glance \ + http://glance.mydomain:9292/v1 \ + http://glance.mydomain:9292/v1 \ + http://glance.mydomain:9292/v1 \ + 1 1 + +Swift:: + + $ keystone-manage endpointTemplates add RegionOne swift \ + http://swift.mydomain:8080/v1/AUTH_%tenant_id% \ + http://swift.mydomain:8080/v1.0/ \ + http://swift.mydomain:8080/v1/AUTH_%tenant_id% \ + 1 1 + +And setting up an endpoint for Keystone:: + + $ keystone-manage endpointTemplates add RegionOne keystone \ + http://keystone.mydomain:5000/v2.0 \ + http://keystone.mydomain:35357/v2.0 \ + http://keystone.mydomain:5000/v2.0 \ + 1 1 + + +Defining an Administrative Service Token +---------------------------------------- + +An Administrative Service Token is a bit of arbitrary text which is configured +in Keystone and used (typically configured into) Nova, Swift, Glance, and any +other OpenStack projects, to be able to use Keystone services. + +This token is an arbitrary text string, but must be identical between Keystone +and the services using Keystone. This token is bound to a user and tenant as +well, so those also need to be created prior to setting it up. + +The *admin* user was set up above, but we haven't created a tenant for that +user yet:: + + $ keystone-manage tenant add admin + +and while we're here, let's grant the admin user the 'Admin' role to the +'admin' tenant:: + + $ keystone-manage role add Admin + $ keystone-manage role grant Admin admin admin + +Now we can create a service token:: + + $ keystone-manage token add 999888777666 admin admin 2015-02-05T00:00 + +This creates a service token of '999888777666' associated to the admin user, +admin tenant, and expires on February 5th, 2015. This token will be used when +configuring Nova, Glance, or other OpenStack services. + +Securing Communications with SSL +-------------------------------- + +To encrypt traffic between services and Keystone, see :doc:`ssl` + + +Setting up OpenStack users +========================== + +Creating Tenants, Users, and Roles +---------------------------------- + +Let's set up a 'demo' tenant:: + + $ keystone-manage tenant add demo + +And add a 'demo' user with the password 'guest':: + + $ keystone-manage user add demo guest + +Now let's add a role of "Member" and grant 'demo' user that role +as it pertains to the tenant 'demo':: + + $ keystone-manage role add Member + $ keystone-manage role grant Member demo demo + +Let's also add the admin user as an Admin role to the demo tenant:: + + $ keystone-manage role grant Admin admin demo + +Creating EC2 credentials +------------------------ + +To add EC2 credentials for the `admin` and `demo` accounts:: + + $ keystone-manage credentials add admin EC2 'admin' 'secretpassword' + $ keystone-manage credentials add admin EC2 'demo' 'secretpassword' + +If you have a large number of credentials to create, you can put them all +into a single large file and import them using :doc:`man/keystone-import`. The +format of the document looks like:: + + credentials add admin EC2 'username' 'password' + credentials add admin EC2 'username' 'password' + +Then use:: + + $ keystone-import `filename` + + +Setting Up Middleware +===================== + +Keystone Auth-Token Middleware +-------------------------------- + +The Keystone auth_token middleware is a WSGI component that can be inserted in +the WSGI pipeline to handle authenticating tokens with Keystone. See :doc:`middleware` +for details on middleware and configuration parameters. + + +Configuring Nova to use Keystone +-------------------------------- + +To configure Nova to use Keystone for authentication, the Nova API service +can be run against the api-paste file provided by Keystone. This is most +easily accomplished by setting the `--api_paste_config` flag in nova.conf to +point to `examples/paste/nova-api-paste.ini` from Keystone. This paste file +included references to the WSGI authentication middleware provided with the +keystone installation. + +When configuring Nova, it is important to create a admin service token for +the service (from the Configuration step above) and include that as the key +'admin_token' in the nova-api-paste.ini. See the documented +:doc:`nova-api-paste` file for references. + +Configuring Swift to use Keystone +--------------------------------- + +Similar to Nova, swift can be configured to use Keystone for authentication +rather than it's built in 'tempauth'. + +1. Add a service endpoint for Swift to Keystone + +2. Configure the paste file for swift-proxy (`/etc/swift/swift-proxy.conf`) + +3. Reconfigure Swift's proxy server to use Keystone instead of TempAuth. + Here's an example `/etc/swift/proxy-server.conf`:: + + [DEFAULT] + bind_port = 8888 + user = + + [pipeline:main] + pipeline = catch_errors cache keystone proxy-server + + [app:proxy-server] + use = egg:swift#proxy + account_autocreate = true + + [filter:keystone] + use = egg:keystone#tokenauth + auth_protocol = http + auth_host = 127.0.0.1 + auth_port = 35357 + admin_token = 999888777666 + delay_auth_decision = 0 + service_protocol = http + service_host = 127.0.0.1 + service_port = 8100 + service_pass = dTpw + cache = swift.cache + + [filter:cache] + use = egg:swift#memcache + set log_name = cache + + [filter:catch_errors] + use = egg:swift#catch_errors + + Note that the optional "cache" property in the keystone filter allows any + service (not just Swift) to register its memcache client in the WSGI + environment. If such a cache exists, Keystone middleware will utilize it + to store validated token information, which could result in better overall + performance. + +4. Restart swift + +5. Verify that keystone is providing authentication to Swift + +Use `swift` to check everything works (note: you currently have to create a +container or upload something as your first action to have the account +created; there's a Swift bug to be fixed soon):: + + $ swift -A http://127.0.0.1:5000/v1.0 -U joeuser -K secrete post container + $ swift -A http://127.0.0.1:5000/v1.0 -U joeuser -K secrete stat -v + StorageURL: http://127.0.0.1:8888/v1/AUTH_1234 + Auth Token: 74ce1b05-e839-43b7-bd76-85ef178726c3 + Account: AUTH_1234 + Containers: 1 + Objects: 0 + Bytes: 0 + Accept-Ranges: bytes + X-Trans-Id: tx25c1a6969d8f4372b63912f411de3c3b + +.. WARNING:: + Keystone currently allows any valid token to do anything with any account. + diff --git a/docs/source/old/controllingservers.rst b/docs/source/old/controllingservers.rst new file mode 100644 index 00000000..ba8bfc06 --- /dev/null +++ b/docs/source/old/controllingservers.rst @@ -0,0 +1,288 @@ +.. + Copyright 2011 OpenStack, LLC + All Rights Reserved. + + Licensed under the Apache License, Version 2.0 (the "License"); you may + not use this file except in compliance with the License. You may obtain + a copy of the License at + + http://www.apache.org/licenses/LICENSE-2.0 + + Unless required by applicable law or agreed to in writing, software + distributed under the License is distributed on an "AS IS" BASIS, WITHOUT + WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the + License for the specific language governing permissions and limitations + under the License. + +============================ +Controlling Keystone Servers +============================ + +This section describes the ways to start, stop, and reload the Keystone +services. + +Keystone Services +----------------- + +Keystone can serve a number of REST APIs and extensions on different TCP/IP +ports. + +The Service API +~~~~~~~~~~~~~~~~ + +The core Keystone +API is primarily a read-only API (the only write operation being POST /tokens +which authenticates a client, and returns a generated token). +This API is sufficient to use OpenStack if all users, roles, endpoints already +exist. This is often the case if Keystone is using an enterprise backend +and the backend is managed through other entperrise tools and business +processes. This core API is called the Service API and can be started +separately from the more complete Admin API. By default, Keystone runs +this API on port 5000. This is not an IANA assigned port and should not +be relied upon (instead, use the Admin API on port 35357 to look for +this endpoint - more on this later) + +The Service API is started using this command in the /bin directory:: + + $ ./keystone-auth + +The Admin API +~~~~~~~~~~~~~ + +Inn order for Keystone to be a fully functional service out of the box, +API extensions that provide full CRUD operations is included with Keystone. +This full set of API calls includes the OS-KSCATALOG, OS-KSADM, and OS-KSEC2 +extensions. These extensions provide a full set of create, read, update, delete +(CRUD) operations that can be used to manage Keystone objects through REST +calls. By default Keystone runs this full REST API on TCP/IP port 35357 +(assigned by IANA to Keystone). + +The Admin API is started using this command in the /bin directory:: + + $ ./keystone-admin + + +Both APIs can be loaded simultaneously (on different ports) using this command:: + + $ ./keystone + +Starting a server +----------------- + +There are two ways to start a Keystone service (either the Service API server +or the Admin API server): + +- Manually calling the server program +- Using the ``keystone-control`` server daemon wrapper program + +We recommend using the second way in production and the first for development +and debugging. + +Manually starting the server +~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +The first is by directly calling the server program, passing in command-line +options and a single argument for a ``paste.deploy`` configuration file to +use when configuring the server application. + +.. note:: + + Keystone ships with an ``etc/`` directory that contains a sample ``paste.deploy`` + configuration files that you can copy to a standard configuration directory and + adapt for your own uses. + +If you do `not` specify a configuration file on the command line, Keystone will +do its best to locate a configuration file in one of the +following directories, stopping at the first config file it finds: + +- ``$CWD`` +- ``~/.keystone`` +- ``~/`` +- ``/etc/keystone`` +- ``/etc`` + +The filename that is searched for is ``keystone.conf`` by default. + +If no configuration file is found, you will see an error, like:: + + $ keystone + ERROR: Unable to locate any configuration file. Cannot load application keystone + +Here is an example showing how you can manually start the ``keystone-auth`` server and ``keystone-registry`` in a shell:: + + $ ./keystone -d + keystone-legacy-auth: INFO ************************************************** + keystone-legacy-auth: INFO Configuration options gathered from config file: + keystone-legacy-auth: INFO /Users/ziadsawalha/Documents/Code/keystone/etc/keystone.conf + keystone-legacy-auth: INFO ================================================ + keystone-legacy-auth: INFO admin_host 0.0.0.0 + keystone-legacy-auth: INFO admin_port 35357 + keystone-legacy-auth: INFO admin_ssl False + keystone-legacy-auth: INFO backends keystone.backends.sqlalchemy + keystone-legacy-auth: INFO ca_certs /etc/keystone/ssl/certs/ca.pem + keystone-legacy-auth: INFO cert_required True + keystone-legacy-auth: INFO certfile /etc/keystone/ssl/certs/keystone.pem + keystone-legacy-auth: INFO debug True + keystone-legacy-auth: INFO default_store sqlite + keystone-legacy-auth: INFO extensions osksadm,oskscatalog,hpidm + keystone-legacy-auth: INFO hash-password True + keystone-legacy-auth: INFO keyfile /etc/keystone/ssl/private/keystonekey.pem + keystone-legacy-auth: INFO keystone-admin-role Admin + keystone-legacy-auth: INFO keystone-service-admin-role KeystoneServiceAdmin + keystone-legacy-auth: INFO log_dir . + keystone-legacy-auth: INFO log_file keystone.log + keystone-legacy-auth: INFO service-header-mappings { + 'nova' : 'X-Server-Management-Url', + 'swift' : 'X-Storage-Url', + 'cdn' : 'X-CDN-Management-Url'} + keystone-legacy-auth: INFO service_host 0.0.0.0 + keystone-legacy-auth: INFO service_port 5000 + keystone-legacy-auth: INFO service_ssl False + keystone-legacy-auth: INFO verbose False + keystone-legacy-auth: INFO ************************************************** + passlib.registry: INFO registered crypt handler 'sha512_crypt': + Starting the RAX-KEY extension + Starting the Legacy Authentication component + admin : INFO ************************************************** + admin : INFO Configuration options gathered from config file: + admin : INFO /Users/ziadsawalha/Documents/Code/keystone/etc/keystone.conf + admin : INFO ================================================ + admin : INFO admin_host 0.0.0.0 + admin : INFO admin_port 35357 + admin : INFO admin_ssl False + admin : INFO backends keystone.backends.sqlalchemy + admin : INFO ca_certs /etc/keystone/ssl/certs/ca.pem + admin : INFO cert_required True + admin : INFO certfile /etc/keystone/ssl/certs/keystone.pem + admin : INFO debug True + admin : INFO default_store sqlite + admin : INFO extensions osksadm,oskscatalog,hpidm + admin : INFO hash-password True + admin : INFO keyfile /etc/keystone/ssl/private/keystonekey.pem + admin : INFO keystone-admin-role Admin + admin : INFO keystone-service-admin-role KeystoneServiceAdmin + admin : INFO log_dir . + admin : INFO log_file keystone.log + admin : INFO service-header-mappings { + 'nova' : 'X-Server-Management-Url', + 'swift' : 'X-Storage-Url', + 'cdn' : 'X-CDN-Management-Url'} + admin : INFO service_host 0.0.0.0 + admin : INFO service_port 5000 + admin : INFO service_ssl False + admin : INFO verbose False + admin : INFO ************************************************** + Using config file: /Users/ziadsawalha/Documents/Code/keystone/etc/keystone.conf + Service API (ssl=False) listening on 0.0.0.0:5000 + Admin API (ssl=False) listening on 0.0.0.0:35357 + eventlet.wsgi.server: DEBUG (77128) wsgi starting up on http://0.0.0.0:5000/ + eventlet.wsgi.server: DEBUG (77128) wsgi starting up on http://0.0.0.0:35357/ + + $ sudo keystone-registry keystone-registry.conf & + jsuh@mc-ats1:~$ 2011-04-13 14:51:16 INFO [sqlalchemy.engine.base.Engine.0x...feac] PRAGMA table_info("images") + 2011-04-13 14:51:16 INFO [sqlalchemy.engine.base.Engine.0x...feac] () + 2011-04-13 14:51:16 DEBUG [sqlalchemy.engine.base.Engine.0x...feac] Col ('cid', 'name', 'type', 'notnull', 'dflt_value', 'pk') + 2011-04-13 14:51:16 DEBUG [sqlalchemy.engine.base.Engine.0x...feac] Row (0, u'created_at', u'DATETIME', 1, None, 0) + 2011-04-13 14:51:16 DEBUG [sqlalchemy.engine.base.Engine.0x...feac] Row (1, u'updated_at', u'DATETIME', 0, None, 0) + 2011-04-13 14:51:16 DEBUG [sqlalchemy.engine.base.Engine.0x...feac] Row (2, u'deleted_at', u'DATETIME', 0, None, 0) + 2011-04-13 14:51:16 DEBUG [sqlalchemy.engine.base.Engine.0x...feac] Row (3, u'deleted', u'BOOLEAN', 1, None, 0) + 2011-04-13 14:51:16 DEBUG [sqlalchemy.engine.base.Engine.0x...feac] Row (4, u'id', u'INTEGER', 1, None, 1) + 2011-04-13 14:51:16 DEBUG [sqlalchemy.engine.base.Engine.0x...feac] Row (5, u'name', u'VARCHAR(255)', 0, None, 0) + 2011-04-13 14:51:16 DEBUG [sqlalchemy.engine.base.Engine.0x...feac] Row (6, u'disk_format', u'VARCHAR(20)', 0, None, 0) + 2011-04-13 14:51:16 DEBUG [sqlalchemy.engine.base.Engine.0x...feac] Row (7, u'container_format', u'VARCHAR(20)', 0, None, 0) + 2011-04-13 14:51:16 DEBUG [sqlalchemy.engine.base.Engine.0x...feac] Row (8, u'size', u'INTEGER', 0, None, 0) + 2011-04-13 14:51:16 DEBUG [sqlalchemy.engine.base.Engine.0x...feac] Row (9, u'status', u'VARCHAR(30)', 1, None, 0) + 2011-04-13 14:51:16 DEBUG [sqlalchemy.engine.base.Engine.0x...feac] Row (10, u'is_public', u'BOOLEAN', 1, None, 0) + 2011-04-13 14:51:16 DEBUG [sqlalchemy.engine.base.Engine.0x...feac] Row (11, u'location', u'TEXT', 0, None, 0) + 2011-04-13 14:51:16 INFO [sqlalchemy.engine.base.Engine.0x...feac] PRAGMA table_info("image_properties") + 2011-04-13 14:51:16 INFO [sqlalchemy.engine.base.Engine.0x...feac] () + 2011-04-13 14:51:16 DEBUG [sqlalchemy.engine.base.Engine.0x...feac] Col ('cid', 'name', 'type', 'notnull', 'dflt_value', 'pk') + 2011-04-13 14:51:16 DEBUG [sqlalchemy.engine.base.Engine.0x...feac] Row (0, u'created_at', u'DATETIME', 1, None, 0) + 2011-04-13 14:51:16 DEBUG [sqlalchemy.engine.base.Engine.0x...feac] Row (1, u'updated_at', u'DATETIME', 0, None, 0) + 2011-04-13 14:51:16 DEBUG [sqlalchemy.engine.base.Engine.0x...feac] Row (2, u'deleted_at', u'DATETIME', 0, None, 0) + 2011-04-13 14:51:16 DEBUG [sqlalchemy.engine.base.Engine.0x...feac] Row (3, u'deleted', u'BOOLEAN', 1, None, 0) + 2011-04-13 14:51:16 DEBUG [sqlalchemy.engine.base.Engine.0x...feac] Row (4, u'id', u'INTEGER', 1, None, 1) + 2011-04-13 14:51:16 DEBUG [sqlalchemy.engine.base.Engine.0x...feac] Row (5, u'image_id', u'INTEGER', 1, None, 0) + 2011-04-13 14:51:16 DEBUG [sqlalchemy.engine.base.Engine.0x...feac] Row (6, u'key', u'VARCHAR(255)', 1, None, 0) + 2011-04-13 14:51:16 DEBUG [sqlalchemy.engine.base.Engine.0x...feac] Row (7, u'value', u'TEXT', 0, None, 0) + + $ ps aux | grep keystone + myuser 77148 0.0 0.0 2434892 472 s012 U+ 11:50AM 0:00.01 grep keystone + myuser 77128 0.0 0.6 2459356 25360 s011 S+ 11:48AM 0:00.82 python ./keystone -d + +Simply supply the configuration file as the first argument +and then any common options +you want to use (``-d`` was used above to show some of the debugging +output that the server shows when starting up. Call the server program +with ``--help`` to see all available options you can specify on the +command line.) + +Using ``--trace-calls`` is useful for showing a trace of calls (errors in red) +for debugging. + +For more information on configuring the server via the ``paste.deploy`` +configuration files, see the section entitled +:doc:`Configuring Keystone ` + +Note that the server `daemonizes` itself by using the standard +shell backgrounding indicator, ``&``, in the previous example. For most use cases, we recommend +using the ``keystone-control`` server daemon wrapper for daemonizing. See below +for more details on daemonization with ``keystone-control``. + +Using ``keystone-control`` to start the server +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +The second way to start up a Keystone server is to use the ``keystone-control`` +program. ``keystone-control`` is a wrapper script that allows the user to +start, stop, restart, and reload the other Keystone server programs in +a fashion that is more conducive to automation and scripting. + +Servers started via the ``keystone-control`` program are always `daemonized`, +meaning that the server program process runs in the background. + +To start a Keystone server with ``keystone-control``, simply call +``keystone-control`` with a server and the word "start", followed by +any command-line options you wish to provide. Start the server with ``keystone-control`` +in the following way:: + + $ sudo keystone-control start [CONFPATH] + +.. note:: + + You must use the ``sudo`` program to run ``keystone-control`` currently, as the + pid files for the server programs are written to /var/run/keystone/ + +Start the ``keystone-admin`` server using ``keystone-control``:: + + $ sudo keystone-control admin start + Starting keystone-admin with /etc/keystone.conf + +The same ``paste.deploy`` configuration files are used by ``keystone-control`` +to start the Keystone server programs, and you can specify (as the example above +shows) a configuration file when starting the server. + +Stopping a server +----------------- + +If you started a Keystone server manually and did not use the ``&`` backgrounding +function, simply send a terminate signal to the server process by typing +``Ctrl-C`` + +If you started the Keystone server using ``keystone-control``, you can +use the ``keystone-control`` program to stop it:: + + $ sudo keystone-control stop + +For example:: + + $ sudo keystone-control auth stop + Stopping keystone-auth pid: 77401 signal: 15 + +Restarting a server +------------------- + +Restart the Keystone server using ``keystone-control``:: + + $ sudo keystone-control admin restart /etc/keystone.conf + Stopping keystone-admin pid: 77401 signal: 15 + Starting keystone-admin with /etc/keystone.conf diff --git a/docs/source/old/endpoints.rst b/docs/source/old/endpoints.rst new file mode 100644 index 00000000..84a42e09 --- /dev/null +++ b/docs/source/old/endpoints.rst @@ -0,0 +1,430 @@ +.. + Copyright 2011 OpenStack, LLC + All Rights Reserved. + + Licensed under the Apache License, Version 2.0 (the "License"); you may + not use this file except in compliance with the License. You may obtain + a copy of the License at + + http://www.apache.org/licenses/LICENSE-2.0 + + Unless required by applicable law or agreed to in writing, software + distributed under the License is distributed on an "AS IS" BASIS, WITHOUT + WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the + License for the specific language governing permissions and limitations + under the License. + +================================ +Endpoints and Endpoint Templates +================================ + +.. toctree:: + :maxdepth: 1 + +What are Endpoints? +------------------- + +Simply, endpoints are URLs that point to OpenStack services. When you +authenticate to Keystone you get back a token which has a service catalog in +it. The service catalog is basically a list of the OpenStack services that +you have access to and the URLs you can use to get to them; their endpoints. + +Here is an example response from Keystone when you authenticate:: + + { + "access":{ + "token":{ + "id":"ab48a9efdfedb23ty3494", + "expires":"2010-11-01T03:32:15-05:00", + "tenant":{ + "id": "t1000", + "name": "My Project" + } + }, + "user":{ + "id":"u123", + "name":"jqsmith", + "roles":[{ + "id":"100", + "name":"compute:admin" + }, + { + "id":"101", + "name":"object-store:admin", + "tenantId":"t1000" + } + ], + "roles_links":[] + }, + "serviceCatalog":[{ + "name":"Nova", + "type":"compute", + "endpoints":[{ + "tenantId":"t1000", + "publicURL":"https://compute.north.host.com/v1/t1000", + "internalURL":"https://compute.north.internal/v1/t1000", + "region":"North", + "versionId":"1", + "versionInfo":"https://compute.north.host.com/v1/", + "versionList":"https://compute.north.host.com/" + }, + { + "tenantId":"t1000", + "publicURL":"https://compute.north.host.com/v1.1/t1000", + "internalURL":"https://compute.north.internal/v1.1/t1000", + "region":"North", + "versionId":"1.1", + "versionInfo":"https://compute.north.host.com/v1.1/", + "versionList":"https://compute.north.host.com/" + } + ], + "endpoints_links":[] + }, + { + "name":"Swift", + "type":"object-store", + "endpoints":[{ + "tenantId":"t1000", + "publicURL":"https://storage.north.host.com/v1/t1000", + "internalURL":"https://storage.north.internal/v1/t1000", + "region":"North", + "versionId":"1", + "versionInfo":"https://storage.north.host.com/v1/", + "versionList":"https://storage.north.host.com/" + }, + { + "tenantId":"t1000", + "publicURL":"https://storage.south.host.com/v1/t1000", + "internalURL":"https://storage.south.internal/v1/t1000", + "region":"South", + "versionId":"1", + "versionInfo":"https://storage.south.host.com/v1/", + "versionList":"https://storage.south.host.com/" + } + ] + }, + { + "name":"DNS-as-a-Service", + "type":"dnsextension:dns", + "endpoints":[{ + "tenantId":"t1000", + "publicURL":"https://dns.host.com/v2.0/t1000", + "versionId":"2.0", + "versionInfo":"https://dns.host.com/v2.0/", + "versionList":"https://dns.host.com/" + } + ] + } + ] + } + } + +Note the following about this response: + +#. There are two endpoints given to the Nova compute service. The only + difference between them is the version (1.0 vs. 1.1). This allows for code + written to look for the version 1.0 endpoint to still work even after the 1.1 + version is released. + +#. There are two endpoints for the Swift object-store service. The difference + between them is they are in different regions (North and South). + +#. Note the DNS service is global; it does not have a Region. Also, since DNS + is not a core OpenStack service, the endpoint type is "dnsextension:dns" + showing it is coming from an extension to the Keystone service. + +#. The Region, Tenant, and versionId are listed under the endpoint. You do not + (and should not) have to parse those out of the URL. In fact, they may not be + embedded in the URL if the service developer so chooses. + + +What do the fields in an Endpoint mean? +--------------------------------------- + +The schema definition for an endpoint is in endpoints.xsd under +keystone/content/common/xsd in the Keystone code repo. The fields are: + +id + A unique ID for the endpoint. + +type + The OpenStack-registered type (ex. 'compute', 'object-store', 'image service') + This can also be extended using the OpenStack Extension mechanism to support + non-core services. Extended services will be in the form ``extension:type`` + (e.g. ``dnsextension:dns``) + +name + This can be anything that the operator of OpenStack chooses. It could be a + brand or marketing name (ex. Rackspace Cloud Servers). + +region + This is a string that identifies the region where this endpoint exists. + Examples are 'North America', 'Europe', 'Asia'. Or 'North' and 'South'. Or + 'Data Center 1', 'Data Center 2'. + The list of regions and what a region means is decided by the operator. The + spec treats them as opaque strings. + +publicURL + This is the URL to use to access that endpoint over the internet. + +internalURL + This is the URL to use to communicate between services. This is genenrally + a way to communicate between services over a high bandwidth, low latency, + unmetered (free, no bandwidth charges) network. An example would be if you + want to access a swift cluster from inside your Nova VMs and want to make + sure the communication stays local and does not go over a public network + and rack up your bandwidth charges. + +adminURL + This is the URL to use to administer the service. In Keystone, this URL + is only shown to users with the appropriate rights. + +tenantId + If an endpoint is specific to a tenant, the tenantId field identifies the + tenant that URL applies to. Some operators include the tenant in the + URLs for a service, while others may provide one endpoint and use some + other mechanism to identify the tenant. This field is therefore optional. + Having this field also means you do not have to parse the URL to identify + a tenant if the operator includes it in the URL. + +versionId + This identifies the version of the API contract that endpoint supports. + While many APIs include the version in the URL (ex: https://compute.host/v1), + this field allows you to identify the version without parsing the URL. It + therefore also allows operators and service developers to publish endpoints + that do not have versions embedded in the URL. + +versionInfo + This is the URL to call to get some information on the version. This returns + information in this format:: + + { + "version": { + "id": "v2.0", + "status": "CURRENT", + "updated": "2011-01-21T11:33:21-06:00", + "links": [ + { + "rel": "self", + "href": "http://identity.api.openstack.org/v2.0/" + }, { + "rel": "describedby", + "type": "application/pdf", + "href": "http://docs.openstack.org/identity/api/v2.0/identity-latest.pdf" + }, { + "rel": "describedby", + "type": "application/vnd.sun.wadl+xml", + "href": "http://docs.openstack.org/identity/api/v2.0/identity.wadl" + } + ], + "media-types": [ + { + "base": "application/xml", + "type": "application/vnd.openstack.identity+xml;version=2.0" + }, { + "base": "application/json", + "type": "application/vnd.openstack.identity+json;version=2.0" + } + ] + } + } + +versionList + + This is the URL to call to find out which versions are supported at that + endpoint. The response is in this format:: + + { + "versions":[{ + "id":"v1.0", + "status":"DEPRECATED", + "updated":"2009-10-09T11:30:00Z", + "links":[{ + "rel":"self", + "href":"http://identity.api.openstack.org/v1.0/" + } + ] + }, + { + "id":"v1.1", + "status":"CURRENT", + "updated":"2010-12-12T18:30:02.25Z", + "links":[{ + "rel":"self", + "href":"http://identity.api.openstack.org/v1.1/" + } + ] + }, + { + "id":"v2.0", + "status":"BETA", + "updated":"2011-05-27T20:22:02.25Z", + "links":[{ + "rel":"self", + "href":"http://identity.api.openstack.org/v2.0/" + } + ] + } + ], + "versions_links":[] + } + + Here, the response shows that the endpoint supports version 1.0, 1.1, and 2.0. + It also shows that 1.0 is in DEPRECTAED status and 2.0 is in BETA. + +What are Endpoint Templates? +---------------------------- + +Endpoint Templates are a way for an administrator to manage endpoints en masse. +They provide a way to define Endpoints that apply to many or all tenants +without having to a create each endpoint on each tenant manually. Without +Endpoint Templates, if I wanted to create Endpoints for each tenant in my +OpenStack deployment, I'd have to manually create a bunch of endpoints on +each tenant (probably when I created the tenant). And then I'd have to go change +them all whenever a service changed versions or I added a new service. + +To provide a simpler mechanism to manage endpoints on tenants, Keystone uses +Endpoint Templates. I can, for example, define a template with parametrized URLs +and set it's `global` to true and that will show up as an endpoint on all the tenants +I have. Here is an example: + +Define a global Endpoint Template:: + + $ ./keystone-manage endpointTemplates add North nova https://compute.north.example.com/v1/%tenant_id%/ https://compute.north.example.corp/v1/ https://compute.north.example.local/v1/%tenant_id%/ 1 1 + + The arguments are: object_type action 'region' 'service_name' 'publicURL' 'adminURL' 'internalURL' 'enabled' 'global' + +This creates a global endpoint (global means it gets applied to all tenants automatically). + +Now, when a user authenticates, they get that endpoint in their service catalog. Here's an example +authentication request for use against tenant 1:: + + $ curl -H "Content-type: application/json" -d '{"auth":{"passwordCredentials":{"username":"joeuser","password":"secrete"}, "tenantId": "1"}}' http://localhost:5000/v2.0/tokens + +The response is:: + + { + "access": { + "serviceCatalog": [ + { + "endpoints": [ + { + "internalURL": "https://compute.north.example.local", + "publicURL": "https://compute.north.example.com/v1/1/", + "region": "North" + } + ], + "name": "nova", + "type": "compute" + } + ], + "token": { + "expires": "2012-02-05T00:00:00", + "id": "887665443383838", + "tenant": { + "id": "1", + "name": "customer-x" + } + }, + "user": { + "id": "1", + "name": "joeuser", + "roles": [ + { + "id": "3", + "name": "Member", + "tenantId": "1" + } + ] + } + } + } + +Notice the adminURL is not showing (this user is a regular user and does not +have rights to see the adminURL) and the tenant ID has been substituted in the +URL:: + + "publicURL": "https://compute.north.example.com/v1/1/", + +This endpoint will show up for all tenants. The OpenStack administrator does +not need to create the endpoint manually. + +.. note:: Endpoint Templates are not part of the core Keystone API (but Endpoints are). + + +What parameters can I use in a Template URL +------------------------------------------- + +Currently the only parameterization available is %tenant_id% which gets +substituted by the Tenant ID. + + +Endpoint Template Types: Global or not +-------------------------------------- + +When the global flag is set to true on an Endpoint Template, it means it should +be available to all tenants. Whenever someone authenticates to a tenant, they +will see the Endpoint generated by that template. + +When the global flag is not set, the template only shows up when it is added to +a tenant manually. To add an endpoint to a tenant manually, you must create +the Endpoint and supply the Endpoint Template ID: + +Create the Endpoint Template:: + + $ ./keystone-manage endpointTemplates add West nova https://compute.west.example.com/v1/%tenant_id%/ https://compute.west.example.corp https://compute.west.example.local 1 0 + + Note the 0 at the end - this Endpoint Template is not global. So it will not show up for users authenticating. + +Find the Endpoint Template ID:: + + $ ./keystone-manage endpointTemplates list + + All EndpointTemplates + id service type region enabled is_global Public URL Admin URL + ------------------------------------------------------------------------------- + 15 nova compute North True True https://compute.north.example.com/v1/%tenant_id%/ https://compute.north.example.corp + 16 nova compute West True False https://compute.west.example.com/v1/%tenant_id%/ https://compute.west.example.corp + +Add the Endpoint to the tenant:: + + $ ./keystone-manage endpoint add customer-x 16 + +Now, when the user authenticates, they get the endpoint:: + + { + "internalURL": "https://compute.west.example.local", + "publicURL": "https://compute.west.example.com/v1/1/", + "region": "West" + } + +Who can see the AdminURL? +------------------------- + +Users who have the Keystone `Admin` or `Service Admin` roles will see the +AdminURL when they authenticate or when they retrieve token information: + +Using an administrator token to authenticate, GET a client token's endpoints:: + + $ curl -H "X-Auth-Token: 999888777666" http://localhost:35357/v2.0/tokens/887665443383838/endpoints + + { + "endpoints": [ + { + "adminURL": "https://compute.west.example.corp", + "id": 6, + "internalURL": "https://compute.west.example.local", + "name": "nova", + "publicURL": "https://compute.west.example.com/v1/1/", + "region": "West", + "tenantId": 1, + "type": "compute" + } + ], + "endpoints_links": [ + { + "href": "http://127.0.0.1:35357/tokens/887665443383838/endpoints?marker=6&limit=10", + "rel": "next" + } + ] + } diff --git a/docs/source/old/extensions.rst b/docs/source/old/extensions.rst new file mode 100644 index 00000000..539bef39 --- /dev/null +++ b/docs/source/old/extensions.rst @@ -0,0 +1,183 @@ +.. + Copyright 2011 OpenStack, LLC + All Rights Reserved. + + Licensed under the Apache License, Version 2.0 (the "License"); you may + not use this file except in compliance with the License. You may obtain + a copy of the License at + + http://www.apache.org/licenses/LICENSE-2.0 + + Unless required by applicable law or agreed to in writing, software + distributed under the License is distributed on an "AS IS" BASIS, WITHOUT + WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the + License for the specific language governing permissions and limitations + under the License. + +========== +Extensions +========== + +Extensions support adding features and functions to OpenStack APIs at any time, without prior +approval or waiting for a new API and release cycles. + +The extension framework is in development and documented in extensions_ and extensionspresentation_. + +This document describes the extensions included with Keystone, how to enable and disable them, +and briefly touches on how to write your own extensions. + +.. _extensions: http://docs.openstack.org/trunk/openstack-compute/developer/openstack-api-extensions/content/ch02s01.html +.. _extensionspresentation: http://www.slideshare.net/RackerWilliams/openstack-extensions + +Built-in Extensions +------------------- + +Keystone ships with a number of extensions found under the +``keystone/contib/extensions`` folder. + +The following built-in extensions are included: + +OS-KSADM + + This is an extensions that supports managing users, tenants, and roles + through the API. Without this extensions, the ony way to manage those + objects is through keystone-manage or directly in the underlying database. + + This is an Admin API extension only. + +OS-KSCATALOG + + This extensions supports managing Endpoints and prrovides the Endpoint + Template mechanism for managing bulk endpoints. + + This is an Admin API extension only. + +OS-EC2 + + This extension adds support for EC2 credentials. + + This is an Admin and Service API extension. + +RAX-GRP + + This extension adds functionality the enables groups. + + This is an Admin and Service API extension. + +RAX-KEY + + This extensions adds support for authentication with an API Key (the core + Keystone API only supports username/password credentials) + + This is an Admin and Service API extension. + +HP-IDM + + This extension adds capability to filter roles with optional service IDs + for token validation to mitigate security risks with role name conflicts. + See https://bugs.launchpad.net/keystone/+bug/890411 for more details. + + This is an Admin API extension. Applicable to validate token (GET) + and check token (HEAD) APIs only. + +OS-KSVALIDATE + + This extensions supports admin calls to /tokens without having to specify + the token ID in the URL. Instead, the ID is supplied in a header called + X-Subject-Token. This is provided as an alternative to address any security + concerns that arise when token IDs are passed as part of the URL which is + often (and by default) logged to insecure media. + + This is an Admin API extension only. + +.. note:: + + The included extensions are in the process of being rewritten. Currently + osksadm, oskscatalog, hpidm, and osksvalidate work with this new + extensions design. + + +Enabling & Disabling Extensions +------------------------------- + +The Keystone conf file has a property called extensions. This property holds +the list of supported extensions that you want enabled. If you want to +add/remove an extension from being supported, add/remove the extension key +from this property. The key is the name of the folder of the extension +under the keystone/contrib/extensions folder. + +.. note:: + + If you want to load different extensions in the service API than the Admin API + you need to use different config files. + +Creating New Extensions +----------------------- + +#. **Adopt a unique organization abbreviation.** + + This prefix should uniquely identify your organization within the community. + The goal is to avoid schema and resource collisions with similiar extensions. + (e.g. ``OS`` for OpenStack, ``RAX`` for Rackspace, or ``HP`` for Hewlett-Packard) + +#. **Adopt a unique extension abbreviation.** + + Select an abbreviation to identify your extension, and append to + your organization prefix using a hyphen (``-``), by convention + (e.g. ``OS-KSADM`` (for OpenStack's Keystone Administration extension). + + This combination is referred to as your extension's prefix. + +#. **Determine the scope of your extension.** + + Extensions can enhance the Admin API, Service API or both. + +#. **Create a new module.** + + Create a module to isolate your namespace based on the extension prefix + you selected:: + + keystone/contrib/extensions/admin + + ... and/or:: + + keystone/contrib/extensions/service/ + + ... based on which API you are enhancing. + + .. note:: + + In the future, we will support loading external extensions. + +#. Add static extension files for JSON (``*.json``) and XML + (``*.xml``) to the new extension module. + + Refer to `Service Guide `_ + `Sample extension XML `_ + `Sample extension JSON `_ for the the content and structure. + +#. If your extension is adding additional methods override the base class + ``BaseExtensionHandler``, name it ``ExtensionHandler``, and add your methods. + +#. **Document your work.** + + Provide documentation to support your extension. + + Extensions documentation, WADL, and XSD files can be stored in the + ``keystone/content`` folder. + +#. Add your extension name to the list of supported extensions in The + ``keystone.conf`` file. + +Which extensions are enabled? +----------------------------- + +Discover which extensions are available (service API):: + + curl http://localhost:5000/v2.0/extensions + +... or (admin API):: + + curl http://localhost:35357/v2.0/extensions + +The response will list the extensions available. diff --git a/docs/source/old/middleware.rst b/docs/source/old/middleware.rst new file mode 100644 index 00000000..69506ee2 --- /dev/null +++ b/docs/source/old/middleware.rst @@ -0,0 +1,169 @@ +.. + Copyright 2011 OpenStack, LLC + All Rights Reserved. + + Licensed under the Apache License, Version 2.0 (the "License"); you may + not use this file except in compliance with the License. You may obtain + a copy of the License at + + http://www.apache.org/licenses/LICENSE-2.0 + + Unless required by applicable law or agreed to in writing, software + distributed under the License is distributed on an "AS IS" BASIS, WITHOUT + WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the + License for the specific language governing permissions and limitations + under the License. + +========== +Middleware +========== + +The Keystone middleware sits in front of an OpenStack service and handles authenticating +incoming requests. The middleware was designed according to `this spec`. + +The middleware is found in source under Keystone/middleware. + +The middleware supports two interfaces; WSGI and REST/HTTP. + +.. _`this spec`: http://wiki.openstack.org/openstack-authn + +REST & HTTP API +=============== + +If an unauthenticated call comes in, the middleware will respond with a 401 Unauthorized error. As per +HTTP standards, it will also return a WWW-Authenticate header informing the caller +of what protocols are supported. For Keystone authentication, the response syntax will be:: + + WWW-Authenticate: Keystone uri="url to Keystone server" + +The client can then make the necessary calls to the Keystone server, obtain a token, and retry the call with the token. + +The token is passed in using ther X-Auth-Token header. + +WSGI API (Headers) +================== + +Upon successful authentication the middleware sends the following +headers to the downstream WSGI app: + +X-Identity-Status + Provides information on whether the request was authenticated or not. + +X-Tenant + Provides the tenant ID (as it appears in the URL in Keystone). This is to support any legacy implementations before Keystone switched to an ID/Name schema for tenants. + +X-Tenant-Id + The unique, immutable tenant Id + +X-Tenant-Name + The unique, but mutable (it can change) tenant name. + +X-User-Id + The user id of the user used to log in + +X-User-Name + The username used to log in + +X-User + The username used to log in. This is to support any legacy implementations before Keystone switched to an ID/Name schema for tenants. + +X-Roles + The roles associated with that user + + +Configuration +============= + +The middleware is configured within the config file of the main application as +a WSGI component. Example for the auth_token middleware:: + + [app:myService] + paste.app_factory = myService:app_factory + + [pipeline:main] + pipeline = + tokenauth + myService + + [filter:tokenauth] + paste.filter_factory = keystone.middleware.auth_token:filter_factory + auth_host = 127.0.0.1 + auth_port = 35357 + auth_protocol = http + auth_uri = http://127.0.0.1:5000/ + admin_token = 999888777666 + ;Uncomment next line and check ip:port to use memcached to cache token requests + ;memcache_hosts = 127.0.0.1:11211 + +*The required configuration entries are:* + +auth_host + The IP address or DNS name of the Keystone server + +auth_port + The TCP/IP port of the Keystone server + +auth_protocol + The protocol of the Keystone server ('http' or 'https') + +auth_uri + The externally accessible URL of the Keystone server. This will be where unauthenticated + clients are redirected to. This is in the form of a URL. For example, if they make an + unauthenticated call, they get this response:: + + HTTP/1.1 401 Unauthorized + Www-Authenticate: Keystone uri='https://auth.example.com/' + Content-Length: 381 + + In this case, the auth_uri setting is set to https://auth.example.com/ + +admin_token + This is the long-lived token issued to the service to authenticate itself when calling + Keystone. See :doc:`configuration` for more information on setting this up. + + +*Optional parameters are:* + +delay_auth_decision + Whether the middleware should reject invalid or unauthenticated calls directly or not. If not, + it will send all calls down to the service to decide, but it will set the HTTP-X-IDENTITY-STATUS + header appropriately (set to'Confirmed' or 'Indeterminate' based on validation) and the + service can then decide if it wants to honor the call or not. This is useful if the service offers + some resources publicly, for example. + +auth_timeout + The amount of time to wait before timing out a call to Keystone (in seconds) + +memcache_hosts + This is used to point to a memcached server (in ip:port format). If supplied, + the middleware will cache tokens and data retrieved from Keystone in memcached + to minimize calls made to Keystone and optimize performance. + +.. warning:: + Tokens are cached for the duration of their validity. If they are revoked eariler in Keystone, + the service will not know and will continue to honor the token as it has them stored in memcached. + Also note that tokens and data stored in memcached are not encrypted. The memcached server must + be trusted and on a secure network. + + +*Parameters needed in a distributed topology.* In this configuration, the middleware is running +on a separate machine or cluster than the protected service (not common - see :doc:`middleware_architecture` +for details on different deployment topologies): + +service_host + The IP address or DNS name of the location of the service (since it is remote + and not automatically down the WSGI chain) + +service_port + The TCP/IP port of the remote service. + +service_protocol + The protocol of the service ('http' or 'https') + +service_pass + The basic auth password used to authenticate to the service (so the service + knows the call is coming from a server that has validated the token and not from + an untrusted source or spoofer) + +service_timeout + The amount of time to wait for the service to respond before timing out. diff --git a/docs/source/old/middleware_architecture.rst b/docs/source/old/middleware_architecture.rst new file mode 100644 index 00000000..a8c38f3c --- /dev/null +++ b/docs/source/old/middleware_architecture.rst @@ -0,0 +1,529 @@ +.. + Copyright 2011 OpenStack, LLC + All Rights Reserved. + + Licensed under the Apache License, Version 2.0 (the "License"); you may + not use this file except in compliance with the License. You may obtain + a copy of the License at + + http://www.apache.org/licenses/LICENSE-2.0 + + Unless required by applicable law or agreed to in writing, software + distributed under the License is distributed on an "AS IS" BASIS, WITHOUT + WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the + License for the specific language governing permissions and limitations + under the License. + +======================= +Middleware Architecture +======================= + +Abstract +======== + +The Keystone middleware architecture supports multiple authentication protocols +in a pluggable manner in OpenStack. By providing support for authentication via +pluggable authentication components, this architecture allows OpenStack +services to be integrated easily into existing deployment environments. It also +provides a path by which to implement support for emerging authentication +standards such as OAUTH. + +Rationale and Goals +=================== + +Keystone is the Identity service for OpenStack. To support the easy integrating +of OpenStack with existing authentication and identity management systems, +Keystone supports talking to multiple backends like LDAP. +And to support different deployment needs, it can support multiple +authentication protocols via pluggable 'authentication components' implemented +as WSGI middleware. + +In this document, we describe the responsibilities of the authentication +middleware. We describe how these interact with underlying OpenStack services +and how existing services can be modified to take advantage of pluggable +authentication. The goal is to allow OpenStack services to be integrated easily +into existing deployment environments and to provide a path by which to +implement support for emerging authentication standards such as OAUTH. + +Specification Overview +====================== + +'Authentication' is the process of determining that users are who they say they +are. Typically, 'authentication protocols' such as HTTP Basic Auth, Digest +Access, public key, token, etc, are used to verify a user's identity. In this +document, we define an ''authentication component'' as a software module that +implements an authentication protocol for an OpenStack service. + +At a high level, an authentication component is simply a reverse proxy that +intercepts HTTP calls from clients. Once it has verified a user's identity, the +authentication component extends the call with information about the current +user and forwards the request to the OpenStack service. Otherwise, if a user's +identity is not verified, the message is rejected before it gets to the +service. This is illustrated in :ref:`authComponent`. + +.. _authComponent: + +Authentication Component +------------------------ + +Figure 1. Authentication Component + +.. image:: images/graphs_authComp.svg + :width: 100% + :height: 180 + :alt: An Authentication Component + +Authentication components may operate in 'delegated mode'. In this mode, the +decision reject an unauthenticated client is delegated to the OpenStack +service. Delegated mode is illustrated in :ref:`authComponentDelegated`. + +Here, requests are forwarded to the OpenStack service with an identity status +message that indicates whether the client's identity has been confirmed or is +indeterminate. It is the OpenStack service that decides whether or not a reject +message should be sent to the client. Note that it is always the responsibility +of the Authentication Component to transmit reject messages to the client. + +.. _authComponentDelegated: + +Authentication Component (Delegated Mode) +----------------------------------------- + +Figure 2. Authentication Component (Delegated Mode) + +.. image:: images/graphs_authCompDelegate.svg + :width: 100% + :height: 180 + :alt: An Authentication Component (Delegated Mode) + +In this architecture, we define interactions between the authentication component +and the OpenStack service. Interactions between the client and the +authentication component are defined only for exceptional cases. For example, +we define the message that should be returned when the OpenStack service is +down. Other interactions, however, are defined by the underlying authentication +protocol and the OpenStack service and are considered out of scope. + +.. _deployStrategies: + +Deployment Strategies +===================== + +An authentication component may be integrated directly into the service +implementation, or it may be deployed separately as an HTTP reverse proxy. This +is illustrated in :ref:`deployment`, showing both approaches to +authentication, labeled Option (a) and Option (b). + +.. _deployment: + +Authentication Component Deployments Options +-------------------------------------------- + +Figure 3. Authentication Component Deployments Options + +.. image:: images/images_layouts.svg + :width: 100% + :height: 180 + :alt: Authentication Component Deployments Options + +In Option (a), the component is integrated into the service implementation. In +this case, communication between the authentication component and the service +can be efficiently implemented via a method call. In Option (b), the component +is deployed separately and communication between the service and the component +involves an HTTP request. In both cases, unauthenticated requests are filtered +before they reach the service. + +Each approach offers some benefits. Option (a) offers low latency and ease of +initial implementation, making it possibly most appropriate as a starting point +for simple configurations. Option (b) offers several key advantages that may be +of particular value in complex and dynamic configurations. It offers the +ability to scale horizontally in cases where authentication is computationally +expensive, such as when verifying digital signatures. Option (b) also allows +authentication components to be written in different programming languages. +Finally, Option (b) allows multiple authentication components to be deployed in +front of the same service. + +OpenStack services can support both embedded (Option (a)) and external (Option +(b)) deployment strategies. Individual authentication components should support +either strategy or they |may| support both strategies. In order to support +option (a), authentication components written in the Python programming +language should be written as WSGI middleware components (in accordance with +the Web Server Gateway Interface (WSGI) standard [PEP-333]_. + +Additionally, services should support the ability to swap between different +embedded or external authentication components via configuration options. + +Exchanging User Information +=========================== + +If a request is successfully authenticated, the authentication component must +extend the request by adding an ``X-Authorization`` header. The header |must| +be formatted as illustrated in :ref:`xAuthHeader`. + +.. _xAuthHeader: + +X-Authorization Header +---------------------- + +Example 1. X-Authorization Header:: + + X-Authorization: Proxy JoeUser + +Here, `Proxy` denotes that the authentication occurred via a proxy (in this +case authentication component) and ''JoeUser'' is the name of the user who +issued the request. + +.. note: + + We considered using an ``Authorization`` header rather than an + ``X-Authorization``, thereby following normal HTTP semantics. There are some + cases, however, where multiple ``Authorization`` headers need to be transmitted + in a single request. We want to assure ourselves that this will not break + common clients before we recommend the approach. + +Authentication components |may| extend the request with additional +information. For example, an authentication system may add additional headers +or modify the target URI to pass authentication information to the back-end +service. Additionally, an authentication component |may| strip sensitive +information — a plain text password, for example — from the request. That said, +an authentication component |should| pass the majority of the request +unmodified. + +Reverse Proxy Authentication +---------------------------- + +An OpenStack service |should| verify that it is receiving requests from a +trusted authentication component. This is particularly important in cases where +the authentication component and the OpenStack service are deployed separately. +In order to trust incoming requests, the OpenStack service should therefore +authenticate the authentication component. To avoid confusion, we call this +'reverse proxy authentication', since in this case the authentication +component is acting as an HTTP reverse proxy. + +Any HTTP-based authentication scheme may be used for reverse proxy +authentication; however, all OpenStack services and all authentication +components |must| support HTTP Basic Authentication as defined in +[RFC-2617]_. + +Whether or not reverse proxy authentication is required is strictly a +deployment concern. For example, an operations team may opt to utilize firewall +rules instead of an authentication protocol to verify the integrity of incoming +request. Because of this, both OpenStack services and authentication components +|must| also allow for unauthenticated communication. + +In cases where reverse proxy authentication is used, the authorization +component may receive an HTTP 401 authentication error or an HTTP 403 +authorization error. These errors indicate that the component does not have +access to the underlying OpenStack service. The authentication component +|must not| return these errors to the client application. Instead, the +component |must| return a 500 internal error. This is illustrated in +:ref:`proxyAuth` and :ref:`proxyAuthDelegated` below. The component +|should| format the errors in a manner that does not break the service +contract defined by the OpenStack service. :ref:`proxyAuthDelegated` +illustrates proxy authorization in delegated mode. Delegated mode is discussed +in detail in the next section. + +.. _proxyAuth: + +Reverse Proxy Authentication +---------------------------- + +Figure 4. Reverse Proxy Authentication + +.. image:: images/graphs_proxyAuth.svg + :width: 100% + :height: 180 + :alt: Reverse Proxy Authentication + +.. _proxyAuthDelegated: + +Reverse Proxy Authentication (Delegated Mode) +--------------------------------------------- + +Figure 5. Reverse Proxy Authentication (Delegated Mode) + +.. image:: images/graphs_delegate_forbiden_proxy.svg + :width: 100% + :height: 180 + :alt: Reverse Proxy Authentication (Delegated Mode) + +Delegated Mode +============== +In some cases, the decision to reject an unauthenticated request should be +delegated to the OpenStack service. An unauthenticated request may be +appropriate in cases when anonymous access is allowed. In order to support +these cases, an authentication component may be placed in Delegated Mode. In +this mode, the component forwards requests to the OpenStack service when the +client's identity has been confirmed or is indeterminate — that is when +credentials are missing. The authentication component directly rejects requests +with invalid credentials. Authentication components |must| extend the +request by adding an `X-Identity-Status` header. The identity status header +|must| contain one of the following values: + +Identity Status Values +---------------------- + +Confirmed + A `confirmed` value indicates that valid credentials were sent and identity + has been confirmed. The service can trust that the request has been sent on + behalf of the user specified in the `X-Authorization` header. + +Indeterminate + An `indeterminate` value indicates that no credentials were sent and + identity has not been confirmed. In this case, the service will receive an + `X-Authorization` header with no user entry as illustrated in + :ref:`xauth-header-indeterminate`. + +.. _xauth-header-indeterminate: + +Indeterminate Identity Headers +------------------------------ + +Example 2. Indeterminate Identity Headers:: + + X-Identity-Status: Indeterminate + X-Authorization: Proxy + +Services |may| reject a delegated request by issuing an HTTP 401 +authentication error or an HTTP 403 authorization error. These responses +|must| contain an ``WWW-Authenticate`` header with a value of ``Delegated`` as +illustrated in :ref:`unauthHeaders`. + +X-Identity-Status + Provides information on whether the request was authenticated or not. + +X-Tenant + Provides the tenant ID (as it appears in the URL in Keystone). This is to support any legacy implementations before Keystone switched to an ID/Name schema for tenants. + +X-Tenant-Id + The unique, immutable tenant Id + +X-Tenant-Name + The unique, but mutable (it can change) tenant name. + +X-User-Id + The user id of the user used to log in + +X-User-Name + The username used to log in + +X-User + The username used to log in. This is to support any legacy implementations before Keystone switched to an ID/Name schema for tenants. + +X-Roles + The roles associated with that user + +.. _unauthHeaders: + +Delegated WWW-Authenticate Header +--------------------------------- + +:: + + WWW-Authenticate: Delegated + +It is important to note that the actual reject message will likely be modified +by the authentication component in order to comply with the authentication +scheme it is implementing. This is illustrated in :ref:`delegateRejectBasic` and +:ref:`delegateRejectOAuth` below. + +.. _delegateRejectBasic: + +Delegated Reject Basic Auth +--------------------------- + +.. image:: images/graphs_delegate_reject_basic.svg + :width: 100% + :height: 180 + :alt: Delegated Reject Basic Auth + +.. _delegateRejectOAuth: + +Delegated Reject OAuth +---------------------- + +.. image:: images/graphs_delegate_reject_oauth.svg + :width: 100% + :height: 180 + :alt: Delegated Reject OAuth + +The presence of the `WWW-Authenticate` header with a value of `Delegated` +distinguishes a client authentication/authorization failure from a component +failure. For example, compare :ref:`delegateForbidden` with :ref:`proxyAuthDelegated`. In +:ref:`delegateForbidden`, the client is not allowed to access the OpenStack service. +In :ref:`proxyAuthDelegated`, it is the authentication component itself which is +unauthorized. + +.. _delegateForbidden: + +Delegated Reject Forbidden +-------------------------- + +Figure 8. Delegated Reject Forbidden + +.. image:: images/graphs_delegate_forbiden_basic.svg + :width: 100% + :height: 180 + :alt: Delegated Reject Forbidden + +Authentication components |must| support both delegated and undelegated +(standard) modes. Delegated mode |should| be configured via a configuration +option. Delegated mode |should| be disabled by default. + +OpenStack services are not required to support delegated mode. If a service +does not support delegated mode, it |must| respond with a 501 not implemented +error and an `WWW-Authenticate` header with a value of `Delegated`. The +authentication component |must not| return the error to the client +application. Instead, the component |must| return a 500 internal error; this is +illustrated in :ref:`delegateUnimplemented`. The component |should| +format the error in a manner that does not break the service contract defined +by the OpenStack service. The component should also log the error such that it +that will inform operators of the misconfiguration. + +.. _delegateUnimplemented: + +Unimplemented Delegated Mode +---------------------------- + +.. image:: images/graphs_delegate_unimplemented.svg + :width: 100% + :height: 180 + :alt: Unimplemented Delegated Mode + +Handling Direct Client Connections +================================== + +Requests from the authentication component to an OpenStack service |must| +contain an ``X-Authorization`` header. If the header is missing, and reverse +proxy authentication fails or is switched off, the OpenStack service |may| +assume that the request is coming directly from a client application. In this +case, the OpenStack service |must| redirect the request to the authentication +component by issuing an HTTP 305 User Proxy redirect. This is illustrated in +:ref:`redirect`. Note that the redirect response |must| include a ``Location`` header +specifying the authentication component's URL as shown in :ref:`redirect-response`. + +.. _redirect: + +Auth Component Redirect +----------------------- + +.. image:: images/graphs_305.svg + :width: 100% + :height: 280 + :alt: Auth Component Redirect + +.. _redirect-response: + +Auth Component Redirect Response +-------------------------------- + +:: + + HTTP/1.1 305 Use Proxy + Date: Thu, 28 Oct 2011 07:41:16 GMT + Location: http://sample.auth.openstack.com/path/to/resource + +Using Multiple Authentication Components +======================================== + +There are some use cases when a service provider might want to consider using +multiple authentication components for different purposes. For instance, a +service provider may have one authentication scheme to authenticate the users +of the service and another one to authenticate the administrators or operations +personnel that maintain the service. For such scenarios, we propose using a +mapper as illustrated in :ref:`multiAuth`. + +.. _multiAuth: + +Multiple Authentication Components +---------------------------------- + +.. image:: images/graphs_mapper.svg + :width: 100% + :height: 320 + :alt: Multiple Authentication Components + +At a high level, a mapper is a simple reverse proxy that intercepts HTTP calls +from clients and routes the request to the appropriate authentication +component. A mapper can make the routing decisions based on a number of routing +rules that map a resource to a specific authentication component. For example, +a request URI may determine whether a call should be authenticated via one +authentication component or another. + +Note that neither the authentication component nor the OpenStack service need +be aware of the mapper. Any external authentication component can be used +alongside others. Mappers may provide a means by which to offer support for +anonymous or guest access to a subset of service resources. A mapper may be +implemented via a traditional reverse proxy server such as Pound or Zeus. + +The Default Component +===================== + +Individual services |must| be distributed with a simple integrated +authentication component by default. Providing such a component lowers barriers +to the deployment of individual services. This is especially important to] +developers who may want to deploy OpenStack services on their own machines. +Also, since there is no direct dependency on an external authentication system, +OpenStack services can be deployed individually, without the need to stand up +and configure additional services. Finally, having a standard authentication +component that all services share promotes a separation of concerns. That is, +as a community we are explicitly stating that services should not develop their +own authentication mechanisms. Additional authentication components may be +developed, of course, but these components should not be intimately coupled to +any one particular service. + +As discussed in :ref:`deployStrategies`, an authentication component may be +integrated directly into the service implementation (Option (a)), or it may be +deployed separately as an HTTP reverse proxy (Option (b)). The default +component should be implemented to support Option (a) and services should +maintain support for Option (b). One way to achieve this is to provide a +method that allows the disabling of the default authentication component via +configuration. This is illustrated in :ref:`both`. Here, requests are +sent directly to the OpenStack service when the default authentication +component is disabled. + +We will discuss the design of the default component in an upcoming blueprint. + +.. _both: + +Disabled Embedded Component +--------------------------- + +.. image:: images/graphs_both.svg + :width: 100% + :height: 250 + :alt: Disabled Embedded Component + +Questions and Answers +===================== + +#. Why do authentication components send reject messages? Why not have + OpenStack services reject requests themselves? + + The content and format of an authentication failed message is determined by + the authentication scheme (or protocol). For the service to respond + appropriately, it would have to be aware of the authentication scheme in + which it participates; this defeats the purpose of pluggable authentication + components. + +#. Why require support for deploying authentication components in separate + nodes? + + The deployment strategy is very flexible. It allows for authentication + components to be horizontally scalable. It allows for components to be written + in different languages. Finally, it allows different authentication components + to be deployed simultaneously as described above. + +References +========== + +.. [PEP-333] pep0333 Phillip J Eby. 'Python Web Server Gateway Interface + v1.0.'' http://www.python.org/dev/peps/pep-0333/. + +.. [RFC-2617] rfc2617 J Franks. P Hallam-Baker. J Hostetler. S Lawrence. + P Leach. A Luotonen. L Stewart. ''HTTP Authentication: Basic and Digest + Access Authentication.'' http://tools.ietf.org/html/rfc2617. + +.. |must| replace:: must must +.. |should| replace:: should should +.. |may| replace:: may may +.. |must not| replace:: "must not" "must not" + diff --git a/docs/source/old/migration.rst b/docs/source/old/migration.rst new file mode 100644 index 00000000..460d980b --- /dev/null +++ b/docs/source/old/migration.rst @@ -0,0 +1,126 @@ +=================== +Database Migrations +=================== + +Keystone uses SQLAlchemy Migrate (``sqlalchemy-migrate``) to manage +migrations. + +Migrations are tracked using a metadata table (``migrate_version``), which +allows keystone to compare the state of your database to the state it +expects, and to move between versions. + +.. WARNING:: + + Backup your database before applying migrations. Migrations may + attempt to modify both your schema and data, and could result in data + loss. + + Always review the behavior of migrations in a staging environment + before applying them in production. + +Getting Started +=============== + +Your initial approach to migrations should depend on whether you have an +empty database or a schema full of data. + +Starting with an empty database +------------------------------- + +If you have an empty database for keystone to work with, you can simply +run:: + + $ ./bin/keystone-manage database sync + +This command will initialize your metadata table, and run through all the +schema & data migrations necessary to bring your database in sync with +keystone. That's it! + +Starting with an existing database +---------------------------------- + +Place an existing database under version control to enable migration +support:: + + $ ./bin/keystone-manage database version_control + +This command simply creates a ``migrate_version`` table, set at +``version_number`` 0, which indicates that no migrations have been applied. + +If you are starting with an existing schema, you can jump to a specific +schema version without performing migrations using the ``database goto`` +command. For example, if you're starting from a diablo-compatible +database, set your current database ``version_number`` to ``1`` using:: + + $ ./bin/keystone-manage database goto + +Determine your appropriate database ``version_number`` by referencing the +following table: + + +------------+-------------+ + | Release | ``version`` | + +============+=============+ + | pre-diablo | (see below) | + +------------+-------------+ + | diablo | 1 | + +------------+-------------+ + | essex-m1 | 3 | + +------------+-------------+ + | essex-m2 | 4 | + +------------+-------------+ + +From there, you can upgrade normally (see :ref:`upgrading`). + +Starting with a pre-diablo database (cactus) +-------------------------------------------- + +You'll need to manually migrate your database to a diablo-compatible +schema, and continue forward from there (if desired) using migrations. + +.. _upgrading: + +Upgrading & Downgrading +======================= + +.. note:: + + Attempting to start keystone with an outdated schema will cause + keystone to abort, to avoid corrupting your data. + +Upgrade to the latest version automatically:: + + $ ./bin/keystone-manage database sync + +Check your current schema version:: + + $ ./bin/keystone-manage database version + +Jump to a specific version without performing migrations:: + + $ ./bin/keystone-manage database goto + +Upgrade to a specific version:: + + $ ./bin/keystone-manage database upgrade + +Downgrade to a specific version (will likely result in data loss!):: + + $ ./bin/keystone-manage database downgrade + +Opting Out of Migrations +======================== + +If you don't want to use migrations (e.g. if you want to manage your +schema manually), keystone will complain in your logs on startup, but +won't actually stop you from doing so. + +It's recommended that you use migrations to get up and running, but if +you want to manage migrations manually after that, simply drop the +``migrate_version`` table:: + + DROP TABLE migrate_version; + +Useful Links +============ + +Principles to follow when developing migrations `OpenStack Deployability `_ diff --git a/docs/source/old/nova-api-paste.rst b/docs/source/old/nova-api-paste.rst new file mode 100644 index 00000000..586bac72 --- /dev/null +++ b/docs/source/old/nova-api-paste.rst @@ -0,0 +1,142 @@ +.. + Copyright 2011 OpenStack, LLC + All Rights Reserved. + + Licensed under the Apache License, Version 2.0 (the "License"); you may + not use this file except in compliance with the License. You may obtain + a copy of the License at + + http://www.apache.org/licenses/LICENSE-2.0 + + Unless required by applicable law or agreed to in writing, software + distributed under the License is distributed on an "AS IS" BASIS, WITHOUT + WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the + License for the specific language governing permissions and limitations + under the License. + +nova-api-paste example +====================== +:: + + ####### + # EC2 # + ####### + + [composite:ec2] + use = egg:Paste#urlmap + /: ec2versions + /services/Cloud: ec2cloud + /services/Admin: ec2admin + /latest: ec2metadata + /2007-01-19: ec2metadata + /2007-03-01: ec2metadata + /2007-08-29: ec2metadata + /2007-10-10: ec2metadata + /2007-12-15: ec2metadata + /2008-02-01: ec2metadata + /2008-09-01: ec2metadata + /2009-04-04: ec2metadata + /1.0: ec2metadata + + [pipeline:ec2cloud] + pipeline = logrequest totoken authtoken keystonecontext cloudrequest authorizer ec2executor + + [pipeline:ec2admin] + pipeline = logrequest totoken authtoken keystonecontext adminrequest authorizer ec2executor + + [pipeline:ec2metadata] + pipeline = logrequest ec2md + + [pipeline:ec2versions] + pipeline = logrequest ec2ver + + [filter:logrequest] + paste.filter_factory = nova.api.ec2:RequestLogging.factory + + [filter:ec2lockout] + paste.filter_factory = nova.api.ec2:Lockout.factory + + [filter:totoken] + paste.filter_factory = keystone.middleware.ec2_token:EC2Token.factory + + [filter:ec2noauth] + paste.filter_factory = nova.api.ec2:NoAuth.factory + + [filter:authenticate] + paste.filter_factory = nova.api.ec2:Authenticate.factory + + [filter:cloudrequest] + controller = nova.api.ec2.cloud.CloudController + paste.filter_factory = nova.api.ec2:Requestify.factory + + [filter:adminrequest] + controller = nova.api.ec2.admin.AdminController + paste.filter_factory = nova.api.ec2:Requestify.factory + + [filter:authorizer] + paste.filter_factory = nova.api.ec2:Authorizer.factory + + [app:ec2executor] + paste.app_factory = nova.api.ec2:Executor.factory + + [app:ec2ver] + paste.app_factory = nova.api.ec2:Versions.factory + + [app:ec2md] + paste.app_factory = nova.api.ec2.metadatarequesthandler:MetadataRequestHandler.factory + + ############# + # Openstack # + ############# + + [composite:osapi] + use = egg:Paste#urlmap + /: osversions + /v1.1: openstackapi + + [pipeline:openstackapi] + pipeline = faultwrap authtoken keystonecontext ratelimit extensions osapiapp + + [filter:faultwrap] + paste.filter_factory = nova.api.openstack:FaultWrapper.factory + + [filter:auth] + paste.filter_factory = nova.api.openstack.auth:AuthMiddleware.factory + + [filter:noauth] + paste.filter_factory = nova.api.openstack.auth:NoAuthMiddleware.factory + + [filter:ratelimit] + paste.filter_factory = nova.api.openstack.limits:RateLimitingMiddleware.factory + + [filter:extensions] + paste.filter_factory = nova.api.openstack.extensions:ExtensionMiddleware.factory + + [app:osapiapp] + paste.app_factory = nova.api.openstack:APIRouter.factory + + [pipeline:osversions] + pipeline = faultwrap osversionapp + + [app:osversionapp] + paste.app_factory = nova.api.openstack.versions:Versions.factory + + ########## + # Shared # + ########## + + [filter:keystonecontext] + paste.filter_factory = keystone.middleware.nova_keystone_context:NovaKeystoneContext.factory + + [filter:authtoken] + paste.filter_factory = keystone.middleware.auth_token:filter_factory + service_protocol = http + service_host = 127.0.0.1 + service_port = 5000 + auth_host = 127.0.0.1 + auth_port = 35357 + auth_protocol = http + auth_uri = http://127.0.0.1:5000/ + admin_token = 999888777666 + ;Uncomment next line and check ip:port to use memcached to cache token requests + ;memcache_hosts = 127.0.0.1:11211 diff --git a/docs/source/old/releases.rst b/docs/source/old/releases.rst new file mode 100644 index 00000000..a4b698d7 --- /dev/null +++ b/docs/source/old/releases.rst @@ -0,0 +1,36 @@ +============= +Release notes +============= + + +E3 (January 26, 2012) +========================================== +* Contract compliance: version response and ATOM, 300 multiple choice +* Global endpoints returned for unscoped calls +* adminUrl only shown to admin clients +* Endpoints have unique ID +* Auth-N/Auth-Z for S3 API (OS-KSS3 extension) +* Default tenant scope optionally returned when authenticating +* Vary header returned for caching proxies + +* Portable identifiers: modifiable, string identifiers in database backend +* Much improved keystone-manage command (see --help and docs) +* OS-KSVALIDATE extension to support not passing tokens in URL +* OS-KSEC2 and OS-KSS3 extensions respond on /tokens +* HP-IDM extension to filter roles to a given service ID +* Additional caching options in middleware (memcache and swift cache) + +* Enhanced configuration management (in line with other OpenStack projects) +* Additional logging +* Enhanced tracer tool (-t or --trace-calls) + +See comprehensive list here https://launchpad.net/keystone/+milestone/essex-3 + + +E2 (December 15, 2011) +======================== +* D5 compatibility middleware +* Database versioning +* Much more documentation: http://keystone.openstack.org + +See https://launchpad.net/keystone/+milestone/essex-2 diff --git a/docs/source/old/services.rst b/docs/source/old/services.rst new file mode 100644 index 00000000..d1c33381 --- /dev/null +++ b/docs/source/old/services.rst @@ -0,0 +1,92 @@ +.. + Copyright 2011 OpenStack, LLC + All Rights Reserved. + + Licensed under the Apache License, Version 2.0 (the "License"); you may + not use this file except in compliance with the License. You may obtain + a copy of the License at + + http://www.apache.org/licenses/LICENSE-2.0 + + Unless required by applicable law or agreed to in writing, software + distributed under the License is distributed on an "AS IS" BASIS, WITHOUT + WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the + License for the specific language governing permissions and limitations + under the License. + +================ +Services +================ + +.. toctree:: + :maxdepth: 1 + + +What are services? +================== + +Keystone includes service registry and service catalog functionality which it +uses to respond to client authentication requests with information useful to +clients in locating the list of available services they can access. + +The Service entity in Keystone represents an OpenStack service that is integrated +with Keystone. The Service entity is also used as a reference from roles, endpoints, +and endpoint templates. + +Keystone also includes an authorization mechanism to allow a service to own +its own roles and endpoints and prevent other services from changing or +modifying them. + +Who can create services? +======================== + +Any user with the Admin or Service Admin roles in Keystone may create services. + +How are services created? +========================= + +Services can be created using ``keystone-manage`` or through the REST API using +the OS-KSADM extension calls. + +Using ``keystone-manage`` (see :doc:`man/keystone-manage` for details):: + + $ keystone-manage add service compute nova 'This is a sample compute service' + +Using the REST API (see `extensions dev guide `_ for details):: + + $ curl -H "Content-type: application/json" -X POST -d '{ + "OS-KSADM:service": { + "name": "nova", + "type": "compute", + "description": "This is a sample compute service" + } + }' -H "X-Auth-Token: 999888777666" http://localhost:35357/v2.0/OS-KSADM/services/ + +How is service ownership determined? +==================================== + +Currently, the way to assign ownership to a service is to provide the owner's +user id in the keystone-manage add command:: + + $ keystone-manage add service nova compute 'This is a sample compute service' joeuser + +This will assign ownership to the new service to joeuser. + +When a service has an owner, then only that owner (or a global Admin) can create and manage +roles that start with that service name (ex: "nova:admin") and manage endpoints +and endpoint templates associated with that service. + +Listing services +================ + +Using ``keystone-manage``, the list of services and their owners can be listed:: + + $ keystone-manage service list + + id name type owner_id description + ------------------------------------------------------------------------------- + 1 compute nova joeuser This is a sample compute service + +Using the REST API, call ``GET /v2.0/OS-KSADM/services`` + +.. note: The rest API does not yet support service ownership diff --git a/docs/source/old/ssl.rst b/docs/source/old/ssl.rst new file mode 100644 index 00000000..839e951e --- /dev/null +++ b/docs/source/old/ssl.rst @@ -0,0 +1,118 @@ +.. + Copyright 2011 OpenStack, LLC + All Rights Reserved. + + Licensed under the Apache License, Version 2.0 (the "License"); you may + not use this file except in compliance with the License. You may obtain + a copy of the License at + + http://www.apache.org/licenses/LICENSE-2.0 + + Unless required by applicable law or agreed to in writing, software + distributed under the License is distributed on an "AS IS" BASIS, WITHOUT + WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the + License for the specific language governing permissions and limitations + under the License. + +=========================== +x.509 Client Authentication +=========================== + +Purpose +======= + +Allows the Keystone middleware to authenticate itself with the Keystone server +via an x.509 client certificate. Both Service API and Admin API may be secured +with this feature. + +Certificates +============ + +The following types of certificates are required. A set of certficates is provided +in the examples/ssl directory with the Keystone distribution for testing. Here +is the description of each of them and their purpose: + +ca.pem + Certificate Authority chain to validate against. + +keystone.pem + Public certificate for Keystone server. + +middleware-key.pem + Public and private certificate for Keystone middleware. + +cakey.pem + Private key for the CA. + +keystonekey.pem + Private key for the Keystone server. + +Note that you may choose whatever names you want for these certificates, or combine +the public/private keys in the same file if you wish. These certificates are just +provided as an example. + +Configuration +============= + +By default, the Keystone server does not use SSL. To enable SSL with client authentication, +modify the etc/keystone.conf file accordingly: + +1. To enable SSL for Service API:: + + service_ssl = True + +2. To enable SSL for Admin API:: + + admin_ssl = True + +3. To enable SSL client authentication:: + + cert_required = True + +4. Set the location of the Keystone certificate file (example):: + + certfile = /etc/keystone/ca/certs/keystone.pem + +5. Set the location of the Keystone private file (example):: + + keyfile = /etc/keystone/ca/private/keystonekey.pem + +6. Set the location of the CA chain:: + + ca_certs = /etc/keystone/ca/certs/ca.pem + +Middleware +========== + +Add the following to your middleware configuration to support x.509 client authentication. +If ``cert_required`` is set to ``False`` on the keystone server, the certfile and keyfile parameters +in steps 3) and 4) may be commented out. + +1. Specify 'https' as the auth_protocol:: + + auth_protocol = https + +2. Modify the protocol in 'auth_uri' to be 'https' as well, if the service API is configured + for SSL:: + + auth_uri = https://localhost:5000/ + +3. Set the location of the middleware certificate file (example):: + + certfile = /etc/keystone/ca/certs/middleware-key.pem + +4. Set the location of the Keystone private file (example):: + + keyfile = /etc/keystone/ca/certs/middleware-key.pem + +For an example, take a look at the ``echo.ini`` middleware configuration for the 'echo' example +service in the examples/echo directory. + +Testing +======= + +You can test out how it works by using the ``echo`` example service in the ``examples/echo`` directory +and the certficates included in the ``examples/ssl`` directory. Invoke the ``echo_client.py`` with +the path to the client certificate:: + + python echo_client.py -s diff --git a/docs/source/releases.rst b/docs/source/releases.rst deleted file mode 100644 index a4b698d7..00000000 --- a/docs/source/releases.rst +++ /dev/null @@ -1,36 +0,0 @@ -============= -Release notes -============= - - -E3 (January 26, 2012) -========================================== -* Contract compliance: version response and ATOM, 300 multiple choice -* Global endpoints returned for unscoped calls -* adminUrl only shown to admin clients -* Endpoints have unique ID -* Auth-N/Auth-Z for S3 API (OS-KSS3 extension) -* Default tenant scope optionally returned when authenticating -* Vary header returned for caching proxies - -* Portable identifiers: modifiable, string identifiers in database backend -* Much improved keystone-manage command (see --help and docs) -* OS-KSVALIDATE extension to support not passing tokens in URL -* OS-KSEC2 and OS-KSS3 extensions respond on /tokens -* HP-IDM extension to filter roles to a given service ID -* Additional caching options in middleware (memcache and swift cache) - -* Enhanced configuration management (in line with other OpenStack projects) -* Additional logging -* Enhanced tracer tool (-t or --trace-calls) - -See comprehensive list here https://launchpad.net/keystone/+milestone/essex-3 - - -E2 (December 15, 2011) -======================== -* D5 compatibility middleware -* Database versioning -* Much more documentation: http://keystone.openstack.org - -See https://launchpad.net/keystone/+milestone/essex-2 diff --git a/docs/source/serviceAPI_curl_examples.rst b/docs/source/serviceAPI_curl_examples.rst deleted file mode 100644 index d05afc9f..00000000 --- a/docs/source/serviceAPI_curl_examples.rst +++ /dev/null @@ -1,69 +0,0 @@ -.. - Copyright 2011 OpenStack, LLC - All Rights Reserved. - - Licensed under the Apache License, Version 2.0 (the "License"); you may - not use this file except in compliance with the License. You may obtain - a copy of the License at - - http://www.apache.org/licenses/LICENSE-2.0 - - Unless required by applicable law or agreed to in writing, software - distributed under the License is distributed on an "AS IS" BASIS, WITHOUT - WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the - License for the specific language governing permissions and limitations - under the License. - -=============================== -Service API Examples Using Curl -=============================== - -The service API is defined to be a subset of the Admin API and, by -default, runs on port 5000. - -GET / -===== - -This call is identical to that documented for the Admin API, except -that it uses port 5000, instead of port 35357, by default:: - - $ curl http://0.0.0.0:5000 - -or:: - - $ curl http://0.0.0.0:5000/v2.0/ - -See the `Admin API Examples Using Curl`_ for more info. - -.. _`Admin API Examples Using Curl`: adminAPI_curl_examples.html - -GET /extensions -=============== - -This call is identical to that documented for the Admin API. - -POST /tokens -============ - -This call is identical to that documented for the Admin API. - -GET /tenants -============ - -List all of the tenants your token can access:: - - $ curl -H "X-Auth-Token:887665443383838" http://localhost:5000/v2.0/tenants - -Returns:: - - { - "tenants_links": [], - "tenants": [ - { - "enabled": true, - "description": "None", - "name": "customer-x", - "id": "1" - } - ] - } diff --git a/docs/source/services.rst b/docs/source/services.rst deleted file mode 100644 index d1c33381..00000000 --- a/docs/source/services.rst +++ /dev/null @@ -1,92 +0,0 @@ -.. - Copyright 2011 OpenStack, LLC - All Rights Reserved. - - Licensed under the Apache License, Version 2.0 (the "License"); you may - not use this file except in compliance with the License. You may obtain - a copy of the License at - - http://www.apache.org/licenses/LICENSE-2.0 - - Unless required by applicable law or agreed to in writing, software - distributed under the License is distributed on an "AS IS" BASIS, WITHOUT - WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the - License for the specific language governing permissions and limitations - under the License. - -================ -Services -================ - -.. toctree:: - :maxdepth: 1 - - -What are services? -================== - -Keystone includes service registry and service catalog functionality which it -uses to respond to client authentication requests with information useful to -clients in locating the list of available services they can access. - -The Service entity in Keystone represents an OpenStack service that is integrated -with Keystone. The Service entity is also used as a reference from roles, endpoints, -and endpoint templates. - -Keystone also includes an authorization mechanism to allow a service to own -its own roles and endpoints and prevent other services from changing or -modifying them. - -Who can create services? -======================== - -Any user with the Admin or Service Admin roles in Keystone may create services. - -How are services created? -========================= - -Services can be created using ``keystone-manage`` or through the REST API using -the OS-KSADM extension calls. - -Using ``keystone-manage`` (see :doc:`man/keystone-manage` for details):: - - $ keystone-manage add service compute nova 'This is a sample compute service' - -Using the REST API (see `extensions dev guide `_ for details):: - - $ curl -H "Content-type: application/json" -X POST -d '{ - "OS-KSADM:service": { - "name": "nova", - "type": "compute", - "description": "This is a sample compute service" - } - }' -H "X-Auth-Token: 999888777666" http://localhost:35357/v2.0/OS-KSADM/services/ - -How is service ownership determined? -==================================== - -Currently, the way to assign ownership to a service is to provide the owner's -user id in the keystone-manage add command:: - - $ keystone-manage add service nova compute 'This is a sample compute service' joeuser - -This will assign ownership to the new service to joeuser. - -When a service has an owner, then only that owner (or a global Admin) can create and manage -roles that start with that service name (ex: "nova:admin") and manage endpoints -and endpoint templates associated with that service. - -Listing services -================ - -Using ``keystone-manage``, the list of services and their owners can be listed:: - - $ keystone-manage service list - - id name type owner_id description - ------------------------------------------------------------------------------- - 1 compute nova joeuser This is a sample compute service - -Using the REST API, call ``GET /v2.0/OS-KSADM/services`` - -.. note: The rest API does not yet support service ownership diff --git a/docs/source/ssl.rst b/docs/source/ssl.rst deleted file mode 100644 index 839e951e..00000000 --- a/docs/source/ssl.rst +++ /dev/null @@ -1,118 +0,0 @@ -.. - Copyright 2011 OpenStack, LLC - All Rights Reserved. - - Licensed under the Apache License, Version 2.0 (the "License"); you may - not use this file except in compliance with the License. You may obtain - a copy of the License at - - http://www.apache.org/licenses/LICENSE-2.0 - - Unless required by applicable law or agreed to in writing, software - distributed under the License is distributed on an "AS IS" BASIS, WITHOUT - WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the - License for the specific language governing permissions and limitations - under the License. - -=========================== -x.509 Client Authentication -=========================== - -Purpose -======= - -Allows the Keystone middleware to authenticate itself with the Keystone server -via an x.509 client certificate. Both Service API and Admin API may be secured -with this feature. - -Certificates -============ - -The following types of certificates are required. A set of certficates is provided -in the examples/ssl directory with the Keystone distribution for testing. Here -is the description of each of them and their purpose: - -ca.pem - Certificate Authority chain to validate against. - -keystone.pem - Public certificate for Keystone server. - -middleware-key.pem - Public and private certificate for Keystone middleware. - -cakey.pem - Private key for the CA. - -keystonekey.pem - Private key for the Keystone server. - -Note that you may choose whatever names you want for these certificates, or combine -the public/private keys in the same file if you wish. These certificates are just -provided as an example. - -Configuration -============= - -By default, the Keystone server does not use SSL. To enable SSL with client authentication, -modify the etc/keystone.conf file accordingly: - -1. To enable SSL for Service API:: - - service_ssl = True - -2. To enable SSL for Admin API:: - - admin_ssl = True - -3. To enable SSL client authentication:: - - cert_required = True - -4. Set the location of the Keystone certificate file (example):: - - certfile = /etc/keystone/ca/certs/keystone.pem - -5. Set the location of the Keystone private file (example):: - - keyfile = /etc/keystone/ca/private/keystonekey.pem - -6. Set the location of the CA chain:: - - ca_certs = /etc/keystone/ca/certs/ca.pem - -Middleware -========== - -Add the following to your middleware configuration to support x.509 client authentication. -If ``cert_required`` is set to ``False`` on the keystone server, the certfile and keyfile parameters -in steps 3) and 4) may be commented out. - -1. Specify 'https' as the auth_protocol:: - - auth_protocol = https - -2. Modify the protocol in 'auth_uri' to be 'https' as well, if the service API is configured - for SSL:: - - auth_uri = https://localhost:5000/ - -3. Set the location of the middleware certificate file (example):: - - certfile = /etc/keystone/ca/certs/middleware-key.pem - -4. Set the location of the Keystone private file (example):: - - keyfile = /etc/keystone/ca/certs/middleware-key.pem - -For an example, take a look at the ``echo.ini`` middleware configuration for the 'echo' example -service in the examples/echo directory. - -Testing -======= - -You can test out how it works by using the ``echo`` example service in the ``examples/echo`` directory -and the certficates included in the ``examples/ssl`` directory. Invoke the ``echo_client.py`` with -the path to the client certificate:: - - python echo_client.py -s diff --git a/docs/source/usingkeystone.rst b/docs/source/usingkeystone.rst deleted file mode 100644 index bb52a94d..00000000 --- a/docs/source/usingkeystone.rst +++ /dev/null @@ -1,28 +0,0 @@ -.. - Copyright 2011 OpenStack, LLC - All Rights Reserved. - - Licensed under the Apache License, Version 2.0 (the "License"); you may - not use this file except in compliance with the License. You may obtain - a copy of the License at - - http://www.apache.org/licenses/LICENSE-2.0 - - Unless required by applicable law or agreed to in writing, software - distributed under the License is distributed on an "AS IS" BASIS, WITHOUT - WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the - License for the specific language governing permissions and limitations - under the License. - -============== -Using Keystone -============== - -Curl examples -------------- - -.. toctree:: - :maxdepth: 1 - - adminAPI_curl_examples - serviceAPI_curl_examples -- cgit From 1908a2d7ba14b830648078e6871fba0e6644fdf5 Mon Sep 17 00:00:00 2001 From: Joe Heck Date: Sun, 29 Jan 2012 13:47:29 -0800 Subject: format tweaks and moving old docs --- docs/source/backends.rst | 188 ---------- docs/source/configuringservices.rst | 174 +++++++++ docs/source/index.rst | 6 + docs/source/middleware_architecture.rst | 529 ++++++++++++++++++++++++++++ docs/source/nova-api-paste.rst | 142 ++++++++ docs/source/old/backends.rst | 188 ++++++++++ docs/source/old/configuringservices.rst | 333 ----------------- docs/source/old/middleware_architecture.rst | 529 ---------------------------- docs/source/old/nova-api-paste.rst | 142 -------- docs/source/setup.rst | 2 +- 10 files changed, 1040 insertions(+), 1193 deletions(-) delete mode 100644 docs/source/backends.rst create mode 100644 docs/source/configuringservices.rst create mode 100644 docs/source/middleware_architecture.rst create mode 100644 docs/source/nova-api-paste.rst create mode 100644 docs/source/old/backends.rst delete mode 100644 docs/source/old/configuringservices.rst delete mode 100644 docs/source/old/middleware_architecture.rst delete mode 100644 docs/source/old/nova-api-paste.rst (limited to 'docs') diff --git a/docs/source/backends.rst b/docs/source/backends.rst deleted file mode 100644 index b3fc2d91..00000000 --- a/docs/source/backends.rst +++ /dev/null @@ -1,188 +0,0 @@ -.. - Copyright 2011 OpenStack, LLC - All Rights Reserved. - - Licensed under the Apache License, Version 2.0 (the "License"); you may - not use this file except in compliance with the License. You may obtain - a copy of the License at - - http://www.apache.org/licenses/LICENSE-2.0 - - Unless required by applicable law or agreed to in writing, software - distributed under the License is distributed on an "AS IS" BASIS, WITHOUT - WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the - License for the specific language governing permissions and limitations - under the License. - -======== -Backends -======== - -Keystone supports multiple types of data stores for things like users, tenants, and -tokens, including SQL, LDAP, and memcache. - -SQL -=== - -In the default backend configuration (SQL-only), Keystone depends on the following database tables. - -``users`` ---------- - -``id`` - Auto-incremented primary key. -``name`` - Unqiue username used for authentication via ``passwordCredentials``. -``password`` - Password used for authentication via ``passwordCredentials``. - - Salted and hashed using ``passlib``. -``email`` - Email address (uniqueness is expected, but not enforced). -``enabled`` - If false, the user is unable to authenticate and the user's tokens will fail validation. -``tenant_id`` - Default tenant for the user. - -``tokens`` ----------- - -``id`` - The actual token provided after successful authentication (*plaintext*). -``user_id`` - References the user who owns the token. -``tenant_id`` - (*optional*) References the tenant the token is scoped to. -``expires`` - Indicates the expiration date of the token, after which the token can no longer be validated successfully. - -``tenants`` ------------ - -``id`` - Auto-incremented primary key. -``name`` - Unique string identifying the tenant. -``desc`` - Description of the tenant. -``enabled`` - If false, users are unable to scope to the tenant. - -``roles`` ---------- - -``id`` - Auto-incremented primary key. -``name`` - Name of the role. - - If the role is owned by a service, the role name **must** follow the convention:: - - serviceName:roleName -``desc`` - Description of the role. -``service_id`` - (*optional*) References the service that owns the role. - -``user_roles`` --------------- - -Maps users to the roles that have been granted to them (*optionally*, within the scope of a tenant). - -``id`` - Auto-incremented primary key. -``user_id`` - References the user the role is granted to. -``role_id`` - References the granted role. -``tenant_id`` - (*optional*) References a tenant upon which this grant is applies. - -``services`` ------------- - -``id`` - Auto-incremented primary key. -``name`` - Unique name of the service. -``type`` - Indicates the type of service (e.g. ``compute``, ``object``, ``identity``, etc). - - This can also be extended to support non-core services. Extended services - follow the naming convention ``extension:type`` (e.g. ``dnsextension:dns``). -``desc`` - Describes the service. -``owner_id`` - (*optional*) References the user who owns the service. - -``credentials`` ---------------- - -Currently only used for Amazon EC2 credential storage, this table is designed to support multiple -types of credentials in the future. - -``id`` - Auto-incremented primary key. -``user_id`` - References the user who owns the credential. -``tenant_id`` - References the tenant upon which the credential is valid. -``types`` - Indicates the type of credential (e.g. ``Password``, ``APIKey``, ``EC2``). -``key`` - Amazon EC2 access key. -``secret`` - Amazon EC2 secret key. - -``endpoints`` -------------- - -Tenant-specific endpoints map endpoint templates to specific tenants. -The ``tenant_id`` which appears here replaces the -``%tenant_id%`` template variable in the specified endpoint template. - -``id`` - Auto-incremented primary key. -``tenant_id`` - References the tenant this endpoint applies to. -``endpoint_template_id`` - The endpoint template to appear in the user's service catalog. - -``endpoint_templates`` ----------------------- - -A multi-purpose model for the service catalog which can be: - -- Provided to users of a specific tenants via ``endpoints``, when ``is_global`` is false. -- Provided to all users as-is, when ``is_global`` is true. - -``id`` - Auto-incremented primary key. -``region`` - Identifies the geographic region the endpoint is physically located within. -``service_id`` - TODO: References the service which owns the endpoints? -``public_url`` - Appears in the service catalog [#first]_. - - Represents an endpoint available on the public Internet. -``admin_url`` - Appears in the service catalog [#first]_. - - Users of this endpoint must have an Admin or ServiceAdmin role. -``internal_url`` - Appears in the service catalog [#first]_. - - Represents an endpoint on an internal, unmetered network. -``enabled`` - If false, this endpoint template will not appear in the service catalog. -``is_global`` - If true, this endpoint can not be mapped to tenant-specific endpoints, and ``%tenant_id%`` will not be substituted in endpoint URL's. Additionally, this endpoint will appear for all users. -``version_id`` - Identifies the version of the API contract that endpoint supports. -``version_list`` - A URL which lists versions supported by the endpoint. -``version_info`` - A URL which provides detailed version info regarding the service. - -.. [#first] ``%tenant_id%`` may be replaced by actual tenant references, depending on the value of ``is_global`` and the existence of a corresponding ``endpoints`` record. diff --git a/docs/source/configuringservices.rst b/docs/source/configuringservices.rst new file mode 100644 index 00000000..88bb9c15 --- /dev/null +++ b/docs/source/configuringservices.rst @@ -0,0 +1,174 @@ +.. + Copyright 2011 OpenStack, LLC + All Rights Reserved. + + Licensed under the Apache License, Version 2.0 (the "License"); you may + not use this file except in compliance with the License. You may obtain + a copy of the License at + + http://www.apache.org/licenses/LICENSE-2.0 + + Unless required by applicable law or agreed to in writing, software + distributed under the License is distributed on an "AS IS" BASIS, WITHOUT + WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the + License for the specific language governing permissions and limitations + under the License. + +========================================== +Configuring Services to work with Keystone +========================================== + +.. toctree:: + :maxdepth: 1 + + nova-api-paste + middleware_architecture + +Once Keystone is installed and running (see :doc:`configuration`), services need to be configured to work +with it. To do this, we primarily install and configure middleware for the OpenStack service to handle authentication tasks or otherwise interact with Keystone. + +In general: +* Clients making calls to the service will pass in an authentication token. +* The Keystone middleware will look for and validate that token, taking the appropriate action. +* It will also retrive additional information from the token such as user name, id, tenant name, id, roles, etc... + +The middleware will pass those data down to the service as headers. More details on the architecture of +that setup is described in :doc:`middleware_architecture` + +Setting up credentials +====================== + +Admin Token +----------- + +For a default installation of Keystone, before you can use the REST API, you +need to define an authorization token. This is configured in the keystone.conf file under the section ``[DEFAULT]``. In the sample file provided with the keystone project, the line defining this token is + + [DEFAULT] + admin_token = ADMIN + +This is a "shared secret" between keystone and other openstack services, and will need to be set the +same between those services in order for keystone services to function correctly. + +Setting up tenants, users, and roles +------------------------------------ + +You need to minimally define a tenant, user, and role to link the tenant and user as the most basic set of details to get other services authenticating and authorizing with keystone. See doc:`configuration` for a walk through on how to create tenants, users, and roles. + +Setting up services +=================== + +Defining Services +----------------- + +Keystone also acts as a service catalog to let other OpenStack systems know +where relevant API endpoints exist for OpenStack Services. The OpenStack +Dashboard, in particular, uses this heavily - and this **must** be configured +for the OpenStack Dashboard to properly function. + +Here's how we define the services:: + + keystone-manage service create name=nova service_type=compute description="Nova Compute Service" + keystone-manage service create name=ec2 service_type=ec2 description="EC2 Compatibility Layer" + keystone-manage service create name=glance service_type=image description="Glance Image Service" + keystone-manage service create name=keystone service_type=identity description="Keystone Identity Service" + keystone-manage service create name=swift service_type=object-store description="Swift Service" + +The endpoints for these services are defined in a template, an example of which is in the project as the file ``etc/default_catalog.templates``. + +Setting Up Middleware +===================== + +Keystone Auth-Token Middleware +-------------------------------- + +The Keystone auth_token middleware is a WSGI component that can be inserted in +the WSGI pipeline to handle authenticating tokens with Keystone. + +Configuring Nova to use Keystone +-------------------------------- + +To configure Nova to use Keystone for authentication, the Nova API service +can be run against the api-paste file provided by Keystone. This is most +easily accomplished by setting the `--api_paste_config` flag in nova.conf to +point to `examples/paste/nova-api-paste.ini` from Keystone. This paste file +included references to the WSGI authentication middleware provided with the +keystone installation. + +When configuring Nova, it is important to create a admin service token for +the service (from the Configuration step above) and include that as the key +'admin_token' in the nova-api-paste.ini. See the documented +:doc:`nova-api-paste` file for references. + +Configuring Swift to use Keystone +--------------------------------- + +Similar to Nova, swift can be configured to use Keystone for authentication +rather than it's built in 'tempauth'. + +1. Add a service endpoint for Swift to Keystone + +2. Configure the paste file for swift-proxy (`/etc/swift/swift-proxy.conf`) + +3. Reconfigure Swift's proxy server to use Keystone instead of TempAuth. + Here's an example `/etc/swift/proxy-server.conf`:: + + [DEFAULT] + bind_port = 8888 + user = + + [pipeline:main] + pipeline = catch_errors cache keystone proxy-server + + [app:proxy-server] + use = egg:swift#proxy + account_autocreate = true + + [filter:keystone] + use = egg:keystone#tokenauth + auth_protocol = http + auth_host = 127.0.0.1 + auth_port = 35357 + admin_token = 999888777666 + delay_auth_decision = 0 + service_protocol = http + service_host = 127.0.0.1 + service_port = 8100 + service_pass = dTpw + cache = swift.cache + + [filter:cache] + use = egg:swift#memcache + set log_name = cache + + [filter:catch_errors] + use = egg:swift#catch_errors + + Note that the optional "cache" property in the keystone filter allows any + service (not just Swift) to register its memcache client in the WSGI + environment. If such a cache exists, Keystone middleware will utilize it + to store validated token information, which could result in better overall + performance. + +4. Restart swift + +5. Verify that keystone is providing authentication to Swift + +Use `swift` to check everything works (note: you currently have to create a +container or upload something as your first action to have the account +created; there's a Swift bug to be fixed soon):: + + $ swift -A http://127.0.0.1:5000/v1.0 -U joeuser -K secrete post container + $ swift -A http://127.0.0.1:5000/v1.0 -U joeuser -K secrete stat -v + StorageURL: http://127.0.0.1:8888/v1/AUTH_1234 + Auth Token: 74ce1b05-e839-43b7-bd76-85ef178726c3 + Account: AUTH_1234 + Containers: 1 + Objects: 0 + Bytes: 0 + Accept-Ranges: bytes + X-Trans-Id: tx25c1a6969d8f4372b63912f411de3c3b + +.. WARNING:: + Keystone currently allows any valid token to do anything with any account. + diff --git a/docs/source/index.rst b/docs/source/index.rst index 8b12ff93..5d7c80fa 100644 --- a/docs/source/index.rst +++ b/docs/source/index.rst @@ -63,6 +63,12 @@ Developers Documentation developing architecture api_curl_examples + +Code Documentation +================== +.. toctree:: + :maxdepth: 1 + modules Indices and tables diff --git a/docs/source/middleware_architecture.rst b/docs/source/middleware_architecture.rst new file mode 100644 index 00000000..a8c38f3c --- /dev/null +++ b/docs/source/middleware_architecture.rst @@ -0,0 +1,529 @@ +.. + Copyright 2011 OpenStack, LLC + All Rights Reserved. + + Licensed under the Apache License, Version 2.0 (the "License"); you may + not use this file except in compliance with the License. You may obtain + a copy of the License at + + http://www.apache.org/licenses/LICENSE-2.0 + + Unless required by applicable law or agreed to in writing, software + distributed under the License is distributed on an "AS IS" BASIS, WITHOUT + WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the + License for the specific language governing permissions and limitations + under the License. + +======================= +Middleware Architecture +======================= + +Abstract +======== + +The Keystone middleware architecture supports multiple authentication protocols +in a pluggable manner in OpenStack. By providing support for authentication via +pluggable authentication components, this architecture allows OpenStack +services to be integrated easily into existing deployment environments. It also +provides a path by which to implement support for emerging authentication +standards such as OAUTH. + +Rationale and Goals +=================== + +Keystone is the Identity service for OpenStack. To support the easy integrating +of OpenStack with existing authentication and identity management systems, +Keystone supports talking to multiple backends like LDAP. +And to support different deployment needs, it can support multiple +authentication protocols via pluggable 'authentication components' implemented +as WSGI middleware. + +In this document, we describe the responsibilities of the authentication +middleware. We describe how these interact with underlying OpenStack services +and how existing services can be modified to take advantage of pluggable +authentication. The goal is to allow OpenStack services to be integrated easily +into existing deployment environments and to provide a path by which to +implement support for emerging authentication standards such as OAUTH. + +Specification Overview +====================== + +'Authentication' is the process of determining that users are who they say they +are. Typically, 'authentication protocols' such as HTTP Basic Auth, Digest +Access, public key, token, etc, are used to verify a user's identity. In this +document, we define an ''authentication component'' as a software module that +implements an authentication protocol for an OpenStack service. + +At a high level, an authentication component is simply a reverse proxy that +intercepts HTTP calls from clients. Once it has verified a user's identity, the +authentication component extends the call with information about the current +user and forwards the request to the OpenStack service. Otherwise, if a user's +identity is not verified, the message is rejected before it gets to the +service. This is illustrated in :ref:`authComponent`. + +.. _authComponent: + +Authentication Component +------------------------ + +Figure 1. Authentication Component + +.. image:: images/graphs_authComp.svg + :width: 100% + :height: 180 + :alt: An Authentication Component + +Authentication components may operate in 'delegated mode'. In this mode, the +decision reject an unauthenticated client is delegated to the OpenStack +service. Delegated mode is illustrated in :ref:`authComponentDelegated`. + +Here, requests are forwarded to the OpenStack service with an identity status +message that indicates whether the client's identity has been confirmed or is +indeterminate. It is the OpenStack service that decides whether or not a reject +message should be sent to the client. Note that it is always the responsibility +of the Authentication Component to transmit reject messages to the client. + +.. _authComponentDelegated: + +Authentication Component (Delegated Mode) +----------------------------------------- + +Figure 2. Authentication Component (Delegated Mode) + +.. image:: images/graphs_authCompDelegate.svg + :width: 100% + :height: 180 + :alt: An Authentication Component (Delegated Mode) + +In this architecture, we define interactions between the authentication component +and the OpenStack service. Interactions between the client and the +authentication component are defined only for exceptional cases. For example, +we define the message that should be returned when the OpenStack service is +down. Other interactions, however, are defined by the underlying authentication +protocol and the OpenStack service and are considered out of scope. + +.. _deployStrategies: + +Deployment Strategies +===================== + +An authentication component may be integrated directly into the service +implementation, or it may be deployed separately as an HTTP reverse proxy. This +is illustrated in :ref:`deployment`, showing both approaches to +authentication, labeled Option (a) and Option (b). + +.. _deployment: + +Authentication Component Deployments Options +-------------------------------------------- + +Figure 3. Authentication Component Deployments Options + +.. image:: images/images_layouts.svg + :width: 100% + :height: 180 + :alt: Authentication Component Deployments Options + +In Option (a), the component is integrated into the service implementation. In +this case, communication between the authentication component and the service +can be efficiently implemented via a method call. In Option (b), the component +is deployed separately and communication between the service and the component +involves an HTTP request. In both cases, unauthenticated requests are filtered +before they reach the service. + +Each approach offers some benefits. Option (a) offers low latency and ease of +initial implementation, making it possibly most appropriate as a starting point +for simple configurations. Option (b) offers several key advantages that may be +of particular value in complex and dynamic configurations. It offers the +ability to scale horizontally in cases where authentication is computationally +expensive, such as when verifying digital signatures. Option (b) also allows +authentication components to be written in different programming languages. +Finally, Option (b) allows multiple authentication components to be deployed in +front of the same service. + +OpenStack services can support both embedded (Option (a)) and external (Option +(b)) deployment strategies. Individual authentication components should support +either strategy or they |may| support both strategies. In order to support +option (a), authentication components written in the Python programming +language should be written as WSGI middleware components (in accordance with +the Web Server Gateway Interface (WSGI) standard [PEP-333]_. + +Additionally, services should support the ability to swap between different +embedded or external authentication components via configuration options. + +Exchanging User Information +=========================== + +If a request is successfully authenticated, the authentication component must +extend the request by adding an ``X-Authorization`` header. The header |must| +be formatted as illustrated in :ref:`xAuthHeader`. + +.. _xAuthHeader: + +X-Authorization Header +---------------------- + +Example 1. X-Authorization Header:: + + X-Authorization: Proxy JoeUser + +Here, `Proxy` denotes that the authentication occurred via a proxy (in this +case authentication component) and ''JoeUser'' is the name of the user who +issued the request. + +.. note: + + We considered using an ``Authorization`` header rather than an + ``X-Authorization``, thereby following normal HTTP semantics. There are some + cases, however, where multiple ``Authorization`` headers need to be transmitted + in a single request. We want to assure ourselves that this will not break + common clients before we recommend the approach. + +Authentication components |may| extend the request with additional +information. For example, an authentication system may add additional headers +or modify the target URI to pass authentication information to the back-end +service. Additionally, an authentication component |may| strip sensitive +information — a plain text password, for example — from the request. That said, +an authentication component |should| pass the majority of the request +unmodified. + +Reverse Proxy Authentication +---------------------------- + +An OpenStack service |should| verify that it is receiving requests from a +trusted authentication component. This is particularly important in cases where +the authentication component and the OpenStack service are deployed separately. +In order to trust incoming requests, the OpenStack service should therefore +authenticate the authentication component. To avoid confusion, we call this +'reverse proxy authentication', since in this case the authentication +component is acting as an HTTP reverse proxy. + +Any HTTP-based authentication scheme may be used for reverse proxy +authentication; however, all OpenStack services and all authentication +components |must| support HTTP Basic Authentication as defined in +[RFC-2617]_. + +Whether or not reverse proxy authentication is required is strictly a +deployment concern. For example, an operations team may opt to utilize firewall +rules instead of an authentication protocol to verify the integrity of incoming +request. Because of this, both OpenStack services and authentication components +|must| also allow for unauthenticated communication. + +In cases where reverse proxy authentication is used, the authorization +component may receive an HTTP 401 authentication error or an HTTP 403 +authorization error. These errors indicate that the component does not have +access to the underlying OpenStack service. The authentication component +|must not| return these errors to the client application. Instead, the +component |must| return a 500 internal error. This is illustrated in +:ref:`proxyAuth` and :ref:`proxyAuthDelegated` below. The component +|should| format the errors in a manner that does not break the service +contract defined by the OpenStack service. :ref:`proxyAuthDelegated` +illustrates proxy authorization in delegated mode. Delegated mode is discussed +in detail in the next section. + +.. _proxyAuth: + +Reverse Proxy Authentication +---------------------------- + +Figure 4. Reverse Proxy Authentication + +.. image:: images/graphs_proxyAuth.svg + :width: 100% + :height: 180 + :alt: Reverse Proxy Authentication + +.. _proxyAuthDelegated: + +Reverse Proxy Authentication (Delegated Mode) +--------------------------------------------- + +Figure 5. Reverse Proxy Authentication (Delegated Mode) + +.. image:: images/graphs_delegate_forbiden_proxy.svg + :width: 100% + :height: 180 + :alt: Reverse Proxy Authentication (Delegated Mode) + +Delegated Mode +============== +In some cases, the decision to reject an unauthenticated request should be +delegated to the OpenStack service. An unauthenticated request may be +appropriate in cases when anonymous access is allowed. In order to support +these cases, an authentication component may be placed in Delegated Mode. In +this mode, the component forwards requests to the OpenStack service when the +client's identity has been confirmed or is indeterminate — that is when +credentials are missing. The authentication component directly rejects requests +with invalid credentials. Authentication components |must| extend the +request by adding an `X-Identity-Status` header. The identity status header +|must| contain one of the following values: + +Identity Status Values +---------------------- + +Confirmed + A `confirmed` value indicates that valid credentials were sent and identity + has been confirmed. The service can trust that the request has been sent on + behalf of the user specified in the `X-Authorization` header. + +Indeterminate + An `indeterminate` value indicates that no credentials were sent and + identity has not been confirmed. In this case, the service will receive an + `X-Authorization` header with no user entry as illustrated in + :ref:`xauth-header-indeterminate`. + +.. _xauth-header-indeterminate: + +Indeterminate Identity Headers +------------------------------ + +Example 2. Indeterminate Identity Headers:: + + X-Identity-Status: Indeterminate + X-Authorization: Proxy + +Services |may| reject a delegated request by issuing an HTTP 401 +authentication error or an HTTP 403 authorization error. These responses +|must| contain an ``WWW-Authenticate`` header with a value of ``Delegated`` as +illustrated in :ref:`unauthHeaders`. + +X-Identity-Status + Provides information on whether the request was authenticated or not. + +X-Tenant + Provides the tenant ID (as it appears in the URL in Keystone). This is to support any legacy implementations before Keystone switched to an ID/Name schema for tenants. + +X-Tenant-Id + The unique, immutable tenant Id + +X-Tenant-Name + The unique, but mutable (it can change) tenant name. + +X-User-Id + The user id of the user used to log in + +X-User-Name + The username used to log in + +X-User + The username used to log in. This is to support any legacy implementations before Keystone switched to an ID/Name schema for tenants. + +X-Roles + The roles associated with that user + +.. _unauthHeaders: + +Delegated WWW-Authenticate Header +--------------------------------- + +:: + + WWW-Authenticate: Delegated + +It is important to note that the actual reject message will likely be modified +by the authentication component in order to comply with the authentication +scheme it is implementing. This is illustrated in :ref:`delegateRejectBasic` and +:ref:`delegateRejectOAuth` below. + +.. _delegateRejectBasic: + +Delegated Reject Basic Auth +--------------------------- + +.. image:: images/graphs_delegate_reject_basic.svg + :width: 100% + :height: 180 + :alt: Delegated Reject Basic Auth + +.. _delegateRejectOAuth: + +Delegated Reject OAuth +---------------------- + +.. image:: images/graphs_delegate_reject_oauth.svg + :width: 100% + :height: 180 + :alt: Delegated Reject OAuth + +The presence of the `WWW-Authenticate` header with a value of `Delegated` +distinguishes a client authentication/authorization failure from a component +failure. For example, compare :ref:`delegateForbidden` with :ref:`proxyAuthDelegated`. In +:ref:`delegateForbidden`, the client is not allowed to access the OpenStack service. +In :ref:`proxyAuthDelegated`, it is the authentication component itself which is +unauthorized. + +.. _delegateForbidden: + +Delegated Reject Forbidden +-------------------------- + +Figure 8. Delegated Reject Forbidden + +.. image:: images/graphs_delegate_forbiden_basic.svg + :width: 100% + :height: 180 + :alt: Delegated Reject Forbidden + +Authentication components |must| support both delegated and undelegated +(standard) modes. Delegated mode |should| be configured via a configuration +option. Delegated mode |should| be disabled by default. + +OpenStack services are not required to support delegated mode. If a service +does not support delegated mode, it |must| respond with a 501 not implemented +error and an `WWW-Authenticate` header with a value of `Delegated`. The +authentication component |must not| return the error to the client +application. Instead, the component |must| return a 500 internal error; this is +illustrated in :ref:`delegateUnimplemented`. The component |should| +format the error in a manner that does not break the service contract defined +by the OpenStack service. The component should also log the error such that it +that will inform operators of the misconfiguration. + +.. _delegateUnimplemented: + +Unimplemented Delegated Mode +---------------------------- + +.. image:: images/graphs_delegate_unimplemented.svg + :width: 100% + :height: 180 + :alt: Unimplemented Delegated Mode + +Handling Direct Client Connections +================================== + +Requests from the authentication component to an OpenStack service |must| +contain an ``X-Authorization`` header. If the header is missing, and reverse +proxy authentication fails or is switched off, the OpenStack service |may| +assume that the request is coming directly from a client application. In this +case, the OpenStack service |must| redirect the request to the authentication +component by issuing an HTTP 305 User Proxy redirect. This is illustrated in +:ref:`redirect`. Note that the redirect response |must| include a ``Location`` header +specifying the authentication component's URL as shown in :ref:`redirect-response`. + +.. _redirect: + +Auth Component Redirect +----------------------- + +.. image:: images/graphs_305.svg + :width: 100% + :height: 280 + :alt: Auth Component Redirect + +.. _redirect-response: + +Auth Component Redirect Response +-------------------------------- + +:: + + HTTP/1.1 305 Use Proxy + Date: Thu, 28 Oct 2011 07:41:16 GMT + Location: http://sample.auth.openstack.com/path/to/resource + +Using Multiple Authentication Components +======================================== + +There are some use cases when a service provider might want to consider using +multiple authentication components for different purposes. For instance, a +service provider may have one authentication scheme to authenticate the users +of the service and another one to authenticate the administrators or operations +personnel that maintain the service. For such scenarios, we propose using a +mapper as illustrated in :ref:`multiAuth`. + +.. _multiAuth: + +Multiple Authentication Components +---------------------------------- + +.. image:: images/graphs_mapper.svg + :width: 100% + :height: 320 + :alt: Multiple Authentication Components + +At a high level, a mapper is a simple reverse proxy that intercepts HTTP calls +from clients and routes the request to the appropriate authentication +component. A mapper can make the routing decisions based on a number of routing +rules that map a resource to a specific authentication component. For example, +a request URI may determine whether a call should be authenticated via one +authentication component or another. + +Note that neither the authentication component nor the OpenStack service need +be aware of the mapper. Any external authentication component can be used +alongside others. Mappers may provide a means by which to offer support for +anonymous or guest access to a subset of service resources. A mapper may be +implemented via a traditional reverse proxy server such as Pound or Zeus. + +The Default Component +===================== + +Individual services |must| be distributed with a simple integrated +authentication component by default. Providing such a component lowers barriers +to the deployment of individual services. This is especially important to] +developers who may want to deploy OpenStack services on their own machines. +Also, since there is no direct dependency on an external authentication system, +OpenStack services can be deployed individually, without the need to stand up +and configure additional services. Finally, having a standard authentication +component that all services share promotes a separation of concerns. That is, +as a community we are explicitly stating that services should not develop their +own authentication mechanisms. Additional authentication components may be +developed, of course, but these components should not be intimately coupled to +any one particular service. + +As discussed in :ref:`deployStrategies`, an authentication component may be +integrated directly into the service implementation (Option (a)), or it may be +deployed separately as an HTTP reverse proxy (Option (b)). The default +component should be implemented to support Option (a) and services should +maintain support for Option (b). One way to achieve this is to provide a +method that allows the disabling of the default authentication component via +configuration. This is illustrated in :ref:`both`. Here, requests are +sent directly to the OpenStack service when the default authentication +component is disabled. + +We will discuss the design of the default component in an upcoming blueprint. + +.. _both: + +Disabled Embedded Component +--------------------------- + +.. image:: images/graphs_both.svg + :width: 100% + :height: 250 + :alt: Disabled Embedded Component + +Questions and Answers +===================== + +#. Why do authentication components send reject messages? Why not have + OpenStack services reject requests themselves? + + The content and format of an authentication failed message is determined by + the authentication scheme (or protocol). For the service to respond + appropriately, it would have to be aware of the authentication scheme in + which it participates; this defeats the purpose of pluggable authentication + components. + +#. Why require support for deploying authentication components in separate + nodes? + + The deployment strategy is very flexible. It allows for authentication + components to be horizontally scalable. It allows for components to be written + in different languages. Finally, it allows different authentication components + to be deployed simultaneously as described above. + +References +========== + +.. [PEP-333] pep0333 Phillip J Eby. 'Python Web Server Gateway Interface + v1.0.'' http://www.python.org/dev/peps/pep-0333/. + +.. [RFC-2617] rfc2617 J Franks. P Hallam-Baker. J Hostetler. S Lawrence. + P Leach. A Luotonen. L Stewart. ''HTTP Authentication: Basic and Digest + Access Authentication.'' http://tools.ietf.org/html/rfc2617. + +.. |must| replace:: must must +.. |should| replace:: should should +.. |may| replace:: may may +.. |must not| replace:: "must not" "must not" + diff --git a/docs/source/nova-api-paste.rst b/docs/source/nova-api-paste.rst new file mode 100644 index 00000000..586bac72 --- /dev/null +++ b/docs/source/nova-api-paste.rst @@ -0,0 +1,142 @@ +.. + Copyright 2011 OpenStack, LLC + All Rights Reserved. + + Licensed under the Apache License, Version 2.0 (the "License"); you may + not use this file except in compliance with the License. You may obtain + a copy of the License at + + http://www.apache.org/licenses/LICENSE-2.0 + + Unless required by applicable law or agreed to in writing, software + distributed under the License is distributed on an "AS IS" BASIS, WITHOUT + WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the + License for the specific language governing permissions and limitations + under the License. + +nova-api-paste example +====================== +:: + + ####### + # EC2 # + ####### + + [composite:ec2] + use = egg:Paste#urlmap + /: ec2versions + /services/Cloud: ec2cloud + /services/Admin: ec2admin + /latest: ec2metadata + /2007-01-19: ec2metadata + /2007-03-01: ec2metadata + /2007-08-29: ec2metadata + /2007-10-10: ec2metadata + /2007-12-15: ec2metadata + /2008-02-01: ec2metadata + /2008-09-01: ec2metadata + /2009-04-04: ec2metadata + /1.0: ec2metadata + + [pipeline:ec2cloud] + pipeline = logrequest totoken authtoken keystonecontext cloudrequest authorizer ec2executor + + [pipeline:ec2admin] + pipeline = logrequest totoken authtoken keystonecontext adminrequest authorizer ec2executor + + [pipeline:ec2metadata] + pipeline = logrequest ec2md + + [pipeline:ec2versions] + pipeline = logrequest ec2ver + + [filter:logrequest] + paste.filter_factory = nova.api.ec2:RequestLogging.factory + + [filter:ec2lockout] + paste.filter_factory = nova.api.ec2:Lockout.factory + + [filter:totoken] + paste.filter_factory = keystone.middleware.ec2_token:EC2Token.factory + + [filter:ec2noauth] + paste.filter_factory = nova.api.ec2:NoAuth.factory + + [filter:authenticate] + paste.filter_factory = nova.api.ec2:Authenticate.factory + + [filter:cloudrequest] + controller = nova.api.ec2.cloud.CloudController + paste.filter_factory = nova.api.ec2:Requestify.factory + + [filter:adminrequest] + controller = nova.api.ec2.admin.AdminController + paste.filter_factory = nova.api.ec2:Requestify.factory + + [filter:authorizer] + paste.filter_factory = nova.api.ec2:Authorizer.factory + + [app:ec2executor] + paste.app_factory = nova.api.ec2:Executor.factory + + [app:ec2ver] + paste.app_factory = nova.api.ec2:Versions.factory + + [app:ec2md] + paste.app_factory = nova.api.ec2.metadatarequesthandler:MetadataRequestHandler.factory + + ############# + # Openstack # + ############# + + [composite:osapi] + use = egg:Paste#urlmap + /: osversions + /v1.1: openstackapi + + [pipeline:openstackapi] + pipeline = faultwrap authtoken keystonecontext ratelimit extensions osapiapp + + [filter:faultwrap] + paste.filter_factory = nova.api.openstack:FaultWrapper.factory + + [filter:auth] + paste.filter_factory = nova.api.openstack.auth:AuthMiddleware.factory + + [filter:noauth] + paste.filter_factory = nova.api.openstack.auth:NoAuthMiddleware.factory + + [filter:ratelimit] + paste.filter_factory = nova.api.openstack.limits:RateLimitingMiddleware.factory + + [filter:extensions] + paste.filter_factory = nova.api.openstack.extensions:ExtensionMiddleware.factory + + [app:osapiapp] + paste.app_factory = nova.api.openstack:APIRouter.factory + + [pipeline:osversions] + pipeline = faultwrap osversionapp + + [app:osversionapp] + paste.app_factory = nova.api.openstack.versions:Versions.factory + + ########## + # Shared # + ########## + + [filter:keystonecontext] + paste.filter_factory = keystone.middleware.nova_keystone_context:NovaKeystoneContext.factory + + [filter:authtoken] + paste.filter_factory = keystone.middleware.auth_token:filter_factory + service_protocol = http + service_host = 127.0.0.1 + service_port = 5000 + auth_host = 127.0.0.1 + auth_port = 35357 + auth_protocol = http + auth_uri = http://127.0.0.1:5000/ + admin_token = 999888777666 + ;Uncomment next line and check ip:port to use memcached to cache token requests + ;memcache_hosts = 127.0.0.1:11211 diff --git a/docs/source/old/backends.rst b/docs/source/old/backends.rst new file mode 100644 index 00000000..b3fc2d91 --- /dev/null +++ b/docs/source/old/backends.rst @@ -0,0 +1,188 @@ +.. + Copyright 2011 OpenStack, LLC + All Rights Reserved. + + Licensed under the Apache License, Version 2.0 (the "License"); you may + not use this file except in compliance with the License. You may obtain + a copy of the License at + + http://www.apache.org/licenses/LICENSE-2.0 + + Unless required by applicable law or agreed to in writing, software + distributed under the License is distributed on an "AS IS" BASIS, WITHOUT + WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the + License for the specific language governing permissions and limitations + under the License. + +======== +Backends +======== + +Keystone supports multiple types of data stores for things like users, tenants, and +tokens, including SQL, LDAP, and memcache. + +SQL +=== + +In the default backend configuration (SQL-only), Keystone depends on the following database tables. + +``users`` +--------- + +``id`` + Auto-incremented primary key. +``name`` + Unqiue username used for authentication via ``passwordCredentials``. +``password`` + Password used for authentication via ``passwordCredentials``. + + Salted and hashed using ``passlib``. +``email`` + Email address (uniqueness is expected, but not enforced). +``enabled`` + If false, the user is unable to authenticate and the user's tokens will fail validation. +``tenant_id`` + Default tenant for the user. + +``tokens`` +---------- + +``id`` + The actual token provided after successful authentication (*plaintext*). +``user_id`` + References the user who owns the token. +``tenant_id`` + (*optional*) References the tenant the token is scoped to. +``expires`` + Indicates the expiration date of the token, after which the token can no longer be validated successfully. + +``tenants`` +----------- + +``id`` + Auto-incremented primary key. +``name`` + Unique string identifying the tenant. +``desc`` + Description of the tenant. +``enabled`` + If false, users are unable to scope to the tenant. + +``roles`` +--------- + +``id`` + Auto-incremented primary key. +``name`` + Name of the role. + + If the role is owned by a service, the role name **must** follow the convention:: + + serviceName:roleName +``desc`` + Description of the role. +``service_id`` + (*optional*) References the service that owns the role. + +``user_roles`` +-------------- + +Maps users to the roles that have been granted to them (*optionally*, within the scope of a tenant). + +``id`` + Auto-incremented primary key. +``user_id`` + References the user the role is granted to. +``role_id`` + References the granted role. +``tenant_id`` + (*optional*) References a tenant upon which this grant is applies. + +``services`` +------------ + +``id`` + Auto-incremented primary key. +``name`` + Unique name of the service. +``type`` + Indicates the type of service (e.g. ``compute``, ``object``, ``identity``, etc). + + This can also be extended to support non-core services. Extended services + follow the naming convention ``extension:type`` (e.g. ``dnsextension:dns``). +``desc`` + Describes the service. +``owner_id`` + (*optional*) References the user who owns the service. + +``credentials`` +--------------- + +Currently only used for Amazon EC2 credential storage, this table is designed to support multiple +types of credentials in the future. + +``id`` + Auto-incremented primary key. +``user_id`` + References the user who owns the credential. +``tenant_id`` + References the tenant upon which the credential is valid. +``types`` + Indicates the type of credential (e.g. ``Password``, ``APIKey``, ``EC2``). +``key`` + Amazon EC2 access key. +``secret`` + Amazon EC2 secret key. + +``endpoints`` +------------- + +Tenant-specific endpoints map endpoint templates to specific tenants. +The ``tenant_id`` which appears here replaces the +``%tenant_id%`` template variable in the specified endpoint template. + +``id`` + Auto-incremented primary key. +``tenant_id`` + References the tenant this endpoint applies to. +``endpoint_template_id`` + The endpoint template to appear in the user's service catalog. + +``endpoint_templates`` +---------------------- + +A multi-purpose model for the service catalog which can be: + +- Provided to users of a specific tenants via ``endpoints``, when ``is_global`` is false. +- Provided to all users as-is, when ``is_global`` is true. + +``id`` + Auto-incremented primary key. +``region`` + Identifies the geographic region the endpoint is physically located within. +``service_id`` + TODO: References the service which owns the endpoints? +``public_url`` + Appears in the service catalog [#first]_. + + Represents an endpoint available on the public Internet. +``admin_url`` + Appears in the service catalog [#first]_. + + Users of this endpoint must have an Admin or ServiceAdmin role. +``internal_url`` + Appears in the service catalog [#first]_. + + Represents an endpoint on an internal, unmetered network. +``enabled`` + If false, this endpoint template will not appear in the service catalog. +``is_global`` + If true, this endpoint can not be mapped to tenant-specific endpoints, and ``%tenant_id%`` will not be substituted in endpoint URL's. Additionally, this endpoint will appear for all users. +``version_id`` + Identifies the version of the API contract that endpoint supports. +``version_list`` + A URL which lists versions supported by the endpoint. +``version_info`` + A URL which provides detailed version info regarding the service. + +.. [#first] ``%tenant_id%`` may be replaced by actual tenant references, depending on the value of ``is_global`` and the existence of a corresponding ``endpoints`` record. diff --git a/docs/source/old/configuringservices.rst b/docs/source/old/configuringservices.rst deleted file mode 100644 index 083c3ec5..00000000 --- a/docs/source/old/configuringservices.rst +++ /dev/null @@ -1,333 +0,0 @@ -.. - Copyright 2011 OpenStack, LLC - All Rights Reserved. - - Licensed under the Apache License, Version 2.0 (the "License"); you may - not use this file except in compliance with the License. You may obtain - a copy of the License at - - http://www.apache.org/licenses/LICENSE-2.0 - - Unless required by applicable law or agreed to in writing, software - distributed under the License is distributed on an "AS IS" BASIS, WITHOUT - WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the - License for the specific language governing permissions and limitations - under the License. - -========================================== -Configuring Services to work with Keystone -========================================== - -.. toctree:: - :maxdepth: 1 - -Once Keystone is installed and running, services need to be configured to work -with it. These are the steps to configure a service to work with Keystone: - -1. Create or get credentials for the service to use - - A set of credentials are needed for each service (they may be - shared if you chose to). Depending on the service, these credentials are - either a username and password or a long-lived token.. - -2. Register the service, endpoints, roles and other entities - - In order for a service to have it's endpoints and roles show in the service - catalog returned by Keystone, a service record needs to be added for the - service. Endpoints and roles associated with that service can then be created. - - This can be done through the REST interface (using the OS-KSCATALOG extension) - or using keystone-manage. - -3. Install and configure middleware for the service to handle authentication - - Clients making calls to the service will pass in an authentication token. The - Keystone middleware will look for and validate that token, taking the - appropriate action. It will also retrive additional information from the token - such as user name, id, tenant name, id, roles, etc... - - The middleware will pass those data down to the service as headers. The - detailed description of this architecture is available here :doc:`middleware_architecture` - -Setting up credentials -====================== - -First admin user - bootstrapping --------------------------------- - -For a default installation of Keystone, before you can use the REST API, you -need to create your first initial user and grant that user the right to -administer Keystone. - -For the keystone service itself, two -Roles are pre-defined in the keystone configuration file -(:doc:`keystone.conf`). - - #Role that allows admin operations (access to all operations) - keystone-admin-role = Admin - - #Role that allows acting as service (validate tokens, register service, - etc...) - keystone-service-admin-role = KeystoneServiceAdmin - -In order to create your first user, once Keystone is running use -the `keystone-manage` command: - - $ keystone-manage user add admin secrete - $ keystone-manage role add Admin - $ keystone-manage role add KeystoneServiceAdmin - $ keystone-manage role grant Admin admin - $ keystone-manage role grant KeystoneServiceAdmin admin - -This creates the `admin` user (with a password of `secrete`), creates -two roles (`Admin` and `KeystoneServiceAdmin`), and assigns those roles to -the `admin` user. From here, you should now have the choice of using the -administrative API (as well as the :doc:`man/keystone-manage` commands) to -further configure keystone. There are a number of examples of how to use -that API at :doc:`adminAPI_curl_examples`. - - -Setting up services -=================== - -Defining Services and Service Endpoints ---------------------------------------- - -Keystone also acts as a service catalog to let other OpenStack systems know -where relevant API endpoints exist for OpenStack Services. The OpenStack -Dashboard, in particular, uses this heavily - and this **must** be configured -for the OpenStack Dashboard to properly function. - -Here's how we define the services:: - - $ keystone-manage service add nova compute "Nova Compute Service" - $ keystone-manage service add glance image "Glance Image Service" - $ keystone-manage service add swift storage "Swift Object Storage Service" - $ keystone-manage service add keystone identity "Keystone Identity Service" - -Once the services are defined, we create endpoints for them. Each service -has three relevant URL's associated with it that are used in the command: - -* the public API URL -* an administrative API URL -* an internal URL - -The "internal URL" is an endpoint the generally offers the same API as the -public URL, but over a high-bandwidth, low-latency, unmetered (free) network. -You would use that to transfer images from nova to glance for example, and -not the Public URL which would go over the internet and be potentially chargeable. - -The "admin URL" is for administering the services and is not exposed or accessible -to customers without the apporpriate privileges. - -An example of setting up the endpoint for Nova:: - - $ keystone-manage endpointTemplates add RegionOne nova \ - http://nova-api.mydomain:8774/v1.1/%tenant_id% \ - http://nova-api.mydomain:8774/v1.1/%tenant_id% \ - http://nova-api.mydomain:8774/v1.1/%tenant_id% \ - 1 1 - -Glance:: - - $ keystone-manage endpointTemplates add RegionOne glance \ - http://glance.mydomain:9292/v1 \ - http://glance.mydomain:9292/v1 \ - http://glance.mydomain:9292/v1 \ - 1 1 - -Swift:: - - $ keystone-manage endpointTemplates add RegionOne swift \ - http://swift.mydomain:8080/v1/AUTH_%tenant_id% \ - http://swift.mydomain:8080/v1.0/ \ - http://swift.mydomain:8080/v1/AUTH_%tenant_id% \ - 1 1 - -And setting up an endpoint for Keystone:: - - $ keystone-manage endpointTemplates add RegionOne keystone \ - http://keystone.mydomain:5000/v2.0 \ - http://keystone.mydomain:35357/v2.0 \ - http://keystone.mydomain:5000/v2.0 \ - 1 1 - - -Defining an Administrative Service Token ----------------------------------------- - -An Administrative Service Token is a bit of arbitrary text which is configured -in Keystone and used (typically configured into) Nova, Swift, Glance, and any -other OpenStack projects, to be able to use Keystone services. - -This token is an arbitrary text string, but must be identical between Keystone -and the services using Keystone. This token is bound to a user and tenant as -well, so those also need to be created prior to setting it up. - -The *admin* user was set up above, but we haven't created a tenant for that -user yet:: - - $ keystone-manage tenant add admin - -and while we're here, let's grant the admin user the 'Admin' role to the -'admin' tenant:: - - $ keystone-manage role add Admin - $ keystone-manage role grant Admin admin admin - -Now we can create a service token:: - - $ keystone-manage token add 999888777666 admin admin 2015-02-05T00:00 - -This creates a service token of '999888777666' associated to the admin user, -admin tenant, and expires on February 5th, 2015. This token will be used when -configuring Nova, Glance, or other OpenStack services. - -Securing Communications with SSL --------------------------------- - -To encrypt traffic between services and Keystone, see :doc:`ssl` - - -Setting up OpenStack users -========================== - -Creating Tenants, Users, and Roles ----------------------------------- - -Let's set up a 'demo' tenant:: - - $ keystone-manage tenant add demo - -And add a 'demo' user with the password 'guest':: - - $ keystone-manage user add demo guest - -Now let's add a role of "Member" and grant 'demo' user that role -as it pertains to the tenant 'demo':: - - $ keystone-manage role add Member - $ keystone-manage role grant Member demo demo - -Let's also add the admin user as an Admin role to the demo tenant:: - - $ keystone-manage role grant Admin admin demo - -Creating EC2 credentials ------------------------- - -To add EC2 credentials for the `admin` and `demo` accounts:: - - $ keystone-manage credentials add admin EC2 'admin' 'secretpassword' - $ keystone-manage credentials add admin EC2 'demo' 'secretpassword' - -If you have a large number of credentials to create, you can put them all -into a single large file and import them using :doc:`man/keystone-import`. The -format of the document looks like:: - - credentials add admin EC2 'username' 'password' - credentials add admin EC2 'username' 'password' - -Then use:: - - $ keystone-import `filename` - - -Setting Up Middleware -===================== - -Keystone Auth-Token Middleware --------------------------------- - -The Keystone auth_token middleware is a WSGI component that can be inserted in -the WSGI pipeline to handle authenticating tokens with Keystone. See :doc:`middleware` -for details on middleware and configuration parameters. - - -Configuring Nova to use Keystone --------------------------------- - -To configure Nova to use Keystone for authentication, the Nova API service -can be run against the api-paste file provided by Keystone. This is most -easily accomplished by setting the `--api_paste_config` flag in nova.conf to -point to `examples/paste/nova-api-paste.ini` from Keystone. This paste file -included references to the WSGI authentication middleware provided with the -keystone installation. - -When configuring Nova, it is important to create a admin service token for -the service (from the Configuration step above) and include that as the key -'admin_token' in the nova-api-paste.ini. See the documented -:doc:`nova-api-paste` file for references. - -Configuring Swift to use Keystone ---------------------------------- - -Similar to Nova, swift can be configured to use Keystone for authentication -rather than it's built in 'tempauth'. - -1. Add a service endpoint for Swift to Keystone - -2. Configure the paste file for swift-proxy (`/etc/swift/swift-proxy.conf`) - -3. Reconfigure Swift's proxy server to use Keystone instead of TempAuth. - Here's an example `/etc/swift/proxy-server.conf`:: - - [DEFAULT] - bind_port = 8888 - user = - - [pipeline:main] - pipeline = catch_errors cache keystone proxy-server - - [app:proxy-server] - use = egg:swift#proxy - account_autocreate = true - - [filter:keystone] - use = egg:keystone#tokenauth - auth_protocol = http - auth_host = 127.0.0.1 - auth_port = 35357 - admin_token = 999888777666 - delay_auth_decision = 0 - service_protocol = http - service_host = 127.0.0.1 - service_port = 8100 - service_pass = dTpw - cache = swift.cache - - [filter:cache] - use = egg:swift#memcache - set log_name = cache - - [filter:catch_errors] - use = egg:swift#catch_errors - - Note that the optional "cache" property in the keystone filter allows any - service (not just Swift) to register its memcache client in the WSGI - environment. If such a cache exists, Keystone middleware will utilize it - to store validated token information, which could result in better overall - performance. - -4. Restart swift - -5. Verify that keystone is providing authentication to Swift - -Use `swift` to check everything works (note: you currently have to create a -container or upload something as your first action to have the account -created; there's a Swift bug to be fixed soon):: - - $ swift -A http://127.0.0.1:5000/v1.0 -U joeuser -K secrete post container - $ swift -A http://127.0.0.1:5000/v1.0 -U joeuser -K secrete stat -v - StorageURL: http://127.0.0.1:8888/v1/AUTH_1234 - Auth Token: 74ce1b05-e839-43b7-bd76-85ef178726c3 - Account: AUTH_1234 - Containers: 1 - Objects: 0 - Bytes: 0 - Accept-Ranges: bytes - X-Trans-Id: tx25c1a6969d8f4372b63912f411de3c3b - -.. WARNING:: - Keystone currently allows any valid token to do anything with any account. - diff --git a/docs/source/old/middleware_architecture.rst b/docs/source/old/middleware_architecture.rst deleted file mode 100644 index a8c38f3c..00000000 --- a/docs/source/old/middleware_architecture.rst +++ /dev/null @@ -1,529 +0,0 @@ -.. - Copyright 2011 OpenStack, LLC - All Rights Reserved. - - Licensed under the Apache License, Version 2.0 (the "License"); you may - not use this file except in compliance with the License. You may obtain - a copy of the License at - - http://www.apache.org/licenses/LICENSE-2.0 - - Unless required by applicable law or agreed to in writing, software - distributed under the License is distributed on an "AS IS" BASIS, WITHOUT - WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the - License for the specific language governing permissions and limitations - under the License. - -======================= -Middleware Architecture -======================= - -Abstract -======== - -The Keystone middleware architecture supports multiple authentication protocols -in a pluggable manner in OpenStack. By providing support for authentication via -pluggable authentication components, this architecture allows OpenStack -services to be integrated easily into existing deployment environments. It also -provides a path by which to implement support for emerging authentication -standards such as OAUTH. - -Rationale and Goals -=================== - -Keystone is the Identity service for OpenStack. To support the easy integrating -of OpenStack with existing authentication and identity management systems, -Keystone supports talking to multiple backends like LDAP. -And to support different deployment needs, it can support multiple -authentication protocols via pluggable 'authentication components' implemented -as WSGI middleware. - -In this document, we describe the responsibilities of the authentication -middleware. We describe how these interact with underlying OpenStack services -and how existing services can be modified to take advantage of pluggable -authentication. The goal is to allow OpenStack services to be integrated easily -into existing deployment environments and to provide a path by which to -implement support for emerging authentication standards such as OAUTH. - -Specification Overview -====================== - -'Authentication' is the process of determining that users are who they say they -are. Typically, 'authentication protocols' such as HTTP Basic Auth, Digest -Access, public key, token, etc, are used to verify a user's identity. In this -document, we define an ''authentication component'' as a software module that -implements an authentication protocol for an OpenStack service. - -At a high level, an authentication component is simply a reverse proxy that -intercepts HTTP calls from clients. Once it has verified a user's identity, the -authentication component extends the call with information about the current -user and forwards the request to the OpenStack service. Otherwise, if a user's -identity is not verified, the message is rejected before it gets to the -service. This is illustrated in :ref:`authComponent`. - -.. _authComponent: - -Authentication Component ------------------------- - -Figure 1. Authentication Component - -.. image:: images/graphs_authComp.svg - :width: 100% - :height: 180 - :alt: An Authentication Component - -Authentication components may operate in 'delegated mode'. In this mode, the -decision reject an unauthenticated client is delegated to the OpenStack -service. Delegated mode is illustrated in :ref:`authComponentDelegated`. - -Here, requests are forwarded to the OpenStack service with an identity status -message that indicates whether the client's identity has been confirmed or is -indeterminate. It is the OpenStack service that decides whether or not a reject -message should be sent to the client. Note that it is always the responsibility -of the Authentication Component to transmit reject messages to the client. - -.. _authComponentDelegated: - -Authentication Component (Delegated Mode) ------------------------------------------ - -Figure 2. Authentication Component (Delegated Mode) - -.. image:: images/graphs_authCompDelegate.svg - :width: 100% - :height: 180 - :alt: An Authentication Component (Delegated Mode) - -In this architecture, we define interactions between the authentication component -and the OpenStack service. Interactions between the client and the -authentication component are defined only for exceptional cases. For example, -we define the message that should be returned when the OpenStack service is -down. Other interactions, however, are defined by the underlying authentication -protocol and the OpenStack service and are considered out of scope. - -.. _deployStrategies: - -Deployment Strategies -===================== - -An authentication component may be integrated directly into the service -implementation, or it may be deployed separately as an HTTP reverse proxy. This -is illustrated in :ref:`deployment`, showing both approaches to -authentication, labeled Option (a) and Option (b). - -.. _deployment: - -Authentication Component Deployments Options --------------------------------------------- - -Figure 3. Authentication Component Deployments Options - -.. image:: images/images_layouts.svg - :width: 100% - :height: 180 - :alt: Authentication Component Deployments Options - -In Option (a), the component is integrated into the service implementation. In -this case, communication between the authentication component and the service -can be efficiently implemented via a method call. In Option (b), the component -is deployed separately and communication between the service and the component -involves an HTTP request. In both cases, unauthenticated requests are filtered -before they reach the service. - -Each approach offers some benefits. Option (a) offers low latency and ease of -initial implementation, making it possibly most appropriate as a starting point -for simple configurations. Option (b) offers several key advantages that may be -of particular value in complex and dynamic configurations. It offers the -ability to scale horizontally in cases where authentication is computationally -expensive, such as when verifying digital signatures. Option (b) also allows -authentication components to be written in different programming languages. -Finally, Option (b) allows multiple authentication components to be deployed in -front of the same service. - -OpenStack services can support both embedded (Option (a)) and external (Option -(b)) deployment strategies. Individual authentication components should support -either strategy or they |may| support both strategies. In order to support -option (a), authentication components written in the Python programming -language should be written as WSGI middleware components (in accordance with -the Web Server Gateway Interface (WSGI) standard [PEP-333]_. - -Additionally, services should support the ability to swap between different -embedded or external authentication components via configuration options. - -Exchanging User Information -=========================== - -If a request is successfully authenticated, the authentication component must -extend the request by adding an ``X-Authorization`` header. The header |must| -be formatted as illustrated in :ref:`xAuthHeader`. - -.. _xAuthHeader: - -X-Authorization Header ----------------------- - -Example 1. X-Authorization Header:: - - X-Authorization: Proxy JoeUser - -Here, `Proxy` denotes that the authentication occurred via a proxy (in this -case authentication component) and ''JoeUser'' is the name of the user who -issued the request. - -.. note: - - We considered using an ``Authorization`` header rather than an - ``X-Authorization``, thereby following normal HTTP semantics. There are some - cases, however, where multiple ``Authorization`` headers need to be transmitted - in a single request. We want to assure ourselves that this will not break - common clients before we recommend the approach. - -Authentication components |may| extend the request with additional -information. For example, an authentication system may add additional headers -or modify the target URI to pass authentication information to the back-end -service. Additionally, an authentication component |may| strip sensitive -information — a plain text password, for example — from the request. That said, -an authentication component |should| pass the majority of the request -unmodified. - -Reverse Proxy Authentication ----------------------------- - -An OpenStack service |should| verify that it is receiving requests from a -trusted authentication component. This is particularly important in cases where -the authentication component and the OpenStack service are deployed separately. -In order to trust incoming requests, the OpenStack service should therefore -authenticate the authentication component. To avoid confusion, we call this -'reverse proxy authentication', since in this case the authentication -component is acting as an HTTP reverse proxy. - -Any HTTP-based authentication scheme may be used for reverse proxy -authentication; however, all OpenStack services and all authentication -components |must| support HTTP Basic Authentication as defined in -[RFC-2617]_. - -Whether or not reverse proxy authentication is required is strictly a -deployment concern. For example, an operations team may opt to utilize firewall -rules instead of an authentication protocol to verify the integrity of incoming -request. Because of this, both OpenStack services and authentication components -|must| also allow for unauthenticated communication. - -In cases where reverse proxy authentication is used, the authorization -component may receive an HTTP 401 authentication error or an HTTP 403 -authorization error. These errors indicate that the component does not have -access to the underlying OpenStack service. The authentication component -|must not| return these errors to the client application. Instead, the -component |must| return a 500 internal error. This is illustrated in -:ref:`proxyAuth` and :ref:`proxyAuthDelegated` below. The component -|should| format the errors in a manner that does not break the service -contract defined by the OpenStack service. :ref:`proxyAuthDelegated` -illustrates proxy authorization in delegated mode. Delegated mode is discussed -in detail in the next section. - -.. _proxyAuth: - -Reverse Proxy Authentication ----------------------------- - -Figure 4. Reverse Proxy Authentication - -.. image:: images/graphs_proxyAuth.svg - :width: 100% - :height: 180 - :alt: Reverse Proxy Authentication - -.. _proxyAuthDelegated: - -Reverse Proxy Authentication (Delegated Mode) ---------------------------------------------- - -Figure 5. Reverse Proxy Authentication (Delegated Mode) - -.. image:: images/graphs_delegate_forbiden_proxy.svg - :width: 100% - :height: 180 - :alt: Reverse Proxy Authentication (Delegated Mode) - -Delegated Mode -============== -In some cases, the decision to reject an unauthenticated request should be -delegated to the OpenStack service. An unauthenticated request may be -appropriate in cases when anonymous access is allowed. In order to support -these cases, an authentication component may be placed in Delegated Mode. In -this mode, the component forwards requests to the OpenStack service when the -client's identity has been confirmed or is indeterminate — that is when -credentials are missing. The authentication component directly rejects requests -with invalid credentials. Authentication components |must| extend the -request by adding an `X-Identity-Status` header. The identity status header -|must| contain one of the following values: - -Identity Status Values ----------------------- - -Confirmed - A `confirmed` value indicates that valid credentials were sent and identity - has been confirmed. The service can trust that the request has been sent on - behalf of the user specified in the `X-Authorization` header. - -Indeterminate - An `indeterminate` value indicates that no credentials were sent and - identity has not been confirmed. In this case, the service will receive an - `X-Authorization` header with no user entry as illustrated in - :ref:`xauth-header-indeterminate`. - -.. _xauth-header-indeterminate: - -Indeterminate Identity Headers ------------------------------- - -Example 2. Indeterminate Identity Headers:: - - X-Identity-Status: Indeterminate - X-Authorization: Proxy - -Services |may| reject a delegated request by issuing an HTTP 401 -authentication error or an HTTP 403 authorization error. These responses -|must| contain an ``WWW-Authenticate`` header with a value of ``Delegated`` as -illustrated in :ref:`unauthHeaders`. - -X-Identity-Status - Provides information on whether the request was authenticated or not. - -X-Tenant - Provides the tenant ID (as it appears in the URL in Keystone). This is to support any legacy implementations before Keystone switched to an ID/Name schema for tenants. - -X-Tenant-Id - The unique, immutable tenant Id - -X-Tenant-Name - The unique, but mutable (it can change) tenant name. - -X-User-Id - The user id of the user used to log in - -X-User-Name - The username used to log in - -X-User - The username used to log in. This is to support any legacy implementations before Keystone switched to an ID/Name schema for tenants. - -X-Roles - The roles associated with that user - -.. _unauthHeaders: - -Delegated WWW-Authenticate Header ---------------------------------- - -:: - - WWW-Authenticate: Delegated - -It is important to note that the actual reject message will likely be modified -by the authentication component in order to comply with the authentication -scheme it is implementing. This is illustrated in :ref:`delegateRejectBasic` and -:ref:`delegateRejectOAuth` below. - -.. _delegateRejectBasic: - -Delegated Reject Basic Auth ---------------------------- - -.. image:: images/graphs_delegate_reject_basic.svg - :width: 100% - :height: 180 - :alt: Delegated Reject Basic Auth - -.. _delegateRejectOAuth: - -Delegated Reject OAuth ----------------------- - -.. image:: images/graphs_delegate_reject_oauth.svg - :width: 100% - :height: 180 - :alt: Delegated Reject OAuth - -The presence of the `WWW-Authenticate` header with a value of `Delegated` -distinguishes a client authentication/authorization failure from a component -failure. For example, compare :ref:`delegateForbidden` with :ref:`proxyAuthDelegated`. In -:ref:`delegateForbidden`, the client is not allowed to access the OpenStack service. -In :ref:`proxyAuthDelegated`, it is the authentication component itself which is -unauthorized. - -.. _delegateForbidden: - -Delegated Reject Forbidden --------------------------- - -Figure 8. Delegated Reject Forbidden - -.. image:: images/graphs_delegate_forbiden_basic.svg - :width: 100% - :height: 180 - :alt: Delegated Reject Forbidden - -Authentication components |must| support both delegated and undelegated -(standard) modes. Delegated mode |should| be configured via a configuration -option. Delegated mode |should| be disabled by default. - -OpenStack services are not required to support delegated mode. If a service -does not support delegated mode, it |must| respond with a 501 not implemented -error and an `WWW-Authenticate` header with a value of `Delegated`. The -authentication component |must not| return the error to the client -application. Instead, the component |must| return a 500 internal error; this is -illustrated in :ref:`delegateUnimplemented`. The component |should| -format the error in a manner that does not break the service contract defined -by the OpenStack service. The component should also log the error such that it -that will inform operators of the misconfiguration. - -.. _delegateUnimplemented: - -Unimplemented Delegated Mode ----------------------------- - -.. image:: images/graphs_delegate_unimplemented.svg - :width: 100% - :height: 180 - :alt: Unimplemented Delegated Mode - -Handling Direct Client Connections -================================== - -Requests from the authentication component to an OpenStack service |must| -contain an ``X-Authorization`` header. If the header is missing, and reverse -proxy authentication fails or is switched off, the OpenStack service |may| -assume that the request is coming directly from a client application. In this -case, the OpenStack service |must| redirect the request to the authentication -component by issuing an HTTP 305 User Proxy redirect. This is illustrated in -:ref:`redirect`. Note that the redirect response |must| include a ``Location`` header -specifying the authentication component's URL as shown in :ref:`redirect-response`. - -.. _redirect: - -Auth Component Redirect ------------------------ - -.. image:: images/graphs_305.svg - :width: 100% - :height: 280 - :alt: Auth Component Redirect - -.. _redirect-response: - -Auth Component Redirect Response --------------------------------- - -:: - - HTTP/1.1 305 Use Proxy - Date: Thu, 28 Oct 2011 07:41:16 GMT - Location: http://sample.auth.openstack.com/path/to/resource - -Using Multiple Authentication Components -======================================== - -There are some use cases when a service provider might want to consider using -multiple authentication components for different purposes. For instance, a -service provider may have one authentication scheme to authenticate the users -of the service and another one to authenticate the administrators or operations -personnel that maintain the service. For such scenarios, we propose using a -mapper as illustrated in :ref:`multiAuth`. - -.. _multiAuth: - -Multiple Authentication Components ----------------------------------- - -.. image:: images/graphs_mapper.svg - :width: 100% - :height: 320 - :alt: Multiple Authentication Components - -At a high level, a mapper is a simple reverse proxy that intercepts HTTP calls -from clients and routes the request to the appropriate authentication -component. A mapper can make the routing decisions based on a number of routing -rules that map a resource to a specific authentication component. For example, -a request URI may determine whether a call should be authenticated via one -authentication component or another. - -Note that neither the authentication component nor the OpenStack service need -be aware of the mapper. Any external authentication component can be used -alongside others. Mappers may provide a means by which to offer support for -anonymous or guest access to a subset of service resources. A mapper may be -implemented via a traditional reverse proxy server such as Pound or Zeus. - -The Default Component -===================== - -Individual services |must| be distributed with a simple integrated -authentication component by default. Providing such a component lowers barriers -to the deployment of individual services. This is especially important to] -developers who may want to deploy OpenStack services on their own machines. -Also, since there is no direct dependency on an external authentication system, -OpenStack services can be deployed individually, without the need to stand up -and configure additional services. Finally, having a standard authentication -component that all services share promotes a separation of concerns. That is, -as a community we are explicitly stating that services should not develop their -own authentication mechanisms. Additional authentication components may be -developed, of course, but these components should not be intimately coupled to -any one particular service. - -As discussed in :ref:`deployStrategies`, an authentication component may be -integrated directly into the service implementation (Option (a)), or it may be -deployed separately as an HTTP reverse proxy (Option (b)). The default -component should be implemented to support Option (a) and services should -maintain support for Option (b). One way to achieve this is to provide a -method that allows the disabling of the default authentication component via -configuration. This is illustrated in :ref:`both`. Here, requests are -sent directly to the OpenStack service when the default authentication -component is disabled. - -We will discuss the design of the default component in an upcoming blueprint. - -.. _both: - -Disabled Embedded Component ---------------------------- - -.. image:: images/graphs_both.svg - :width: 100% - :height: 250 - :alt: Disabled Embedded Component - -Questions and Answers -===================== - -#. Why do authentication components send reject messages? Why not have - OpenStack services reject requests themselves? - - The content and format of an authentication failed message is determined by - the authentication scheme (or protocol). For the service to respond - appropriately, it would have to be aware of the authentication scheme in - which it participates; this defeats the purpose of pluggable authentication - components. - -#. Why require support for deploying authentication components in separate - nodes? - - The deployment strategy is very flexible. It allows for authentication - components to be horizontally scalable. It allows for components to be written - in different languages. Finally, it allows different authentication components - to be deployed simultaneously as described above. - -References -========== - -.. [PEP-333] pep0333 Phillip J Eby. 'Python Web Server Gateway Interface - v1.0.'' http://www.python.org/dev/peps/pep-0333/. - -.. [RFC-2617] rfc2617 J Franks. P Hallam-Baker. J Hostetler. S Lawrence. - P Leach. A Luotonen. L Stewart. ''HTTP Authentication: Basic and Digest - Access Authentication.'' http://tools.ietf.org/html/rfc2617. - -.. |must| replace:: must must -.. |should| replace:: should should -.. |may| replace:: may may -.. |must not| replace:: "must not" "must not" - diff --git a/docs/source/old/nova-api-paste.rst b/docs/source/old/nova-api-paste.rst deleted file mode 100644 index 586bac72..00000000 --- a/docs/source/old/nova-api-paste.rst +++ /dev/null @@ -1,142 +0,0 @@ -.. - Copyright 2011 OpenStack, LLC - All Rights Reserved. - - Licensed under the Apache License, Version 2.0 (the "License"); you may - not use this file except in compliance with the License. You may obtain - a copy of the License at - - http://www.apache.org/licenses/LICENSE-2.0 - - Unless required by applicable law or agreed to in writing, software - distributed under the License is distributed on an "AS IS" BASIS, WITHOUT - WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the - License for the specific language governing permissions and limitations - under the License. - -nova-api-paste example -====================== -:: - - ####### - # EC2 # - ####### - - [composite:ec2] - use = egg:Paste#urlmap - /: ec2versions - /services/Cloud: ec2cloud - /services/Admin: ec2admin - /latest: ec2metadata - /2007-01-19: ec2metadata - /2007-03-01: ec2metadata - /2007-08-29: ec2metadata - /2007-10-10: ec2metadata - /2007-12-15: ec2metadata - /2008-02-01: ec2metadata - /2008-09-01: ec2metadata - /2009-04-04: ec2metadata - /1.0: ec2metadata - - [pipeline:ec2cloud] - pipeline = logrequest totoken authtoken keystonecontext cloudrequest authorizer ec2executor - - [pipeline:ec2admin] - pipeline = logrequest totoken authtoken keystonecontext adminrequest authorizer ec2executor - - [pipeline:ec2metadata] - pipeline = logrequest ec2md - - [pipeline:ec2versions] - pipeline = logrequest ec2ver - - [filter:logrequest] - paste.filter_factory = nova.api.ec2:RequestLogging.factory - - [filter:ec2lockout] - paste.filter_factory = nova.api.ec2:Lockout.factory - - [filter:totoken] - paste.filter_factory = keystone.middleware.ec2_token:EC2Token.factory - - [filter:ec2noauth] - paste.filter_factory = nova.api.ec2:NoAuth.factory - - [filter:authenticate] - paste.filter_factory = nova.api.ec2:Authenticate.factory - - [filter:cloudrequest] - controller = nova.api.ec2.cloud.CloudController - paste.filter_factory = nova.api.ec2:Requestify.factory - - [filter:adminrequest] - controller = nova.api.ec2.admin.AdminController - paste.filter_factory = nova.api.ec2:Requestify.factory - - [filter:authorizer] - paste.filter_factory = nova.api.ec2:Authorizer.factory - - [app:ec2executor] - paste.app_factory = nova.api.ec2:Executor.factory - - [app:ec2ver] - paste.app_factory = nova.api.ec2:Versions.factory - - [app:ec2md] - paste.app_factory = nova.api.ec2.metadatarequesthandler:MetadataRequestHandler.factory - - ############# - # Openstack # - ############# - - [composite:osapi] - use = egg:Paste#urlmap - /: osversions - /v1.1: openstackapi - - [pipeline:openstackapi] - pipeline = faultwrap authtoken keystonecontext ratelimit extensions osapiapp - - [filter:faultwrap] - paste.filter_factory = nova.api.openstack:FaultWrapper.factory - - [filter:auth] - paste.filter_factory = nova.api.openstack.auth:AuthMiddleware.factory - - [filter:noauth] - paste.filter_factory = nova.api.openstack.auth:NoAuthMiddleware.factory - - [filter:ratelimit] - paste.filter_factory = nova.api.openstack.limits:RateLimitingMiddleware.factory - - [filter:extensions] - paste.filter_factory = nova.api.openstack.extensions:ExtensionMiddleware.factory - - [app:osapiapp] - paste.app_factory = nova.api.openstack:APIRouter.factory - - [pipeline:osversions] - pipeline = faultwrap osversionapp - - [app:osversionapp] - paste.app_factory = nova.api.openstack.versions:Versions.factory - - ########## - # Shared # - ########## - - [filter:keystonecontext] - paste.filter_factory = keystone.middleware.nova_keystone_context:NovaKeystoneContext.factory - - [filter:authtoken] - paste.filter_factory = keystone.middleware.auth_token:filter_factory - service_protocol = http - service_host = 127.0.0.1 - service_port = 5000 - auth_host = 127.0.0.1 - auth_port = 35357 - auth_protocol = http - auth_uri = http://127.0.0.1:5000/ - admin_token = 999888777666 - ;Uncomment next line and check ip:port to use memcached to cache token requests - ;memcache_hosts = 127.0.0.1:11211 diff --git a/docs/source/setup.rst b/docs/source/setup.rst index 25a43655..4f6b6137 100644 --- a/docs/source/setup.rst +++ b/docs/source/setup.rst @@ -150,7 +150,7 @@ If you want to check the version of Keystone you are running: >>> print keystone.version.version() 2012.1-dev -If you can import keystone successfully, you should be ready to move on to :doc:`testing` and :doc:`developing` +If you can import keystone successfully, you should be ready to move on to :doc:`developing` Troubleshooting =============== -- cgit From ef8b8f1d9b61ff527b223d69c52f35f25536b8dd Mon Sep 17 00:00:00 2001 From: Joe Heck Date: Sun, 29 Jan 2012 14:09:24 -0800 Subject: updating formating for configuration page --- docs/source/configuration.rst | 133 +++++++++++++++++++++++++----------------- 1 file changed, 81 insertions(+), 52 deletions(-) (limited to 'docs') diff --git a/docs/source/configuration.rst b/docs/source/configuration.rst index e16d1892..410e7b1b 100644 --- a/docs/source/configuration.rst +++ b/docs/source/configuration.rst @@ -101,13 +101,14 @@ from the API call. Invoking keystone-manage by itself will give you some usage information. Available keystone-manage commands: - db_sync: Sync the database. - ec2: no docs - role: Role CRUD functions. - service: Service CRUD functions. - tenant: Tenant CRUD functions. - token: Token CRUD functions. - user: User CRUD functions. + +* ``db_sync``: Sync the database. +* ``ec2``: no docs +* ``role``: Role CRUD functions. +* ``service``: Service CRUD functions. +* ``tenant``: Tenant CRUD functions. +* ``token``: Token CRUD functions. +* ``user``: User CRUD functions. Tenants ------- @@ -116,33 +117,42 @@ Tenants are the high level grouping within Keystone that represent groups of users. A tenant is the grouping that owns virtual machines within Nova, or containers within Swift. A tenant can have zero or more users, Users can be assocaited with more than one tenant, and each tenant - user pairing can have a role associated with it. -* tenant create +``tenant create`` +^^^^^^^^^^^^^^^^^ + +keyword arguments - keyword arguments - * tenant_name - * id (optional) +* tenant_name +* id (optional) example:: + keystone-manage --id-only tenant create tenant_name=admin creates a tenant named "admin". -* tenant delete +``tenant delete`` +^^^^^^^^^^^^^^^^^ + +keyword arguments - keyword arguments - * tenant_id +* tenant_id example:: + keystone-manage tenant delete tenant_id=f2b7b39c860840dfa47d9ee4adffa0b3 -* tenant update +``tenant update`` +^^^^^^^^^^^^^^^^^ + +keyword arguments - keyword arguments - * description - * name - * tenant_id +* description +* name +* tenant_id example:: + keystone-manage tenant update \ tenant_id=f2b7b39c860840dfa47d9ee4adffa0b3 \ description="those other guys" \ @@ -151,60 +161,74 @@ example:: Users ----- -* user create +``user create`` +^^^^^^^^^^^^^^^ - keyword arguments - * name - * password - * email +keyword arguments + +* name +* password +* email example:: + keystone-manage user --ks-id-only create \ name=admin \ password=secrete \ email=admin@example.com -* user delete +``user delete`` +^^^^^^^^^^^^^^^ - keyword arguments +keyword arguments -* user list +``user list`` +^^^^^^^^^^^^^ - keyword arguments +keyword arguments -* user update_email +``user update_email`` +^^^^^^^^^^^^^^^^^^^^^ - keyword arguments +keyword arguments -* user update_enabled +``user update_enabled`` +^^^^^^^^^^^^^^^^^^^^^^^ - keyword arguments +keyword arguments -* user update_password +``user update_password`` +^^^^^^^^^^^^^^^^^^^^^^^^ - keyword arguments +keyword arguments -* user update_tenant +``user update_tenant`` +^^^^^^^^^^^^^^^^^^^^^^ - keyword arguments +keyword arguments Roles ----- -* role create +``role create`` +^^^^^^^^^^^^^^^ - keyword arguments - * name +keyword arguments + +* name exmaple:: + keystone-manage role --ks-id-only create name=Admin -* role add_user_to_tenant +``role add_user_to_tenant`` +^^^^^^^^^^^^^^^^^^^^^^^^^^^ - keyword arguments - * role_id - * user_id - * tenant_id +keyword arguments + +* role_id +* user_id +* tenant_id example:: @@ -213,22 +237,27 @@ example:: user_id=08741d8ed88242ca88d1f61484a0fe3b \ tenant_id=20601a7f1d94447daa4dff438cb1c209 -* role remove_user_from_tenant +``role remove_user_from_tenant`` +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ -* role get_user_role_refs +``role get_user_role_refs`` +^^^^^^^^^^^^^^^^^^^^^^^^^^^ Services -------- -* service create +``service create`` +^^^^^^^^^^^^^^^^^^ + +keyword arguments - keyword arguments - * name - * service_type - * description +* name +* service_type +* description example:: - keystone-manage service create \ + + keystone-manage service create \ name=nova \ service_type=compute \ description="Nova Compute Service" -- cgit From 22c3f8067ed7e480e5d06c67677a4f60d740a10d Mon Sep 17 00:00:00 2001 From: Joe Heck Date: Sun, 29 Jan 2012 14:14:09 -0800 Subject: moved notes from README.rst into docs/architecture.rst --- docs/source/architecture.rst | 228 +++++++++++++++++++++++++++++++------------ docs/source/developing.rst | 14 +++ 2 files changed, 179 insertions(+), 63 deletions(-) (limited to 'docs') diff --git a/docs/source/architecture.rst b/docs/source/architecture.rst index 21d9b895..b308a9e5 100644 --- a/docs/source/architecture.rst +++ b/docs/source/architecture.rst @@ -20,82 +20,184 @@ Keystone Architecture Much of the design is precipitated from the expectation that the auth backends for most deployments will actually be shims in front of existing user systems. -.........JOEEDIT.......... -Keystone has two major components: Authentication and a Service Catalog. +------------ +The Services +------------ -Authentication --------------- +Keystone is organized as a group of services exposed on one or many endpoints. +Many of these services are used in a combined fashion by the frontend, for +example an authenticate call will validate user/tenant credentials with the +Identity service and, upon success, create and return a token with the Token +service. -In providing a token-based authentication service for OpenStack, keystone -has several major concepts: -Tenant - A grouping used in OpenStack to contain relevant OpenStack services. A - tenant maps to a Nova "project-id", and in object storage, a tenant can - have multiple containers. Depending on the installation, a tenant can - represent a customer, account, organization, or project. +Identity +-------- -User - Represents an individual within OpenStack for the purposes of - authenticating them to OpenStack services. Users have credentials, and may - be assigned to one or more tenants. When authenticated, a token is - provided that is specific to a single tenant. +The Identity service provides auth credential validation and data about Users, +Tenants and Roles, as well as any associated metadata. + +In the basic case all this data is managed by the service, allowing the service +to manage all the CRUD associated with the data. + +In other cases, this data is pulled, by varying degrees, from an authoritative +backend service. An example of this would be when backending on LDAP. See +`LDAP Backend` below for more details. -Credentials - Password or other information that uniquely identifies a User to Keystone - for the purposes of providing a token. Token - A token is an arbitrary bit of text that is used to share authentication - with other OpenStack services so that Keystone can provide a central - location for authenticating users for access to OpenStack services. A - token may be "scoped" or "unscoped". A scoped token represents a user - authenticated to a Tenant, where an unscoped token represents just the - user. - - Tokens are valid for a limited amount of time and may be revoked at any - time. - -Role - A role is a set of permissions to access and use specific operations for - a given user when applied to a tenant. Roles are logical groupings of - those permissions to enable common permissions to be easily grouped and - bound to users associated with a given tenant. - -Service Catalog ---------------- +----- + +The Token service validates and manages Tokens used for authenticating requests +once a user/tenant's credentials have already been verified. + + +Catalog +------- + +The Catalog service provides an endpoint registry used for endpoint discovery. + + +Policy +------ + +The Policy service provides a rule-based authorization engine and the +associated rule management interface. + +---------- +Data Model +---------- + +Keystone was designed from the ground up to be amenable to multiple styles of +backends and as such many of the methods and data types will happily accept +more data than they know what to do with and pass them on to a backend. + +There are a few main data types: + + * **User**: has account credentials, is associated with one or more tenants + * **Tenant**: unit of ownership in openstack, contains one or more users + * **Role**: a first-class piece of metadata associated with many user-tenant pairs. + * **Token**: identifying credential associated with a user or user and tenant + * **Extras**: bucket of key-value metadata associated with a user-tenant pair. + * **Rule**: describes a set of requirements for performing an action. + +While the general data model allows a many-to-many relationship between Users +and Tenants and a many-to-one relationship between Extras and User-Tenant pairs, +the actual backend implementations take varying levels of advantage of that +functionality. + + +KVS Backend +----------- + +A simple backend interface meant to be further backended on anything that can +support primary key lookups, the most trivial implementation being an in-memory +dict. + +Supports all features of the general data model. + + +PAM Backend +----------- + +Extra simple backend that uses the current system's PAM service to authenticate, +providing a one-to-one relationship between Users and Tenants with the `root` +User also having the 'admin' role. + + +Templated Backend +----------------- + +Largely designed for a common use case around service catalogs in the Keystone +project, a Catalog backend that simply expands pre-configured templates to +provide catalog data. -Keystone also provides a list of REST API endpoints as a definitive list for -an OpenStack installation. Key concepts include: +Example paste.deploy config (uses $ instead of % to avoid ConfigParser's +interpolation):: -Service - An OpenStack service such as nova, swift, glance, or keystone. A service - may have one of more endpoints through which users can interact with - OpenStack services and resources. + [DEFAULT] + catalog.RegionOne.identity.publicURL = http://localhost:$(public_port)s/v2.0 + catalog.RegionOne.identity.adminURL = http://localhost:$(public_port)s/v2.0 + catalog.RegionOne.identity.internalURL = http://localhost:$(public_port)s/v2.0 + catalog.RegionOne.identity.name = 'Identity Service' + + +---------------- +Approach to CRUD +---------------- + +While it is expected that any "real" deployment at a large company will manage +their users, tenants and other metadata in their existing user systems, a +variety of CRUD operations are provided for the sake of development and testing. + +CRUD is treated as an extension or additional feature to the core feature set in +that it is not required that a backend support it. + + +---------------------------------- +Approach to Authorization (Policy) +---------------------------------- + +Various components in the system require that different actions are allowed +based on whether the user is authorized to perform that action. + +For the purposes of Keystone Light there are only a couple levels of +authorization being checked for: + + * Require that the performing user is considered an admin. + * Require that the performing user matches the user being referenced. + +Other systems wishing to use the policy engine will require additional styles +of checks and will possibly write completely custom backends. Backends included +in Keystone Light are: + + +Trivial True +------------ + +Allows all actions. + + +Simple Match +------------ + +Given a list of matches to check for, simply verify that the credentials +contain the matches. For example:: + + credentials = {'user_id': 'foo', 'is_admin': 1, 'roles': ['nova:netadmin']} + + # An admin only call: + policy_api.can_haz(('is_admin:1',), credentials) + + # An admin or owner call: + policy_api.can_haz(('is_admin:1', 'user_id:foo'), + credentials) + + # A netadmin call: + policy_api.can_haz(('roles:nova:netadmin',), + credentials) + + +Credentials are generally built from the user metadata in the 'extras' part +of the Identity API. So, adding a 'role' to the user just means adding the role +to the user metadata. + + +Capability RBAC +--------------- -Endpoint - A network accessible address (typically a URL) that represents the API - interface to an OpenStack service. Endpoints may also be grouped into - templates which represent a group of consumable OpenStack services - available across regions. +(Not yet implemented.) -Template - A collection of endpoints representing a set of consumable OpenStack - service endpoints. +Another approach to authorization can be action-based, with a mapping of roles +to which capabilities are allowed for that role. For example:: -Components of Keystone ----------------------- + credentials = {'user_id': 'foo', 'is_admin': 1, 'roles': ['nova:netadmin']} -Keystone includes a command-line interface which interacts with the Keystone -API for administrating keystone and related services. + # add a policy + policy_api.add_policy('action:nova:add_network', ('roles:nova:netadmin',)) -* keystone - runs both keystone-admin and keystone-service -* keystone-admin - the administrative API for manipulating keystone -* keystone-service - the user oriented API for authentication -* keystone-manage - the command line interface to manipulate keystone + policy_api.can_haz(('action:nova:add_network',), credentials) -Keystone also includes WSGI middelware to provide authentication support -for Nova and Swift. -Keystone uses a built-in SQLite datastore - and may use an external LDAP -service to authenticate users instead of using stored credentials. +In the backend this would look up the policy for 'action:nova:add_network' and +then do what is effectively a 'Simple Match' style match against the creds. diff --git a/docs/source/developing.rst b/docs/source/developing.rst index b19fec24..48ba2873 100644 --- a/docs/source/developing.rst +++ b/docs/source/developing.rst @@ -107,3 +107,17 @@ or the `OpenStack Integration Testing Project`_. .. _devstack: http://devstack.org/ .. _OpenStack Continuous Integration Project: https://github.com/openstack/openstack-ci .. _OpenStack Integration Testing Project: https://github.com/openstack/tempest + +Building the Documentation +========================== + +The documentation is all generated with Sphinx from within the docs directory. +To generate the full set of HTML documentation: + + cd docs + make autodoc + make html + make man + +the results are in the docs/build/html and docs/build/man directories +respectively. -- cgit From d1f4ddcb81d470401f5b6c80b66ac9649e3c224e Mon Sep 17 00:00:00 2001 From: Joe Heck Date: Sun, 29 Jan 2012 14:36:11 -0800 Subject: adding in testing details --- docs/source/developing.rst | 13 +++++++++++-- 1 file changed, 11 insertions(+), 2 deletions(-) (limited to 'docs') diff --git a/docs/source/developing.rst b/docs/source/developing.rst index 48ba2873..344a6e8b 100644 --- a/docs/source/developing.rst +++ b/docs/source/developing.rst @@ -70,7 +70,15 @@ light integration testing to verify the keystone API against other projects. Test Structure -------------- -UPDATE THIS... +``./run_test.sh`` uses it's python cohort (``run_tests.py``) to iterate through the ``tests`` directory, using Nosetest to collect the tests and invoke them using an +OpenStack custom test running that displays the tests as well as the time taken to +run those tests. + +Within the tests directory, the general structure of the tests is a basic set of tests represented under a test class, and then subclasses of those tests under other classes with different configurations to drive different backends through the APIs. + +For example, ``test_backend.py`` has a sequence of tests under the class ``IdentityTests`` that will work with the default drivers as configured in this projects etc/ directory. ``test_backend_sql.py`` subclasses those tests, changing the configuration by overriding with configuration files stored in the tests directory aimed at enabling the SQL backend for the Identity module. + +Likewise, ``test_cli.py`` takes advantage of the tests written aainst ``test_keystoneclient`` to verify the same tests function through different drivers. Testing Schema Migrations ------------------------- @@ -92,8 +100,9 @@ This command references to a SQLite database (test.db) to be used. Depending on Writing Tests ------------- -UPDATE THIS... +To add tests covering all drivers, update the base test class (``test_backend.py``, ``test_legacy_compat.py``, and ``test_keystoneclient.py``). +To add new drivers, subclass the ``test_backend.py`` (look towards ``test_backend_sql.py`` or ``test_backend_kvs.py`` for examples) and update the configuration of the test class in ``setUp()``. Further Testing --------------- -- cgit From 9d7d898586566cf2f7c21846961f67a773c2ee6c Mon Sep 17 00:00:00 2001 From: Joe Heck Date: Mon, 30 Jan 2012 19:53:08 +0000 Subject: shifting contents from _static to static --- docs/source/_static/basic.css | 416 ------------------------------------ docs/source/_static/default.css | 230 -------------------- docs/source/_static/jquery.tweet.js | 154 ------------- docs/source/_static/tweaks.css | 65 ------ docs/source/conf.py | 2 +- docs/source/static/basic.css | 416 ++++++++++++++++++++++++++++++++++++ docs/source/static/default.css | 230 ++++++++++++++++++++ docs/source/static/jquery.tweet.js | 154 +++++++++++++ docs/source/static/tweaks.css | 65 ++++++ 9 files changed, 866 insertions(+), 866 deletions(-) delete mode 100644 docs/source/_static/basic.css delete mode 100644 docs/source/_static/default.css delete mode 100644 docs/source/_static/jquery.tweet.js delete mode 100644 docs/source/_static/tweaks.css create mode 100644 docs/source/static/basic.css create mode 100644 docs/source/static/default.css create mode 100644 docs/source/static/jquery.tweet.js create mode 100644 docs/source/static/tweaks.css (limited to 'docs') diff --git a/docs/source/_static/basic.css b/docs/source/_static/basic.css deleted file mode 100644 index d909ce37..00000000 --- a/docs/source/_static/basic.css +++ /dev/null @@ -1,416 +0,0 @@ -/** - * Sphinx stylesheet -- basic theme - * ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - */ - -/* -- main layout ----------------------------------------------------------- */ - -div.clearer { - clear: both; -} - -/* -- relbar ---------------------------------------------------------------- */ - -div.related { - width: 100%; - font-size: 90%; -} - -div.related h3 { - display: none; -} - -div.related ul { - margin: 0; - padding: 0 0 0 10px; - list-style: none; -} - -div.related li { - display: inline; -} - -div.related li.right { - float: right; - margin-right: 5px; -} - -/* -- sidebar --------------------------------------------------------------- */ - -div.sphinxsidebarwrapper { - padding: 10px 5px 0 10px; -} - -div.sphinxsidebar { - float: left; - width: 230px; - margin-left: -100%; - font-size: 90%; -} - -div.sphinxsidebar ul { - list-style: none; -} - -div.sphinxsidebar ul ul, -div.sphinxsidebar ul.want-points { - margin-left: 20px; - list-style: square; -} - -div.sphinxsidebar ul ul { - margin-top: 0; - margin-bottom: 0; -} - -div.sphinxsidebar form { - margin-top: 10px; -} - -div.sphinxsidebar input { - border: 1px solid #98dbcc; - font-family: sans-serif; - font-size: 1em; -} - -img { - border: 0; -} - -/* -- search page ----------------------------------------------------------- */ - -ul.search { - margin: 10px 0 0 20px; - padding: 0; -} - -ul.search li { - padding: 5px 0 5px 20px; - background-image: url(file.png); - background-repeat: no-repeat; - background-position: 0 7px; -} - -ul.search li a { - font-weight: bold; -} - -ul.search li div.context { - color: #888; - margin: 2px 0 0 30px; - text-align: left; -} - -ul.keywordmatches li.goodmatch a { - font-weight: bold; -} - -/* -- index page ------------------------------------------------------------ */ - -table.contentstable { - width: 90%; -} - -table.contentstable p.biglink { - line-height: 150%; -} - -a.biglink { - font-size: 1.3em; -} - -span.linkdescr { - font-style: italic; - padding-top: 5px; - font-size: 90%; -} - -/* -- general index --------------------------------------------------------- */ - -table.indextable td { - text-align: left; - vertical-align: top; -} - -table.indextable dl, table.indextable dd { - margin-top: 0; - margin-bottom: 0; -} - -table.indextable tr.pcap { - height: 10px; -} - -table.indextable tr.cap { - margin-top: 10px; - background-color: #f2f2f2; -} - -img.toggler { - margin-right: 3px; - margin-top: 3px; - cursor: pointer; -} - -/* -- general body styles --------------------------------------------------- */ - -a.headerlink { - visibility: hidden; -} - -h1:hover > a.headerlink, -h2:hover > a.headerlink, -h3:hover > a.headerlink, -h4:hover > a.headerlink, -h5:hover > a.headerlink, -h6:hover > a.headerlink, -dt:hover > a.headerlink { - visibility: visible; -} - -div.body p.caption { - text-align: inherit; -} - -div.body td { - text-align: left; -} - -.field-list ul { - padding-left: 1em; -} - -.first { -} - -p.rubric { - margin-top: 30px; - font-weight: bold; -} - -/* -- sidebars -------------------------------------------------------------- */ - -div.sidebar { - margin: 0 0 0.5em 1em; - border: 1px solid #ddb; - padding: 7px 7px 0 7px; - background-color: #ffe; - width: 40%; - float: right; -} - -p.sidebar-title { - font-weight: bold; -} - -/* -- topics ---------------------------------------------------------------- */ - -div.topic { - border: 1px solid #ccc; - padding: 7px 7px 0 7px; - margin: 10px 0 10px 0; -} - -p.topic-title { - font-size: 1.1em; - font-weight: bold; - margin-top: 10px; -} - -/* -- admonitions ----------------------------------------------------------- */ - -div.admonition { - margin-top: 10px; - margin-bottom: 10px; - padding: 7px; -} - -div.admonition dt { - font-weight: bold; -} - -div.admonition dl { - margin-bottom: 0; -} - -p.admonition-title { - margin: 0px 10px 5px 0px; - font-weight: bold; -} - -div.body p.centered { - text-align: center; - margin-top: 25px; -} - -/* -- tables ---------------------------------------------------------------- */ - -table.docutils { - border: 0; - border-collapse: collapse; -} - -table.docutils td, table.docutils th { - padding: 1px 8px 1px 0; - border-top: 0; - border-left: 0; - border-right: 0; - border-bottom: 1px solid #aaa; -} - -table.field-list td, table.field-list th { - border: 0 !important; -} - -table.footnote td, table.footnote th { - border: 0 !important; -} - -th { - text-align: left; - padding-right: 5px; -} - -/* -- other body styles ----------------------------------------------------- */ - -dl { - margin-bottom: 15px; -} - -dd p { - margin-top: 0px; -} - -dd ul, dd table { - margin-bottom: 10px; -} - -dd { - margin-top: 3px; - margin-bottom: 10px; - margin-left: 30px; -} - -dt:target, .highlight { - background-color: #fbe54e; -} - -dl.glossary dt { - font-weight: bold; - font-size: 1.1em; -} - -.field-list ul { - margin: 0; - padding-left: 1em; -} - -.field-list p { - margin: 0; -} - -.refcount { - color: #060; -} - -.optional { - font-size: 1.3em; -} - -.versionmodified { - font-style: italic; -} - -.system-message { - background-color: #fda; - padding: 5px; - border: 3px solid red; -} - -.footnote:target { - background-color: #ffa -} - -.line-block { - display: block; - margin-top: 1em; - margin-bottom: 1em; -} - -.line-block .line-block { - margin-top: 0; - margin-bottom: 0; - margin-left: 1.5em; -} - -/* -- code displays --------------------------------------------------------- */ - -pre { - overflow: auto; -} - -td.linenos pre { - padding: 5px 0px; - border: 0; - background-color: transparent; - color: #aaa; -} - -table.highlighttable { - margin-left: 0.5em; -} - -table.highlighttable td { - padding: 0 0.5em 0 0.5em; -} - -tt.descname { - background-color: transparent; - font-weight: bold; - font-size: 1.2em; -} - -tt.descclassname { - background-color: transparent; -} - -tt.xref, a tt { - background-color: transparent; - font-weight: bold; -} - -h1 tt, h2 tt, h3 tt, h4 tt, h5 tt, h6 tt { - background-color: transparent; -} - -/* -- math display ---------------------------------------------------------- */ - -img.math { - vertical-align: middle; -} - -div.body div.math p { - text-align: center; -} - -span.eqno { - float: right; -} - -/* -- printout stylesheet --------------------------------------------------- */ - -@media print { - div.document, - div.documentwrapper, - div.bodywrapper { - margin: 0 !important; - width: 100%; - } - - div.sphinxsidebar, - div.related, - div.footer, - #top-link { - display: none; - } -} diff --git a/docs/source/_static/default.css b/docs/source/_static/default.css deleted file mode 100644 index c8091ecb..00000000 --- a/docs/source/_static/default.css +++ /dev/null @@ -1,230 +0,0 @@ -/** - * Sphinx stylesheet -- default theme - * ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - */ - -@import url("basic.css"); - -/* -- page layout ----------------------------------------------------------- */ - -body { - font-family: sans-serif; - font-size: 100%; - background-color: #11303d; - color: #000; - margin: 0; - padding: 0; -} - -div.document { - background-color: #1c4e63; -} - -div.documentwrapper { - float: left; - width: 100%; -} - -div.bodywrapper { - margin: 0 0 0 230px; -} - -div.body { - background-color: #ffffff; - color: #000000; - padding: 0 20px 30px 20px; -} - -div.footer { - color: #ffffff; - width: 100%; - padding: 9px 0 9px 0; - text-align: center; - font-size: 75%; -} - -div.footer a { - color: #ffffff; - text-decoration: underline; -} - -div.related { - background-color: #133f52; - line-height: 30px; - color: #ffffff; -} - -div.related a { - color: #ffffff; -} - -div.sphinxsidebar { -} - -div.sphinxsidebar h3 { - font-family: 'Trebuchet MS', sans-serif; - color: #ffffff; - font-size: 1.4em; - font-weight: normal; - margin: 0; - padding: 0; -} - -div.sphinxsidebar h3 a { - color: #ffffff; -} - -div.sphinxsidebar h4 { - font-family: 'Trebuchet MS', sans-serif; - color: #ffffff; - font-size: 1.3em; - font-weight: normal; - margin: 5px 0 0 0; - padding: 0; -} - -div.sphinxsidebar p { - color: #ffffff; -} - -div.sphinxsidebar p.topless { - margin: 5px 10px 10px 10px; -} - -div.sphinxsidebar ul { - margin: 10px; - padding: 0; - color: #ffffff; -} - -div.sphinxsidebar a { - color: #98dbcc; -} - -div.sphinxsidebar input { - border: 1px solid #98dbcc; - font-family: sans-serif; - font-size: 1em; -} - -/* -- body styles ----------------------------------------------------------- */ - -a { - color: #355f7c; - text-decoration: none; -} - -a:hover { - text-decoration: underline; -} - -div.body p, div.body dd, div.body li { - text-align: left; - line-height: 130%; -} - -div.body h1, -div.body h2, -div.body h3, -div.body h4, -div.body h5, -div.body h6 { - font-family: 'Trebuchet MS', sans-serif; - background-color: #f2f2f2; - font-weight: normal; - color: #20435c; - border-bottom: 1px solid #ccc; - margin: 20px -20px 10px -20px; - padding: 3px 0 3px 10px; -} - -div.body h1 { margin-top: 0; font-size: 200%; } -div.body h2 { font-size: 160%; } -div.body h3 { font-size: 140%; } -div.body h4 { font-size: 120%; } -div.body h5 { font-size: 110%; } -div.body h6 { font-size: 100%; } - -a.headerlink { - color: #c60f0f; - font-size: 0.8em; - padding: 0 4px 0 4px; - text-decoration: none; -} - -a.headerlink:hover { - background-color: #c60f0f; - color: white; -} - -div.body p, div.body dd, div.body li { - text-align: left; - line-height: 130%; -} - -div.admonition p.admonition-title + p { - display: inline; -} - -div.admonition p { - margin-bottom: 5px; -} - -div.admonition pre { - margin-bottom: 5px; -} - -div.admonition ul, div.admonition ol { - margin-bottom: 5px; -} - -div.note { - background-color: #eee; - border: 1px solid #ccc; -} - -div.seealso { - background-color: #ffc; - border: 1px solid #ff6; -} - -div.topic { - background-color: #eee; -} - -div.warning { - background-color: #ffe4e4; - border: 1px solid #f66; -} - -p.admonition-title { - display: inline; -} - -p.admonition-title:after { - content: ":"; -} - -pre { - padding: 5px; - background-color: #eeffcc; - color: #333333; - line-height: 120%; - border: 1px solid #ac9; - border-left: none; - border-right: none; -} - -tt { - background-color: #ecf0f3; - padding: 0 1px 0 1px; - font-size: 0.95em; -} - -.warning tt { - background: #efc2c2; -} - -.note tt { - background: #d6d6d6; -} diff --git a/docs/source/_static/jquery.tweet.js b/docs/source/_static/jquery.tweet.js deleted file mode 100644 index c93fea87..00000000 --- a/docs/source/_static/jquery.tweet.js +++ /dev/null @@ -1,154 +0,0 @@ -(function($) { - - $.fn.tweet = function(o){ - var s = { - username: ["seaofclouds"], // [string] required, unless you want to display our tweets. :) it can be an array, just do ["username1","username2","etc"] - list: null, //[string] optional name of list belonging to username - avatar_size: null, // [integer] height and width of avatar if displayed (48px max) - count: 3, // [integer] how many tweets to display? - intro_text: null, // [string] do you want text BEFORE your your tweets? - outro_text: null, // [string] do you want text AFTER your tweets? - join_text: null, // [string] optional text in between date and tweet, try setting to "auto" - auto_join_text_default: "i said,", // [string] auto text for non verb: "i said" bullocks - auto_join_text_ed: "i", // [string] auto text for past tense: "i" surfed - auto_join_text_ing: "i am", // [string] auto tense for present tense: "i was" surfing - auto_join_text_reply: "i replied to", // [string] auto tense for replies: "i replied to" @someone "with" - auto_join_text_url: "i was looking at", // [string] auto tense for urls: "i was looking at" http:... - loading_text: null, // [string] optional loading text, displayed while tweets load - query: null // [string] optional search query - }; - - if(o) $.extend(s, o); - - $.fn.extend({ - linkUrl: function() { - var returning = []; - var regexp = /((ftp|http|https):\/\/(\w+:{0,1}\w*@)?(\S+)(:[0-9]+)?(\/|\/([\w#!:.?+=&%@!\-\/]))?)/gi; - this.each(function() { - returning.push(this.replace(regexp,"$1")); - }); - return $(returning); - }, - linkUser: function() { - var returning = []; - var regexp = /[\@]+([A-Za-z0-9-_]+)/gi; - this.each(function() { - returning.push(this.replace(regexp,"@$1")); - }); - return $(returning); - }, - linkHash: function() { - var returning = []; - var regexp = / [\#]+([A-Za-z0-9-_]+)/gi; - this.each(function() { - returning.push(this.replace(regexp, ' #$1')); - }); - return $(returning); - }, - capAwesome: function() { - var returning = []; - this.each(function() { - returning.push(this.replace(/\b(awesome)\b/gi, '$1')); - }); - return $(returning); - }, - capEpic: function() { - var returning = []; - this.each(function() { - returning.push(this.replace(/\b(epic)\b/gi, '$1')); - }); - return $(returning); - }, - makeHeart: function() { - var returning = []; - this.each(function() { - returning.push(this.replace(/(<)+[3]/gi, "♥")); - }); - return $(returning); - } - }); - - function relative_time(time_value) { - var parsed_date = Date.parse(time_value); - var relative_to = (arguments.length > 1) ? arguments[1] : new Date(); - var delta = parseInt((relative_to.getTime() - parsed_date) / 1000); - var pluralize = function (singular, n) { - return '' + n + ' ' + singular + (n == 1 ? '' : 's'); - }; - if(delta < 60) { - return 'less than a minute ago'; - } else if(delta < (45*60)) { - return 'about ' + pluralize("minute", parseInt(delta / 60)) + ' ago'; - } else if(delta < (24*60*60)) { - return 'about ' + pluralize("hour", parseInt(delta / 3600)) + ' ago'; - } else { - return 'about ' + pluralize("day", parseInt(delta / 86400)) + ' ago'; - } - } - - function build_url() { - var proto = ('https:' == document.location.protocol ? 'https:' : 'http:'); - if (s.list) { - return proto+"//api.twitter.com/1/"+s.username[0]+"/lists/"+s.list+"/statuses.json?per_page="+s.count+"&callback=?"; - } else if (s.query == null && s.username.length == 1) { - return proto+'//twitter.com/status/user_timeline/'+s.username[0]+'.json?count='+s.count+'&callback=?'; - } else { - var query = (s.query || 'from:'+s.username.join('%20OR%20from:')); - return proto+'//search.twitter.com/search.json?&q='+query+'&rpp='+s.count+'&callback=?'; - } - } - - return this.each(function(){ - var list = $('
      ').appendTo(this); - var intro = '

      '+s.intro_text+'

      '; - var outro = '

      '+s.outro_text+'

      '; - var loading = $('

      '+s.loading_text+'

      '); - - if(typeof(s.username) == "string"){ - s.username = [s.username]; - } - - if (s.loading_text) $(this).append(loading); - $.getJSON(build_url(), function(data){ - if (s.loading_text) loading.remove(); - if (s.intro_text) list.before(intro); - $.each((data.results || data), function(i,item){ - // auto join text based on verb tense and content - if (s.join_text == "auto") { - if (item.text.match(/^(@([A-Za-z0-9-_]+)) .*/i)) { - var join_text = s.auto_join_text_reply; - } else if (item.text.match(/(^\w+:\/\/[A-Za-z0-9-_]+\.[A-Za-z0-9-_:%&\?\/.=]+) .*/i)) { - var join_text = s.auto_join_text_url; - } else if (item.text.match(/^((\w+ed)|just) .*/im)) { - var join_text = s.auto_join_text_ed; - } else if (item.text.match(/^(\w*ing) .*/i)) { - var join_text = s.auto_join_text_ing; - } else { - var join_text = s.auto_join_text_default; - } - } else { - var join_text = s.join_text; - }; - - var from_user = item.from_user || item.user.screen_name; - var profile_image_url = item.profile_image_url || item.user.profile_image_url; - var join_template = ' '+join_text+' '; - var join = ((s.join_text) ? join_template : ' '); - var avatar_template = ''+from_user+'\'s avatar'; - var avatar = (s.avatar_size ? avatar_template : ''); - var date = ''+relative_time(item.created_at)+''; - var text = '' +$([item.text]).linkUrl().linkUser().linkHash().makeHeart().capAwesome().capEpic()[0]+ ''; - - // until we create a template option, arrange the items below to alter a tweet's display. - list.append('
    • ' + avatar + date + join + text + '
      • '); - - list.children('li:first').addClass('tweet_first'); - list.children('li:odd').addClass('tweet_even'); - list.children('li:even').addClass('tweet_odd'); - }); - if (s.outro_text) list.after(outro); - }); - - }); - }; -})(jQuery); \ No newline at end of file diff --git a/docs/source/_static/tweaks.css b/docs/source/_static/tweaks.css deleted file mode 100644 index 16cd6e76..00000000 --- a/docs/source/_static/tweaks.css +++ /dev/null @@ -1,65 +0,0 @@ -ul.todo_list { - list-style-type: none; - margin: 0; - padding: 0; -} - -ul.todo_list li { - display: block; - margin: 0; - padding: 7px 0; - border-top: 1px solid #eee; -} - -ul.todo_list li p { - display: inline; -} - -ul.todo_list li p.link { - font-weight: bold; -} - -ul.todo_list li p.details { - font-style: italic; -} - -ul.todo_list li { -} - -div.admonition { - border: 1px solid #8F1000; -} - -div.admonition p.admonition-title { - background-color: #8F1000; - border-bottom: 1px solid #8E8E8E; -} - -a { - color: #CF2F19; -} - -div.related ul li a { - color: #CF2F19; -} - -div.sphinxsidebar h4 { - background-color:#8E8E8E; - border:1px solid #255E6E; - color:white; - font-size:1em; - margin:1em 0 0.5em; - padding:0.1em 0 0.1em 0.5em; -} - -em { - font-style: normal; -} - -table.docutils { - font-size: 11px; -} - -a tt { - color:#CF2F19; -} \ No newline at end of file diff --git a/docs/source/conf.py b/docs/source/conf.py index 63515726..edae0b8a 100644 --- a/docs/source/conf.py +++ b/docs/source/conf.py @@ -144,7 +144,7 @@ html_theme = '_theme' # Add any paths that contain custom static files (such as style sheets) here, # relative to this directory. They are copied after the builtin static files, # so a file named "default.css" will overwrite the builtin "default.css". -html_static_path = ['_static', 'images'] +html_static_path = ['static', 'images'] # If not '', a 'Last updated on:' timestamp is inserted at every page bottom, # using the given strftime format. diff --git a/docs/source/static/basic.css b/docs/source/static/basic.css new file mode 100644 index 00000000..d909ce37 --- /dev/null +++ b/docs/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/docs/source/static/default.css b/docs/source/static/default.css new file mode 100644 index 00000000..c8091ecb --- /dev/null +++ b/docs/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/docs/source/static/jquery.tweet.js b/docs/source/static/jquery.tweet.js new file mode 100644 index 00000000..c93fea87 --- /dev/null +++ b/docs/source/static/jquery.tweet.js @@ -0,0 +1,154 @@ +(function($) { + + $.fn.tweet = function(o){ + var s = { + username: ["seaofclouds"], // [string] required, unless you want to display our tweets. :) it can be an array, just do ["username1","username2","etc"] + list: null, //[string] optional name of list belonging to username + avatar_size: null, // [integer] height and width of avatar if displayed (48px max) + count: 3, // [integer] how many tweets to display? + intro_text: null, // [string] do you want text BEFORE your your tweets? + outro_text: null, // [string] do you want text AFTER your tweets? + join_text: null, // [string] optional text in between date and tweet, try setting to "auto" + auto_join_text_default: "i said,", // [string] auto text for non verb: "i said" bullocks + auto_join_text_ed: "i", // [string] auto text for past tense: "i" surfed + auto_join_text_ing: "i am", // [string] auto tense for present tense: "i was" surfing + auto_join_text_reply: "i replied to", // [string] auto tense for replies: "i replied to" @someone "with" + auto_join_text_url: "i was looking at", // [string] auto tense for urls: "i was looking at" http:... + loading_text: null, // [string] optional loading text, displayed while tweets load + query: null // [string] optional search query + }; + + if(o) $.extend(s, o); + + $.fn.extend({ + linkUrl: function() { + var returning = []; + var regexp = /((ftp|http|https):\/\/(\w+:{0,1}\w*@)?(\S+)(:[0-9]+)?(\/|\/([\w#!:.?+=&%@!\-\/]))?)/gi; + this.each(function() { + returning.push(this.replace(regexp,"$1")); + }); + return $(returning); + }, + linkUser: function() { + var returning = []; + var regexp = /[\@]+([A-Za-z0-9-_]+)/gi; + this.each(function() { + returning.push(this.replace(regexp,"@$1")); + }); + return $(returning); + }, + linkHash: function() { + var returning = []; + var regexp = / [\#]+([A-Za-z0-9-_]+)/gi; + this.each(function() { + returning.push(this.replace(regexp, ' #$1')); + }); + return $(returning); + }, + capAwesome: function() { + var returning = []; + this.each(function() { + returning.push(this.replace(/\b(awesome)\b/gi, '$1')); + }); + return $(returning); + }, + capEpic: function() { + var returning = []; + this.each(function() { + returning.push(this.replace(/\b(epic)\b/gi, '$1')); + }); + return $(returning); + }, + makeHeart: function() { + var returning = []; + this.each(function() { + returning.push(this.replace(/(<)+[3]/gi, "♥")); + }); + return $(returning); + } + }); + + function relative_time(time_value) { + var parsed_date = Date.parse(time_value); + var relative_to = (arguments.length > 1) ? arguments[1] : new Date(); + var delta = parseInt((relative_to.getTime() - parsed_date) / 1000); + var pluralize = function (singular, n) { + return '' + n + ' ' + singular + (n == 1 ? '' : 's'); + }; + if(delta < 60) { + return 'less than a minute ago'; + } else if(delta < (45*60)) { + return 'about ' + pluralize("minute", parseInt(delta / 60)) + ' ago'; + } else if(delta < (24*60*60)) { + return 'about ' + pluralize("hour", parseInt(delta / 3600)) + ' ago'; + } else { + return 'about ' + pluralize("day", parseInt(delta / 86400)) + ' ago'; + } + } + + function build_url() { + var proto = ('https:' == document.location.protocol ? 'https:' : 'http:'); + if (s.list) { + return proto+"//api.twitter.com/1/"+s.username[0]+"/lists/"+s.list+"/statuses.json?per_page="+s.count+"&callback=?"; + } else if (s.query == null && s.username.length == 1) { + return proto+'//twitter.com/status/user_timeline/'+s.username[0]+'.json?count='+s.count+'&callback=?'; + } else { + var query = (s.query || 'from:'+s.username.join('%20OR%20from:')); + return proto+'//search.twitter.com/search.json?&q='+query+'&rpp='+s.count+'&callback=?'; + } + } + + return this.each(function(){ + var list = $('
        ').appendTo(this); + var intro = '

        '+s.intro_text+'

        '; + var outro = '

        '+s.outro_text+'

        '; + var loading = $('

        '+s.loading_text+'

        '); + + if(typeof(s.username) == "string"){ + s.username = [s.username]; + } + + if (s.loading_text) $(this).append(loading); + $.getJSON(build_url(), function(data){ + if (s.loading_text) loading.remove(); + if (s.intro_text) list.before(intro); + $.each((data.results || data), function(i,item){ + // auto join text based on verb tense and content + if (s.join_text == "auto") { + if (item.text.match(/^(@([A-Za-z0-9-_]+)) .*/i)) { + var join_text = s.auto_join_text_reply; + } else if (item.text.match(/(^\w+:\/\/[A-Za-z0-9-_]+\.[A-Za-z0-9-_:%&\?\/.=]+) .*/i)) { + var join_text = s.auto_join_text_url; + } else if (item.text.match(/^((\w+ed)|just) .*/im)) { + var join_text = s.auto_join_text_ed; + } else if (item.text.match(/^(\w*ing) .*/i)) { + var join_text = s.auto_join_text_ing; + } else { + var join_text = s.auto_join_text_default; + } + } else { + var join_text = s.join_text; + }; + + var from_user = item.from_user || item.user.screen_name; + var profile_image_url = item.profile_image_url || item.user.profile_image_url; + var join_template = ' '+join_text+' '; + var join = ((s.join_text) ? join_template : ' '); + var avatar_template = ''+from_user+'\'s avatar'; + var avatar = (s.avatar_size ? avatar_template : ''); + var date = ''+relative_time(item.created_at)+''; + var text = '' +$([item.text]).linkUrl().linkUser().linkHash().makeHeart().capAwesome().capEpic()[0]+ ''; + + // until we create a template option, arrange the items below to alter a tweet's display. + list.append('
      • ' + avatar + date + join + text + '
        • '); + + list.children('li:first').addClass('tweet_first'); + list.children('li:odd').addClass('tweet_even'); + list.children('li:even').addClass('tweet_odd'); + }); + if (s.outro_text) list.after(outro); + }); + + }); + }; +})(jQuery); \ No newline at end of file diff --git a/docs/source/static/tweaks.css b/docs/source/static/tweaks.css new file mode 100644 index 00000000..16cd6e76 --- /dev/null +++ b/docs/source/static/tweaks.css @@ -0,0 +1,65 @@ +ul.todo_list { + list-style-type: none; + margin: 0; + padding: 0; +} + +ul.todo_list li { + display: block; + margin: 0; + padding: 7px 0; + border-top: 1px solid #eee; +} + +ul.todo_list li p { + display: inline; +} + +ul.todo_list li p.link { + font-weight: bold; +} + +ul.todo_list li p.details { + font-style: italic; +} + +ul.todo_list li { +} + +div.admonition { + border: 1px solid #8F1000; +} + +div.admonition p.admonition-title { + background-color: #8F1000; + border-bottom: 1px solid #8E8E8E; +} + +a { + color: #CF2F19; +} + +div.related ul li a { + color: #CF2F19; +} + +div.sphinxsidebar h4 { + background-color:#8E8E8E; + border:1px solid #255E6E; + color:white; + font-size:1em; + margin:1em 0 0.5em; + padding:0.1em 0 0.1em 0.5em; +} + +em { + font-style: normal; +} + +table.docutils { + font-size: 11px; +} + +a tt { + color:#CF2F19; +} \ No newline at end of file -- cgit From 8d695b83df68367be9172f0659a90a844680039b Mon Sep 17 00:00:00 2001 From: Joe Heck Date: Mon, 30 Jan 2012 20:22:34 +0000 Subject: removing unused images, cleaning up RST in docstrings from sphinx warnings --- docs/source/configuration.rst | 36 ++-- docs/source/images/305.svg | 158 ----------------- docs/source/images/both.svg | 135 --------------- docs/source/images/graphs_delegate_accept.svg | 52 ------ docs/source/images/graphs_separate.svg | 30 ---- docs/source/images/graphs_standard_accept.svg | 51 ------ docs/source/images/graphs_standard_reject.svg | 39 ----- docs/source/images/graphs_together.svg | 24 --- docs/source/images/layouts.svg | 215 ----------------------- docs/source/images/mapper.svg | 237 ------------------------- docs/source/images/proxyAuth.svg | 238 -------------------------- 11 files changed, 21 insertions(+), 1194 deletions(-) delete mode 100644 docs/source/images/305.svg delete mode 100644 docs/source/images/both.svg delete mode 100644 docs/source/images/graphs_delegate_accept.svg delete mode 100644 docs/source/images/graphs_separate.svg delete mode 100644 docs/source/images/graphs_standard_accept.svg delete mode 100644 docs/source/images/graphs_standard_reject.svg delete mode 100644 docs/source/images/graphs_together.svg delete mode 100644 docs/source/images/layouts.svg delete mode 100644 docs/source/images/mapper.svg delete mode 100644 docs/source/images/proxyAuth.svg (limited to 'docs') diff --git a/docs/source/configuration.rst b/docs/source/configuration.rst index 410e7b1b..782e9fb5 100644 --- a/docs/source/configuration.rst +++ b/docs/source/configuration.rst @@ -31,7 +31,7 @@ initializing data into keystone using the command line client. Keystone Configuration File =========================== -The keystone configuration file is an 'ini' file format with sections, +The keystone configuration file is an 'ini' file format with sections, extended from Paste_, a common system used to configure python WSGI based applications. In addition to the paste config entries, general configuration values are stored under [DEFAULT] and [sql], and then drivers for the various @@ -44,7 +44,7 @@ The driver sections include: * ``[policy]`` - the python module that drives the policy system for RBAC * ``[ec2]`` - the python module providing the EC2 translations for OpenStack -The keystone configuration file is expected to be named ``keystone.conf``. +The keystone configuration file is expected to be named ``keystone.conf``. When starting up Keystone, you can specify a different configuration file to use with ``--config-file``. If you do **not** specify a configuration file, keystone will look in the following directories for a configuration file, in @@ -57,7 +57,7 @@ order: Logging is configured externally to the rest of keystone, the file specifying the logging configuration is in the [DEFAULT] section of the keystone conf -file under ``log_config``. If you wish to route all your logging through +file under ``log_config``. If you wish to route all your logging through syslog, there is a ``use_syslog`` option also in the [DEFAULT] section that easy. @@ -81,20 +81,26 @@ Sample Configuration Files Initializing Keystone ===================== -Keystone must be running in order to initialize data within it. This is because -the keystone-manage commands are all used the same REST API that other +Keystone must be running in order to initialize data within it. This is +because the keystone-manage commands are all used the same REST API that other OpenStack systems utilize. General keystone-manage options: -------------------------------- * ``--id-only`` : causes ``keystone-manage`` to return only the UUID result -from the API call. -* ``--endpoint`` : allows you to specify the keystone endpoint to communicate with. The default endpoint is http://localhost:35357/v2.0' + from the API call. + +* ``--endpoint`` : allows you to specify the keystone endpoint to communicate + with. The default endpoint is http://localhost:35357/v2.0' + * ``--auth-token`` : provides the authorization token -``keystone-manage`` is set up to expect commands in the general form of ``keystone-manage`` ``command`` ``subcommand``, with keyword arguments to provide additional information to the command. For example, the command -``tenant`` has the subcommand ``create``, which takes the required keyword ``tenant_name``:: +``keystone-manage`` is set up to expect commands in the general form of +``keystone-manage`` ``command`` ``subcommand``, with keyword arguments to +provide additional information to the command. For example, the command +``tenant`` has the subcommand ``create``, which takes the required keyword +``tenant_name``:: keystone-manage tenant create tenant_name=example_tenant @@ -137,7 +143,7 @@ creates a tenant named "admin". keyword arguments * tenant_id - + example:: keystone-manage tenant delete tenant_id=f2b7b39c860840dfa47d9ee4adffa0b3 @@ -169,14 +175,14 @@ keyword arguments * name * password * email - + example:: keystone-manage user --ks-id-only create \ name=admin \ password=secrete \ email=admin@example.com - + ``user delete`` ^^^^^^^^^^^^^^^ @@ -199,7 +205,7 @@ keyword arguments ``user update_password`` ^^^^^^^^^^^^^^^^^^^^^^^^ - + keyword arguments ``user update_tenant`` @@ -220,7 +226,7 @@ keyword arguments exmaple:: keystone-manage role --ks-id-only create name=Admin - + ``role add_user_to_tenant`` ^^^^^^^^^^^^^^^^^^^^^^^^^^^ @@ -236,7 +242,7 @@ example:: role_id=19d1d3344873464d819c45f521ff9890 \ user_id=08741d8ed88242ca88d1f61484a0fe3b \ tenant_id=20601a7f1d94447daa4dff438cb1c209 - + ``role remove_user_from_tenant`` ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ diff --git a/docs/source/images/305.svg b/docs/source/images/305.svg deleted file mode 100644 index 7d79464e..00000000 --- a/docs/source/images/305.svg +++ /dev/null @@ -1,158 +0,0 @@ - - - - - - - - - - image/svg+xml - - - - - - - - Request - service directly - - - Auth - Component - 305 - Use proxy to - redirect to Auth - - - - - - - OpenStack - Service - - - diff --git a/docs/source/images/both.svg b/docs/source/images/both.svg deleted file mode 100644 index d29872a4..00000000 --- a/docs/source/images/both.svg +++ /dev/null @@ -1,135 +0,0 @@ - - - - - - - - - - image/svg+xml - - - - - - - - - - Auth - Component - - Auth - Component - - - OpenStack - Service - - - - - diff --git a/docs/source/images/graphs_delegate_accept.svg b/docs/source/images/graphs_delegate_accept.svg deleted file mode 100644 index 1d86cadf..00000000 --- a/docs/source/images/graphs_delegate_accept.svg +++ /dev/null @@ -1,52 +0,0 @@ - - - - - - -DelegateAcceptAuth - - - -AuthComp - -Auth -Component - - -Start->AuthComp - - -Authorization: Basic VTpQ - - -AuthComp->Start - - -200 Okay - - -Service - -OpenStack -Service - - -AuthComp->Service - - -Authorization: Basic dTpw -X-Authorization: Proxy U -X-Identity-Status: Confirmed - - -Service->AuthComp - - -200 Okay - - - diff --git a/docs/source/images/graphs_separate.svg b/docs/source/images/graphs_separate.svg deleted file mode 100644 index 376e5988..00000000 --- a/docs/source/images/graphs_separate.svg +++ /dev/null @@ -1,30 +0,0 @@ - - - - - - -Seperate - - -AuthComp - -Auth -Component - - -Service - -OpenStack -Service - - -AuthComp->Service - - - - - diff --git a/docs/source/images/graphs_standard_accept.svg b/docs/source/images/graphs_standard_accept.svg deleted file mode 100644 index bddf4b5f..00000000 --- a/docs/source/images/graphs_standard_accept.svg +++ /dev/null @@ -1,51 +0,0 @@ - - - - - - -StandardAcceptAuth - - - -AuthComp - -Auth -Component - - -Start->AuthComp - - -Authorization: Basic VTpQ - - -AuthComp->Start - - -200 Okay - - -Service - -OpenStack -Service - - -AuthComp->Service - - -Authorization: Basic dTpw -X-Authorization: Proxy U - - -Service->AuthComp - - -200 Okay - - - diff --git a/docs/source/images/graphs_standard_reject.svg b/docs/source/images/graphs_standard_reject.svg deleted file mode 100644 index 6020ad67..00000000 --- a/docs/source/images/graphs_standard_reject.svg +++ /dev/null @@ -1,39 +0,0 @@ - - - - - - -StandardRejectAuth - - - -AuthComp - -Auth -Component - - -Start->AuthComp - - -Authorization: Basic Yjpw - - -AuthComp->Start - - -401 Unauthorized -WWW-Authenticate: Basic Realm="API Realm" - - -Service - -OpenStack -Service - - - diff --git a/docs/source/images/graphs_together.svg b/docs/source/images/graphs_together.svg deleted file mode 100644 index 1425a28b..00000000 --- a/docs/source/images/graphs_together.svg +++ /dev/null @@ -1,24 +0,0 @@ - - - - - - -Together - - -Together - - -Auth -Component - - -OpenStack -Service - - - diff --git a/docs/source/images/layouts.svg b/docs/source/images/layouts.svg deleted file mode 100644 index fdf61b7d..00000000 --- a/docs/source/images/layouts.svg +++ /dev/null @@ -1,215 +0,0 @@ - - - - - - - - - - image/svg+xml - - - - - - - - - - Auth - Component - - - OpenStack - Service - - - Option - ( - b - ) - - - Auth - Component - - - OpenStack - Service - Option - ( - a - ) - - - - diff --git a/docs/source/images/mapper.svg b/docs/source/images/mapper.svg deleted file mode 100644 index b5a2b7b1..00000000 --- a/docs/source/images/mapper.svg +++ /dev/null @@ -1,237 +0,0 @@ - - - - - - - - - - image/svg+xml - - - - - - - - - - OpenStack - Service - - - - - - - - - - - - - - - Mapper - - - Auth - 1 - - - Auth - 2 - - - Auth - 3 - - - - - diff --git a/docs/source/images/proxyAuth.svg b/docs/source/images/proxyAuth.svg deleted file mode 100644 index f60b40d8..00000000 --- a/docs/source/images/proxyAuth.svg +++ /dev/null @@ -1,238 +0,0 @@ - - - - - - - - - - image/svg+xml - - - - - - - - Authorization - : - Basic dTpw - X - - - Authorization - : - Proxy U - Authorization - : - Basic VTpQ - 500 - Internal Error - 403 - Proxy Unauthorized - - - - - Auth - Component - - - - - OpenStack - Service - - - - - - - -- cgit From 2d2ce8c72efa965b6db4affe1a5d9e3e6ca5d47b Mon Sep 17 00:00:00 2001 From: Andy Smith Date: Wed, 1 Feb 2012 11:07:32 -0800 Subject: Update docs/source/developing.rst --- docs/source/developing.rst | 6 ++++++ 1 file changed, 6 insertions(+) (limited to 'docs') diff --git a/docs/source/developing.rst b/docs/source/developing.rst index 344a6e8b..f529761e 100644 --- a/docs/source/developing.rst +++ b/docs/source/developing.rst @@ -54,6 +54,12 @@ You can also interact with Keystone through it's REST API. There is a python keystone client library `python-keystoneclient`_ which interacts exclusively through the REST API, and which keystone itself uses to provide it's command-line interface. +When initially getting set up, after you've configured which databases to use, +you're probably going to need to run the following to your database schema in place :: + + $ bin/keystone-manage db_sync + + .. _`python-keystoneclient`: https://github.com/openstack/python-keystoneclient Running Tests -- cgit From 32ff03b6dc9d8a6b5c1102faabf7f84bd1ebd3c1 Mon Sep 17 00:00:00 2001 From: Joe Heck Date: Thu, 2 Feb 2012 20:40:39 -0800 Subject: updating docs: * reference keystone-all instead of keystone * remove reference to keystone.version * rename gnerated man page * spacing and line wrapping --- docs/source/conf.py | 16 ++-- docs/source/configuration.rst | 154 ++++++++++++++++++++++++++++++------ docs/source/configuringservices.rst | 23 +++--- docs/source/developing.rst | 30 ++++--- docs/source/man/keystone-all.rst | 83 +++++++++++++++++++ docs/source/man/keystone.rst | 81 ------------------- docs/source/nova-api-paste.rst | 3 +- docs/source/setup.rst | 17 ++-- 8 files changed, 266 insertions(+), 141 deletions(-) create mode 100644 docs/source/man/keystone-all.rst delete mode 100644 docs/source/man/keystone.rst (limited to 'docs') diff --git a/docs/source/conf.py b/docs/source/conf.py index edae0b8a..fc7d9476 100644 --- a/docs/source/conf.py +++ b/docs/source/conf.py @@ -52,7 +52,7 @@ master_doc = 'index' # General information about the project. project = u'keystone' -copyright = u'2012, termie' +copyright = u'2012, OpenStack, LLC' # The version info for the project you're documenting, acts as replacement for # |version| and |release|, also used in various other places throughout the @@ -105,7 +105,7 @@ modindex_common_prefix = ['keystone.'] man_pages = [ ('man/keystone-manage', 'keystone-manage', u'Keystone Management Utility', [u'OpenStack'], 1), - ('man/keystone', 'keystone', u'Keystone Startup Command', + ('man/keystone-all', 'keystone-all', u'Keystone Startup Command', [u'OpenStack'], 1), ] @@ -207,8 +207,8 @@ latex_elements = { # Grouping the document tree into LaTeX files. List of tuples # (source start file, target name, title, author, documentclass [howto/manual]). latex_documents = [ - ('index', 'keystone.tex', u'keystone Documentation', - u'termie', 'manual'), + ('index', 'keystone.tex', u'Keystone Documentation', + u'OpenStack', 'manual'), ] # The name of an image file (relative to this directory) to place at the top of @@ -237,8 +237,8 @@ latex_documents = [ # One entry per manual page. List of tuples # (source start file, name, description, authors, manual section). man_pages = [ - ('index', 'keystone', u'keystone Documentation', - [u'termie'], 1) + ('index', 'keystone', u'Keystone Documentation', + [u'OpenStack'], 1) ] # If true, show URL addresses after external links. @@ -251,8 +251,8 @@ man_pages = [ # (source start file, target name, title, author, # dir menu entry, description, category) texinfo_documents = [ - ('index', 'keystone', u'keystone Documentation', - u'termie', 'keystone', 'One line description of project.', + ('index', 'keystone', u'Keystone Documentation', + u'OpenStack', 'keystone', 'One line description of project.', 'Miscellaneous'), ] diff --git a/docs/source/configuration.rst b/docs/source/configuration.rst index 782e9fb5..7fbcf026 100644 --- a/docs/source/configuration.rst +++ b/docs/source/configuration.rst @@ -22,6 +22,7 @@ Configuring Keystone :maxdepth: 1 man/keystone-manage + man/keystone-all Once Keystone is installed, it is configured via a primary configuration file (``etc/keystone.conf``), possibly a separate logging configuration file, and @@ -34,15 +35,14 @@ Keystone Configuration File The keystone configuration file is an 'ini' file format with sections, extended from Paste_, a common system used to configure python WSGI based applications. In addition to the paste config entries, general configuration -values are stored under [DEFAULT] and [sql], and then drivers for the various -backend components are included under their individual sections. +values are stored under ``[DEFAULT]``, ``[sql]``, ``[ec2]`` and then drivers +for the various services are included under their individual sections. -The driver sections include: +The services include: * ``[identity]`` - the python module that backends the identity system * ``[catalog]`` - the python module that backends the service catalog * ``[token]`` - the python module that backends the token providing mechanisms * ``[policy]`` - the python module that drives the policy system for RBAC -* ``[ec2]`` - the python module providing the EC2 translations for OpenStack The keystone configuration file is expected to be named ``keystone.conf``. When starting up Keystone, you can specify a different configuration file to @@ -61,7 +61,8 @@ file under ``log_config``. If you wish to route all your logging through syslog, there is a ``use_syslog`` option also in the [DEFAULT] section that easy. -A sample logging file is available with the project in the directory ``etc/logging.conf.sample``. Like other OpenStack projects, keystone uses the +A sample logging file is available with the project in the directory +``etc/logging.conf.sample``. Like other OpenStack projects, keystone uses the `python logging module`, which includes extensive configuration options for choosing the output levels and formats. @@ -78,6 +79,18 @@ Sample Configuration Files * ``etc/keystone.conf`` * ``etc/logging.conf.sample`` +Running Keystone +================ + +Running keystone is simply starting the services by using the command:: + + keystone-all + +Invoking this command starts up two wsgi.Server instances, configured by the +``keystone.conf`` file as described above. One of these wsgi 'servers' is +``admin`` (the administration API) and the other is ``main`` (the +primary/public API interface). Both of these run in a single process. + Initializing Keystone ===================== @@ -129,7 +142,8 @@ containers within Swift. A tenant can have zero or more users, Users can be asso keyword arguments * tenant_name -* id (optional) +* description (optional, defaults to None) +* enabled (optional, defaults to True) example:: @@ -142,7 +156,7 @@ creates a tenant named "admin". keyword arguments -* tenant_id +* tenant example:: @@ -153,9 +167,10 @@ example:: keyword arguments -* description -* name * tenant_id +* tenant_name (optional, defaults to None) +* description (optional, defaults to None) +* enabled (optional, defaults to True) example:: @@ -175,6 +190,8 @@ keyword arguments * name * password * email +* tenant_id (optional, defaults to None) +* enabled (optional, defaults to True) example:: @@ -188,31 +205,56 @@ example:: keyword arguments +* user + +example:: + + keystone-manage user --ks-id-only delete f2b7b39c860840dfa47d9ee4adffa0b3 + ``user list`` ^^^^^^^^^^^^^ +list users in the system, optionally by a specific tenant (identified by tenant_id) + keyword arguments +* tenant_id (optional, defaults to None) +* limit (optional, defaults to None) +* marker (optional, defaults to None) + ``user update_email`` ^^^^^^^^^^^^^^^^^^^^^ keyword arguments +* user +* email + ``user update_enabled`` ^^^^^^^^^^^^^^^^^^^^^^^ keyword arguments +* user +* enabled (True or False) + ``user update_password`` ^^^^^^^^^^^^^^^^^^^^^^^^ keyword arguments +* user +* password + ``user update_tenant`` ^^^^^^^^^^^^^^^^^^^^^^ keyword arguments +* user +* tenant + + Roles ----- @@ -227,27 +269,67 @@ exmaple:: keystone-manage role --ks-id-only create name=Admin -``role add_user_to_tenant`` -^^^^^^^^^^^^^^^^^^^^^^^^^^^ +``role delete`` +^^^^^^^^^^^^^^^ keyword arguments -* role_id -* user_id -* tenant_id +* role + +exmaple:: + + keystone-manage role delete role=19d1d3344873464d819c45f521ff9890 + +``role list`` +^^^^^^^^^^^^^^^ + +exmaple:: + + keystone-manage role list + +``role add_user_role`` +^^^^^^^^^^^^^^^^^^^^^^ + +keyword arguments + +* role +* user +* tenant (optional, defaults to None) example:: - keystone-manage role add_user_to_tenant \ - role_id=19d1d3344873464d819c45f521ff9890 \ - user_id=08741d8ed88242ca88d1f61484a0fe3b \ - tenant_id=20601a7f1d94447daa4dff438cb1c209 + keystone-manage role add_user_role \ + role=19d1d3344873464d819c45f521ff9890 \ + user=08741d8ed88242ca88d1f61484a0fe3b \ + tenant=20601a7f1d94447daa4dff438cb1c209 -``role remove_user_from_tenant`` -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ +``role remove_user_role`` +^^^^^^^^^^^^^^^^^^^^^^^^^ -``role get_user_role_refs`` -^^^^^^^^^^^^^^^^^^^^^^^^^^^ +keyword arguments + +* role +* user +* tenant (optional, defaults to None) + +example:: + + keystone-manage role remove_user_to_tenant \ + role=19d1d3344873464d819c45f521ff9890 \ + user=08741d8ed88242ca88d1f61484a0fe3b \ + tenant=20601a7f1d94447daa4dff438cb1c209 + +``role roles_for_user`` +^^^^^^^^^^^^^^^^^^^^^^^ + +keyword arguments + +* user +* tenant (optional, defaults to None) + +example:: + + keystone-manage role roles_for_user user=08741d8ed88242ca88d1f61484a0fe3b Services -------- @@ -267,3 +349,31 @@ example:: name=nova \ service_type=compute \ description="Nova Compute Service" + +``service list`` +^^^^^^^^^^^^^^^^ + +keyword arguments + +example:: + + keystone-manage service list + +``service get`` +^^^^^^^^^^^^^^^ + +keyword arguments + +example:: + + keystone-manage service get id=08741d8ed88242ca88d1f61484a0fe3b + +``service delete`` +^^^^^^^^^^^^^^^^^^ + +keyword arguments + +example:: + + keystone-manage service delete id=08741d8ed88242ca88d1f61484a0fe3b + diff --git a/docs/source/configuringservices.rst b/docs/source/configuringservices.rst index 88bb9c15..5ea75461 100644 --- a/docs/source/configuringservices.rst +++ b/docs/source/configuringservices.rst @@ -24,12 +24,14 @@ Configuring Services to work with Keystone nova-api-paste middleware_architecture -Once Keystone is installed and running (see :doc:`configuration`), services need to be configured to work -with it. To do this, we primarily install and configure middleware for the OpenStack service to handle authentication tasks or otherwise interact with Keystone. +Once Keystone is installed and running (see :doc:`configuration`), services +need to be configured to work with it. To do this, we primarily install and +configure middleware for the OpenStack service to handle authentication tasks +or otherwise interact with Keystone. In general: -* Clients making calls to the service will pass in an authentication token. -* The Keystone middleware will look for and validate that token, taking the appropriate action. +* Clients making calls to the service will pass in an authentication token. +* The Keystone middleware will look for and validate that token, taking the appropriate action. * It will also retrive additional information from the token such as user name, id, tenant name, id, roles, etc... The middleware will pass those data down to the service as headers. More details on the architecture of @@ -42,13 +44,16 @@ Admin Token ----------- For a default installation of Keystone, before you can use the REST API, you -need to define an authorization token. This is configured in the keystone.conf file under the section ``[DEFAULT]``. In the sample file provided with the keystone project, the line defining this token is +need to define an authorization token. This is configured in ``keystone.conf`` +file under the section ``[DEFAULT]``. In the sample file provided with the keystone project, the line defining this token is [DEFAULT] admin_token = ADMIN -This is a "shared secret" between keystone and other openstack services, and will need to be set the -same between those services in order for keystone services to function correctly. +This configured token is a "shared secret" between keystone and other +openstack services (for example: nova, swift, glance, or horizon), and will +need to be set the same between those services in order for keystone services +to function correctly. Setting up tenants, users, and roles ------------------------------------ @@ -58,7 +63,7 @@ You need to minimally define a tenant, user, and role to link the tenant and use Setting up services =================== -Defining Services +Defining Services ----------------- Keystone also acts as a service catalog to let other OpenStack systems know @@ -146,7 +151,7 @@ rather than it's built in 'tempauth'. Note that the optional "cache" property in the keystone filter allows any service (not just Swift) to register its memcache client in the WSGI - environment. If such a cache exists, Keystone middleware will utilize it + environment. If such a cache exists, Keystone middleware will utilize it to store validated token information, which could result in better overall performance. diff --git a/docs/source/developing.rst b/docs/source/developing.rst index f529761e..f7c0b87b 100644 --- a/docs/source/developing.rst +++ b/docs/source/developing.rst @@ -22,7 +22,7 @@ Contributing Code ================= To contribute code, sign up for a Launchpad account and sign a contributor license agreement, -available on the ``_. Once the CLA is signed you +available on the ``_. Once the CLA is signed you can contribute code through the Gerrit version control system which is related to your Launchpad account. To contribute tests, docs, code, etc, refer to our `Gerrit-Jenkins-Github Workflow`_. @@ -40,8 +40,8 @@ Running Keystone To run the keystone Admin and API server instances, use:: - $ tools/with_venv.sh bin/keystone - + $ tools/with_venv.sh bin/keystone-all + this runs keystone with the configuration the etc/ directory of the project. See :doc:`configuration` for details on how Keystone is configured. Interacting with Keystone @@ -76,20 +76,32 @@ light integration testing to verify the keystone API against other projects. Test Structure -------------- -``./run_test.sh`` uses it's python cohort (``run_tests.py``) to iterate through the ``tests`` directory, using Nosetest to collect the tests and invoke them using an -OpenStack custom test running that displays the tests as well as the time taken to +``./run_test.sh`` uses its python cohort (``run_tests.py``) to iterate +through the ``tests`` directory, using Nosetest to collect the tests and +invoke them using an OpenStack custom test running that displays the tests +as well as the time taken to run those tests. -Within the tests directory, the general structure of the tests is a basic set of tests represented under a test class, and then subclasses of those tests under other classes with different configurations to drive different backends through the APIs. +Within the tests directory, the general structure of the tests is a basic +set of tests represented under a test class, and then subclasses of those +tests under other classes with different configurations to drive different +backends through the APIs. -For example, ``test_backend.py`` has a sequence of tests under the class ``IdentityTests`` that will work with the default drivers as configured in this projects etc/ directory. ``test_backend_sql.py`` subclasses those tests, changing the configuration by overriding with configuration files stored in the tests directory aimed at enabling the SQL backend for the Identity module. +For example, ``test_backend.py`` has a sequence of tests under the class +``IdentityTests`` that will work with the default drivers as configured in +this projects etc/ directory. ``test_backend_sql.py`` subclasses those tests, +changing the configuration by overriding with configuration files stored in +the tests directory aimed at enabling the SQL backend for the Identity module. -Likewise, ``test_cli.py`` takes advantage of the tests written aainst ``test_keystoneclient`` to verify the same tests function through different drivers. +Likewise, ``test_cli.py`` takes advantage of the tests written aainst +``test_keystoneclient`` to verify the same tests function through different +drivers. Testing Schema Migrations ------------------------- -The application of schema migrations can be tested using SQLAlchemy Migrate’s built-in test runner, one migration at a time. +The application of schema migrations can be tested using SQLAlchemy Migrate’s +built-in test runner, one migration at a time. .. WARNING:: diff --git a/docs/source/man/keystone-all.rst b/docs/source/man/keystone-all.rst new file mode 100644 index 00000000..66d0ee4e --- /dev/null +++ b/docs/source/man/keystone-all.rst @@ -0,0 +1,83 @@ +======== +keystone +======== + +--------------------------- +Keystone Management Utility +--------------------------- + +:Author: keystone@lists.launchpad.net +:Date: 2010-11-16 +:Copyright: OpenStack LLC +:Version: 0.1.2 +:Manual section: 1 +:Manual group: cloud computing + +SYNOPSIS +======== + + keystone-all [options] + +DESCRIPTION +=========== + +keystone-all starts both the service and administrative APIs in a single +process to provide catalog, authorization, and authentication services for +OpenStack. + +USAGE +===== + + ``keystone-all [options]`` + +Common Options: +^^^^^^^^^^^^^^^ + -h, --help show this help message and exit + +The following configuration options are common to all keystone +programs.:: + + -h, --help show this help message and exit + --config-file=PATH Path to a config file to use. Multiple config files + can be specified, with values in later files taking + precedence. The default files used are: [] + -d, --debug Print debugging output + --nodebug Print debugging output + -v, --verbose Print more verbose output + --noverbose Print more verbose output + --log-config=PATH If this option is specified, the logging configuration + file specified is used and overrides any other logging + options specified. Please see the Python logging + module documentation for details on logging + configuration files. + --log-format=FORMAT A logging.Formatter log message format string which + may use any of the available logging.LogRecord + attributes. Default: none + --log-date-format=DATE_FORMAT + Format string for %(asctime)s in log records. Default: + none + --log-file=PATH (Optional) Name of log file to output to. If not set, + logging will go to stdout. + --log-dir=LOG_DIR (Optional) The directory to keep log files in (will be + prepended to --logfile) + --syslog-log-facility=SYSLOG_LOG_FACILITY + (Optional) The syslog facility to use when logging to + syslog (defaults to LOG_USER) + --use-syslog Use syslog for logging. + --nouse-syslog Use syslog for logging. + +FILES +===== + +None + +SEE ALSO +======== + +* `Keystone `__ + +SOURCE +====== + +* Keystone source in managed in GitHub `Keystone `__ +* Keystone bugs are managed at Launchpad `Launchpad Keystone `__ diff --git a/docs/source/man/keystone.rst b/docs/source/man/keystone.rst deleted file mode 100644 index 74d0bb69..00000000 --- a/docs/source/man/keystone.rst +++ /dev/null @@ -1,81 +0,0 @@ -======== -keystone -======== - ---------------------------- -Keystone Management Utility ---------------------------- - -:Author: keystone@lists.launchpad.net -:Date: 2010-11-16 -:Copyright: OpenStack LLC -:Version: 0.1.2 -:Manual section: 1 -:Manual group: cloud computing - -SYNOPSIS -======== - - keystone [options] - -DESCRIPTION -=========== - -keystone starts both the service and administrative APIs for Keystone. - -USAGE -===== - - keystone ``keystone [options]`` - -Common Options: -^^^^^^^^^^^^^^^ - -h, --help show this help message and exit - -The following configuration options are common to all keystone -programs.:: - - -h, --help show this help message and exit - --config-file=PATH Path to a config file to use. Multiple config files - can be specified, with values in later files taking - precedence. The default files used are: [] - -d, --debug Print debugging output - --nodebug Print debugging output - -v, --verbose Print more verbose output - --noverbose Print more verbose output - --log-config=PATH If this option is specified, the logging configuration - file specified is used and overrides any other logging - options specified. Please see the Python logging - module documentation for details on logging - configuration files. - --log-format=FORMAT A logging.Formatter log message format string which - may use any of the available logging.LogRecord - attributes. Default: none - --log-date-format=DATE_FORMAT - Format string for %(asctime)s in log records. Default: - none - --log-file=PATH (Optional) Name of log file to output to. If not set, - logging will go to stdout. - --log-dir=LOG_DIR (Optional) The directory to keep log files in (will be - prepended to --logfile) - --syslog-log-facility=SYSLOG_LOG_FACILITY - (Optional) The syslog facility to use when logging to - syslog (defaults to LOG_USER) - --use-syslog Use syslog for logging. - --nouse-syslog Use syslog for logging. - -FILES -===== - -None - -SEE ALSO -======== - -* `Keystone `__ - -SOURCE -====== - -* Keystone is sourced in GitHub `Keystone `__ -* Keystone bugs are managed at Launchpad `Launchpad Keystone `__ diff --git a/docs/source/nova-api-paste.rst b/docs/source/nova-api-paste.rst index 586bac72..602895ac 100644 --- a/docs/source/nova-api-paste.rst +++ b/docs/source/nova-api-paste.rst @@ -136,7 +136,8 @@ nova-api-paste example auth_host = 127.0.0.1 auth_port = 35357 auth_protocol = http - auth_uri = http://127.0.0.1:5000/ + auth_uri = http://your_keystone_host.com:5000/ + ;identical to the admin token defined in keystone.conf admin_token = 999888777666 ;Uncomment next line and check ip:port to use memcached to cache token requests ;memcache_hosts = 127.0.0.1:11211 diff --git a/docs/source/setup.rst b/docs/source/setup.rst index 4f6b6137..7d03fd66 100644 --- a/docs/source/setup.rst +++ b/docs/source/setup.rst @@ -62,10 +62,10 @@ When that is complete, you can:: Installing dependencies ======================= -Keystone maintains two lists of dependencies: +Keystone maintains two lists of dependencies:: tools/pip-requires - tools/pip-requires-test + tools/pip-requires-test The first is the list of dependencies needed for running keystone, the second list includes dependencies used for active development and testing of keystone itself. @@ -97,7 +97,7 @@ PyPi Packages and VirtualEnv ---------------------------- We recommend establishing a virtualenv to run keystone within. Virtualenv limits the python environment -to just what you're installing as depdendencies, useful to keep a clean environment for working on +to just what you're installing as depdendencies, useful to keep a clean environment for working on Keystone. The tools directory in keystone has a script already created to make this very simple:: $ python tools/install_venv.py @@ -125,10 +125,10 @@ into your system from the requires files:: # Install the dependencies for developing, testing, and running keystone $ pip install -r tools/pip-requires-test - + # Fake-install the project by symlinking Keystone into your Python site-packages $ python setup.py develop - + Verifying Keystone is set up ============================ @@ -142,14 +142,9 @@ the libraries. If you're using a virtualenv, don't forget to activate it:: You should then be able to `import keystone` from your Python shell without issue:: - >>> import keystone.version + >>> import keystone >>> -If you want to check the version of Keystone you are running: - - >>> print keystone.version.version() - 2012.1-dev - If you can import keystone successfully, you should be ready to move on to :doc:`developing` Troubleshooting -- cgit From cc371272f2f650765f39d03bd17c1afc80b0e561 Mon Sep 17 00:00:00 2001 From: Joe Heck Date: Sun, 5 Feb 2012 20:32:37 +0000 Subject: ran through all commands to verify keywords against current (master) keystonelight --- docs/source/configuration.rst | 58 +++++++++++++++++++++++++++++++++++++------ 1 file changed, 50 insertions(+), 8 deletions(-) (limited to 'docs') diff --git a/docs/source/configuration.rst b/docs/source/configuration.rst index 7fbcf026..d4ea8868 100644 --- a/docs/source/configuration.rst +++ b/docs/source/configuration.rst @@ -195,7 +195,7 @@ keyword arguments example:: - keystone-manage user --ks-id-only create \ + keystone-manage user --id-only create \ name=admin \ password=secrete \ email=admin@example.com @@ -209,7 +209,7 @@ keyword arguments example:: - keystone-manage user --ks-id-only delete f2b7b39c860840dfa47d9ee4adffa0b3 + keystone-manage user delete user=f2b7b39c860840dfa47d9ee4adffa0b3 ``user list`` ^^^^^^^^^^^^^ @@ -219,8 +219,10 @@ list users in the system, optionally by a specific tenant (identified by tenant_ keyword arguments * tenant_id (optional, defaults to None) -* limit (optional, defaults to None) -* marker (optional, defaults to None) + +example:: + + keystone-manage user list ``user update_email`` ^^^^^^^^^^^^^^^^^^^^^ @@ -230,6 +232,11 @@ keyword arguments * user * email +example:: + + keystone-manage user update_email user=03c84b51574841ba9a0d8db7882ac645 email="someone@somewhere.com" + + ``user update_enabled`` ^^^^^^^^^^^^^^^^^^^^^^^ @@ -238,6 +245,10 @@ keyword arguments * user * enabled (True or False) +example:: + + keystone-manage user update_enabled user=03c84b51574841ba9a0d8db7882ac645 enabled=False + ``user update_password`` ^^^^^^^^^^^^^^^^^^^^^^^^ @@ -246,6 +257,10 @@ keyword arguments * user * password +example:: + + keystone-manage user update_password user=03c84b51574841ba9a0d8db7882ac645 password=foo + ``user update_tenant`` ^^^^^^^^^^^^^^^^^^^^^^ @@ -254,6 +269,21 @@ keyword arguments * user * tenant +example:: + + keystone-manage user update_tenant user=03c84b51574841ba9a0d8db7882ac645 tenant=b7b8be32c4be4208949f0373c5909e3b + +``user get`` +^^^^^^^^^^^^ + +keyword arguments + +* user + +example:: + + keystone-manage ususer get user=03c84b51574841ba9a0d8db7882ac645 + Roles ----- @@ -267,7 +297,7 @@ keyword arguments exmaple:: - keystone-manage role --ks-id-only create name=Admin + keystone-manage role --id-only create name=Admin ``role delete`` ^^^^^^^^^^^^^^^ @@ -287,6 +317,18 @@ exmaple:: keystone-manage role list +``role get`` +^^^^^^^^^^^^ + +keysword arguments + +* role + +exmaple:: + + keystone-manage role get role=19d1d3344873464d819c45f521ff9890 + + ``role add_user_role`` ^^^^^^^^^^^^^^^^^^^^^^ @@ -294,13 +336,13 @@ keyword arguments * role * user -* tenant (optional, defaults to None) +* tenant example:: keystone-manage role add_user_role \ - role=19d1d3344873464d819c45f521ff9890 \ - user=08741d8ed88242ca88d1f61484a0fe3b \ + role=3a751f78ef4c412b827540b829e2d7dd \ + user=03c84b51574841ba9a0d8db7882ac645 \ tenant=20601a7f1d94447daa4dff438cb1c209 ``role remove_user_role`` -- cgit From 62a92c44baf533fe316016c1fa5be892fc85009c Mon Sep 17 00:00:00 2001 From: Joe Heck Date: Mon, 6 Feb 2012 20:43:24 +0000 Subject: fixing grammar, noting broken enable, adding hacking with prefs for project --- docs/source/configuration.rst | 11 ++++++++++ docs/source/configuringservices.rst | 44 ++++++++++++++++++++++++++----------- docs/source/man/keystone-all.rst | 2 +- 3 files changed, 43 insertions(+), 14 deletions(-) (limited to 'docs') diff --git a/docs/source/configuration.rst b/docs/source/configuration.rst index d4ea8868..8c998700 100644 --- a/docs/source/configuration.rst +++ b/docs/source/configuration.rst @@ -200,6 +200,11 @@ example:: password=secrete \ email=admin@example.com +.. warning:: + Until https://bugs.launchpad.net/keystone/+bug/927873 is resolved, the + keystone-manage cli doesn't allow the setting enabled to be False, making + this command partially broken at the moment. + ``user delete`` ^^^^^^^^^^^^^^^ @@ -249,6 +254,12 @@ example:: keystone-manage user update_enabled user=03c84b51574841ba9a0d8db7882ac645 enabled=False +.. warning:: + Until https://bugs.launchpad.net/keystone/+bug/927873 is resolved, the + keystone-manage cli doesn't allow the setting enabled to False, making + this command broken at the moment. + + ``user update_password`` ^^^^^^^^^^^^^^^^^^^^^^^^ diff --git a/docs/source/configuringservices.rst b/docs/source/configuringservices.rst index 5ea75461..3777ce5e 100644 --- a/docs/source/configuringservices.rst +++ b/docs/source/configuringservices.rst @@ -31,11 +31,14 @@ or otherwise interact with Keystone. In general: * Clients making calls to the service will pass in an authentication token. -* The Keystone middleware will look for and validate that token, taking the appropriate action. -* It will also retrive additional information from the token such as user name, id, tenant name, id, roles, etc... +* The Keystone middleware will look for and validate that token, taking the + appropriate action. +* It will also retrive additional information from the token such as user + name, id, tenant name, id, roles, etc... -The middleware will pass those data down to the service as headers. More details on the architecture of -that setup is described in :doc:`middleware_architecture` +The middleware will pass those data down to the service as headers. More +details on the architecture of that setup is described in +:doc:`middleware_architecture` Setting up credentials ====================== @@ -45,7 +48,8 @@ Admin Token For a default installation of Keystone, before you can use the REST API, you need to define an authorization token. This is configured in ``keystone.conf`` -file under the section ``[DEFAULT]``. In the sample file provided with the keystone project, the line defining this token is +file under the section ``[DEFAULT]``. In the sample file provided with the +keystone project, the line defining this token is [DEFAULT] admin_token = ADMIN @@ -58,7 +62,10 @@ to function correctly. Setting up tenants, users, and roles ------------------------------------ -You need to minimally define a tenant, user, and role to link the tenant and user as the most basic set of details to get other services authenticating and authorizing with keystone. See doc:`configuration` for a walk through on how to create tenants, users, and roles. +You need to minimally define a tenant, user, and role to link the tenant and +user as the most basic set of details to get other services authenticating +and authorizing with keystone. See doc:`configuration` for a walk through on +how to create tenants, users, and roles. Setting up services =================== @@ -73,13 +80,24 @@ for the OpenStack Dashboard to properly function. Here's how we define the services:: - keystone-manage service create name=nova service_type=compute description="Nova Compute Service" - keystone-manage service create name=ec2 service_type=ec2 description="EC2 Compatibility Layer" - keystone-manage service create name=glance service_type=image description="Glance Image Service" - keystone-manage service create name=keystone service_type=identity description="Keystone Identity Service" - keystone-manage service create name=swift service_type=object-store description="Swift Service" - -The endpoints for these services are defined in a template, an example of which is in the project as the file ``etc/default_catalog.templates``. + keystone-manage service create name=nova \ + service_type=compute \ + description="Nova Compute Service" + keystone-manage service create name=ec2 \ + service_type=ec2 \ + description="EC2 Compatibility Layer" + keystone-manage service create name=glance \ + service_type=image \ + description="Glance Image Service" + keystone-manage service create name=keystone \ + service_type=identity \ + description="Keystone Identity Service" + keystone-manage service create name=swift \ + service_type=object-store \ + description="Swift Service" + +The endpoints for these services are defined in a template, an example of +which is in the project as the file ``etc/default_catalog.templates``. Setting Up Middleware ===================== diff --git a/docs/source/man/keystone-all.rst b/docs/source/man/keystone-all.rst index 66d0ee4e..fc2d68d7 100644 --- a/docs/source/man/keystone-all.rst +++ b/docs/source/man/keystone-all.rst @@ -79,5 +79,5 @@ SEE ALSO SOURCE ====== -* Keystone source in managed in GitHub `Keystone `__ +* Keystone source is managed in GitHub `Keystone `__ * Keystone bugs are managed at Launchpad `Launchpad Keystone `__ -- cgit From aed78aa21a84881e6abaa662a5bb345db830e8e7 Mon Sep 17 00:00:00 2001 From: Joe Heck Date: Mon, 6 Feb 2012 20:06:31 -0800 Subject: fixes lp:925721 adds .gitreview for redux branch Change-Id: Ic993ee7abd5f54b118b1b58688199f58a529222c --- docs/source/configuration.rst | 12 ++++++++++++ 1 file changed, 12 insertions(+) (limited to 'docs') diff --git a/docs/source/configuration.rst b/docs/source/configuration.rst index 8c998700..586b66bc 100644 --- a/docs/source/configuration.rst +++ b/docs/source/configuration.rst @@ -179,6 +179,18 @@ example:: description="those other guys" \ name=tog +``tenant get`` +^^^^^^^^^^^^^^ + +keyword arguments + +* tenant_id + +example:: + + keystone-manage tenant get \ + tenant_id=523df7c89ce34640996d3d804cbc56f4 + Users ----- -- cgit From 448c6414a176831b400ed5a1618fe89a8780968b Mon Sep 17 00:00:00 2001 From: Anthony Young Date: Tue, 14 Feb 2012 12:30:23 -0800 Subject: Update docs to for current keystone-manage usage * Document how to manage users, roles, tenants, services, etc with keystoneclient cli * keystone-manage only does db_sync right now * Fixes bug 931837 * Add docs for import_legacy and export_legacy_catalog Change-Id: I7f55fd607363d0cd4f1646564e430dfb5b12855f --- docs/source/configuration.rst | 322 ++++++++++++++++++------------------ docs/source/configuringservices.rst | 30 ++-- docs/source/man/keystone-manage.rst | 156 +---------------- 3 files changed, 183 insertions(+), 325 deletions(-) (limited to 'docs') diff --git a/docs/source/configuration.rst b/docs/source/configuration.rst index 586b66bc..7b975b10 100644 --- a/docs/source/configuration.rst +++ b/docs/source/configuration.rst @@ -94,130 +94,152 @@ primary/public API interface). Both of these run in a single process. Initializing Keystone ===================== -Keystone must be running in order to initialize data within it. This is -because the keystone-manage commands are all used the same REST API that other -OpenStack systems utilize. +keystone-manage is designed to execute commands that cannot be administered +through the normal REST api. At the moment, the following calls are supported: -General keystone-manage options: --------------------------------- +* ``db_sync``: Sync the database. +* ``import_legacy``: Import a legacy (pre-essex) version of the db. +* ``export_legacy_catalog``: Export service catalog from a legacy (pre-essex) db. -* ``--id-only`` : causes ``keystone-manage`` to return only the UUID result - from the API call. -* ``--endpoint`` : allows you to specify the keystone endpoint to communicate - with. The default endpoint is http://localhost:35357/v2.0' +Generally, the following is the first step after a source installation:: -* ``--auth-token`` : provides the authorization token + keystone-manage db_sync -``keystone-manage`` is set up to expect commands in the general form of -``keystone-manage`` ``command`` ``subcommand``, with keyword arguments to -provide additional information to the command. For example, the command -``tenant`` has the subcommand ``create``, which takes the required keyword -``tenant_name``:: +Invoking keystone-manage by itself will give you additional usage information. - keystone-manage tenant create tenant_name=example_tenant +Adding Users, Tenants, and Roles with python-keystoneclient +=========================================================== -Invoking keystone-manage by itself will give you some usage information. +User, tenants, and roles must be administered using admin credentials. +There are two ways to configure python-keystoneclient to use admin +credentials, using the token auth method, or password auth method. -Available keystone-manage commands: +Token Auth Method +----------------- +To use keystone client using token auth, set the following flags -* ``db_sync``: Sync the database. -* ``ec2``: no docs -* ``role``: Role CRUD functions. -* ``service``: Service CRUD functions. -* ``tenant``: Tenant CRUD functions. -* ``token``: Token CRUD functions. -* ``user``: User CRUD functions. +* ``--endpoint SERVIVE_ENDPOINT`` : allows you to specify the keystone endpoint to communicate + with. The default endpoint is http://localhost:35357/v2.0' +* ``--token SERVIVE_TOKEN`` : your administrator service token. + +Password Auth Method +-------------------- + +* ``--username OS_USERNAME`` : allows you to specify the keystone endpoint to communicate + with. For example, http://localhost:35357/v2.0' +* ``--password OS_PASSWORD`` : Your administrator password +* ``--tenant_name OS_TENANT_NAME`` : Name of your tenant +* ``--auth_url OS_AUTH_URL`` : url of your keystone auth server, for example +http://localhost:5000/v2.0' + +Example usage +------------- +``keystone`` is set up to expect commands in the general form of +``keystone`` ``command`` ``argument``, followed by flag-like keyword arguments to +provide additional (often optional) information. For example, the command +``user-list`` and ``tenant-create`` can be invoked as follows:: + + # Using token auth env variables + export SERVICE_ENDPOINT=http://127.0.0.1:5000/v2.0/ + export SERVICE_TOKEN=secrete_token + keystone user-list + keystone tenant-create --name=demo + + # Using token auth flags + keystone --token=secrete --endpoint=http://127.0.0.1:5000/v2.0/ user-list + keystone --token=secrete --endpoint=http://127.0.0.1:5000/v2.0/ tenant-create --name=demo + + # Using user + password + tenant_name env variables + export OS_USERNAME=admin + export OS_PASSWORD=secrete + export OS_TENANT_NAME=admin + keystone user-list + keystone tenant-create --name=demo + + # Using user + password + tenant_name flags + keystone --username=admin --password=secrete --tenant_name=admin user-list + keystone --username=admin --password=secrete --tenant_name=admin tenant-create --name=demo Tenants ------- Tenants are the high level grouping within Keystone that represent groups of users. A tenant is the grouping that owns virtual machines within Nova, or -containers within Swift. A tenant can have zero or more users, Users can be assocaited with more than one tenant, and each tenant - user pairing can have a role associated with it. +containers within Swift. A tenant can have zero or more users, Users can +be associated with more than one tenant, and each tenant - user pairing can +have a role associated with it. -``tenant create`` +``tenant-create`` ^^^^^^^^^^^^^^^^^ keyword arguments -* tenant_name +* name * description (optional, defaults to None) * enabled (optional, defaults to True) example:: - keystone-manage --id-only tenant create tenant_name=admin + keystone tenant-create --name=demo -creates a tenant named "admin". +creates a tenant named "demo". -``tenant delete`` +``tenant-delete`` ^^^^^^^^^^^^^^^^^ -keyword arguments +arguments -* tenant +* tenant_id example:: - keystone-manage tenant delete tenant_id=f2b7b39c860840dfa47d9ee4adffa0b3 + keystone tenant-delete f2b7b39c860840dfa47d9ee4adffa0b3 -``tenant update`` +``tenant-enable`` ^^^^^^^^^^^^^^^^^ -keyword arguments +arguments * tenant_id -* tenant_name (optional, defaults to None) -* description (optional, defaults to None) -* enabled (optional, defaults to True) example:: - keystone-manage tenant update \ - tenant_id=f2b7b39c860840dfa47d9ee4adffa0b3 \ - description="those other guys" \ - name=tog + keystone tenant-enable f2b7b39c860840dfa47d9ee4adffa0b3 -``tenant get`` -^^^^^^^^^^^^^^ +``tenant-disable`` +^^^^^^^^^^^^^^^^^ -keyword arguments +arguments * tenant_id example:: - keystone-manage tenant get \ - tenant_id=523df7c89ce34640996d3d804cbc56f4 + keystone tenant-disable f2b7b39c860840dfa47d9ee4adffa0b3 Users ----- -``user create`` +``user-create`` ^^^^^^^^^^^^^^^ keyword arguments * name -* password +* pass * email -* tenant_id (optional, defaults to None) +* default_tenant (optional, defaults to None) * enabled (optional, defaults to True) example:: - keystone-manage user --id-only create \ - name=admin \ - password=secrete \ - email=admin@example.com - -.. warning:: - Until https://bugs.launchpad.net/keystone/+bug/927873 is resolved, the - keystone-manage cli doesn't allow the setting enabled to be False, making - this command partially broken at the moment. + keystone user-create + --name=admin \ + --pass=secrete \ + --email=admin@example.com -``user delete`` +``user-delete`` ^^^^^^^^^^^^^^^ keyword arguments @@ -226,219 +248,193 @@ keyword arguments example:: - keystone-manage user delete user=f2b7b39c860840dfa47d9ee4adffa0b3 + keystone user-delete f2b7b39c860840dfa47d9ee4adffa0b3 -``user list`` +``user-list`` ^^^^^^^^^^^^^ list users in the system, optionally by a specific tenant (identified by tenant_id) -keyword arguments +arguments * tenant_id (optional, defaults to None) example:: - keystone-manage user list + keystone user-list -``user update_email`` +``user-update-email`` ^^^^^^^^^^^^^^^^^^^^^ -keyword arguments - -* user +arguments +* user_id * email -example:: - keystone-manage user update_email user=03c84b51574841ba9a0d8db7882ac645 email="someone@somewhere.com" +example:: + keystone user-update-email 03c84b51574841ba9a0d8db7882ac645 "someone@somewhere.com" -``user update_enabled`` +``user-enable`` ^^^^^^^^^^^^^^^^^^^^^^^ -keyword arguments +arguments -* user -* enabled (True or False) +* user_id example:: - keystone-manage user update_enabled user=03c84b51574841ba9a0d8db7882ac645 enabled=False - -.. warning:: - Until https://bugs.launchpad.net/keystone/+bug/927873 is resolved, the - keystone-manage cli doesn't allow the setting enabled to False, making - this command broken at the moment. + keystone user-enable 03c84b51574841ba9a0d8db7882ac645 +``user-disable`` +^^^^^^^^^^^^^^^^^^^^^^^ -``user update_password`` -^^^^^^^^^^^^^^^^^^^^^^^^ - -keyword arguments +arguments -* user -* password +* user_id example:: - keystone-manage user update_password user=03c84b51574841ba9a0d8db7882ac645 password=foo + keystone user-disable 03c84b51574841ba9a0d8db7882ac645 -``user update_tenant`` -^^^^^^^^^^^^^^^^^^^^^^ - -keyword arguments -* user -* tenant - -example:: - - keystone-manage user update_tenant user=03c84b51574841ba9a0d8db7882ac645 tenant=b7b8be32c4be4208949f0373c5909e3b - -``user get`` -^^^^^^^^^^^^ +``user-update-password`` +^^^^^^^^^^^^^^^^^^^^^^^^ -keyword arguments +arguments -* user +* user_id +* password example:: - keystone-manage ususer get user=03c84b51574841ba9a0d8db7882ac645 - + keystone user-update-password 03c84b51574841ba9a0d8db7882ac645 foo Roles ----- -``role create`` +``role-create`` ^^^^^^^^^^^^^^^ -keyword arguments +arguments * name exmaple:: - keystone-manage role --id-only create name=Admin + keystone role-create --name=demo -``role delete`` +``role-delete`` ^^^^^^^^^^^^^^^ -keyword arguments +arguments -* role +* role_id exmaple:: - keystone-manage role delete role=19d1d3344873464d819c45f521ff9890 + keystone role-delete 19d1d3344873464d819c45f521ff9890 -``role list`` +``role-list`` ^^^^^^^^^^^^^^^ exmaple:: - keystone-manage role list + keystone role-list -``role get`` +``role-get`` ^^^^^^^^^^^^ -keysword arguments +arguments -* role +* role_id exmaple:: - keystone-manage role get role=19d1d3344873464d819c45f521ff9890 + keystone role-get role=19d1d3344873464d819c45f521ff9890 -``role add_user_role`` +``add-user-role`` ^^^^^^^^^^^^^^^^^^^^^^ -keyword arguments +arguments -* role -* user -* tenant +* role_id +* user_id +* tenant_id example:: - keystone-manage role add_user_role \ - role=3a751f78ef4c412b827540b829e2d7dd \ - user=03c84b51574841ba9a0d8db7882ac645 \ - tenant=20601a7f1d94447daa4dff438cb1c209 + keystone role add-user-role \ + 3a751f78ef4c412b827540b829e2d7dd \ + 03c84b51574841ba9a0d8db7882ac645 \ + 20601a7f1d94447daa4dff438cb1c209 -``role remove_user_role`` +``remove-user-role`` ^^^^^^^^^^^^^^^^^^^^^^^^^ -keyword arguments +arguments -* role -* user -* tenant (optional, defaults to None) - -example:: - - keystone-manage role remove_user_to_tenant \ - role=19d1d3344873464d819c45f521ff9890 \ - user=08741d8ed88242ca88d1f61484a0fe3b \ - tenant=20601a7f1d94447daa4dff438cb1c209 - -``role roles_for_user`` -^^^^^^^^^^^^^^^^^^^^^^^ - -keyword arguments - -* user -* tenant (optional, defaults to None) +* role_id +* user_id +* tenant_id example:: - keystone-manage role roles_for_user user=08741d8ed88242ca88d1f61484a0fe3b + keystone remove-user-role \ + 19d1d3344873464d819c45f521ff9890 \ + 08741d8ed88242ca88d1f61484a0fe3b \ + 20601a7f1d94447daa4dff438cb1c209 Services -------- -``service create`` +``service-create`` ^^^^^^^^^^^^^^^^^^ keyword arguments * name -* service_type +* type * description example:: - keystone-manage service create \ - name=nova \ - service_type=compute \ - description="Nova Compute Service" + keystone service create \ + --name=nova \ + --type=compute \ + --description="Nova Compute Service" -``service list`` +``service-list`` ^^^^^^^^^^^^^^^^ -keyword arguments +arguments + +* service_id example:: - keystone-manage service list + keystone service-list -``service get`` +``service-get`` ^^^^^^^^^^^^^^^ -keyword arguments +arguments + +* service_id example:: - keystone-manage service get id=08741d8ed88242ca88d1f61484a0fe3b + keystone service-get 08741d8ed88242ca88d1f61484a0fe3b -``service delete`` +``service-delete`` ^^^^^^^^^^^^^^^^^^ -keyword arguments +arguments + +* service_id example:: - keystone-manage service delete id=08741d8ed88242ca88d1f61484a0fe3b + keystone service-delete 08741d8ed88242ca88d1f61484a0fe3b diff --git a/docs/source/configuringservices.rst b/docs/source/configuringservices.rst index 3777ce5e..615187ea 100644 --- a/docs/source/configuringservices.rst +++ b/docs/source/configuringservices.rst @@ -80,21 +80,21 @@ for the OpenStack Dashboard to properly function. Here's how we define the services:: - keystone-manage service create name=nova \ - service_type=compute \ - description="Nova Compute Service" - keystone-manage service create name=ec2 \ - service_type=ec2 \ - description="EC2 Compatibility Layer" - keystone-manage service create name=glance \ - service_type=image \ - description="Glance Image Service" - keystone-manage service create name=keystone \ - service_type=identity \ - description="Keystone Identity Service" - keystone-manage service create name=swift \ - service_type=object-store \ - description="Swift Service" + keystone service-create --name=nova \ + --type=compute \ + --description="Nova Compute Service" + keystone service-create --name=ec2 \ + --type=ec2 \ + --description="EC2 Compatibility Layer" + keystone service-create --name=glance \ + --type=image \ + --description="Glance Image Service" + keystone service-create --name=keystone \ + --type=identity \ + --description="Keystone Identity Service" + keystone service-create --name=swift \ + --type=object-store \ + --description="Swift Service" The endpoints for these services are defined in a template, an example of which is in the project as the file ``etc/default_catalog.templates``. diff --git a/docs/source/man/keystone-manage.rst b/docs/source/man/keystone-manage.rst index da5fc941..91f2b9e7 100644 --- a/docs/source/man/keystone-manage.rst +++ b/docs/source/man/keystone-manage.rst @@ -22,162 +22,29 @@ DESCRIPTION =========== keystone-manage is the command line tool that interacts with the keystone -service to initialize and update data within Keystone. Keystone *must* be -opertional for the keystone-manage commands to function correctly. +service to initialize and update data within Keystone. Generally, +keystone-manage is only used for operations that can not be accomplished +with through the keystone REST api, such data import/export and schema +migrations. + USAGE ===== - ``keystone-manage [options] type action [additional args]`` + ``keystone-manage [options] action [additional args]`` General keystone-manage options: -------------------------------- -* ``--id-only`` : causes ``keystone-manage`` to return only the UUID result -from the API call. -* ``--endpoint`` : allows you to specify the keystone endpoint to communicate with. The default endpoint is http://localhost:35357/v2.0' -* ``--auth-token`` : provides the authorization token - -``keystone-manage`` is set up to expect commands in the general form of ``keystone-manage`` ``command`` ``subcommand``, with keyword arguments to provide additional information to the command. For example, the command -``tenant`` has the subcommand ``create``, which takes the required keyword ``tenant_name``:: - - keystone-manage tenant create tenant_name=example_tenant +* ``--help`` : display verbose help output. Invoking keystone-manage by itself will give you some usage information. Available keystone-manage commands: db_sync: Sync the database. - ec2: no docs - role: Role CRUD functions. - service: Service CRUD functions. - tenant: Tenant CRUD functions. - token: Token CRUD functions. - user: User CRUD functions. - -Tenants -------- - -Tenants are the high level grouping within Keystone that represent groups of -users. A tenant is the grouping that owns virtual machines within Nova, or -containers within Swift. A tenant can have zero or more users, Users can be assocaited with more than one tenant, and each tenant - user pairing can have a role associated with it. - -* tenant create - - keyword arguments - * tenant_name - * id (optional) - -example:: - keystone-manage --id-only tenant create tenant_name=admin - -creates a tenant named "admin". - -* tenant delete - - keyword arguments - * tenant_id - -example:: - keystone-manage tenant delete tenant_id=f2b7b39c860840dfa47d9ee4adffa0b3 - -* tenant update - - keyword arguments - * description - * name - * tenant_id - -example:: - keystone-manage tenant update \ - tenant_id=f2b7b39c860840dfa47d9ee4adffa0b3 \ - description="those other guys" \ - name=tog - -Users ------ - -* user create - - keyword arguments - * name - * password - * email - -example:: - keystone-manage user --ks-id-only create \ - name=admin \ - password=secrete \ - email=admin@example.com - -* user delete - - keyword arguments - -* user list - - keyword arguments - -* user update_email - - keyword arguments - -* user update_enabled - - keyword arguments - -* user update_password - - keyword arguments - -* user update_tenant - - keyword arguments - -Roles ------ - -* role create - - keyword arguments - * name - -exmaple:: - keystone-manage role --ks-id-only create name=Admin - -* role add_user_to_tenant - - keyword arguments - * role_id - * user_id - * tenant_id - -example:: - - keystone-manage role add_user_to_tenant \ - role_id=19d1d3344873464d819c45f521ff9890 \ - user_id=08741d8ed88242ca88d1f61484a0fe3b \ - tenant_id=20601a7f1d94447daa4dff438cb1c209 - -* role remove_user_from_tenant - -* role get_user_role_refs - -Services --------- - -* service create - - keyword arguments - * name - * service_type - * description - -example:: - keystone-manage service create \ - name=nova \ - service_type=compute \ - description="Nova Compute Service" + import_legacy: Import a legacy (pre-essex) version of the db. + export_legacy_catalog: Export service catalog from a legacy (pre-essex) db. OPTIONS @@ -212,11 +79,6 @@ Options: syslog (defaults to LOG_USER) --use-syslog Use syslog for logging. --nouse-syslog Use syslog for logging. - --endpoint=ENDPOINT - --auth-token=AUTH_TOKEN - authorization token - --id-only - --noid-only FILES ===== -- cgit From 90068b0143af788869116d08533d5ebc99874a17 Mon Sep 17 00:00:00 2001 From: Anthony Young Date: Tue, 14 Feb 2012 14:58:55 -0800 Subject: Add docs on keystone_old -> ksl migration * Fixes bug 928046 Change-Id: I4af516dbc9577c08a77850e75e45d98040e4fb27 --- docs/source/configuration.rst | 48 +++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 48 insertions(+) (limited to 'docs') diff --git a/docs/source/configuration.rst b/docs/source/configuration.rst index 7b975b10..22f3748b 100644 --- a/docs/source/configuration.rst +++ b/docs/source/configuration.rst @@ -91,6 +91,54 @@ Invoking this command starts up two wsgi.Server instances, configured by the ``admin`` (the administration API) and the other is ``main`` (the primary/public API interface). Both of these run in a single process. +Migrating from legacy versions of keystone +========================================== +Migration support is provided for the following legacy keystone versions: + +* diablo-5 +* stable/diablo +* essex-2 +* essex-3 + +To migrate from legacy versions of keystone, use the following steps: + +Step 1: Configure keystone.conf +------------------------------- +It is important that the database that you specify be different from the one +containing your existing install. + +Step 2: db_sync your new, empty database +---------------------------------------- +Run the following command to configure the most recent schema in your new +keystone installation:: + + keystone-manage db_sync + +Step 3: Import your legacy data +------------------------------- +Use the following command to import your old data:: + + keystone-manage import_legacy [db_url, e.g. 'mysql://root@foobar/keystone'] + +Specify db_url as the connection string that was present in your old +keystone.conf file. + +Step 3: Import your legacy service catalog +------------------------------------------ +While the older keystone stored the service catalog in the database, +the updated version configures the service catalog using a template file. +An example service catalog template file may be found in +etc/default_catalog.templates. + +To import your legacy catalog, run this command:: + + keystone-manage export_legacy_catalog \ + [db_url e.g. 'mysql://root@foobar/keystone'] > \ + [path_to_templates e.g. 'etc/default_catalog.templates'] + +After executing this command, you will need to restart the keystone service to +see your changes. + Initializing Keystone ===================== -- cgit