Merging upstream version 18.2.3.

Signed-off-by: Daniel Baumann <daniel.baumann@progress-linux.org>

6 files changed, 106 insertions, 47 deletions

diff --git a/doc/man/8/ceph-mds.rst b/doc/man/8/ceph-mds.rst
index fd8fc800e..c68d3d110 100644
--- a/doc/man/8/ceph-mds.rst
+++ b/doc/man/8/ceph-mds.rst
@@ -1,5 +1,7 @@
 :orphan:
 
+.. _ceph_mds_man:
+
 =========================================
  ceph-mds -- ceph metadata server daemon
 =========================================
diff --git a/doc/man/8/ceph-objectstore-tool.rst b/doc/man/8/ceph-objectstore-tool.rst
index de1304733..9b5436f24 100644
--- a/doc/man/8/ceph-objectstore-tool.rst
+++ b/doc/man/8/ceph-objectstore-tool.rst
@@ -244,45 +244,56 @@ Procedure
 Manipulating the Object Map Key
 -------------------------------
 
-Use the **ceph-objectstore-tool** utility to change the object map (OMAP) key. You need to provide the data path, the placement group identifier (PG ID), the object, and the key in the OMAP.
-Note
+Use the **ceph-objectstore-tool** utility to change the object map (OMAP) key.
+Provide the data path, the placement group identifier (PG ID), the object, and
+the key in the OMAP.
 
 Prerequisites
+^^^^^^^^^^^^^
 
     * Having root access to the Ceph OSD node.
     * Stopping the ceph-osd daemon. 
 
-Procedure
+Commands
+^^^^^^^^
+
+Run the commands in this section as ``root`` on an OSD node.
+
+* **Getting the object map key**
 
-    Get the object map key:
+   Syntax:
 
-    Syntax::
+   .. code-block:: ini 
      
-       ceph-objectstore-tool --data-path $PATH_TO_OSD --pgid $PG_ID $OBJECT get-omap $KEY > $OBJECT_MAP_FILE_NAME
+      ceph-objectstore-tool --data-path $PATH_TO_OSD --pgid $PG_ID $OBJECT get-omap $KEY > $OBJECT_MAP_FILE_NAME
 
    Example::
 
-    [root@osd ~]# ceph-objectstore-tool --data-path /var/lib/ceph/osd/ceph-0 --pgid 0.1c '{"oid":"zone_info.default","key":"","snapid":-2,"hash":235010478,"max":0,"pool":11,"namespace":""}'  get-omap "" > zone_info.default.omap.txt
+    ceph-objectstore-tool --data-path /var/lib/ceph/osd/ceph-0 --pgid 0.1c '{"oid":"zone_info.default","key":"","snapid":-2,"hash":235010478,"max":0,"pool":11,"namespace":""}'  get-omap "" > zone_info.default.omap.txt
 
-   Set the object map key:
+* **Setting the object map key**
 
-   Syntax::
+   Syntax:
+
+   .. code-block:: ini 
 
-    ceph-objectstore-tool --data-path $PATH_TO_OSD --pgid $PG_ID $OBJECT set-omap $KEY < $OBJECT_MAP_FILE_NAME
+      ceph-objectstore-tool --data-path $PATH_TO_OSD --pgid $PG_ID $OBJECT set-omap $KEY < $OBJECT_MAP_FILE_NAME
 
    Example::
 
-    [root@osd ~]# ceph-objectstore-tool --data-path /var/lib/ceph/osd/ceph-0 --pgid 0.1c '{"oid":"zone_info.default","key":"","snapid":-2,"hash":235010478,"max":0,"pool":11,"namespace":""}' set-omap "" < zone_info.default.omap.txt
+    ceph-objectstore-tool --data-path /var/lib/ceph/osd/ceph-0 --pgid 0.1c '{"oid":"zone_info.default","key":"","snapid":-2,"hash":235010478,"max":0,"pool":11,"namespace":""}' set-omap "" < zone_info.default.omap.txt
 
-   Remove the object map key:
+* **Removing the object map key**
 
-   Syntax::
+   Syntax:
+
+   .. code-block:: ini 
 
