Restore man pages source files

Partially reverts I6d67e7a40e16468bb7bf4ac742361fb44eec4e28 to
restore the source files for the man pages.  These are used by
some packagers (confirmed that this is the case for Ubuntu) to
generate the man pages included in their distributions.

Does not add the man pages back to the HTML index, so these will
be orphans for now.  A follow up patch will either add a man build
to tox, or add the HTML generation back so we can review generated
content.

Long term fix will be to merge the content of the --help text
in the cmd files with the content of the man pages and figure
out how to generate the man pages from the --help text.  Right
now, the --help text is better in some regards, and the man pages
are better in others.

Change-Id: I2aa85b63a196c75224630981b322fecbf36f1b7c
This commit is contained in:
Brian Rosmaita 2017-03-03 16:34:27 -05:00
parent 1f55688ee0
commit d785e837d0
14 changed files with 736 additions and 0 deletions

View File

@ -146,6 +146,30 @@ modindex_common_prefix = ['glance.']
# Grouping the document tree for man pages.
# List of tuples 'sourcefile', 'target', u'title', u'Authors name', 'manual'
man_pages = [
('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/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/glancereplicator', 'glance-replicator', u'Glance Replicator',
[u'OpenStack'], 1),
('man/glancescrubber', 'glance-scrubber', u'Glance Scrubber Service',
[u'OpenStack'], 1)
]
# -- Options for HTML output -------------------------------------------------
# The theme to use for HTML and HTML Help pages. Major themes that come with

View File

@ -0,0 +1,9 @@
SEE ALSO
========
* `OpenStack Glance <http://glance.openstack.org>`__
BUGS
====
* Glance bugs are tracked in Launchpad so you can view current bugs at `OpenStack Glance <http://bugs.launchpad.net/glance>`__

View File

@ -0,0 +1,66 @@
**-h, --help**
Show the help message and exit
**--version**
Print the version number and exit
**-v, --verbose**
Print more verbose output
**--noverbose**
Disable verbose output
**-d, --debug**
Print debugging output (set logging level to DEBUG instead of
default WARNING level)
**--nodebug**
Disable debugging output
**--use-syslog**
Use syslog for logging
**--nouse-syslog**
Disable the use of syslog for logging
**--syslog-log-facility SYSLOG_LOG_FACILITY**
syslog facility to receive log lines
**--config-dir DIR**
Path to a config directory to pull \*.conf files from. This
file set is sorted, to provide a predictable parse order
if individual options are over-ridden. The set is parsed after
the file(s) specified via previous --config-file, arguments hence
over-ridden options in the directory take precedence. This means
that configuration from files in a specified config-dir will
always take precedence over configuration from files specified
by --config-file, regardless to argument order.
**--config-file PATH**
Path to a config file to use. Multiple config files can be
specified by using this flag multiple times, for example,
--config-file <file1> --config-file <file2>. Values in latter
files take precedence.
**--log-config-append PATH** **--log-config PATH**
The name of logging configuration file. It does not
disable existing loggers, but just appends specified
logging configuration to any other existing logging
options. Please see the Python logging module documentation
for details on logging configuration files. The log-config
name for this option is deprecated.
**--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, --logfile PATH**
(Optional) Name of log file to output to. If not set, logging
will go to stdout.
**--log-dir LOG_DIR, --logdir LOG_DIR**
(Optional) The directory to keep log files in (will be prepended
to --log-file)

View File

@ -0,0 +1,39 @@
==========
glance-api
==========
---------------------------------------
Server for the Glance Image Service API
---------------------------------------
:Author: glance@lists.launchpad.net
:Date: 2016-10-6
:Copyright: OpenStack Foundation
:Version: 13.0.0
:Manual section: 1
:Manual group: cloud computing
SYNOPSIS
========
glance-api [options]
DESCRIPTION
===========
glance-api is a server daemon that serves the Glance API
OPTIONS
=======
**General options**
.. include:: general_options.rst
FILES
=====
**/etc/glance/glance-api.conf**
Default configuration file for Glance API
.. include:: footer.rst

View File

@ -0,0 +1,47 @@
====================
glance-cache-cleaner
====================
----------------------------------------------------------------
Glance Image Cache Invalid Cache Entry and Stalled Image cleaner
----------------------------------------------------------------
:Author: glance@lists.launchpad.net
:Date: 2016-10-6
:Copyright: OpenStack Foundation
:Version: 13.0.0
: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
entries 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
=======
**General options**
.. include:: general_options.rst
FILES
=====
**/etc/glance/glance-cache.conf**
Default configuration file for the Glance Cache
.. include:: footer.rst

View File

@ -0,0 +1,88 @@
===================
glance-cache-manage
===================
------------------------
Cache management utility
------------------------
:Author: glance@lists.launchpad.net
:Date: 2016-10-6
:Copyright: OpenStack Foundation
:Version: 13.0.0
: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
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
**-k, --insecure**
Explicitly allow glance to perform "insecure" SSL
(https) requests. The server's certificate will not be
verified against any certificate authorities. This
option should be used with caution.
**-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
**-S STRATEGY, --os-auth-strategy=STRATEGY**
Authentication strategy (keystone or noauth)
.. include:: openstack_options.rst
.. include:: footer.rst

