From 58532a43738917dc7588f2bd5e96f658ce7ba64d Mon Sep 17 00:00:00 2001 From: Russell Bryant Date: Tue, 3 Jan 2012 16:04:25 -0500 Subject: [PATCH] Add more man pages. A few man pages were already in place. This patch uses the --help output from each executable to seed a man page for the rest of the executables, which include: - glance - glance-cache-cleaner - glance-cache-manage - glance-cache-prefetcher - glance-cache-pruner - glance-cache-queue-image - glance-control - glance-scrubber Fixes bug 911291. Change-Id: Ie0de990ff6617e7eb953f270a089c99bc340b4fe --- doc/source/conf.py | 18 +++- doc/source/man/glance.rst | 131 +++++++++++++++++++++++ doc/source/man/glancecachecleaner.rst | 101 +++++++++++++++++ doc/source/man/glancecachemanage.rst | 88 +++++++++++++++ doc/source/man/glancecacheprefetcher.rst | 96 +++++++++++++++++ doc/source/man/glancecachepruner.rst | 95 ++++++++++++++++ doc/source/man/glancecachequeueimage.rst | 87 +++++++++++++++ doc/source/man/glancecontrol.rst | 94 ++++++++++++++++ doc/source/man/glancescrubber.rst | 100 +++++++++++++++++ 9 files changed, 809 insertions(+), 1 deletion(-) create mode 100644 doc/source/man/glance.rst create mode 100644 doc/source/man/glancecachecleaner.rst create mode 100644 doc/source/man/glancecachemanage.rst create mode 100644 doc/source/man/glancecacheprefetcher.rst create mode 100644 doc/source/man/glancecachepruner.rst create mode 100644 doc/source/man/glancecachequeueimage.rst create mode 100644 doc/source/man/glancecontrol.rst create mode 100644 doc/source/man/glancescrubber.rst diff --git a/doc/source/conf.py b/doc/source/conf.py index 3ecbb03f7b..5b02862180 100644 --- a/doc/source/conf.py +++ b/doc/source/conf.py @@ -126,11 +126,27 @@ modindex_common_prefix = ['glance.'] # List of tuples 'sourcefile', 'target', u'title', u'Authors name', 'manual' man_pages = [ + ('man/glance', 'glance', u'Glance CLI', + [u'OpenStack'], 1), ('man/glanceapi', 'glance-api', u'Glance API Server', [u'OpenStack'], 1), + ('man/glancecachecleaner', 'glance-cache-cleaner', u'Glance Cache Cleaner', + [u'OpenStack'], 1), + ('man/glancecachemanage', 'glance-cache-manage', u'Glance Cache Manager', + [u'OpenStack'], 1), + ('man/glancecacheprefetcher', 'glance-cache-prefetcher', + u'Glance Cache Pre-fetcher', [u'OpenStack'], 1), + ('man/glancecachepruner', 'glance-cache-pruner', u'Glance Cache Pruner', + [u'OpenStack'], 1), + ('man/glancecachequeueimage', 'glance-cache-queue-image', + u'Glance Cache Queue Image', [u'OpenStack'], 1), + ('man/glancecontrol', 'glance-control', u'Glance Daemon Control Helper ', + [u'OpenStack'], 1), + ('man/glancemanage', 'glance-manage', u'Glance Management Utility', + [u'OpenStack'], 1), ('man/glanceregistry', 'glance-registry', u'Glance Registry Server', [u'OpenStack'], 1), - ('man/glancemanage', 'glance-manage', u'Glance Management Utility', + ('man/glancescrubber', 'glance-scrubber', u'Glance Scrubber Service', [u'OpenStack'], 1) ] diff --git a/doc/source/man/glance.rst b/doc/source/man/glance.rst new file mode 100644 index 0000000000..16ecdc11bf --- /dev/null +++ b/doc/source/man/glance.rst @@ -0,0 +1,131 @@ +====== +glance +====== + +----------------------------- +Glance command line interface +----------------------------- + +:Author: glance@lists.launchpad.net +:Date: 2012-01-03 +:Copyright: OpenStack LLC +:Version: 2012.1-dev +:Manual section: 1 +:Manual group: cloud computing + + +SYNOPSIS +======== + + glance [options] [args] + + +COMMANDS +======== + + **help ** + Output help for one of the commands below + + **add** + Adds a new image to Glance + + **update** + Updates an image's metadata in Glance + + **delete** + Deletes an image from Glance + + **index** + Return brief information about images in Glance + + **details** + Return detailed information about images in Glance + + **show** + Show detailed information about an image in Glance + + **clear** + Removes all images and metadata from Glance + + +MEMBER COMMANDS +=============== + + **image-members** + List members an image is shared with + + **member-images** + List images shared with a member + + **member-add** + Grants a member access to an image + + **member-delete** + Revokes a member's access to an image + + **members-replace** + Replaces all membership for an image + + +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 more verbose output + + **-H ADDRESS, --host=ADDRESS** + Address of Glance API host. Default: 0.0.0.0 + + **-p PORT, --port=PORT** + Port the Glance API host listens on. Default: 9292 + + **-U URL, --url=URL** + URL of Glance service. This option can be used to specify the hostname, + port and protocol (http/https) of the glance server, for example + -U https://localhost:9292/v1 + Default: None + + **-A TOKEN, --auth_token=TOKEN** + Authentication token to use to identify the client to the glance server + + **--limit=LIMIT** + Page size to use while requesting image metadata + + **--marker=MARKER** + Image index after which to begin pagination + + **--sort_key=KEY** + Sort results by this image attribute. + + **--sort_dir=[desc|asc]** + Sort results in this direction. + + **-f, --force** + Prevent select actions from requesting user confirmation + + **--dry-run** + Don't actually execute the command, just print output showing what + WOULD happen. + + **--can-share** + Allow member to further share image. + + +SEE ALSO +======== + +* `OpenStack Glance `__ + +BUGS +==== + +* Glance is sourced in Launchpad so you can view current bugs at `OpenStack Glance `__ diff --git a/doc/source/man/glancecachecleaner.rst b/doc/source/man/glancecachecleaner.rst new file mode 100644 index 0000000000..99d044681e --- /dev/null +++ b/doc/source/man/glancecachecleaner.rst @@ -0,0 +1,101 @@ +==================== +glance-cache-cleaner +==================== + +---------------------------------------------------------------- +Glance Image Cache Invalid Cache Entry and Stalled Image cleaner +---------------------------------------------------------------- + +:Author: glance@lists.launchpad.net +:Date: 2012-01-03 +:Copyright: OpenStack LLC +:Version: 2012.1-dev +:Manual section: 1 +:Manual group: cloud computing + +SYNOPSIS +======== + + glance-cache-cleaner [options] + +DESCRIPTION +=========== + +This is meant to be run as a periodic task from cron. + +If something goes wrong while we're caching an image (for example the fetch +times out, or an exception is raised), we create an 'invalid' entry. These +entires are left around for debugging purposes. However, after some period of +time, we want to clean these up. + +Also, if an incomplete image hangs around past the image_cache_stall_time +period, we automatically sweep it up. + +OPTIONS +======= + + **--version** + show program's version number and exit + + **-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** + Do not print debugging output + + **-v, --verbose** + Print more verbose output + + **--noverbose** + Do not print 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) + + **--use-syslog** + Use syslog for logging. + + **--nouse-syslog** + Do not use syslog for logging. + + **--syslog-log-facility=SYSLOG_LOG_FACILITY** + syslog facility to receive log lines + +SEE ALSO +======== + +* `OpenStack Glance `__ + +BUGS +==== + +* Glance is sourced in Launchpad so you can view current bugs at `OpenStack Glance `__ diff --git a/doc/source/man/glancecachemanage.rst b/doc/source/man/glancecachemanage.rst new file mode 100644 index 0000000000..e32a99cbee --- /dev/null +++ b/doc/source/man/glancecachemanage.rst @@ -0,0 +1,88 @@ +=================== +glance-cache-manage +=================== + +------------------------ +Cache management utility +------------------------ + +:Author: glance@lists.launchpad.net +:Date: 2012-01-03 +:Copyright: OpenStack LLC +:Version: 2012.1-dev +:Manual section: 1 +:Manual group: cloud computing + +SYNOPSIS +======== + + glance-cache-manage [options] [args] + +COMMANDS +======== + + **help ** + Output help for one of the commands below + + **list-cached** + List all images currently cached + + **list-queued** + List all images currently queued for caching + + **queue-image** + Queue an image for caching + + **delete-cached-image** + Purges an image from the cache + + **delete-all-cached-images** + Removes all images from the cache + + **delete-queued-image** + Deletes an image from the cache queue + + **delete-all-queued-images** + Deletes all images from the cache queue + + **clean** + Removes any stale or invalid image files from the cache + +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 more verbose output + + **-H ADDRESS, --host=ADDRESS** + Address of Glance API host. + Default: 0.0.0.0 + + **-p PORT, --port=PORT** + Port the Glance API host listens on. + Default: 9292 + + **-A TOKEN, --auth_token=TOKEN** + Authentication token to use to identify the client to the glance server + + **-f, --force** + Prevent select actions from requesting user confirmation + +SEE ALSO +======== + +* `OpenStack Glance `__ + +BUGS +==== + +* Glance is sourced in Launchpad so you can view current bugs at `OpenStack Glance `__ diff --git a/doc/source/man/glancecacheprefetcher.rst b/doc/source/man/glancecacheprefetcher.rst new file mode 100644 index 0000000000..e9e9fb7a0c --- /dev/null +++ b/doc/source/man/glancecacheprefetcher.rst @@ -0,0 +1,96 @@ +======================= +glance-cache-prefetcher +======================= + +------------------------------ +Glance Image Cache Pre-fetcher +------------------------------ + +:Author: glance@lists.launchpad.net +:Date: 2012-01-03 +:Copyright: OpenStack LLC +:Version: 2012.1-dev +:Manual section: 1 +:Manual group: cloud computing + +SYNOPSIS +======== + + glance-cache-prefetcher [options] + +DESCRIPTION +=========== + +This is meant to be run from the command line after queueing +images to be pretched. + +OPTIONS +======= + + **--version** + show program's version number and exit + + **-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** + Do not print debugging output + + **-v, --verbose** + Print more verbose output + + **--noverbose** + Do not print 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) + + **--use-syslog** + Use syslog for logging. + + **--nouse-syslog** + Do not use syslog for logging. + + **--syslog-log-facility=SYSLOG_LOG_FACILITY** + syslog facility to receive log lines + +SEE ALSO +======== + +* `OpenStack Glance `__ + +BUGS +==== + +* Glance is sourced in Launchpad so you can view current bugs at `OpenStack Glance `__ diff --git a/doc/source/man/glancecachepruner.rst b/doc/source/man/glancecachepruner.rst new file mode 100644 index 0000000000..6e048a05e7 --- /dev/null +++ b/doc/source/man/glancecachepruner.rst @@ -0,0 +1,95 @@ +=================== +glance-cache-pruner +=================== + +------------------- +Glance cache pruner +------------------- + +:Author: glance@lists.launchpad.net +:Date: 2012-01-03 +:Copyright: OpenStack LLC +:Version: 2012.1-dev +:Manual section: 1 +:Manual group: cloud computing + +SYNOPSIS +======== + + glance-cache-pruner [options] + +DESCRIPTION +=========== + +This is meant to be run as a periodic task, perhaps every half-hour. + +OPTIONS +======= + + **--version** + show program's version number and exit + + **-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** + Do not print debugging output + + **-v, --verbose** + Print more verbose output + + **--noverbose** + Do not 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) + + **--use-syslog** + Use syslog for logging. + + **--nouse-syslog** + Do not use syslog for logging. + + **--syslog-log-facility=SYSLOG_LOG_FACILITY** + syslog facility to receive log lines + +SEE ALSO +======== + +* `OpenStack Glance `__ + +BUGS +==== + +* Glance is sourced in Launchpad so you can view current bugs at `OpenStack Glance `__ diff --git a/doc/source/man/glancecachequeueimage.rst b/doc/source/man/glancecachequeueimage.rst new file mode 100644 index 0000000000..84bba176c9 --- /dev/null +++ b/doc/source/man/glancecachequeueimage.rst @@ -0,0 +1,87 @@ +======================== +glance-cache-queue-image +======================== + +---------------------------- +Queue images for prefetching +---------------------------- + +:Author: glance@lists.launchpad.net +:Date: 2012-01-03 +:Copyright: OpenStack LLC +:Version: 2012.1-dev +:Manual section: 1 +:Manual group: cloud computing + +SYNOPSIS +======== + + glance-cache-queue-image [OPTIONS] [ ... ] + +OPTIONS +======= + + **--version** + show program's version number and exit + + **-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** + Do not print debugging output + + **-v, --verbose** + Print more verbose output + + **--noverbose** + Do not 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) + + **--use-syslog** + Use syslog for logging. + + **--nouse-syslog** + Do not use syslog for logging. + + **--syslog-log-facility=SYSLOG_LOG_FACILITY** + syslog facility to receive log lines + +SEE ALSO +======== + +* `OpenStack Glance `__ + +BUGS +==== + +* Glance is sourced in Launchpad so you can view current bugs at `OpenStack Glance `__ diff --git a/doc/source/man/glancecontrol.rst b/doc/source/man/glancecontrol.rst new file mode 100644 index 0000000000..0d3dc1ee42 --- /dev/null +++ b/doc/source/man/glancecontrol.rst @@ -0,0 +1,94 @@ +============== +glance-control +============== + +-------------------------------------- +Glance daemon start/stop/reload helper +-------------------------------------- + +SYNOPSIS +======== + + glance-control [options] [CONFPATH] + +Where is one of: + + all, api, registry, scrubber + +And command is one of: + + start, stop, shutdown, restart, reload, force-reload + +And CONFPATH is the optional configuration file to use. + +OPTIONS +======= + + **--version** + show program's version number and exit + + **-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** + Do not print debugging output + + **-v, --verbose** + Print more verbose output + + **--noverbose** + Do not 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) + + **--use-syslog** + Use syslog for logging. + + **--nouse-syslog** + Do not use syslog for logging. + + **--syslog-log-facility=SYSLOG_LOG_FACILITY** + syslog facility to receive log lines + + **--pid-file=PATH** + File to use as pid file. Default: + /var/run/glance/$server.pid + +SEE ALSO +======== + +* `OpenStack Glance `__ + +BUGS +==== + +* Glance is sourced in Launchpad so you can view current bugs at `OpenStack Glance `__ diff --git a/doc/source/man/glancescrubber.rst b/doc/source/man/glancescrubber.rst new file mode 100644 index 0000000000..9131b6ea5f --- /dev/null +++ b/doc/source/man/glancescrubber.rst @@ -0,0 +1,100 @@ +=============== +glance-scrubber +=============== + +-------------------- +Glance scrub service +-------------------- + +:Author: glance@lists.launchpad.net +:Date: 2012-01-03 +:Copyright: OpenStack LLC +:Version: 2012.1-dev +:Manual section: 1 +:Manual group: cloud computing + +SYNOPSIS +======== + + glance-scrubber [options] + +OPTIONS +======= + + **--version** + show program's version number and exit + + **-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** + Do not print debugging output + + **-v, --verbose** + Print more verbose output + + **--noverbose** + Do not print 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) + + **--use-syslog** + Use syslog for logging. + + **--nouse-syslog** + Do not use syslog for logging. + + **--syslog-log-facility=SYSLOG_LOG_FACILITY** + syslog facility to receive log lines + + **-D, --daemon** + Run as a long-running process. When not specified (the + default) run the scrub operation once and then exits. + When specified do not exit and run scrub on + wakeup_time interval as specified in the config. + + **--nodaemon** + Run as a long-running process. When not specified (the + default) run the scrub operation once and then exits. + When specified do not exit and run scrub on + wakeup_time interval as specified in the config. + +SEE ALSO +======== + +* `OpenStack Glance `__ + +BUGS +==== + +* Glance is sourced in Launchpad so you can view current bugs at `OpenStack Glance `__