-    ceph-objectstore-tool --data-path $PATH_TO_OSD --pgid $PG_ID $OBJECT rm-omap $KEY
+      ceph-objectstore-tool --data-path $PATH_TO_OSD --pgid $PG_ID $OBJECT rm-omap $KEY
 
    Example::
 
-    [root@osd ~]# ceph-objectstore-tool --data-path /var/lib/ceph/osd/ceph-0 --pgid 0.1c '{"oid":"zone_info.default","key":"","snapid":-2,"hash":235010478,"max":0,"pool":11,"namespace":""}' rm-omap ""
+    ceph-objectstore-tool --data-path /var/lib/ceph/osd/ceph-0 --pgid 0.1c '{"oid":"zone_info.default","key":"","snapid":-2,"hash":235010478,"max":0,"pool":11,"namespace":""}' rm-omap ""
 
 
 Listing an Object's Attributes
diff --git a/doc/man/8/ceph-osd.rst b/doc/man/8/ceph-osd.rst
index 5b631eeff..4b038437b 100644
--- a/doc/man/8/ceph-osd.rst
+++ b/doc/man/8/ceph-osd.rst
@@ -18,14 +18,16 @@ Synopsis
 Description
 ===========
 
-**ceph-osd** is the object storage daemon for the Ceph distributed file
-system. It is responsible for storing objects on a local file system
-and providing access to them over the network.
-
-The datapath argument should be a directory on a xfs file system
-where the object data resides. The journal is optional, and is only
-useful performance-wise when it resides on a different disk than
-datapath with low latency (ideally, an NVRAM device).
+**ceph-osd** is the **o**\bject **s**\torage **d**\aemon for the Ceph
+distributed file system. It manages data on local storage with redundancy and
+provides access to that data over the network. 
+
+For Filestore-backed clusters, the argument of the ``--osd-data datapath``
+option (which is ``datapath`` in this example) should be a directory on an XFS
+file system where the object data resides. The journal is optional. The journal
+improves performance only when it resides on a different disk than the disk
+specified by ``datapath`` . The storage medium on which the journal is stored
+should be a low-latency medium (ideally, an SSD device).
 
 
 Options
diff --git a/doc/man/8/cephfs-shell.rst b/doc/man/8/cephfs-shell.rst
index a615dab98..974ba37d9 100644
--- a/doc/man/8/cephfs-shell.rst
+++ b/doc/man/8/cephfs-shell.rst
@@ -56,7 +56,7 @@ Options
 
 .. code:: bash
 
-    [build]$ python3 -m venv venv && source venv/bin/activate && pip3 install cmd2
+    [build]$ python3 -m venv venv && source venv/bin/activate && pip3 install cmd2 colorama
     [build]$ source vstart_environment.sh && source venv/bin/activate && python3 ../src/tools/cephfs/shell/cephfs-shell
 
 Commands
diff --git a/doc/man/8/mount.ceph.rst b/doc/man/8/mount.ceph.rst
index fbe8790dd..e45030cd0 100644
--- a/doc/man/8/mount.ceph.rst
+++ b/doc/man/8/mount.ceph.rst
@@ -199,6 +199,50 @@ Advanced
     option is enabled, a namespace operation may complete before the MDS
     replies, if it has sufficient capabilities to do so.
 