View File

@ -0,0 +1,40 @@
=======================
glance-cache-prefetcher
=======================
------------------------------
Glance Image Cache Pre-fetcher
------------------------------
:Author: glance@lists.launchpad.net
:Date: 2016-10-6
:Copyright: OpenStack Foundation
:Version: 13.0.0
: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
=======
**General options**
.. include:: general_options.rst
FILES
=====
**/etc/glance/glance-cache.conf**
Default configuration file for the Glance Cache
.. include:: footer.rst

View File

@ -0,0 +1,41 @@
===================
glance-cache-pruner
===================
-------------------
Glance cache pruner
-------------------
:Author: glance@lists.launchpad.net
:Date: 2016-10-6
:Copyright: OpenStack Foundation
:Version: 13.0.0
:Manual section: 1
:Manual group: cloud computing
SYNOPSIS
========
glance-cache-pruner [options]
DESCRIPTION
===========
Prunes images from the Glance cache when the space exceeds the value
set in the image_cache_max_size configuration option. This is meant
to be run as a periodic task, perhaps every half-hour.
OPTIONS
=======
**General options**
.. include:: general_options.rst
FILES
=====
**/etc/glance/glance-cache.conf**
Default configuration file for the Glance Cache
.. include:: footer.rst

View File

@ -0,0 +1,58 @@
==============
glance-control
==============
--------------------------------------
Glance daemon start/stop/reload helper
--------------------------------------
:Author: glance@lists.launchpad.net
:Date: 2016-10-6
:Copyright: OpenStack Foundation
:Version: 13.0.0
:Manual section: 1
:Manual group: cloud computing
SYNOPSIS
========
glance-control [options] <SERVER> <COMMAND> [CONFPATH]
Where <SERVER> is one of:
all, api, glance-api, registry, glance-registry, scrubber, glance-scrubber
And command is one of:
start, status, stop, shutdown, restart, reload, force-reload
And CONFPATH is the optional configuration file to use.
OPTIONS
=======
**General Options**
.. include:: general_options.rst
**--pid-file=PATH**
File to use as pid file. Default:
/var/run/glance/$server.pid
**--await-child DELAY**
Period to wait for service death in order to report
exit code (default is to not wait at all)
**--capture-output**
Capture stdout/err in syslog instead of discarding
**--nocapture-output**
The inverse of --capture-output
**--norespawn**
The inverse of --respawn
**--respawn**
Restart service on unexpected death
.. include:: footer.rst

View File

@ -0,0 +1,109 @@
=============
glance-manage
=============
-------------------------
Glance Management Utility
-------------------------
:Author: glance@lists.launchpad.net
:Date: 2016-10-6
:Copyright: OpenStack Foundation
:Version: 13.0.0
:Manual section: 1
:Manual group: cloud computing
SYNOPSIS
========
glance-manage [options]
DESCRIPTION
===========
glance-manage is a utility for managing and configuring a Glance installation.
One important use of glance-manage is to setup the database. To do this run::
glance-manage db_sync
Note: glance-manage commands can be run either like this::
glance-manage db sync
or with the db commands concatenated, like this::
glance-manage db_sync
COMMANDS
========
**db**
This is the prefix for the commands below when used with a space
rather than a _. For example "db version".
**db_version**
This will print the current migration level of a glance database.
**db_upgrade [VERSION]**
This will take an existing database and upgrade it to the
specified VERSION.
**db_version_control**
Place the database under migration control.
**db_sync [VERSION]**
Place an existing database under migration control and upgrade it to
the specified VERSION.
**db_expand**
Run this command to expand the database as the first step of a rolling
upgrade process.
**db_migrate**
Run this command to migrate the database as the second step of a
rolling upgrade process.
**db_contract**
Run this command to contract the database as the last step of a rolling
upgrade process.
**db_export_metadefs [PATH | PREFIX]**
Export the metadata definitions into json format. By default the
definitions are exported to /etc/glance/metadefs directory.
**Note: this command will overwrite existing files in the supplied or
default path.**
**db_load_metadefs [PATH]**
Load the metadata definitions into glance database. By default the
definitions are imported from /etc/glance/metadefs directory.
**db_unload_metadefs**
Unload the metadata definitions. Clears the contents of all the glance
db tables including metadef_namespace_resource_types, metadef_tags,
metadef_objects, metadef_resource_types, metadef_namespaces and
metadef_properties.
OPTIONS
=======
**General Options**
.. include:: general_options.rst
.. include:: footer.rst
CONFIGURATION
=============
The following paths are searched for a ``glance-manage.conf`` file in the
following order:
* ``~/.glance``
* ``~/``
* ``/etc/glance``
* ``/etc``
All options set in ``glance-manage.conf`` override those set in
``glance-registry.conf`` and ``glance-api.conf``.

