From 99e5a1ac9a8dd207c72a7e7956c4cd00c480f1b6 Mon Sep 17 00:00:00 2001 From: Stephen Finucane Date: Thu, 7 May 2020 16:50:03 +0100 Subject: [PATCH] docs: Document options for remaining nova-* commands Most of these share the same collection of oslo.config and oslo.log options so it makes sense to group them together. The only exception is nova-rootwrap, which is a wrapper around the 'oslo_rootwrap.cmd.main' module, which curiously does not use argparse and doesn't have any options. Change-Id: I393ff162be58700956fbab29ff6b9ba3cf5860a6 Signed-off-by: Stephen Finucane --- doc/source/cli/nova-api-metadata.rst | 8 ++- doc/source/cli/nova-api-os-compute.rst | 8 ++- doc/source/cli/nova-api.rst | 8 ++- doc/source/cli/nova-compute.rst | 8 ++- doc/source/cli/nova-conductor.rst | 8 ++- doc/source/cli/nova-novncproxy.rst | 55 +++++++++++++- doc/source/cli/nova-rootwrap.rst | 7 +- doc/source/cli/nova-scheduler.rst | 8 ++- doc/source/cli/nova-serialproxy.rst | 28 +++++++- doc/source/cli/nova-spicehtml5proxy.rst | 29 +++++++- doc/source/cli/opts/common.rst | 96 +++++++++++++++++++++++++ doc/source/cli/opts/debugger.rst | 15 ++++ doc/source/cli/opts/websockify.rst | 41 +++++++++++ 13 files changed, 304 insertions(+), 15 deletions(-) create mode 100644 doc/source/cli/opts/common.rst create mode 100644 doc/source/cli/opts/debugger.rst create mode 100644 doc/source/cli/opts/websockify.rst diff --git a/doc/source/cli/nova-api-metadata.rst b/doc/source/cli/nova-api-metadata.rst index 2845ab09c607..7e97f99ea568 100644 --- a/doc/source/cli/nova-api-metadata.rst +++ b/doc/source/cli/nova-api-metadata.rst @@ -22,7 +22,13 @@ so there are some considerations about using this in a Options ======= -**General options** +.. rubric:: General options + +.. include:: opts/common.rst + +.. rubric:: Debugger options + +.. include:: opts/debugger.rst Files ===== diff --git a/doc/source/cli/nova-api-os-compute.rst b/doc/source/cli/nova-api-os-compute.rst index 2127a9738901..c789472bcb16 100644 --- a/doc/source/cli/nova-api-os-compute.rst +++ b/doc/source/cli/nova-api-os-compute.rst @@ -20,7 +20,13 @@ OpenStack Compute API. Options ======= -**General options** +.. rubric:: General options + +.. include:: opts/common.rst + +.. rubric:: Debugger options + +.. include:: opts/debugger.rst Files ===== diff --git a/doc/source/cli/nova-api.rst b/doc/source/cli/nova-api.rst index cc611242179d..ef649fe07910 100644 --- a/doc/source/cli/nova-api.rst +++ b/doc/source/cli/nova-api.rst @@ -20,7 +20,13 @@ APIs in separate greenthreads. Options ======= -**General options** +.. rubric:: General options + +.. include:: opts/common.rst + +.. rubric:: Debugger options + +.. include:: opts/debugger.rst Files ===== diff --git a/doc/source/cli/nova-compute.rst b/doc/source/cli/nova-compute.rst index a2d896749830..f670d0916b2d 100644 --- a/doc/source/cli/nova-compute.rst +++ b/doc/source/cli/nova-compute.rst @@ -22,7 +22,13 @@ instance's state, attaching persistent storage, and terminating the instance. Options ======= -**General options** +.. rubric:: General options + +.. include:: opts/common.rst + +.. rubric:: Debugger options + +.. include:: opts/debugger.rst Files ===== diff --git a/doc/source/cli/nova-conductor.rst b/doc/source/cli/nova-conductor.rst index d6442a152a3f..38aa927b9091 100644 --- a/doc/source/cli/nova-conductor.rst +++ b/doc/source/cli/nova-conductor.rst @@ -20,7 +20,13 @@ service, which provides coordination and database query support for nova. Options ======= -**General options** +.. rubric:: General options + +.. include:: opts/common.rst + +.. rubric:: Debugger options + +.. include:: opts/debugger.rst Files ===== diff --git a/doc/source/cli/nova-novncproxy.rst b/doc/source/cli/nova-novncproxy.rst index 306b42ad2dd6..816a9a0be938 100644 --- a/doc/source/cli/nova-novncproxy.rst +++ b/doc/source/cli/nova-novncproxy.rst @@ -21,7 +21,60 @@ with OpenStack Nova noVNC consoles. Options ======= -**General options** +.. rubric:: General options + +.. include:: opts/common.rst + +.. rubric:: Websockify options + +.. include:: opts/websockify.rst + +.. rubric:: VNC options + +.. option:: --vnc-auth_schemes VNC_AUTH_SCHEMES + + The authentication schemes to use with the compute node. Control what RFB + authentication schemes are permitted for connections between the proxy and + the compute host. If multiple schemes are enabled, the first matching + scheme will be used, thus the strongest schemes should be listed first. + +.. option:: --vnc-novncproxy_host VNC_NOVNCPROXY_HOST + + IP address that the noVNC console proxy should bind to. The VNC proxy is an + OpenStack component that enables compute service users to access their + instances through VNC clients. noVNC provides VNC support through a + websocket-based client. This option sets the private address to which the + noVNC console proxy service should bind to. + +.. option:: --vnc-novncproxy_port VNC_NOVNCPROXY_PORT + + Port that the noVNC console proxy should bind to. The VNC proxy is an + OpenStack component that enables compute service users to access their + instances through VNC clients. noVNC provides VNC support through a + websocket-based client. This option sets the private port to which the + noVNC console proxy service should bind to. + +.. option:: --vnc-vencrypt_ca_certs VNC_VENCRYPT_CA_CERTS + + The path to the CA certificate PEM file The fully qualified path to a PEM + file containing one or more x509 certificates for the certificate + authorities used by the compute node VNC server. + +.. option:: --vnc-vencrypt_client_cert VNC_VENCRYPT_CLIENT_CERT + + The path to the client key file (for x509) The fully qualified path to a + PEM file containing the x509 certificate which the VNC proxy server + presents to the compute node during VNC authentication. + +.. option:: --vnc-vencrypt_client_key VNC_VENCRYPT_CLIENT_KEY + + The path to the client certificate PEM file (for x509) The fully qualified + path to a PEM file containing the private key which the VNC proxy server + presents to the compute node during VNC authentication. + +.. rubric:: Debugger options + +.. include:: opts/debugger.rst Files ===== diff --git a/doc/source/cli/nova-rootwrap.rst b/doc/source/cli/nova-rootwrap.rst index 6da14c4131fc..f5865b33673d 100644 --- a/doc/source/cli/nova-rootwrap.rst +++ b/doc/source/cli/nova-rootwrap.rst @@ -9,7 +9,7 @@ Synopsis :: - nova-rootwrap [...] + nova-rootwrap CONFIG_FILE COMMMAND Description =========== @@ -35,11 +35,6 @@ To make allowed commands node-specific, your packaging should only install :program:`nova-rootwrap` is being slowly deprecated and replaced by ``oslo.privsep``, and will eventually be removed. -Options -======= - -**General options** - Files ===== diff --git a/doc/source/cli/nova-scheduler.rst b/doc/source/cli/nova-scheduler.rst index 59b0519acb06..361979e88b8d 100644 --- a/doc/source/cli/nova-scheduler.rst +++ b/doc/source/cli/nova-scheduler.rst @@ -21,7 +21,13 @@ instance on. Options ======= -**General options** +.. rubric:: General options + +.. include:: opts/common.rst + +.. rubric:: Debugger options + +.. include:: opts/debugger.rst Files ===== diff --git a/doc/source/cli/nova-serialproxy.rst b/doc/source/cli/nova-serialproxy.rst index dff32f2c8470..e2ea551dd688 100644 --- a/doc/source/cli/nova-serialproxy.rst +++ b/doc/source/cli/nova-serialproxy.rst @@ -21,7 +21,33 @@ with OpenStack Nova serial ports. Options ======= -**General options** +.. rubric:: General options + +.. include:: opts/common.rst + +.. rubric:: Websockify options + +.. include:: opts/websockify.rst + +.. rubric:: Serial options + +.. option:: --serial_console-serialproxy_host SERIAL_CONSOLE_SERIALPROXY_HOST + + The IP address which is used by the ``nova-serialproxy`` service to listen + for incoming requests. The ``nova-serialproxy`` service listens on this IP + address for incoming connection requests to instances which expose serial + console. + +.. option:: --serial_console-serialproxy_port SERIAL_CONSOLE_SERIALPROXY_PORT + + The port number which is used by the ``nova-serialproxy`` service to + listen for incoming requests. The ``nova-serialproxy`` service listens on + this port number for incoming connection requests to instances which expose + serial console. + +.. rubric:: Debugger options + +.. include:: opts/debugger.rst Files ===== diff --git a/doc/source/cli/nova-spicehtml5proxy.rst b/doc/source/cli/nova-spicehtml5proxy.rst index e7779e271508..5718a8f29419 100644 --- a/doc/source/cli/nova-spicehtml5proxy.rst +++ b/doc/source/cli/nova-spicehtml5proxy.rst @@ -21,7 +21,34 @@ compatible with OpenStack Nova SPICE HTML5 consoles. Options ======= -**General options** +.. rubric:: General options + +.. include:: opts/common.rst + +.. rubric:: Websockify options + +.. include:: opts/websockify.rst + +.. rubric:: Spice options + +.. option:: --spice-html5proxy_host SPICE_HTML5PROXY_HOST + + IP address or a hostname on which the ``nova-spicehtml5proxy`` service + listens for incoming requests. This option depends on the ``[spice] + html5proxy_base_url`` option in ``nova.conf``. The ``nova-spicehtml5proxy`` + service must be listening on a host that is accessible from the HTML5 + client. + +.. option:: --spice-html5proxy_port SPICE_HTML5PROXY_PORT + + Port on which the ``nova-spicehtml5proxy`` service listens for incoming + requests. This option depends on the ``[spice] html5proxy_base_url`` option + in ``nova.conf``. The ``nova-spicehtml5proxy`` service must be listening + on a port that is accessible from the HTML5 client. + +.. rubric:: Debugger options + +.. include:: opts/debugger.rst Files ===== diff --git a/doc/source/cli/opts/common.rst b/doc/source/cli/opts/common.rst new file mode 100644 index 000000000000..d369b3171104 --- /dev/null +++ b/doc/source/cli/opts/common.rst @@ -0,0 +1,96 @@ +.. 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 + --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 + + Set the logging level 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, 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 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 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 log_config_append is set. + +.. option:: --nodebug + + The inverse of :option:`--debug`. + +.. 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:: --syslog-log-facility SYSLOG_LOG_FACILITY + + Syslog facility to receive log lines. This option is ignored if + 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 log_config_append is set. + +.. option:: --use-json + + Use JSON formatting for logging. This option is ignored if + 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 + 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 log_file option is specified and + Linux platform is used. This option is ignored if log_config_append is set. diff --git a/doc/source/cli/opts/debugger.rst b/doc/source/cli/opts/debugger.rst new file mode 100644 index 000000000000..a0698e0c9799 --- /dev/null +++ b/doc/source/cli/opts/debugger.rst @@ -0,0 +1,15 @@ +.. option:: --remote_debug-host REMOTE_DEBUG_HOST + + Debug host (IP or name) to connect to. This command line parameter is used + when you want to connect to a nova service via a debugger running on a + different host. Note that using the remote debug option changes how Nova + uses the eventlet library to support async IO. This could result in + failures that do not occur under normal operation. Use at your own risk. + +.. option:: --remote_debug-port REMOTE_DEBUG_PORT + + Debug port to connect to. This command line parameter allows you to specify + the port you want to use to connect to a nova service via a debugger + running on different host. Note that using the remote debug option changes + how Nova uses the eventlet library to support async IO. This could result + in failures that do not occur under normal operation. Use at your own risk. diff --git a/doc/source/cli/opts/websockify.rst b/doc/source/cli/opts/websockify.rst new file mode 100644 index 000000000000..5d6fbe51cda8 --- /dev/null +++ b/doc/source/cli/opts/websockify.rst @@ -0,0 +1,41 @@ +.. option:: --cert CERT + + Path to SSL certificate file. + +.. option:: --daemon + + Run as a background process. + +.. option:: --key KEY + + SSL key file (if separate from cert). + +.. option:: --nodaemon + + The inverse of :option:`--daemon`. + +.. option:: --nosource_is_ipv6 + + The inverse of :option:`--source_is_ipv6`. + +.. option:: --nossl_only + + The inverse of :option:`--ssl_only`. + +.. option:: --record RECORD + + Filename that will be used for storing websocket frames received and sent + by a proxy service (like VNC, spice, serial) running on this host. If this + is not set, no recording will be done. + +.. option:: --source_is_ipv6 + + Set to True if source host is addressed with IPv6. + +.. option:: --ssl_only + + Disallow non-encrypted connections. + +.. option:: --web WEB + + Path to directory with content which will be served by a web server.