ceph/doc/rbd/rbd-persistent-write-back-cache.rst

   1 ================================
   2  RBD Persistent Write-back Cache
   3 ================================
   4
   5 .. index:: Ceph Block Device; Persistent Write-back Cache
   6
   7 Persistent Write-back Cache
   8 ===========================
   9
  10 The persistent write-back cache provides a persistent, fault-tolerant write-back
  11 cache for librbd-based RBD clients.
  12
  13 This cache uses a log-ordered write-back design which maintains checkpoints
  14 internally so that writes that get flushed back to the cluster are always
  15 crash consistent. Even if the client cache is lost entirely, the disk image is
  16 still consistent but the data will appear to be stale.
  17
  18 This cache can be used with PMEM or SSD as a cache device.
  19
  20 Usage
  21 =====
  22
  23 The persistent write-back cache manages the cache data in a persistent device.
  24 It looks for and creates cache files in a configured directory, and then caches
  25 data in the file.
  26
  27 The persistent write-back cache can't be enabled without the exclusive-lock
  28 feature. It tries to enable the write-back cache only when the exclusive lock
  29 is acquired.
  30
  31 The cache provides two different persistence modes. In persistent-on-write mode,
  32 the writes are completed only when they are persisted to the cache device and
  33 will be readable after a crash. In persistent-on-flush mode, the writes are
  34 completed as soon as it no longer needs the caller's data buffer to complete
  35 the writes, but does not guarantee that writes will be readable after a crash.
  36 The data is persisted to the cache device when a flush request is received.
  37
  38 Initially it defaults to the persistent-on-write mode and it switches to
  39 persistent-on-flush mode after the first flush request is received.
  40
  41 Enable Persistent Write-back Cache
  42 ========================================
  43
  44 To enable the persistent write-back cache, the following Ceph settings
  45 need to be enabled.::
  46
  47         rbd persistent cache mode = {cache-mode}
  48         rbd plugins = pwl_cache
  49
  50 Value of {cache-mode} can be ``rwl``, ``ssd`` or ``disabled``. By default the
  51 cache is disabled.
  52
  53 Here are some cache configuration settings:
  54
  55 - ``rbd_persistent_cache_path`` A file folder to cache data. This folder must
  56   have DAX enabled (see `DAX`_) when using ``rwl`` mode to avoid performance
  57   degradation.
  58
  59 - ``rbd_persistent_cache_size`` The cache size per image. The minimum cache
  60   size is 1 GB.
  61
  62 - ``rbd_persistent_cache_log_periodic_stats`` This is a debug option. It is
  63   used to emit periodic perf stats to the debug log if ``debug rbd pwl`` is
  64   set to ``1`` or higher.
  65
  66 The above configurations can be set per-host, per-pool, per-image etc. Eg, to
  67 set per-host, add the overrides to the appropriate `section`_ in the host's
  68 ``ceph.conf`` file. To set per-pool, per-image, etc, please refer to the
  69 ``rbd config`` `commands`_.
  70
  71 Cache Status
  72 ------------
  73
  74 The persistent write-back cache is enabled when the exclusive lock is acquired,
  75 and it is closed when the exclusive lock is released. To check the cache status,
  76 users may use the command ``rbd status``.  ::
  77
  78         rbd status {pool-name}/{image-name}
  79
  80 The status of the cache is shown, including present, clean, cache size and the
  81 location. Currently the status is updated only at the time the cache is opened
  82 and closed and therefore may appear to be out of date (e.g. show that the cache
  83 is clean when it is actually dirty).
  84
  85 For example::
  86
  87         $ rbd status rbd/foo
  88         Watchers: none
  89         Image cache state: {"present":"true","empty":"false","clean":"true","cache_type":"ssd","pwl_host":"sceph9","pwl_path":"/tmp/rbd-pwl.rbd.abcdef123456.pool","pwl_size":1073741824}
  90
  91 Discard Cache
  92 -------------
  93
  94 To discard a cache file with ``rbd``, specify the ``image-cache invalidate``
  95 option, the pool name and the image name.  ::
  96
  97         rbd image-cache invalidate {pool-name}/{image-name}
  98
  99 The command removes the cache metadata of the corresponding image, disable
 100 the cache feature and deletes the local cache file if it exists.
 101
 102 For example::
 103
 104         $ rbd image-cache invalidate rbd/foo
 105
 106 .. _section: ../../rados/configuration/ceph-conf/#configuration-sections
 107 .. _commands: ../../man/8/rbd#commands
 108 .. _DAX: https://www.kernel.org/doc/Documentation/filesystems/dax.txt