openstack/glance
Code Issues Proposed changes

Add more man pages.

Browse Source 
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
This commit is contained in:
Russell Bryant 2012-01-03 16:04:25 -05:00
parent 98b19af07b
commit 58532a4373
9 changed files with 809 additions and 1 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

18
doc/source/conf.py
View File

@ -126,11 +126,27 @@ modindex_common_prefix = ['glance.']
# List of tuples 'sourcefile', 'target', u'title', u'Authors name', 'manual' # List of tuples 'sourcefile', 'target', u'title', u'Authors name', 'manual'
man_pages = [ man_pages = [
('man/glance', 'glance', u'Glance CLI',
[u'OpenStack'], 1),
('man/glanceapi', 'glance-api', u'Glance API Server', ('man/glanceapi', 'glance-api', u'Glance API Server',
[u'OpenStack'], 1), [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', ('man/glanceregistry', 'glance-registry', u'Glance Registry Server',
[u'OpenStack'], 1), [u'OpenStack'], 1),
('man/glancemanage', 'glance-manage', u'Glance Management Utility', ('man/glancescrubber', 'glance-scrubber', u'Glance Scrubber Service',
[u'OpenStack'], 1) [u'OpenStack'], 1)
] ]

131
doc/source/man/glance.rst Normal file
View File

@ -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 <command> [options] [args]
COMMANDS
========
**help <command>**
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 <http://glance.openstack.org>`__
BUGS
====
* Glance is sourced in Launchpad so you can view current bugs at `OpenStack Glance <http://glance.openstack.org>`__

101
doc/source/man/glancecachecleaner.rst Normal file
View File

@ -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 <http://glance.openstack.org>`__
BUGS
====
* Glance is sourced in Launchpad so you can view current bugs at `OpenStack Glance <http://glance.openstack.org>`__

88
doc/source/man/glancecachemanage.rst Normal file
View File

@ -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 <command> [options] [args]
COMMANDS
========
**help <command>**
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 <http://glance.openstack.org>`__
BUGS
====
* Glance is sourced in Launchpad so you can view current bugs at `OpenStack Glance <http://glance.openstack.org>`__

96
doc/source/man/glancecacheprefetcher.rst Normal file
View File

@ -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 <http://glance.openstack.org>`__
BUGS
====
* Glance is sourced in Launchpad so you can view current bugs at `OpenStack Glance <http://glance.openstack.org>`__

95
doc/source/man/glancecachepruner.rst Normal file
View File

@ -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 <http://glance.openstack.org>`__
BUGS
====
* Glance is sourced in Launchpad so you can view current bugs at `OpenStack Glance <http://glance.openstack.org>`__

87
doc/source/man/glancecachequeueimage.rst Normal file
View File

@ -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] <IMAGE_ID1> [<IMAGE_ID2> ... <IMAGE_IDN>]
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 <http://glance.openstack.org>`__
BUGS
====
* Glance is sourced in Launchpad so you can view current bugs at `OpenStack Glance <http://glance.openstack.org>`__

94
doc/source/man/glancecontrol.rst Normal file
View File

@ -0,0 +1,94 @@
==============
glance-control
==============
--------------------------------------
Glance daemon start/stop/reload helper
--------------------------------------
SYNOPSIS
========
glance-control [options] <SERVER> <COMMAND> [CONFPATH]
Where <SERVER> 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 <http://glance.openstack.org>`__
BUGS
====
* Glance is sourced in Launchpad so you can view current bugs at `OpenStack Glance <http://glance.openstack.org>`__

100
doc/source/man/glancescrubber.rst Normal file
View File

@ -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 <http://glance.openstack.org>`__
BUGS
====
* Glance is sourced in Launchpad so you can view current bugs at `OpenStack Glance <http://glance.openstack.org>`__