Merge "docs: Use proper headers in nova-manage man page"

doc/source/cli/nova-manage.rst

@@ -11,6 +11,7 @@ Synopsis
 
   nova-manage <category> [<action> [<options>...]]
 
+
 Description
 ===========
 
@@ -30,8 +31,6 @@ commands in that category::
 
     nova-manage db
 
-These sections describe the available categories and arguments for
-:program:`nova-manage`.
 
 Options
 =======
@@ -152,16 +151,30 @@ without an argument can be combined after a single dash.
     specified and Linux platform is used. This option is ignored if
     :option:`--log-config-append` is set.
 
-Commands
-========
 
-Nova Database
+Database Commands
-~~~~~~~~~~~~~
+=================
+
+db version
+----------
+
+.. program:: nova-manage db version
+
+.. code-block:: shell
+
+    nova-manage db version
 
-``nova-manage db version``
 Print the current main database version.
 
-``nova-manage db sync [--local_cell] [VERSION]``
+db sync
+-------
+
+.. program:: nova-manage db sync
+
+.. code-block:: shell
+
+    nova-manage db sync [--local_cell] [VERSION]
+
 Upgrade the main database schema up to the most recent version or
 ``VERSION`` if specified. By default, this command will also attempt to
 upgrade the schema for the cell0 database if it is mapped (see the
@@ -175,7 +188,16 @@ Nova Database
 Returns exit code 0 if the database schema was synced successfully, or 1 if
 cell0 cannot be accessed.
 
-``nova-manage db archive_deleted_rows [--max_rows <number>] [--verbose] [--until-complete] [--before <date>] [--purge] [--all-cells]``
+db archive_deleted_rows
+-----------------------
+
+.. program:: nova-manage db archive_deleted_rows
+
+.. code-block:: shell
+
+    nova-manage db archive_deleted_rows [--max_rows <number>] [--verbose]
+      [--until-complete] [--before <date>] [--purge] [--all-cells]
+
 Move deleted rows from production tables to shadow tables. Note that the
 corresponding rows in the ``instance_mappings``, ``request_specs`` and
 ``instance_group_member`` tables of the API database are purged when
@@ -201,12 +223,12 @@ Nova Database
    format produced by the ``date`` command, e.g. ``Fri May 24 09:20:11 CDT 2019``.
    Date strings containing spaces must be quoted appropriately. Some examples::
 
-         # Purge shadow table rows older than a specific date
+     # Archive deleted row older than a specific date
-         nova-manage db purge --before 2015-10-21
+     nova-manage db archive_deleted_rows --before 2015-10-21
      # or
-         nova-manage db purge --before "Oct 21 2015"
+     nova-manage db archive_deleted_rows --before "Oct 21 2015"
      # Times are also accepted
-         nova-manage db purge --before "2015-10-21 12:00"
+     nova-manage db archive_deleted_rows --before "2015-10-21 12:00"
 
    Relative dates (such as ``yesterday``) are not supported natively.
    The ``date`` command can be helpful here::
@@ -239,7 +261,15 @@ Nova Database
 If automating, this should be run continuously while the result is 1,
 stopping at 0, or use the ``--until-complete`` option.
 
-``nova-manage db purge [--all] [--before <date>] [--verbose] [--all-cells]``
+db purge
+--------
+
+.. program:: nova-manage db purge
+
+.. code-block:: shell
+
+    nova-manage db purge [--all] [--before <date>] [--verbose] [--all-cells]
+
 Delete rows from shadow tables. Specifying ``--all`` will delete all data from
 all shadow tables. Specifying ``--before`` will delete data from all shadow tables
 that is older than the date provided. Specifying ``--verbose`` will
@@ -268,9 +298,17 @@ Nova Database
    The ``date`` command can be helpful here::
 
      # Archive deleted rows more than one month old
-         nova-manage db archive_deleted_rows --before "$(date -d 'now - 1 month')"
+     nova-manage db purge --before "$(date -d 'now - 1 month')"
+
+db online_data_migrations
+-------------------------
+
+.. program:: nova-manage db online_data_migrations
+
+.. code-block:: shell
+
+    nova-manage db online_data_migrations [--max-count]
 
-``nova-manage db online_data_migrations [--max-count]``
 Perform data migration to update all live data.
 
 ``--max-count`` controls the maximum number of objects to migrate in a given
@@ -317,13 +355,30 @@ Nova Database
 and only two records were migrated with no more candidates remaining, the
 command completed successfully with exit code 0.
 
-Nova API Database
-~~~~~~~~~~~~~~~~~
 
-``nova-manage api_db version``
+API Database Commands
+=====================
+
+api_db version
+--------------
+
+.. program:: nova-manage api_db version
+
+.. code-block:: shell
+
+    nova-manage api_db version
+
 Print the current API database version.
 
-``nova-manage api_db sync [VERSION]``
+api_db sync
+-----------
+
+.. program:: nova-manage api_db sync
+
+.. code-block:: shell
+
+    nova-manage api_db sync [VERSION]
+
 Upgrade the API database schema up to the most recent version or
 ``VERSION`` if specified. This command does not create the API
 database, it runs schema migration scripts. The API database connection is
@@ -337,19 +392,36 @@ Nova API Database
 Returns exit code 0 if the database schema was synced successfully. This
 command should be run before ``nova-manage db sync``.
 
+
 .. _man-page-cells-v2:
 
-Nova Cells v2
+Cells v2 Commands
-~~~~~~~~~~~~~
+=================
+
+cell_v2 simple_cell_setup
+-------------------------
+
+.. program:: nova-manage cell_v2 simple_cell_setup
+
+.. code-block:: shell
+
+    nova-manage cell_v2 simple_cell_setup [--transport-url <transport_url>]
 
-``nova-manage cell_v2 simple_cell_setup [--transport-url <transport_url>]``
 Setup a fresh cells v2 environment. If a ``transport_url`` is not
 specified, it will use the one defined by :oslo.config:option:`transport_url`
 in the configuration file. Returns 0 if setup is completed
 (or has already been done), 1 if no hosts are reporting (and cannot be
 mapped) and 1 if the transport url is missing or invalid.
 
-``nova-manage cell_v2 map_cell0 [--database_connection <database_connection>]``
+cell_v2 map_cell0
+-----------------
+
+.. program:: nova-manage cell_v2 map_cell0
+
+.. code-block:: shell
+
+    nova-manage cell_v2 map_cell0 [--database_connection <database_connection>]
+
 Create a cell mapping to the database connection for the cell0 database.
 If a database_connection is not specified, it will use the one defined by
 :oslo.config:option:`database.connection` in the configuration file passed
@@ -358,7 +430,16 @@ Nova Cells v2
 encountered an error before they have been scheduled. Returns 0 if cell0 is
 created successfully or already setup.
 
-``nova-manage cell_v2 map_instances --cell_uuid <cell_uuid> [--max-count <max_count>] [--reset]``
+cell_v2 map_instances
+---------------------
+
+.. program:: nova-manage cell_v2 map_instances
+
+.. code-block:: shell
+
+    nova-manage cell_v2 map_instances --cell_uuid <cell_uuid>
+      [--max-count <max_count>] [--reset]
+
 Map instances to the provided cell. Instances in the nova database will
 be queried from oldest to newest and mapped to the provided cell. A
 ``--max-count`` can be set on the number of instance to map in a single run.
@@ -389,7 +470,16 @@ Nova Cells v2
    * - 255
      - An unexpected error occurred.
 
-``nova-manage cell_v2 map_cell_and_hosts [--name <cell_name>] [--transport-url <transport_url>] [--verbose]``
+cell_v2 map_cell_and_hosts
+--------------------------
+
+.. program:: nova-manage cell_v2 map_cell_and_hosts
+
+.. code-block:: shell
+
+    nova-manage cell_v2 map_cell_and_hosts [--name <cell_name>]
+      [--transport-url <transport_url>] [--verbose]
+
 Create a cell mapping to the database connection and message queue
 transport url, and map hosts to that cell. The database connection
 comes from the :oslo.config:option:`database.connection` defined in the
@@ -400,7 +490,15 @@ Nova Cells v2
 print out the resulting cell mapping uuid. Returns 0 on successful
 completion, and 1 if the transport url is missing or invalid.
 
-``nova-manage cell_v2 verify_instance --uuid <instance_uuid> [--quiet]``
+cell_v2 verify_instance
+-----------------------
+
+.. program:: nova-manage cell_v2 verify_instance
+
+.. code-block:: shell
+
+    nova-manage cell_v2 verify_instance --uuid <instance_uuid> [--quiet]
+
 Verify instance mapping to a cell. This command is useful to determine if
 the cells v2 environment is properly setup, specifically in terms of the
 cell, host, and instance mapping records required. Returns 0 when the
@@ -412,7 +510,17 @@ Nova Cells v2
 instance which has instance mapping, and 4 if it is an archived instance
 which still has an instance mapping.
 
-``nova-manage cell_v2 create_cell [--name <cell_name>] [--transport-url <transport_url>] [--database_connection <database_connection>] [--verbose] [--disabled]``
+cell_v2 create_cell
+-------------------
+
+.. program:: nova-manage cell_v2 create_cell
+
+.. code-block:: shell
+
+    nova-manage cell_v2 create_cell [--name <cell_name>]
+      [--transport-url <transport_url>]
+      [--database_connection <database_connection>] [--verbose] [--disabled]
+
 Create a cell mapping to the database connection and message queue
 transport url. If a database_connection is not specified, it will use the
 one defined by :oslo.config:option:`database.connection` in the
@@ -431,7 +539,16 @@ Nova Cells v2
 * Returns 2 if another cell is already using that transport url and/or
   database connection combination.
 
-``nova-manage cell_v2 discover_hosts [--cell_uuid <cell_uuid>] [--verbose] [--strict] [--by-service]``
+cell_v2 discover_hosts
+----------------------
+
+.. program:: nova-manage cell_v2 discover_hosts
+
+.. code-block:: shell
+
+    nova-manage cell_v2 discover_hosts [--cell_uuid <cell_uuid>] [--verbose]
+      [--strict] [--by-service]
+
 Searches cells, or a single cell, and maps found hosts. This command will
 check the database for each cell (or a single one if passed in) and map any
 hosts which are not currently mapped. If a host is already mapped, nothing
@@ -462,12 +579,28 @@ Nova Cells v2
   found. This means the command collided with another running
   discover_hosts command or scheduler periodic task and is safe to retry.
 
-``nova-manage cell_v2 list_cells [--verbose]``
+cell_v2 list_cells
+------------------
+
+.. program:: nova-manage cell_v2 list_cells
+
+.. code-block:: shell
+
+    nova-manage cell_v2 list_cells [--verbose]
+
 By default the cell name, uuid, disabled state, masked transport URL and
 database connection details are shown. Use the ``--verbose`` option to see
 transport URL and database connection with their sensitive details.
 
-``nova-manage cell_v2 delete_cell [--force] --cell_uuid <cell_uuid>``
+cell_v2 delete_cell
+-------------------
+
+.. program:: nova-manage cell_v2 delete_cell
+
+.. code-block:: shell
+
+    nova-manage cell_v2 delete_cell [--force] --cell_uuid <cell_uuid>
+
 Delete a cell by the given uuid. Returns 0 if the empty cell is found and
 deleted successfully or the cell that has hosts is found and the cell, hosts
 and the instance_mappings are deleted successfully with ``--force`` option
@@ -478,13 +611,31 @@ Nova Cells v2
 instance mappings to the cell but all instances have been deleted in the cell,
 again without the ``--force`` option.
 
-``nova-manage cell_v2 list_hosts [--cell_uuid <cell_uuid>]``
+cell_v2 list_hosts
+------------------
+
+.. program:: nova-manage cell_v2 list_hosts
+
+.. code-block:: shell
+
+    nova-manage cell_v2 list_hosts [--cell_uuid <cell_uuid>]
+
 Lists the hosts in one or all v2 cells. By default hosts in all v2 cells
 are listed. Use the ``--cell_uuid`` option to list hosts in a specific cell.
 If the cell is not found by uuid, this command will return an exit code
 of 1. Otherwise, the exit code will be 0.
 
-``nova-manage cell_v2 update_cell --cell_uuid <cell_uuid> [--name <cell_name>] [--transport-url <transport_url>] [--database_connection <database_connection>] [--disable] [--enable]``
+cell_v2 update_cell
+-------------------
+
+.. program:: nova-manage cell_v2 update_cell
+
+.. code-block:: shell
+
+    nova-manage cell_v2 update_cell --cell_uuid <cell_uuid>
+      [--name <cell_name>] [--transport-url <transport_url>]
+      [--database_connection <database_connection>] [--disable] [--enable]
+
 Updates the properties of a cell by the given uuid. If a
 database_connection is not specified, it will attempt to use the one
 defined by :oslo.config:option:`database.connection` in the configuration
@@ -511,7 +662,15 @@ Nova Cells v2
     The scheduler will not notice that a cell has been enabled/disabled until
     it is restarted or sent the SIGHUP signal.
 
-``nova-manage cell_v2 delete_host --cell_uuid <cell_uuid> --host <host>``
+cell_v2 delete_host
+-------------------
+
+.. program:: nova-manage cell_v2 delete_host
+
+.. code-block:: shell
+
+    nova-manage cell_v2 delete_host --cell_uuid <cell_uuid> --host <host>
+
 Delete a host by the given host name and the given cell uuid. Returns 0
 if the empty host is found and deleted successfully, 1 if a cell with
 that uuid could not be found, 2 if a host with that name could not be
@@ -523,12 +682,23 @@ Nova Cells v2
     The scheduler caches host-to-cell mapping information so when deleting
     a host the scheduler may need to be restarted or sent the SIGHUP signal.
 
-Placement
+
-~~~~~~~~~
+Placement Commands
+==================
 
 .. _heal_allocations_cli:
 
-``nova-manage placement heal_allocations [--max-count <max_count>] [--verbose] [--skip-port-allocations] [--dry-run] [--instance <instance_uuid>] [--cell <cell_uuid] [--force]``
+placement heal_allocations
+--------------------------
+
+.. program:: nova-manage placement heal_allocations
+
+.. code-block:: shell
+
+    nova-manage placement heal_allocations [--max-count <max_count>]
+      [--verbose] [--skip-port-allocations] [--dry-run]
+      [--instance <instance_uuid>] [--cell <cell_uuid] [--force]
+
 Iterates over non-cell0 cells looking for instances which do not have
 allocations in the Placement service and which are not undergoing a task
 state transition. For each instance found, allocations are created against
@@ -633,7 +803,15 @@ Placement
 
 .. _sync_aggregates_cli:
 
-``nova-manage placement sync_aggregates [--verbose]``
+placement sync_aggregates
+-------------------------
+
+.. program:: nova-manage placement sync_aggregates
+
+.. code-block:: shell
+
+    nova-manage placement sync_aggregates [--verbose]
+
 Mirrors compute host aggregates to resource provider aggregates
 in the Placement service. Requires the :oslo.config:group:`api_database`
 and :oslo.config:group:`placement` sections of the nova configuration file
@@ -673,7 +851,16 @@ Placement
    * - 255
      - An unexpected error occurred.
 
-``nova-manage placement audit [--verbose] [--delete] [--resource_provider <uuid>]``
+placement audit
+---------------
+
+.. program:: nova-manage placement audit
+
+.. code-block:: shell
+
+    nova-manage placement audit [--verbose] [--delete]
+      [--resource_provider <uuid>]
+
 Iterates over all the Resource Providers (or just one if you provide the
 UUID) and then verifies if the compute allocations are either related to
 an existing instance or a migration UUID.
@@ -708,10 +895,19 @@ Placement
    * - 127
      - Invalid input
 
-libvirt
-~~~~~~~
 
-``nova-manage libvirt get_machine_type [instance-uuid]``
+Libvirt Commands
+================
+
+libvirt get_machine_type
+------------------------
+
+.. program:: nova-manage libvirt get_machine_type
+
+.. code-block:: shell
+
+    nova-manage libvirt get_machine_type [INSTANCE_UUID]
+
 Fetch and display the recorded machine type of a libvirt instance.
 
 **Return Codes**
@@ -731,7 +927,16 @@ libvirt
    * - 3
      - No machine type found for instance
 
-``nova-manage libvirt update_machine_type [instance-uuid] [machine_type] [--force]``
+libvirt update_machine_type
+---------------------------
+
+.. program:: nova-manage libvirt update_machine_type
+
+.. code-block:: shell
+
+    nova-manage libvirt update_machine_type \
+        [INSTANCE_UUID] [MACHINE_TYPE] [--force]
+
 Set or update the recorded machine type of an instance.
 
 The following criteria must also be met when using this command:
@@ -775,7 +980,15 @@ libvirt
    * - 5
      - The provided machine type is unsupported
 
-``nova-manage libvirt list_unset_machine_type [--cell-uuid]``
+libvirt list_unset_machine_type
+-------------------------------
+
+.. program:: nova-manage libvirt list_unset_machine_type
+
+.. code-block:: shell
+
+    nova-manage libvirt list_unset_machine_type [--cell-uuid <cell-uuid>]
+
 List the UUID of any instance without ``hw_machine_type`` set.
 
 This command is useful for operators attempting to determine when it is
@@ -799,11 +1012,13 @@ libvirt
    * - 3
      - Instances found without hw_machine_type set
 
+
 See Also
 ========
 
 * :nova-doc:`OpenStack Nova <>`
 
+
 Bugs
 ====