openstack/glance
Code Issues Proposed changes

Update all the glance manpages

Browse Source 
Finish updating the glance manpages:
  - Update and modernize all files and references
  - Add a new manpage for glance-replicator
  - Move the common configuration options to common files for
    easier maintenance and less redundancy

Change-Id: If2cbcc30f2761b187038f39324c7698de4eb2ab9
Closes-Bug: #1238366
This commit is contained in:
Matt Fischer 2014-01-16 22:03:58 -07:00
parent 016204e8c4
commit 8f1c1b1a3b
14 changed files with 325 additions and 454 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

4
doc/source/conf.py
View File

@ -64,7 +64,7 @@ master_doc = 'index'
# General information about the project.
project = u'Glance'
copyright = u'2010, OpenStack Foundation.'
copyright = u'2010-2014, OpenStack Foundation.'
# The version info for the project you're documenting, acts as replacement for
# |version| and |release|, also used in various other places throughout the
@ -136,6 +136,8 @@ man_pages = [
[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)
]

9
doc/source/man/footer.rst Normal file
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>`__

67
doc/source/man/general_options.rst Normal file
View File

@ -0,0 +1,67 @@
**-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, so as 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 depcrecated.
**--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)

78
doc/source/man/glanceapi.rst
View File

@ -7,7 +7,7 @@ Server for the Glance Image Service API
---------------------------------------
:Author: glance@lists.launchpad.net
:Date: 2014-01-02
:Date: 2014-01-16
:Copyright: OpenStack LLC
:Version: 2014.1
:Manual section: 1
@ -28,71 +28,7 @@ OPTIONS
**General options**
**-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, so as 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. If not specified, the default file
used is: /etc/glance/glance-api.conf
**--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, --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)
.. include:: general_options.rst
FILES
=====
@ -100,12 +36,4 @@ FILES
**/etc/glance/glance-api.conf**
Default configuration file for Glance API
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>`__
.. include:: footer.rst

74
doc/source/man/glancecachecleaner.rst
View File

@ -7,16 +7,16 @@ Glance Image Cache Invalid Cache Entry and Stalled Image cleaner
----------------------------------------------------------------
:Author: glance@lists.launchpad.net
:Date: 2012-01-03
:Date: 2014-01-16
:Copyright: OpenStack LLC
:Version: 2012.1-dev
:Version: 2014.1
:Manual section: 1
:Manual group: cloud computing
SYNOPSIS
========
glance-cache-cleaner [options]
glance-cache-cleaner [options]
DESCRIPTION
===========
@ -34,68 +34,14 @@ period, we automatically sweep it up.
OPTIONS
=======
**--version**
show program's version number and exit
**General options**
**-h, --help**
show this help message and exit
.. include:: general_options.rst
**--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: []
FILES
======
**-d, --debug**
Print debugging output
**/etc/glance/glance-cache.conf**
Default configuration file for the Glance Cache
**--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>`__
.. include:: footer.rst

21
doc/source/man/glancecachemanage.rst
View File

@ -7,9 +7,9 @@ Cache management utility
------------------------
:Author: glance@lists.launchpad.net
:Date: 2012-01-03
:Date: 2014-01-16
:Copyright: OpenStack LLC
:Version: 2012.1-dev
:Version: 2014.1
:Manual section: 1
:Manual group: cloud computing
@ -68,18 +68,21 @@ OPTIONS
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
SEE ALSO
========
**-S STRATEGY, --os-auth-strategy=STRATEGY**
Authentication strategy (keystone or noauth)
* `OpenStack Glance <http://glance.openstack.org>`__
.. include:: openstack_options.rst
BUGS
====
* Glance is sourced in Launchpad so you can view current bugs at `OpenStack Glance <http://glance.openstack.org>`__
.. include:: footer.rst

74
doc/source/man/glancecacheprefetcher.rst
View File

@ -7,9 +7,9 @@ Glance Image Cache Pre-fetcher
------------------------------
:Author: glance@lists.launchpad.net
:Date: 2012-01-03
:Date: 2014-01-16
:Copyright: OpenStack LLC
:Version: 2012.1-dev
:Version: 2014.1
:Manual section: 1
:Manual group: cloud computing
@ -27,70 +27,14 @@ images to be pretched.
OPTIONS
=======
**--version**
show program's version number and exit
**General options**
**-h, --help**
show this help message and exit
.. include:: general_options.rst
**--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: []
FILES
=====
**-d, --debug**
Print debugging output
**/etc/glance/glance-cache.conf**
Default configuration file for the Glance Cache
**--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>`__
.. include:: footer.rst

82
doc/source/man/glancecachepruner.rst
View File

@ -7,9 +7,9 @@ Glance cache pruner
-------------------
:Author: glance@lists.launchpad.net
:Date: 2012-01-03
:Date: 2014-01-16
:Copyright: OpenStack LLC
:Version: 2012.1-dev
:Version: 2014.1
:Manual section: 1
:Manual group: cloud computing
@ -21,75 +21,21 @@ SYNOPSIS
DESCRIPTION
===========
This is meant to be run as a periodic task, perhaps every half-hour.
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
=======
**--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>`__
**General options**
BUGS
====
.. include:: general_options.rst
* Glance is sourced in Launchpad so you can view current bugs at `OpenStack Glance <http://glance.openstack.org>`__
FILES
=====
**/etc/glance/glance-cache.conf**
Default configuration file for the Glance Cache
.. include:: footer.rst

88
doc/source/man/glancecontrol.rst
View File