View File

@ -0,0 +1,40 @@
===============
glance-registry
===============
--------------------------------------
Server for the Glance Registry Service
--------------------------------------
:Author: glance@lists.launchpad.net
:Date: 2016-10-6
:Copyright: OpenStack Foundation
:Version: 13.0.0
:Manual section: 1
:Manual group: cloud computing
SYNOPSIS
========
glance-registry [options]
DESCRIPTION
===========
glance-registry is a server daemon that serves image metadata through a
REST-like API.
OPTIONS
=======
**General options**
.. include:: general_options.rst
FILES
=====
**/etc/glance/glance-registry.conf**
Default configuration file for Glance Registry
.. include:: footer.rst

View File

@ -0,0 +1,90 @@
=================
glance-replicator
=================
---------------------------------------------
Replicate images across multiple data centers
---------------------------------------------
:Author: glance@lists.launchpad.net
:Date: 2016-10-6
:Copyright: OpenStack Foundation
:Version: 13.0.0
:Manual section: 1
:Manual group: cloud computing
SYNOPSIS
========
glance-replicator <command> [options] [args]
DESCRIPTION
===========
glance-replicator is a utility can be used to populate a new glance
server using the images stored in an existing glance server. The images
in the replicated glance server preserve the uuids, metadata, and image
data from the original.
COMMANDS
========
**help <command>**
Output help for one of the commands below
**compare**
What is missing from the slave glance?
**dump**
Dump the contents of a glance instance to local disk.
**livecopy**
Load the contents of one glance instance into another.
**load**
Load the contents of a local directory into glance.
**size**
Determine the size of a glance instance if dumped to disk.
OPTIONS
=======
**-h, --help**
Show this help message and exit
**-c CHUNKSIZE, --chunksize=CHUNKSIZE**
Amount of data to transfer per HTTP write
**-d, --debug**
Print debugging information
**-D DONTREPLICATE, --dontreplicate=DONTREPLICATE**
List of fields to not replicate
**-m, --metaonly**
Only replicate metadata, not images
**-l LOGFILE, --logfile=LOGFILE**
Path of file to log to
**-s, --syslog**
Log to syslog instead of a file
**-t TOKEN, --token=TOKEN**
Pass in your authentication token if you have one. If
you use this option the same token is used for both
the master and the slave.
**-M MASTERTOKEN, --mastertoken=MASTERTOKEN**
Pass in your authentication token if you have one.
This is the token used for the master.
**-S SLAVETOKEN, --slavetoken=SLAVETOKEN**
Pass in your authentication token if you have one.
This is the token used for the slave.
**-v, --verbose**
Print more verbose output
.. include:: footer.rst

View File

@ -0,0 +1,63 @@
===============
glance-scrubber
===============
--------------------
Glance scrub service
--------------------
:Author: glance@lists.launchpad.net
:Date: 2016-10-6
:Copyright: OpenStack Foundation
:Version: 13.0.0
:Manual section: 1
:Manual group: cloud computing
SYNOPSIS
========
glance-scrubber [options]
DESCRIPTION
===========
glance-scrubber is a utility that cleans up images that have been deleted. The
mechanics of this differ depending on the backend store and pending_deletion
options chosen.
Multiple glance-scrubbers can be run in a single deployment, but only one of
them may be designated as the 'cleanup_scrubber' in the glance-scrubber.conf
file. The 'cleanup_scrubber' coordinates other glance-scrubbers by maintaining
the master queue of images that need to be removed.
The glance-scubber.conf file also specifies important configuration items such
as the time between runs ('wakeup_time' in seconds), length of time images
can be pending before their deletion ('cleanup_scrubber_time' in seconds) as
well as registry connectivity options.
glance-scrubber can run as a periodic job or long-running daemon.
OPTIONS
=======
**General options**
.. include:: general_options.rst
**-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**
The inverse of --daemon. Runs the scrub operation once and
then exits. This is the default.
FILES
=====
**/etc/glance/glance-scrubber.conf**
Default configuration file for the Glance Scrubber
.. include:: footer.rst

View File

@ -0,0 +1,22 @@
**-os-auth-token=OS_AUTH_TOKEN**
Defaults to env[OS_AUTH_TOKEN]
**--os-username=OS_USERNAME**
Defaults to env[OS_USERNAME]
**--os-password=OS_PASSWORD**
Defaults to env[OS_PASSWORD]
**--os-region-name=OS_REGION_NAME**
Defaults to env[OS_REGION_NAME]
**--os-tenant-id=OS_TENANT_ID**
Defaults to env[OS_TENANT_ID]
**--os-tenant-name=OS_TENANT_NAME**
Defaults to env[OS_TENANT_NAME]
**--os-auth-url=OS_AUTH_URL**
Defaults to env[OS_AUTH_URL]