From 3dbaca275ed8973a9377ecb968dd562dd6812939 Mon Sep 17 00:00:00 2001 From: Zac Dover Date: Tue, 29 Nov 2022 23:30:02 +1000 Subject: [PATCH] doc/rados: add prompts to control.rst Add unselectable prompts to doc/rados/operations/control.rst. https://tracker.ceph.com/issues/57108 Signed-off-by: Zac Dover --- doc/rados/operations/control.rst | 342 ++++++++++++++++++++----------- 1 file changed, 227 insertions(+), 115 deletions(-) diff --git a/doc/rados/operations/control.rst b/doc/rados/operations/control.rst index f44cbde3c6cd8..0884ca885e98f 100644 --- a/doc/rados/operations/control.rst +++ b/doc/rados/operations/control.rst @@ -8,38 +8,50 @@ Monitor Commands ================ -Monitor commands are issued using the ``ceph`` utility:: +Monitor commands are issued using the ``ceph`` utility: - ceph [-m monhost] {command} +.. prompt:: bash $ -The command is usually (though not always) of the form:: + ceph [-m monhost] {command} - ceph {subsystem} {command} +The command is usually (though not always) of the form: + +.. prompt:: bash $ + + ceph {subsystem} {command} System Commands =============== -Execute the following to display the current cluster status. :: +Execute the following to display the current cluster status. : - ceph -s - ceph status +.. prompt:: bash $ + + ceph -s + ceph status Execute the following to display a running summary of cluster status -and major events. :: +and major events. : + +.. prompt:: bash $ - ceph -w + ceph -w Execute the following to show the monitor quorum, including which monitors are -participating and which one is the leader. :: +participating and which one is the leader. : - ceph mon stat - ceph quorum_status +.. prompt:: bash $ + + ceph mon stat + ceph quorum_status Execute the following to query the status of a single monitor, including whether -or not it is in the quorum. :: +or not it is in the quorum. : + +.. prompt:: bash $ - ceph tell mon.[id] mon_status + ceph tell mon.[id] mon_status where the value of ``[id]`` can be determined, e.g., from ``ceph -s``. @@ -47,21 +59,27 @@ where the value of ``[id]`` can be determined, e.g., from ``ceph -s``. Authentication Subsystem ======================== -To add a keyring for an OSD, execute the following:: +To add a keyring for an OSD, execute the following: + +.. prompt:: bash $ - ceph auth add {osd} {--in-file|-i} {path-to-osd-keyring} + ceph auth add {osd} {--in-file|-i} {path-to-osd-keyring} -To list the cluster's keys and their capabilities, execute the following:: +To list the cluster's keys and their capabilities, execute the following: - ceph auth ls +.. prompt:: bash $ + + ceph auth ls Placement Group Subsystem ========================= -To display the statistics for all placement groups (PGs), execute the following:: +To display the statistics for all placement groups (PGs), execute the following: + +.. prompt:: bash $ - ceph pg dump [--format {format}] + ceph pg dump [--format {format}] The valid formats are ``plain`` (default), ``json`` ``json-pretty``, ``xml``, and ``xml-pretty``. When implementing monitoring and other tools, it is best to use ``json`` format. @@ -70,9 +88,11 @@ less variable from release to release. The ``jq`` utility can be invaluable whe data from JSON output. To display the statistics for all placement groups stuck in a specified state, -execute the following:: +execute the following: - ceph pg dump_stuck inactive|unclean|stale|undersized|degraded [--format {format}] [-t|--threshold {seconds}] +.. prompt:: bash $ + + ceph pg dump_stuck inactive|unclean|stale|undersized|degraded [--format {format}] [-t|--threshold {seconds}] ``--format`` may be ``plain`` (default), ``json``, ``json-pretty``, ``xml``, or ``xml-pretty``. @@ -90,9 +110,11 @@ reported to the monitor cluster in a while (configured by ``mon_osd_report_timeout``). Delete "lost" objects or revert them to their prior state, either a previous version -or delete them if they were just created. :: +or delete them if they were just created. : + +.. prompt:: bash $ - ceph pg {pgid} mark_unfound_lost revert|delete + ceph pg {pgid} mark_unfound_lost revert|delete .. _osd-subsystem: @@ -100,105 +122,149 @@ or delete them if they were just created. :: OSD Subsystem ============= -Query OSD subsystem status. :: +Query OSD subsystem status. : - ceph osd stat +.. prompt:: bash $ + + ceph osd stat Write a copy of the most recent OSD map to a file. See -:ref:`osdmaptool `. :: +:ref:`osdmaptool `. : + +.. prompt:: bash $ - ceph osd getmap -o file + ceph osd getmap -o file Write a copy of the crush map from the most recent OSD map to -file. :: +file. : + +.. prompt:: bash $ - ceph osd getcrushmap -o file + ceph osd getcrushmap -o file -The foregoing is functionally equivalent to :: +The foregoing is functionally equivalent to : - ceph osd getmap -o /tmp/osdmap - osdmaptool /tmp/osdmap --export-crush file +.. prompt:: bash $ + + ceph osd getmap -o /tmp/osdmap + osdmaptool /tmp/osdmap --export-crush file Dump the OSD map. Valid formats for ``-f`` are ``plain``, ``json``, ``json-pretty``, ``xml``, and ``xml-pretty``. If no ``--format`` option is given, the OSD map is -dumped as plain text. As above, JSON format is best for tools, scripting, and other automation. :: +dumped as plain text. As above, JSON format is best for tools, scripting, and other automation. : + +.. prompt:: bash $ - ceph osd dump [--format {format}] + ceph osd dump [--format {format}] Dump the OSD map as a tree with one line per OSD containing weight -and state. :: +and state. : + +.. prompt:: bash $ + + ceph osd tree [--format {format}] - ceph osd tree [--format {format}] +Find out where a specific object is or would be stored in the system: -Find out where a specific object is or would be stored in the system:: +.. prompt:: bash $ - ceph osd map + ceph osd map Add or move a new item (OSD) with the given id/name/weight at the specified -location. :: +location. : + +.. prompt:: bash $ + + ceph osd crush set {id} {weight} [{loc1} [{loc2} ...]] + +Remove an existing item (OSD) from the CRUSH map. : - ceph osd crush set {id} {weight} [{loc1} [{loc2} ...]] +.. prompt:: bash $ -Remove an existing item (OSD) from the CRUSH map. :: + ceph osd crush remove {name} - ceph osd crush remove {name} +Remove an existing bucket from the CRUSH map. : -Remove an existing bucket from the CRUSH map. :: +.. prompt:: bash $ - ceph osd crush remove {bucket-name} + ceph osd crush remove {bucket-name} -Move an existing bucket from one position in the hierarchy to another. :: +Move an existing bucket from one position in the hierarchy to another. : - ceph osd crush move {id} {loc1} [{loc2} ...] +.. prompt:: bash $ -Set the weight of the item given by ``{name}`` to ``{weight}``. :: + ceph osd crush move {id} {loc1} [{loc2} ...] - ceph osd crush reweight {name} {weight} +Set the weight of the item given by ``{name}`` to ``{weight}``. : -Mark an OSD as ``lost``. This may result in permanent data loss. Use with caution. :: +.. prompt:: bash $ - ceph osd lost {id} [--yes-i-really-mean-it] + ceph osd crush reweight {name} {weight} + +Mark an OSD as ``lost``. This may result in permanent data loss. Use with caution. : + +.. prompt:: bash $ + + ceph osd lost {id} [--yes-i-really-mean-it] Create a new OSD. If no UUID is given, it will be set automatically when the OSD -starts up. :: +starts up. : + +.. prompt:: bash $ + + ceph osd create [{uuid}] + +Remove the given OSD(s). : + +.. prompt:: bash $ - ceph osd create [{uuid}] + ceph osd rm [{id}...] -Remove the given OSD(s). :: +Query the current ``max_osd`` parameter in the OSD map. : - ceph osd rm [{id}...] +.. prompt:: bash $ -Query the current ``max_osd`` parameter in the OSD map. :: + ceph osd getmaxosd - ceph osd getmaxosd +Import the given crush map. : -Import the given crush map. :: +.. prompt:: bash $ - ceph osd setcrushmap -i file + ceph osd setcrushmap -i file Set the ``max_osd`` parameter in the OSD map. This defaults to 10000 now so -most admins will never need to adjust this. :: +most admins will never need to adjust this. : - ceph osd setmaxosd +.. prompt:: bash $ -Mark OSD ``{osd-num}`` down. :: + ceph osd setmaxosd - ceph osd down {osd-num} +Mark OSD ``{osd-num}`` down. : -Mark OSD ``{osd-num}`` out of the distribution (i.e. allocated no data). :: +.. prompt:: bash $ - ceph osd out {osd-num} + ceph osd down {osd-num} -Mark ``{osd-num}`` in the distribution (i.e. allocated data). :: +Mark OSD ``{osd-num}`` out of the distribution (i.e. allocated no data). : - ceph osd in {osd-num} +.. prompt:: bash $ + + ceph osd out {osd-num} + +Mark ``{osd-num}`` in the distribution (i.e. allocated data). : + +.. prompt:: bash $ + + ceph osd in {osd-num} Set or clear the pause flags in the OSD map. If set, no IO requests will be sent to any OSD. Clearing the flags via unpause results in -resending pending requests. :: +resending pending requests. : - ceph osd pause - ceph osd unpause +.. prompt:: bash $ + + ceph osd pause + ceph osd unpause Set the override weight (reweight) of ``{osd-num}`` to ``{weight}``. Two OSDs with the same weight will receive roughly the same number of I/O requests and @@ -209,9 +275,11 @@ otherwise live on this drive. It does not change weights assigned to the buckets above the OSD in the crush map, and is a corrective measure in case the normal CRUSH distribution is not working out quite right. For instance, if one of your OSDs is at 90% and the others are -at 50%, you could reduce this weight to compensate. :: +at 50%, you could reduce this weight to compensate. : + +.. prompt:: bash $ - ceph osd reweight {osd-num} {weight} + ceph osd reweight {osd-num} {weight} Balance OSD fullness by reducing the override weight of OSDs which are overly utilized. Note that these override aka ``reweight`` values @@ -219,9 +287,11 @@ default to 1.00000 and are relative only to each other; they not absolute. It is crucial to distinguish them from CRUSH weights, which reflect the absolute capacity of a bucket in TiB. By default this command adjusts override weight on OSDs which have + or - 20% of the average utilization, -but if you include a ``threshold`` that percentage will be used instead. :: +but if you include a ``threshold`` that percentage will be used instead. : + +.. prompt:: bash $ - ceph osd reweight-by-utilization [threshold [max_change [max_osds]]] [--no-increasing] + ceph osd reweight-by-utilization [threshold [max_change [max_osds]]] [--no-increasing] To limit the step by which any OSD's reweight will be changed, specify ``max_change`` which defaults to 0.05. To limit the number of OSDs that will @@ -230,9 +300,11 @@ parameters can speed leveling of OSD utilization, at the potential cost of greater impact on client operations due to more data moving at once. To determine which and how many PGs and OSDs will be affected by a given invocation -you can test before executing. :: +you can test before executing. : - ceph osd test-reweight-by-utilization [threshold [max_change max_osds]] [--no-increasing] +.. prompt:: bash $ + + ceph osd test-reweight-by-utilization [threshold [max_change max_osds]] [--no-increasing] Adding ``--no-increasing`` to either command prevents increasing any override weights that are currently < 1.00000. This can be useful when @@ -256,25 +328,33 @@ including the ``range`` keyword. These commands are mostly only useful for failure testing, as blocklists are normally maintained automatically and shouldn't need -manual intervention. :: +manual intervention. : + +.. prompt:: bash $ + + ceph osd blocklist ["range"] add ADDRESS[:source_port][/netmask_bits] [TIME] + ceph osd blocklist ["range"] rm ADDRESS[:source_port][/netmask_bits] + +Creates/deletes a snapshot of a pool. : - ceph osd blocklist ["range"] add ADDRESS[:source_port][/netmask_bits] [TIME] - ceph osd blocklist ["range"] rm ADDRESS[:source_port][/netmask_bits] +.. prompt:: bash $ -Creates/deletes a snapshot of a pool. :: + ceph osd pool mksnap {pool-name} {snap-name} + ceph osd pool rmsnap {pool-name} {snap-name} - ceph osd pool mksnap {pool-name} {snap-name} - ceph osd pool rmsnap {pool-name} {snap-name} +Creates/deletes/renames a storage pool. : -Creates/deletes/renames a storage pool. :: +.. prompt:: bash $ - ceph osd pool create {pool-name} [pg_num [pgp_num]] - ceph osd pool delete {pool-name} [{pool-name} --yes-i-really-really-mean-it] - ceph osd pool rename {old-name} {new-name} + ceph osd pool create {pool-name} [pg_num [pgp_num]] + ceph osd pool delete {pool-name} [{pool-name} --yes-i-really-really-mean-it] + ceph osd pool rename {old-name} {new-name} -Changes a pool setting. :: +Changes a pool setting. : - ceph osd pool set {pool-name} {field} {value} +.. prompt:: bash $ + + ceph osd pool set {pool-name} {field} {value} Valid fields are: @@ -283,9 +363,11 @@ Valid fields are: * ``pgp_num``: Effective number when calculating pg placement. * ``crush_rule``: rule number for mapping placement. -Get the value of a pool setting. :: +Get the value of a pool setting. : + +.. prompt:: bash $ - ceph osd pool get {pool-name} {field} + ceph osd pool get {pool-name} {field} Valid fields are: @@ -293,49 +375,67 @@ Valid fields are: * ``pgp_num``: Effective number of placement groups when calculating placement. -Sends a scrub command to OSD ``{osd-num}``. To send the command to all OSDs, use ``*``. :: +Sends a scrub command to OSD ``{osd-num}``. To send the command to all OSDs, use ``*``. : + +.. prompt:: bash $ - ceph osd scrub {osd-num} + ceph osd scrub {osd-num} -Sends a repair command to OSD.N. To send the command to all OSDs, use ``*``. :: +Sends a repair command to OSD.N. To send the command to all OSDs, use ``*``. : - ceph osd repair N +.. prompt:: bash $ + + ceph osd repair N Runs a simple throughput benchmark against OSD.N, writing ``TOTAL_DATA_BYTES`` in write requests of ``BYTES_PER_WRITE`` each. By default, the test writes 1 GB in total in 4-MB increments. The benchmark is non-destructive and will not overwrite existing live OSD data, but might temporarily affect the performance of clients -concurrently accessing the OSD. :: +concurrently accessing the OSD. : + +.. prompt:: bash $ + + ceph tell osd.N bench [TOTAL_DATA_BYTES] [BYTES_PER_WRITE] + +To clear an OSD's caches between benchmark runs, use the 'cache drop' command : - ceph tell osd.N bench [TOTAL_DATA_BYTES] [BYTES_PER_WRITE] +.. prompt:: bash $ -To clear an OSD's caches between benchmark runs, use the 'cache drop' command :: + ceph tell osd.N cache drop - ceph tell osd.N cache drop +To get the cache statistics of an OSD, use the 'cache status' command : -To get the cache statistics of an OSD, use the 'cache status' command :: +.. prompt:: bash $ - ceph tell osd.N cache status + ceph tell osd.N cache status MDS Subsystem ============= -Change configuration parameters on a running mds. :: +Change configuration parameters on a running mds. : + +.. prompt:: bash $ + + ceph tell mds.{mds-id} config set {setting} {value} + +Example: - ceph tell mds.{mds-id} config set {setting} {value} +.. prompt:: bash $ -Example:: + ceph tell mds.0 config set debug_ms 1 - ceph tell mds.0 config set debug_ms 1 +Enables debug messages. : -Enables debug messages. :: +.. prompt:: bash $ - ceph mds stat + ceph mds stat -Displays the status of all metadata servers. :: +Displays the status of all metadata servers. : - ceph mds fail 0 +.. prompt:: bash $ + + ceph mds fail 0 Marks the active MDS as failed, triggering failover to a standby if present. @@ -345,18 +445,24 @@ Marks the active MDS as failed, triggering failover to a standby if present. Mon Subsystem ============= -Show monitor stats:: +Show monitor stats: + +.. prompt:: bash $ - ceph mon stat + ceph mon stat + +:: e2: 3 mons at {a=127.0.0.1:40000/0,b=127.0.0.1:40001/0,c=127.0.0.1:40002/0}, election epoch 6, quorum 0,1,2 a,b,c The ``quorum`` list at the end lists monitor nodes that are part of the current quorum. -This is also available more directly:: +This is also available more directly: + +.. prompt:: bash $ - ceph quorum_status -f json-pretty + ceph quorum_status -f json-pretty .. code-block:: javascript @@ -410,9 +516,11 @@ This is also available more directly:: The above will block until a quorum is reached. -For a status of just a single monitor:: +For a status of just a single monitor: - ceph tell mon.[name] mon_status +.. prompt:: bash $ + + ceph tell mon.[name] mon_status where the value of ``[name]`` can be taken from ``ceph quorum_status``. Sample output:: @@ -474,10 +582,14 @@ output:: } } -A dump of the monitor state:: +A dump of the monitor state: + + .. prompt:: bash $ ceph mon dump + :: + dumped monmap epoch 2 epoch 2 fsid ba807e74-b64f-4b72-b43f-597dfe60ddbc -- 2.39.5