@ -6,6 +6,13 @@ glance-control
Glance daemon start/stop/reload helper
--------------------------------------
:Author: glance@lists.launchpad.net
:Date: 2014-01-16
:Copyright: OpenStack LLC
:Version: 2014.1
:Manual section: 1
:Manual group: cloud computing
SYNOPSIS
========
@ -13,82 +20,39 @@ SYNOPSIS
Where <SERVER> is one of:
all, api, registry, scrubber
all, api, glance-api, registry, glance-registry, scrubber, glance-scrubber
And command is one of:
start, stop, shutdown, restart, reload, force-reload
start, status, stop, shutdown, restart, reload, force-reload
And CONFPATH is the optional configuration file to use.
OPTIONS
=======
========
**--version**
show program's version number and exit
**General Options**
**-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
.. include:: general_options.rst
**--pid-file=PATH**
File to use as pid file. Default:
/var/run/glance/$server.pid
SEE ALSO
========
**--await-child DELAY**
Period to wait for service death in order to report
exit code (default is to not wait at all)
* `OpenStack Glance <http://glance.openstack.org>`__
**--capture-output**
Capture stdout/err in syslog instead of discarding
BUGS
====
**--nocapture-output**
The inverse of --capture-output
* Glance is sourced in Launchpad so you can view current bugs at `OpenStack Glance <http://glance.openstack.org>`__
**--norespawn**
The inverse of --respawn
**--respawn**
Restart service on unexpected death
.. include:: footer.rst

61
doc/source/man/glancemanage.rst
View File

@ -7,9 +7,9 @@ Glance Management Utility
-------------------------
:Author: glance@lists.launchpad.net
:Date: 2010-11-16
:Date: 2014-01-16
:Copyright: OpenStack LLC
:Version: 0.1.2
:Version: 2014.1
:Manual section: 1
:Manual group: cloud computing
@ -24,31 +24,52 @@ 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_downgrade <VERSION>**
This will take an existing database and downgrade it to the
specified VERSION.
**db_version_control**
Place the database untder migration control.
**db_sync <VERSION> <CURRENT_VERSION>**
Place a database under migration control and upgrade, creating
it first if necessary.
OPTIONS
=======
========
**General options**
**General Options**
**-v, --verbose**
Print more verbose output
.. include:: general_options.rst
**--sql_connection=CONN_STRING**
A proper SQLAlchemy connection string as described
`here <http://www.sqlalchemy.org/docs/05/reference/sqlalchemy/connections.html?highlight=engine#sqlalchemy.create_engine>`_
FILES
=====
None
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>`__
.. include:: footer.rst

32
doc/source/man/glanceregistry.rst
View File

@ -7,16 +7,16 @@ Server for the Glance Registry Service
--------------------------------------
:Author: glance@lists.launchpad.net
:Date: 2010-11-16
:Date: 2014-01-16
:Copyright: OpenStack LLC
:Version: 0.1.2
:Version: 2014.1
:Manual section: 1
:Manual group: cloud computing
SYNOPSIS
========
glance-registry [options]
glance-registry [options]
DESCRIPTION
===========
@ -29,30 +29,12 @@ OPTIONS
**General options**
**-v, --verbose**
Print more verbose output
**--registry_host=HOST**
Address of host running ``glance-registry``. Defaults to `0.0.0.0`.
**--registry_port=PORT**
Port that ``glance-registry`` listens on. Defaults to `9191`.
**--sql_connection=CONN_STRING**
A proper SQLAlchemy connection string as described
`here <http://www.sqlalchemy.org/docs/05/reference/sqlalchemy/connections.html?highlight=engine#sqlalchemy.create_engine>`_
.. include:: general_options.rst
FILES
=====
None
**/etc/glance/glance-registry.conf**
Default configuration file for Glance Registry
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>`__
.. include:: footer.rst

90
doc/source/man/glancereplicator.rst Normal file
View File

@ -0,0 +1,90 @@
=================
glance-replicator
=================
---------------------------------------------
Replicate images across multiple data centers
---------------------------------------------
:Author: glance@lists.launchpad.net
:Date: 2014-01-16
:Copyright: OpenStack LLC
:Version: 2014.1
: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

77
doc/source/man/glancescrubber.rst
View File

@ -7,16 +7,16 @@ Glance scrub service
--------------------
:Author: glance@lists.launchpad.net
:Date: 2012-01-03
:Date: 2014-01-16
:Copyright: OpenStack LLC
:Version: 2012.1-dev
:Version: 2014.1
:Manual section: 1
:Manual group: cloud computing
SYNOPSIS
========
glance-scrubber [options]
glance-scrubber [options]
DESCRIPTION
===========
@ -40,61 +40,9 @@ glance-scrubber can run as a periodic job or long-running daemon.
OPTIONS
=======
**--version**
show program's version number and exit
**General options**
**-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
.. include:: general_options.rst
**-D, --daemon**
Run as a long-running process. When not specified (the
@ -103,14 +51,13 @@ OPTIONS
wakeup_time interval as specified in the config.
**--nodaemon**
The inverse of --daemon. Runs the scrub operation once and then exits.
The inverse of --daemon. Runs the scrub operation once and
then exits. This is the default.
SEE ALSO
========
FILES
======
* `OpenStack Glance <http://glance.openstack.org>`__
**/etc/glance/glance-scrubber.conf**
Default configuration file for the Glance Scrubber
BUGS
====
* Glance is sourced in Launchpad so you can view current bugs at `OpenStack Glance <http://glance.openstack.org>`__
.. include:: footer.rst

22
doc/source/man/openstack_options.rst Normal file
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]