Update scrubber documentation

Updates scrubber docs to take into account the refactoring done in
change I26f570b85617200880543b7114730a1ac76d3fb1 and updates the
header info for all cli docs in anticipation of the Queens release.

Change-Id: I61095b9ba8f7e12fcf2005aa6f8af501829dfa6b

doc/source/cli/glancescrubber.rst

@@ -16,21 +16,81 @@ glance-scrubber [options]
 DESCRIPTION
 ===========
 
-glance-scrubber is a utility that cleans up images that have been deleted. The
-mechanics of this differ depending on the backend store and pending_deletion
-options chosen.
+glance-scrubber is a utility that allows an operator to configure Glance for
+the asynchronous deletion of images.  Whether this makes sense for your
+deployment depends upon the storage backend you are using and the size of
+typical images handled by your Glance installation.
 
-Multiple glance-scrubbers can be run in a single deployment, but only one of
-them may be designated as the 'cleanup_scrubber' in the glance-scrubber.conf
-file. The 'cleanup_scrubber' coordinates other glance-scrubbers by maintaining
-the master queue of images that need to be removed.
+An image in glance is really a combination of an image record (stored in the
+database) and a file of image data (stored in a storage backend).  Under normal
+operation, the image-delete call is synchronous, that is, Glance receives the
+DELETE request, deletes the image data from the storage backend, then deletes
+the image record from the database, and finally returns a 204 as the result of
+the call.  If the backend is fast and deletion time is not a function of data
+size, these operations occur very quickly.  For backends where deletion time is
+a function of data size, however, the image-delete operation can take a
+significant amount of time to complete, to the point where a client may timeout
+waiting for the response.  This in turn leads to user dissatisfaction.
 
-The glance-scubber.conf file also specifies important configuration items such
-as the time between runs ('wakeup_time' in seconds), length of time images
-can be pending before their deletion ('cleanup_scrubber_time' in seconds) as
-well as registry connectivity options.
+To avoid this problem, Glance has a ``delayed_delete`` configuration option
+(False by default) that may be set in the **glance-api.conf** file.  With this
+option enabled, when Glance receives a DELETE request, it does *only* the
+database part of the request, marking the image's status as ``pending_delete``,
+and returns immediately.  (The ``pending_delete`` status is not visible to
+users; an image-show request for such an image will return 404.)  However, it
+is important to note that when ``delayed_delete`` is enabled, *Glance does not
+delete image data from the storage backend*.  That's where the glance-scrubber
+comes in.
 
-glance-scrubber can run as a periodic job or long-running daemon.
+The glance-scrubber cleans up images that have been deleted.  If you run Glance
+with ``delayed_delete`` enabled, you *must* run the glance-scrubber
+occasionally or your storage backend will eventually fill up with "deleted"
+image data.
+
+Configuration of glance-scrubber is done in the **glance-scrubber.conf** file.
+Options are explained in detail in comments in the sample configuration file,
+so we only point out a few of them here.
+
+``scrub_time``
+    minimum time in seconds that an image will stay in ``pending_delete``
+    status (default is 0)
+
+``scrub_pool_size``
+    configures a thread pool so that scrubbing can be performed in parallel
+    (default is 1, that is, serial scrubbing)
+
+``daemon``
+    a boolean indicating whether the scrubber should run as a daemon
+    (default is False)
+
+``wakeup_time``
+    time in seconds between runs when the scrubber is run in daemon mode
+    (ignored if the scrubber is not being run in daemon mode)
+
+``metadata_encryption_key``
+    If your **glance-api.conf** sets a value for this option (the default is to
+    leave it unset), you must include the same setting in your
+    **glance-scrubber.conf** or the scrubber won't be able to determine the
+    locations of your image data.
+
+``[database]``
+    As of the Queens release of Glance (16.0.0), the glance-scrubber does not
+    use the deprecated Glance registry, but instead contacts the Glance
+    database directly.  Thus your **glance-scrubber.conf** file must contain a
+    [database] section specifying the relevant information.
+
+``[glance_store]``
+   This section of the file contains the configuration information for the
+   storage backends used by your Glance installation.
+
+The usual situation is that whatever your **glance-api.conf** has for the
+``[database]`` and ``[glance_store]`` configuration groups should go into your
+**glance-scrubber.conf**, too.  Of course, if you have heavily customized your
+setup, you know better than we do what you are doing.  The key thing is that
+the scrubber needs to be able to access the Glance database to determine what
+images need to be scrubbed (and to mark them as deleted once their associated
+data has been removed from the storage backend), and it needs the glance_store
+information so it can delete the image data.
 
 OPTIONS
 =======

doc/source/cli/header.txt

@@ -1,7 +1,8 @@
 
-:Author: glance@lists.launchpad.net
-:Date: 2017-09-15
+:Author: OpenStack Glance Project Team
+:Contact: glance@lists.launchpad.net
+:Date: 2018-02-28
 :Copyright: OpenStack Foundation
-:Version: 15.0.0
+:Version: 16.0.0
 :Manual section: 1
 :Manual group: cloud computing