From 01541f49b2ec9bd8d4ff19ac2a38a4a537f48efe Mon Sep 17 00:00:00 2001 From: Stephen Finucane Date: Tue, 20 Aug 2019 10:30:35 +0100 Subject: [PATCH] docs: Document global options for nova-manage Document the config options for this, most of which come from 'oslo.config'. Only the '--remote_debug-host' and '--remote_debug-port' options are not documented since they shouldn't be available for this command (it's not a service) and will be removed in a later patch. Change-Id: Ie321268cc56da04ff4111f7c34a29ba23d416e66 Signed-off-by: Stephen Finucane --- doc/source/cli/nova-manage.rst | 142 ++++++++++++++++++++++++++++++--- doc/source/conf.py | 4 + 2 files changed, 136 insertions(+), 10 deletions(-) diff --git a/doc/source/cli/nova-manage.rst b/doc/source/cli/nova-manage.rst index 7e096c737e68..6e3bc54ea8e5 100644 --- a/doc/source/cli/nova-manage.rst +++ b/doc/source/cli/nova-manage.rst @@ -2,6 +2,8 @@ nova-manage =========== +.. program:: nova-manage + ------------------------------------------- Control and manage cloud computer instances ------------------------------------------- @@ -24,23 +26,143 @@ Description :program:`nova-manage` controls cloud computing instances by managing various admin-only aspects of Nova. -Options -======= +The standard pattern for executing a :program:`nova-manage` command is:: -The standard pattern for executing a nova-manage command is:: - - nova-manage [] + nova-manage [] Run without arguments to see a list of available command categories:: - nova-manage + nova-manage You can also run with a category argument such as user to see a list of all commands in that category:: - nova-manage db + nova-manage db -These sections describe the available categories and arguments for nova-manage. +These sections describe the available categories and arguments for +:program:`nova-manage`. + +Options +======= + +These options apply to all commands and may be given in any order, before or +after commands. Individual commands may provide additional options. Options +without an argument can be combined after a single dash. + +.. option:: -h, --help + + Show a help message and exit + +.. option:: --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 + :option:`--config-file`, arguments hence over-ridden options in the + directory take precedence. This option must be set from the command-line. + +.. option:: --config-file PATH + + Path to a config file to use. Multiple config files can be specified, with + values in later files taking precedence. Defaults to None. This option must + be set from the command-line. + +.. option:: --debug, -d + + If set to true, the logging level will be set to DEBUG instead of the + default INFO level. + +.. option:: --log-config-append PATH, --log-config PATH, --log_config PATH + + The name of a logging configuration file. This file is appended to any + existing logging configuration files. For details about logging + configuration files, see the Python logging module documentation. Note that + when logging configuration files are used then all logging configuration is + set in the configuration file and other logging configuration options are + ignored (for example, :option:`--log-date-format`). + +.. option:: --log-date-format DATE_FORMAT + + Defines the format string for ``%(asctime)s`` in log records. Default: + None. This option is ignored if :option:`--log-config-append` is set. + +.. option:: --log-dir LOG_DIR, --logdir LOG_DIR + + (Optional) The base directory used for relative log_file paths. This option + is ignored if :option:`--log-config-append` is set. + +.. option:: --log-file PATH, --logfile PATH + + (Optional) Name of log file to send logging output to. If no default is + set, logging will go to stderr as defined by use_stderr. This option is + ignored if :option:`--log-config-append` is set. + +.. option:: --nodebug + + The inverse of :option:`--debug`. + +.. option:: --nopost-mortem + + The inverse of :option:`--post-mortem`. + +.. option:: --nouse-journal + + The inverse of :option:`--use-journal`. + +.. option:: --nouse-json + + The inverse of :option:`--use-json`. + +.. option:: --nouse-syslog + + The inverse of :option:`--use-syslog`. + +.. option:: --nowatch-log-file + + The inverse of :option:`--watch-log-file`. + +.. option:: --post-mortem + + Allow post-mortem debugging + +.. option:: --syslog-log-facility SYSLOG_LOG_FACILITY + + Syslog facility to receive log lines. This option is ignored if + :option:`--log-config-append` is set. + +.. option:: --use-journal + + Enable journald for logging. If running in a systemd environment you may + wish to enable journal support. Doing so will use the journal native + protocol which includes structured metadata in addition to log + messages. This option is ignored if :option:`--log-config-append` is + set. + +.. option:: --use-json + + Use JSON formatting for logging. This option is ignored if + :option:`--log-config-append` is set. + +.. option:: --use-syslog + + Use syslog for logging. Existing syslog format is DEPRECATED and will be + changed later to honor RFC5424. This option is ignored if + :option:`--log-config-append` is set. + +.. option:: --version + + Show program's version number and exit + +.. option:: --watch-log-file + + Uses logging handler designed to watch file system. When log file is moved + or removed this handler will open a new log file with specified path + instantaneously. It makes sense only if :option:`--log-file` option is + specified and Linux platform is used. This option is ignored if + :option:`--log-config-append` is set. + +Commands +======== Nova Database ~~~~~~~~~~~~~ @@ -56,8 +178,8 @@ Nova Database the cell0 database). If ``--local_cell`` is specified, then only the main database in the current cell is upgraded. The local database connection is determined by :oslo.config:option:`database.connection` in the - configuration file passed to nova-manage. This command should be run after - ``nova-manage api_db sync``. + configuration file, passed to nova-manage using the ``--config-file`` + option(s). This command should be run after ``nova-manage api_db sync``. Returns exit code 0 if the database schema was synced successfully, or 1 if cell0 cannot be accessed. diff --git a/doc/source/conf.py b/doc/source/conf.py index 1e9088f1dcc2..79d53cab9309 100644 --- a/doc/source/conf.py +++ b/doc/source/conf.py @@ -132,6 +132,10 @@ latex_documents = [ # Allow deeper levels of nesting for \begin...\end stanzas latex_elements = {'maxlistdepth': 10} +# Disable use of xindy since that's another binary dependency that's not +# available on all platforms +latex_use_xindy = False + # -- Options for openstackdocstheme ------------------------------------------- # keep this ordered to keep mriedem happy