Refactor Commands section
Rename this section to 'Watcher Manual Pages' and add man RST files. Partial-Bug: #1535244 Change-Id: I1c890c8d053238aa568075d844f97b1e4289adcb
This commit is contained in:
David TARDIVEL
4
doc/source/man/footer.rst
Normal file
4
doc/source/man/footer.rst
Normal file
@@ -0,0 +1,4 @@
|
||||
BUGS
|
||||
====
|
||||
|
||||
* Watcher bugs are tracked in Launchpad at `OpenStack Watcher <http://bugs.launchpad.net/watcher>`__
|
||||
66
doc/source/man/general-options.rst
Normal file
66
doc/source/man/general-options.rst
Normal 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 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)
|
||||
39
doc/source/man/watcher-api.rst
Normal file
39
doc/source/man/watcher-api.rst
Normal file
@@ -0,0 +1,39 @@
|
||||
===========
|
||||
watcher-api
|
||||
===========
|
||||
|
||||
---------------------------
|
||||
Service for the Watcher API
|
||||
---------------------------
|
||||
|
||||
:Author: openstack@lists.launchpad.net
|
||||
:Date:
|
||||
:Copyright: OpenStack Foundation
|
||||
:Version:
|
||||
:Manual section: 1
|
||||
:Manual group: cloud computing
|
||||
|
||||
SYNOPSIS
|
||||
========
|
||||
|
||||
watcher-api [options]
|
||||
|
||||
DESCRIPTION
|
||||
===========
|
||||
|
||||
watcher-api is a server daemon that serves the Watcher API
|
||||
|
||||
OPTIONS
|
||||
=======
|
||||
|
||||
**General options**
|
||||
|
||||
.. include:: general-options.rst
|
||||
|
||||
FILES
|
||||
=====
|
||||
|
||||
**/etc/watcher/watcher.conf**
|
||||
Default configuration file for Watcher API
|
||||
|
||||
.. include:: footer.rst
|
||||
39
doc/source/man/watcher-applier.rst
Normal file
39
doc/source/man/watcher-applier.rst
Normal file
@@ -0,0 +1,39 @@
|
||||
===============
|
||||
watcher-applier
|
||||
===============
|
||||
|
||||
-------------------------------
|
||||
Service for the Watcher Applier
|
||||
-------------------------------
|
||||
|
||||
:Author: openstack@lists.launchpad.net
|
||||
:Date:
|
||||
:Copyright: OpenStack Foundation
|
||||
:Version:
|
||||
:Manual section: 1
|
||||
:Manual group: cloud computing
|
||||
|
||||
SYNOPSIS
|
||||
========
|
||||
|
||||
watcher-applier [options]
|
||||
|
||||
DESCRIPTION
|
||||
===========
|
||||
|
||||
:ref:`Watcher Applier <watcher_applier_definition>`
|
||||
|
||||
OPTIONS
|
||||
=======
|
||||
|
||||
**General options**
|
||||
|
||||
.. include:: general-options.rst
|
||||
|
||||
FILES
|
||||
=====
|
||||
|
||||
**/etc/watcher/watcher.conf**
|
||||
Default configuration file for Watcher Applier
|
||||
|
||||
.. include:: footer.rst
|
||||
221
doc/source/man/watcher-db-manage.rst
Normal file
221
doc/source/man/watcher-db-manage.rst
Normal file
@@ -0,0 +1,221 @@
|
||||
..
|
||||
Except where otherwise noted, this document is licensed under Creative
|
||||
Commons Attribution 3.0 License. You can view the license at:
|
||||
|
||||
https://creativecommons.org/licenses/by/3.0/
|
||||
|
||||
.. _watcher-db-manage:
|
||||
|
||||
=================
|
||||
watcher-db-manage
|
||||
=================
|
||||
|
||||
The :command:`watcher-db-manage` utility is used to create the database schema
|
||||
tables that the watcher services will use for storage. It can also be used to
|
||||
upgrade (or downgrade) existing database tables when migrating between
|
||||
different versions of watcher.
|
||||
|
||||
The `Alembic library <http://alembic.readthedocs.org>`_ is used to perform
|
||||
the database migrations.
|
||||
|
||||
Options
|
||||
=======
|
||||
|
||||
This is a partial list of the most useful options. To see the full list,
|
||||
run the following::
|
||||
|
||||
watcher-db-manage --help
|
||||
|
||||
.. program:: watcher-db-manage
|
||||
|
||||
.. option:: -h, --help
|
||||
|
||||
Show help message and exit.
|
||||
|
||||
.. option:: --config-dir <DIR>
|
||||
|
||||
Path to a config directory with configuration files.
|
||||
|
||||
.. option:: --config-file <PATH>
|
||||
|
||||
Path to a configuration file to use.
|
||||
|
||||
.. option:: -d, --debug
|
||||
|
||||
Print debugging output.
|
||||
|
||||
.. option:: -v, --verbose
|
||||
|
||||
Print more verbose output.
|
||||
|
||||
.. option:: --version
|
||||
|
||||
Show the program's version number and exit.
|
||||
|
||||
.. option:: upgrade, downgrade, stamp, revision, version, create_schema
|
||||
|
||||
The :ref:`command <db-manage_cmds>` to run.
|
||||
|
||||
Usage
|
||||
=====
|
||||
|
||||
Options for the various :ref:`commands <db-manage_cmds>` for
|
||||
:command:`watcher-db-manage` are listed when the :option:`-h` or
|
||||
:option:`--help`
|
||||
option is used after the command.
|
||||
|
||||
For example::
|
||||
|
||||
watcher-db-manage create_schema --help
|
||||
|
||||
Information about the database is read from the watcher configuration file
|
||||
used by the API server and conductor services. This file must be specified
|
||||
with the :option:`--config-file` option::
|
||||
|
||||
watcher-db-manage --config-file /path/to/watcher.conf create_schema
|
||||
|
||||
The configuration file defines the database backend to use with the
|
||||
*connection* database option::
|
||||
|
||||
[database]
|
||||
connection=mysql://root@localhost/watcher
|
||||
|
||||
If no configuration file is specified with the :option:`--config-file` option,
|
||||
:command:`watcher-db-manage` assumes an SQLite database.
|
||||
|
||||
.. _db-manage_cmds:
|
||||
|
||||
Command Options
|
||||
===============
|
||||
|
||||
:command:`watcher-db-manage` is given a command that tells the utility
|
||||
what actions to perform.
|
||||
These commands can take arguments. Several commands are available:
|
||||
|
||||
.. _create_schema:
|
||||
|
||||
create_schema
|
||||
-------------
|
||||
|
||||
.. program:: create_schema
|
||||
|
||||
.. option:: -h, --help
|
||||
|
||||
Show help for create_schema and exit.
|
||||
|
||||
This command will create database tables based on the most current version.
|
||||
It assumes that there are no existing tables.
|
||||
|
||||
An example of creating database tables with the most recent version::
|
||||
|
||||
watcher-db-manage --config-file=/etc/watcher/watcher.conf create_schema
|
||||
|
||||
downgrade
|
||||
---------
|
||||
|
||||
.. program:: downgrade
|
||||
|
||||
.. option:: -h, --help
|
||||
|
||||
Show help for downgrade and exit.
|
||||
|
||||
.. option:: --revision <REVISION>
|
||||
|
||||
The revision number you want to downgrade to.
|
||||
|
||||
This command will revert existing database tables to a previous version.
|
||||
The version can be specified with the :option:`--revision` option.
|
||||
|
||||
An example of downgrading to table versions at revision 2581ebaf0cb2::
|
||||
|
||||
watcher-db-manage --config-file=/etc/watcher/watcher.conf downgrade --revision 2581ebaf0cb2
|
||||
|
||||
revision
|
||||
--------
|
||||
|
||||
.. program:: revision
|
||||
|
||||
.. option:: -h, --help
|
||||
|
||||
Show help for revision and exit.
|
||||
|
||||
.. option:: -m <MESSAGE>, --message <MESSAGE>
|
||||
|
||||
The message to use with the revision file.
|
||||
|
||||
.. option:: --autogenerate
|
||||
|
||||
Compares table metadata in the application with the status of the database
|
||||
and generates migrations based on this comparison.
|
||||
|
||||
This command will create a new revision file. You can use the
|
||||
:option:`--message` option to comment the revision.
|
||||
|
||||
This is really only useful for watcher developers making changes that require
|
||||
database changes. This revision file is used during database migration and
|
||||
will specify the changes that need to be made to the database tables. Further
|
||||
discussion is beyond the scope of this document.
|
||||
|
||||
stamp
|
||||
-----
|
||||
|
||||
.. program:: stamp
|
||||
|
||||
.. option:: -h, --help
|
||||
|
||||
Show help for stamp and exit.
|
||||
|
||||
.. option:: --revision <REVISION>
|
||||
|
||||
The revision number.
|
||||
|
||||
This command will 'stamp' the revision table with the version specified with
|
||||
the :option:`--revision` option. It will not run any migrations.
|
||||
|
||||
upgrade
|
||||
-------
|
||||
|
||||
.. program:: upgrade
|
||||
|
||||
.. option:: -h, --help
|
||||
|
||||
Show help for upgrade and exit.
|
||||
|
||||
.. option:: --revision <REVISION>
|
||||
|
||||
The revision number to upgrade to.
|
||||
|
||||
This command will upgrade existing database tables to the most recent version,
|
||||
or to the version specified with the :option:`--revision` option.
|
||||
|
||||
If there are no existing tables, then new tables are created, beginning
|
||||
with the oldest known version, and successively upgraded using all of the
|
||||
database migration files, until they are at the specified version. Note
|
||||
that this behavior is different from the :ref:`create_schema` command
|
||||
that creates the tables based on the most recent version.
|
||||
|
||||
An example of upgrading to the most recent table versions::
|
||||
|
||||
watcher-db-manage --config-file=/etc/watcher/watcher.conf upgrade
|
||||
|
||||
.. note::
|
||||
|
||||
This command is the default if no command is given to
|
||||
:command:`watcher-db-manage`.
|
||||
|
||||
.. warning::
|
||||
|
||||
The upgrade command is not compatible with SQLite databases since it uses
|
||||
ALTER TABLE commands to upgrade the database tables. SQLite supports only
|
||||
a limited subset of ALTER TABLE.
|
||||
|
||||
version
|
||||
-------
|
||||
|
||||
.. program:: version
|
||||
|
||||
.. option:: -h, --help
|
||||
|
||||
Show help for version and exit.
|
||||
|
||||
This command will output the current database version.
|
||||
39
doc/source/man/watcher-decision-engine.rst
Normal file
39
doc/source/man/watcher-decision-engine.rst
Normal file
@@ -0,0 +1,39 @@
|
||||
=======================
|
||||
watcher-decision-engine
|
||||
=======================
|
||||
|
||||
---------------------------------------
|
||||
Service for the Watcher Decision Engine
|
||||
---------------------------------------
|
||||
|
||||
:Author: openstack@lists.launchpad.net
|
||||
:Date:
|
||||
:Copyright: OpenStack Foundation
|
||||
:Version:
|
||||
:Manual section: 1
|
||||
:Manual group: cloud computing
|
||||
|
||||
SYNOPSIS
|
||||
========
|
||||
|
||||
watcher-decision-engine [options]
|
||||
|
||||
DESCRIPTION
|
||||
===========
|
||||
|
||||
:ref:`Watcher Decision Engine <watcher_decision_engine_definition>`
|
||||
|
||||
OPTIONS
|
||||
=======
|
||||
|
||||
**General options**
|
||||
|
||||
.. include:: general-options.rst
|
||||
|
||||
FILES
|
||||
=====
|
||||
|
||||
**/etc/watcher/watcher.conf**
|
||||
Default configuration file for Watcher Decision Engine
|
||||
|
||||
.. include:: footer.rst
|
||||
Reference in New Issue
Block a user