updating docs:
* reference keystone-all instead of keystone * remove reference to keystone.version * rename gnerated man page * spacing and line wrapping
This commit is contained in:
parent
4f651ba242
commit
32ff03b6dc
|
@ -152,7 +152,7 @@ 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
|
||||
For the purposes of Keystone there are only a couple levels of
|
||||
authorization being checked for:
|
||||
|
||||
* Require that the performing user is considered an admin.
|
||||
|
@ -160,7 +160,7 @@ authorization being checked for:
|
|||
|
||||
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:
|
||||
in Keystone are:
|
||||
|
||||
|
||||
Trivial True
|
||||
|
|
|
@ -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'),
|
||||
]
|
||||
|
||||
|
|
|
@ -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
|
||||
|
||||
|
|
|
@ -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.
|
||||
|
||||
|
|
|
@ -22,7 +22,7 @@ Contributing Code
|
|||
=================
|
||||
|
||||
To contribute code, sign up for a Launchpad account and sign a contributor license agreement,
|
||||
available on the `<http://wiki.openstack.org/CLA>`_. Once the CLA is signed you
|
||||
available on the `<http://wiki.openstack.org/CLA>`_. Once the CLA is signed you
|
||||
can contribute code through the Gerrit version control system which is related to your Launchpad account.
|
||||
|
||||
To contribute tests, docs, code, etc, refer to our `Gerrit-Jenkins-Github Workflow`_.
|
||||
|
@ -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::
|
||||
|
||||
|
|
|
@ -16,17 +16,19 @@ Keystone Management Utility
|
|||
SYNOPSIS
|
||||
========
|
||||
|
||||
keystone [options]
|
||||
keystone-all [options]
|
||||
|
||||
DESCRIPTION
|
||||
===========
|
||||
|
||||
keystone starts both the service and administrative APIs for Keystone.
|
||||
keystone-all starts both the service and administrative APIs in a single
|
||||
process to provide catalog, authorization, and authentication services for
|
||||
OpenStack.
|
||||
|
||||
USAGE
|
||||
=====
|
||||
|
||||
keystone ``keystone [options]``
|
||||
``keystone-all [options]``
|
||||
|
||||
Common Options:
|
||||
^^^^^^^^^^^^^^^
|
||||
|
@ -63,7 +65,7 @@ programs.::
|
|||
syslog (defaults to LOG_USER)
|
||||
--use-syslog Use syslog for logging.
|
||||
--nouse-syslog Use syslog for logging.
|
||||
|
||||
|
||||
FILES
|
||||
=====
|
||||
|
||||
|
@ -77,5 +79,5 @@ SEE ALSO
|
|||
SOURCE
|
||||
======
|
||||
|
||||
* Keystone is sourced in GitHub `Keystone <http://github.com/openstack/keystone>`__
|
||||
* Keystone source in managed in GitHub `Keystone <http://github.com/openstack/keystone>`__
|
||||
* Keystone bugs are managed at Launchpad `Launchpad Keystone <https://bugs.launchpad.net/keystone>`__
|
|
@ -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
|
||||
|
|
|
@ -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
|
||||
|
|
Loading…
Reference in New Issue