+:command:`crush_location=x`
+    Specify the location of the client in terms of CRUSH hierarchy (since 5.8).
+    This is a set of key-value pairs separated from each other by '|', with
+    keys separated from values by ':'.  Note that '|' may need to be quoted
+    or escaped to avoid it being interpreted as a pipe by the shell. The key
+    is the bucket type name (e.g. rack, datacenter or region with default
+    bucket types) and the value is the bucket name. For example, to indicate
+    that the client is local to rack "myrack", data center "mydc" and region
+    "myregion"::
+
+      crush_location=rack:myrack|datacenter:mydc|region:myregion
+
+    Each key-value pair stands on its own: "myrack" doesn't need to reside in
+    "mydc", which in turn doesn't need to reside in "myregion".  The location
+    is not a path to the root of the hierarchy but rather a set of nodes that
+    are matched independently.  "Multipath" locations are supported, so it is
+    possible to indicate locality for multiple parallel hierarchies::
+
+      crush_location=rack:myrack1|rack:myrack2|datacenter:mydc
+
+
+:command:`read_from_replica=<no|balance|localize>`
+    - ``no``: Disable replica reads, always pick the primary OSD (since 5.8, default).
+
+    - ``balance``: When a replicated pool receives a read request, pick a random
+      OSD from the PG's acting set to serve it (since 5.8).
+
+      This mode is safe for general use only since Octopus (i.e. after "ceph osd
+      require-osd-release octopus"). Otherwise it should be limited to read-only
+      workloads such as snapshots.
+
+    - ``localize``: When a replicated pool receives a read request, pick the most
+      local OSD to serve it (since 5.8). The locality metric is calculated against
+      the location of the client given with crush_location; a match with the
+      lowest-valued bucket type wins.  For example, an OSD in a matching rack
+      is closer than an OSD in a matching data center, which in turn is closer
+      than an OSD in a matching region.
+
+      This mode is safe for general use only since Octopus (i.e. after "ceph osd
+      require-osd-release octopus").  Otherwise it should be limited to read-only
+      workloads such as snapshots.
+
+
+
 Examples
 ========
 
diff --git a/doc/man/8/rbd.rst b/doc/man/8/rbd.rst
index 59e346209..506a7bb3e 100644
--- a/doc/man/8/rbd.rst
+++ b/doc/man/8/rbd.rst
@@ -333,7 +333,7 @@ Commands
   be specified.
 
 :command:`flatten` [--encryption-format *encryption-format* --encryption-passphrase-file *passphrase-file*]... *image-spec*
-  If image is a clone, copy all shared blocks from the parent snapshot and
+  If the image is a clone, copy all shared blocks from the parent snapshot and
   make the child independent of the parent, severing the link between
   parent snap and child.  The parent snapshot can be unprotected and
   deleted if it has no further dependent clones.
@@ -390,7 +390,7 @@ Commands
   Set metadata key with the value. They will displayed in `image-meta list`.
 
 :command:`import` [--export-format *format (1 or 2)*] [--image-format *format-id*] [--object-size *size-in-B/K/M*] [--stripe-unit *size-in-B/K/M* --stripe-count *num*] [--image-feature *feature-name*]... [--image-shared] *src-path* [*image-spec*]
-  Create a new image and imports its data from path (use - for
+  Create a new image and import its data from path (use - for
   stdin).  The import operation will try to create sparse rbd images 
   if possible.  For import from stdin, the sparsification unit is
   the data block size of the destination image (object size).
@@ -402,14 +402,14 @@ Commands
   of image, but also the snapshots and other properties, such as image_order, features.
 
 :command:`import-diff` *src-path* *image-spec*
-  Import an incremental diff of an image and applies it to the current image.  If the diff
+  Import an incremental diff of an image and apply it to the current image.  If the diff
   was generated relative to a start snapshot, we verify that snapshot already exists before
   continuing.  If there was an end snapshot we verify it does not already exist before
   applying the changes, and create the snapshot when we are done.
   
 :command:`info` *image-spec* | *snap-spec*
   Will dump information (such as size and object size) about a specific rbd image.
-  If image is a clone, information about its parent is also displayed.
+  If the image is a clone, information about its parent is also displayed.
   If a snapshot is specified, whether it is protected is shown as well.
 
 :command:`journal client disconnect` *journal-spec*
@@ -472,7 +472,7 @@ Commands
   the destination image are lost.
 
 :command:`migration commit` *image-spec*
-  Commit image migration. This step is run after a successful migration
+  Commit image migration. This step is run after successful migration
   prepare and migration execute steps and removes the source image data.
 
 :command:`migration execute` *image-spec*
@@ -499,14 +499,12 @@ Commands
 :command:`mirror image disable` [--force] *image-spec*
   Disable RBD mirroring for an image. If the mirroring is
   configured in ``image`` mode for the image's pool, then it
-  can be explicitly disabled mirroring for each image within
-  the pool.
+  must be disabled for each image individually.
 
 :command:`mirror image enable` *image-spec* *mode*
   Enable RBD mirroring for an image. If the mirroring is
   configured in ``image`` mode for the image's pool, then it
-  can be explicitly enabled mirroring for each image within
-  the pool.
+  must be enabled for each image individually.
 
   The mirror image mode can either be ``journal`` (default) or
   ``snapshot``. The ``journal`` mode requires the RBD journaling
@@ -523,7 +521,7 @@ Commands
 
 :command:`mirror pool demote` [*pool-name*]
   Demote all primary images within a pool to non-primary.
-  Every mirroring enabled image will demoted in the pool.
+  Every mirror-enabled image in the pool will be demoted.
 
 :command:`mirror pool disable` [*pool-name*]
   Disable RBD mirroring by default within a pool. When mirroring
@@ -551,7 +549,7 @@ Commands
 
   The default for *remote client name* is "client.admin".
 
-  This requires mirroring mode is enabled.
+  This requires mirroring to be enabled on the pool.
 
 :command:`mirror pool peer remove` [*pool-name*] *uuid*
   Remove a mirroring peer from a pool. The peer uuid is available
@@ -564,12 +562,12 @@ Commands
 
 :command:`mirror pool promote` [--force] [*pool-name*]
   Promote all non-primary images within a pool to primary.
-  Every mirroring enabled image will promoted in the pool.
+  Every mirror-enabled image in the pool will be promoted.
 
 :command:`mirror pool status` [--verbose] [*pool-name*]
   Show status for all mirrored images in the pool.
-  With --verbose, also show additionally output status
-  details for every mirroring image in the pool.
+  With ``--verbose``, show additional output status
+  details for every mirror-enabled image in the pool.
 
 :command:`mirror snapshot schedule add` [-p | --pool *pool*] [--namespace *namespace*] [--image *image*] *interval* [*start-time*]
   Add mirror snapshot schedule.
@@ -603,7 +601,7 @@ Commands
   specified to rebuild an invalid object map for a snapshot.
 
 :command:`pool init` [*pool-name*] [--force]
-  Initialize pool for use by RBD. Newly created pools must initialized
+  Initialize pool for use by RBD. Newly created pools must be initialized
   prior to use.
 
 :command:`resize` (-s | --size *size-in-M/G/T*) [--allow-shrink] [--encryption-format *encryption-format* --encryption-passphrase-file *passphrase-file*]... *image-spec*
@@ -615,7 +613,7 @@ Commands
   snapshots, this fails and nothing is deleted.
 
 :command:`snap create` *snap-spec*
-  Create a new snapshot. Requires the snapshot name parameter specified.
+  Create a new snapshot. Requires the snapshot name parameter to be specified.
 
 :command:`snap limit clear` *image-spec*
   Remove any previously set limit on the number of snapshots allowed on
@@ -625,7 +623,7 @@ Commands
   Set a limit for the number of snapshots allowed on an image.
 
 :command:`snap ls` *image-spec*
-  Dump the list of snapshots inside a specific image.
+  Dump the list of snapshots of a specific image.
 
 :command:`snap protect` *snap-spec*
   Protect a snapshot from deletion, so that clones can be made of it
@@ -668,9 +666,11 @@ Commands
 :command:`trash ls` [*pool-name*]
   List all entries from trash.
 
-:command:`trash mv` *image-spec*
+:command:`trash mv` [--expires-at <expires-at>] *image-spec*
   Move an image to the trash. Images, even ones actively in-use by 
-  clones, can be moved to the trash and deleted at a later time.
+  clones, can be moved to the trash and deleted at a later time. Use
+  ``--expires-at`` to set the expiration time of an image after which
+  it's allowed to be removed.
 
 :command:`trash purge` [*pool-name*]
   Remove all expired images from trash.
@@ -678,10 +678,10 @@ Commands
 :command:`trash restore` *image-id*  
   Restore an image from trash.
 
-:command:`trash rm` *image-id* 
-  Delete an image from trash. If image deferment time has not expired
-  you can not removed it unless use force. But an actively in-use by clones 
-  or has snapshots can not be removed.
+:command:`trash rm` [--force] *image-id*
+  Delete an image from trash. If the image deferment time has not expired
+  it can be removed using ``--force``. An image that is actively in-use by clones
+  or has snapshots cannot be removed.
 
 :command:`trash purge schedule add` [-p | --pool *pool*] [--namespace *namespace*] *interval* [*start-time*]
   Add trash purge schedule.