ceph/doc/cephfs/scrub.rst

   1 .. _mds-scrub:
   2
   3 ======================
   4 Ceph File System Scrub
   5 ======================
   6
   7 CephFS provides the cluster admin (operator) to check consistency of a file system
   8 via a set of scrub commands. Scrub can be classified into two parts:
   9
  10 #. Forward Scrub: In which the scrub operation starts at the root of the file system
  11    (or a sub directory) and looks at everything that can be touched in the hierarchy
  12    to ensure consistency.
  13
  14 #. Backward Scrub: In which the scrub operation looks at every RADOS object in the
  15    file system pools and maps it back to the file system hierarchy.
  16
  17 This document details commands to initiate and control forward scrub (referred as
  18 scrub thereafter).
  19
  20 Initiate File System Scrub
  21 ==========================
  22
  23 To start a scrub operation for a directory tree use the following command
  24
  25 ::
  26
  27    ceph tell mds.a scrub start / recursive
  28    {
  29        "return_code": 0,
  30        "scrub_tag": "6f0d204c-6cfd-4300-9e02-73f382fd23c1",
  31        "mode": "asynchronous"
  32    }
  33
  34 Recursive scrub is asynchronous (as hinted by `mode` in the output above). Scrub tag is
  35 a random string that can used to monitor the progress of the scrub operation (explained
  36 further in this document).
  37
  38 Custom tag can also be specified when initiating the scrub operation. Custom tags get
  39 persisted in the metadata object for every inode in the file system tree that is being
  40 scrubbed.
  41
  42 ::
  43
  44    ceph tell mds.a scrub start /a/b/c recursive tag0
  45    {
  46        "return_code": 0,
  47        "scrub_tag": "tag0",
  48        "mode": "asynchronous"
  49    }
  50
  51
  52 Monitor (ongoing) File System Scrubs
  53 ====================================
  54
  55 Status of ongoing scrubs can be monitored using in `scrub status` command. This commands
  56 lists out ongoing scrubs (identified by the tag) along with the path and options used to
  57 initiate the scrub.
  58
  59 ::
  60
  61    ceph tell mds.a scrub status
  62    {
  63        "status": "scrub active (85 inodes in the stack)",
  64        "scrubs": {
  65            "6f0d204c-6cfd-4300-9e02-73f382fd23c1": {
  66                "path": "/",
  67                "options": "recursive"
  68            }
  69        }
  70    }
  71
  72 `status` shows the number of inodes that are scheduled to be scrubbed at any point in time,
  73 hence, can change on subsequent `scrub status` invocations. Also, a high level summary of
  74 scrub operation (which includes the operation state and paths on which scrub is triggered)
  75 gets displayed in `ceph status`.
  76
  77 ::
  78
  79    ceph status
  80    [...]
  81
  82    task status:
  83      scrub status:
  84          mds.0: active [paths:/]
  85
  86    [...]
  87
  88 Control (ongoing) File System Scrubs
  89 ====================================
  90
  91 - Pause: Pausing ongoing scrub operations results in no new or pending inodes being
  92   scrubbed after in-flight RADOS ops (for the inodes that are currently being scrubbed)
  93   finish.
  94
  95 ::
  96
  97    ceph tell mds.a scrub pause
  98    {
  99        "return_code": 0
 100    }
 101
 102 `scrub status` after pausing reflects the paused state. At this point, initiating new scrub
 103 operations (via `scrub start`) would just queue the inode for scrub.
 104
 105 ::
 106
 107    ceph tell mds.a scrub status
 108    {
 109        "status": "PAUSED (66 inodes in the stack)",
 110        "scrubs": {
 111            "6f0d204c-6cfd-4300-9e02-73f382fd23c1": {
 112                "path": "/",
 113                "options": "recursive"
 114            }
 115        }
 116    }
 117
 118 - Resume: Resuming kick starts a paused scrub operation.
 119
 120 ::
 121
 122    ceph tell mds.a. scrub resume
 123    {
 124        "return_code": 0
 125    }
 126
 127 - Abort: Aborting ongoing scrub operations removes pending inodes from the scrub
 128   queue (thereby aborting the scrub) after in-flight RADOS ops (for the inodes that
 129   are currently being scrubbed) finish.
 130
 131 ::
 132
 133    ceph tell mds.a. scrub abort
 134    {
 135        "return_code": 0
 136    }