Browse Source

updating docs:

* reference keystone-all instead of keystone
* remove reference to keystone.version
* rename gnerated man page
* spacing and line wrapping
changes/32/3832/1
Joe Heck 10 years ago
parent
commit
32ff03b6dc
  1. 4
      README.rst
  2. 16
      docs/source/conf.py
  3. 154
      docs/source/configuration.rst
  4. 23
      docs/source/configuringservices.rst
  5. 30
      docs/source/developing.rst
  6. 12
      docs/source/man/keystone-all.rst
  7. 3
      docs/source/nova-api-paste.rst
  8. 17
      docs/source/setup.rst

4
README.rst

@ -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

16
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'),
]

154
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

23
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.

30
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 `<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::

12
docs/source/man/keystone.rst → docs/source/man/keystone-all.rst

@ -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>`__

3
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

17
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

Loading…
Cancel
Save