From 6de9786cc310ec74277413eb692412a1b944b959 Mon Sep 17 00:00:00 2001 From: Joe Heck Date: Mon, 31 Oct 2011 12:22:53 -0700 Subject: [PATCH] adding in doc and setup to cover existing scripts adding doc around credentials command usage (for EC2) Change-Id: Ia5f0ef92caf6e75c8a55fc75a898d835b90b44ac --- doc/source/conf.py | 14 ++- doc/source/configuration.rst | 28 ++++- doc/source/index.rst | 9 +- doc/source/man/keystone-admin.rst | 86 +++++++++++++++ doc/source/man/keystone-auth.rst | 87 +++++++++++++++ doc/source/man/keystone-control.rst | 101 ++++++++++++++++++ doc/source/man/keystone-import.rst | 86 +++++++++++++++ ...keystonemanage.rst => keystone-manage.rst} | 85 ++++++--------- doc/source/man/keystone.rst | 90 ++++++++++++++++ doc/source/man/sampledata.rst | 85 +++++++++++++++ setup.py | 3 +- 11 files changed, 612 insertions(+), 62 deletions(-) create mode 100644 doc/source/man/keystone-admin.rst create mode 100644 doc/source/man/keystone-auth.rst create mode 100644 doc/source/man/keystone-control.rst create mode 100644 doc/source/man/keystone-import.rst rename doc/source/man/{keystonemanage.rst => keystone-manage.rst} (58%) create mode 100644 doc/source/man/keystone.rst create mode 100644 doc/source/man/sampledata.rst diff --git a/doc/source/conf.py b/doc/source/conf.py index a47ad7c568..a6b9591f96 100644 --- a/doc/source/conf.py +++ b/doc/source/conf.py @@ -127,8 +127,18 @@ modindex_common_prefix = ['keystone.'] # List of tuples 'sourcefile', 'target', u'title', u'Authors name', 'manual' man_pages = [ - ('man/keystonemanage', 'keystone-manage', u'Keystone Management Utility', - [u'OpenStack'], 1) + ('man/keystone-manage', 'keystone-manage', u'Keystone Management Utility', + [u'OpenStack'], 1), + ('man/keystone', 'keystone', u'Keystone Startup Command', + [u'OpenStack'], 1), + ('man/keystone-auth', 'keystone-auth', u'Keystone Startup Command', + [u'OpenStack'], 1), + ('man/keystone-admin', 'keystone-admin', u'Keystone Startup Command', + [u'OpenStack'], 1), + ('man/keystone-import', 'keystone-import', u'Keystone Management Utility', + [u'OpenStack'], 1), + ('man/keystone-control', 'keystone-control', + u'Keystone Management Utility', [u'OpenStack'], 1) ] diff --git a/doc/source/configuration.rst b/doc/source/configuration.rst index 4aa5b4fb9e..df770d798a 100644 --- a/doc/source/configuration.rst +++ b/doc/source/configuration.rst @@ -22,7 +22,7 @@ Configuring Keystone :maxdepth: 1 keystone.conf - man/keystonemanage.rst + man/keystone-manage Once Keystone is installed, it needs to be configured with any services that will be using Keystone, and those services need to be provided with @@ -44,7 +44,7 @@ systems may authenticate against them. For the keystone service itself, two Roles are pre-defined in the keystone configuration file (:doc:`keystone.conf`). -These roles still need to be created using :doc:`man/keystonemanage` +These roles still need to be created using :doc:`man/keystone-manage` commands to be able to use them:: $> keystone-manage user add admin secrete @@ -54,9 +54,9 @@ commands to be able to use them:: $> keystone-manage role grant KeystoneServiceAdmin admin Once these are defined, you should now have the choice of using the -administrative API (as well as the :doc:`man/keystonemanage` commands) to further -configure keystone. There are a number of examples of how to use that API at -:doc:`adminAPI_curl_examples`. +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 service endpoints ============================ @@ -175,6 +175,24 @@ 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` Configuring Nova to use Keystone ################################ diff --git a/doc/source/index.rst b/doc/source/index.rst index 85d19565d4..b6505afcd6 100644 --- a/doc/source/index.rst +++ b/doc/source/index.rst @@ -38,6 +38,7 @@ Getting Started testing configuration community + usingkeystone API Use Case Examples ===================== @@ -63,7 +64,13 @@ Man Pages .. toctree:: :maxdepth: 1 - man/keystonemanage.rst + man/keystone-manage + man/keystone + man/keystone-auth + man/keystone-admin + man/keystone-import + man/keystone-control + man/sampledata Developer Docs ============== diff --git a/doc/source/man/keystone-admin.rst b/doc/source/man/keystone-admin.rst new file mode 100644 index 0000000000..aaba6e51b3 --- /dev/null +++ b/doc/source/man/keystone-admin.rst @@ -0,0 +1,86 @@ +============== +keystone-admin +============== + +--------------------------- +Keystone Management Utility +--------------------------- + +:Author: keystone@lists.launchpad.net +:Date: 2011-10-31 +:Copyright: OpenStack LLC +:Version: 0.1.2 +:Manual section: 1 +:Manual group: cloud computing + +SYNOPSIS +======== + + keystone-admin [options] + +DESCRIPTION +=========== + +keystone-admin starts the administrative API server for Keystone. +Use :doc:`keystone-control` to stop/start/restart and manage those services +once started. + +USAGE +===== + + ``keystone-admin [options]`` + +Common 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/doc/source/man/keystone-auth.rst b/doc/source/man/keystone-auth.rst new file mode 100644 index 0000000000..1cec5a9524 --- /dev/null +++ b/doc/source/man/keystone-auth.rst @@ -0,0 +1,87 @@ +============= +keystone-auth +============= + +--------------------------- +Keystone Management Utility +--------------------------- + +:Author: keystone@lists.launchpad.net +:Date: 2011-10-31 +:Copyright: OpenStack LLC +:Version: 0.1.2 +:Manual section: 1 +:Manual group: cloud computing + +SYNOPSIS +======== + + keystone-auth [options] + +DESCRIPTION +=========== + +keystone-auth starts the service API server for Keystone. +Use :doc:`keystone-control` to stop/start/restart and manage those services +once started. + +USAGE +===== + + ``keystone-auth [options]`` + +Common 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/doc/source/man/keystone-control.rst b/doc/source/man/keystone-control.rst new file mode 100644 index 0000000000..8927647ed2 --- /dev/null +++ b/doc/source/man/keystone-control.rst @@ -0,0 +1,101 @@ +================ +keystone-control +================ + +--------------------------- +Keystone Management Utility +--------------------------- + +:Author: keystone@lists.launchpad.net +:Date: 2011-10-31 +:Copyright: OpenStack LLC +:Version: 0.1.2 +:Manual section: 1 +:Manual group: cloud computing + +SYNOPSIS +======== + + keystone-control [options] () + +DESCRIPTION +=========== + +keystone-control is the command line tool that interacts with the keystone +service to configure Keystone + +USAGE +===== + + ``keystone-control [options] ()`` + +where server is one of: + +* all +* auth +* admin + +and command is one of: + +* start +* stop +* shutdown +* restart +* reload +* force-reload + +Common 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/doc/source/man/keystone-import.rst b/doc/source/man/keystone-import.rst new file mode 100644 index 0000000000..69abd93032 --- /dev/null +++ b/doc/source/man/keystone-import.rst @@ -0,0 +1,86 @@ +=============== +keystone-import +=============== + +--------------------------- +Keystone Management Utility +--------------------------- + +:Author: keystone@lists.launchpad.net +:Date: 2011-10-31 +:Copyright: OpenStack LLC +:Version: 0.1.2 +:Manual section: 1 +:Manual group: cloud computing + +SYNOPSIS +======== + + keystone-import [options] filename + +DESCRIPTION +=========== + +keystone-import takes a file of commands written in the same format as using +:doc:`keystone-manage` and imports that data into Keystone. It is intended to +import users, tenants, and EC2 credentials from nova into keystone. + +USAGE +===== + + ``keystone-import [options] filename`` + +Common 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/doc/source/man/keystonemanage.rst b/doc/source/man/keystone-manage.rst similarity index 58% rename from doc/source/man/keystonemanage.rst rename to doc/source/man/keystone-manage.rst index 4e96fc5e23..4335258b96 100644 --- a/doc/source/man/keystonemanage.rst +++ b/doc/source/man/keystone-manage.rst @@ -139,63 +139,42 @@ credentials OPTIONS ======= -Common Options: - - The following configuration options are common to all keystone - programs. - - --version - Show 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 + --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. +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) + --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 ===== diff --git a/doc/source/man/keystone.rst b/doc/source/man/keystone.rst new file mode 100644 index 0000000000..48e062e436 --- /dev/null +++ b/doc/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/doc/source/man/sampledata.rst b/doc/source/man/sampledata.rst new file mode 100644 index 0000000000..636d9bdeed --- /dev/null +++ b/doc/source/man/sampledata.rst @@ -0,0 +1,85 @@ +========== +sampledata +========== + +--------------------------- +Keystone Management Utility +--------------------------- + +:Author: keystone@lists.launchpad.net +:Date: 2011-10-31 +:Copyright: OpenStack LLC +:Version: 0.1.2 +:Manual section: 1 +:Manual group: cloud computing + +SYNOPSIS +======== + + sampledata [options] + +DESCRIPTION +=========== + +sampledata creates a development set of sample data for use with testing +keystone. + +USAGE +===== + + ``sampledata [options]`` + +Common 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/setup.py b/setup.py index 2d99642eb9..49594d78f8 100755 --- a/setup.py +++ b/setup.py @@ -55,7 +55,8 @@ setup( include_package_data=True, packages=find_packages(exclude=['test', 'bin']), scripts=['bin/keystone', 'bin/keystone-auth', 'bin/keystone-admin', - 'bin/keystone-manage'], + 'bin/keystone-manage', 'bin/keystone-import', + 'bin/keystone-control'], zip_safe=False, cmdclass=cmdclass, install_requires=['setuptools'],