Notice

This document is for a development version of Ceph.

# RBD Persistent Write-back Cache¶

## Persistent Write-back Cache¶

The persistent write-back cache provides a persistent, fault-tolerant write-back cache for librbd-based RBD clients.

This cache uses a log-ordered write-back design which maintains checkpoints internally so that writes that get flushed back to the cluster are always crash consistent. Even if the client cache is lost entirely, the disk image is still consistent but the data will appear to be stale.

This cache can be used with PMEM or SSD as a cache device.

## Usage¶

The persistent write-back cache manages the cache data in a persistent device. It looks for and creates cache files in a configured directory, and then caches data in the file.

The persistent write-back cache can’t be enabled without the exclusive-lock feature. It tries to enable the write-back cache only when the exclusive lock is acquired.

The cache provides two different persistence modes. In persistent-on-write mode, the writes are completed only when they are persisted to the cache device and will be readable after a crash. In persistent-on-flush mode, the writes are completed as soon as it no longer needs the caller’s data buffer to complete the writes, but does not guarantee that writes will be readable after a crash. The data is persisted to the cache device when a flush request is received.

Initially it defaults to the persistent-on-write mode and it switches to persistent-on-flush mode after the first flush request is received.

## Enable Persistent Write-back Cache¶

To enable the persistent write-back cache, the following Ceph settings need to be enabled.:

rbd persistent cache mode = {cache-mode}
rbd plugins = pwl_cache


Value of {cache-mode} can be rwl or ssd. By default it is disabled

Here are some cache configuration settings:

• rbd_persistent_cache_path A file folder to cache data. This folder must have DAX enabled (see DAX) when using rwl mode to avoid performance degradation.

• rbd_persistent_cache_size The cache size per image.

• rbd_persistent_cache_log_periodic_stats This is a debug option. It is used to emit periodic perf stats to the debug log.

The above configurations can be set per-host, per-pool, per-image etc. Eg, to set per-host, add the overrides to the appropriate section in the host’s ceph.conf file. To set per-pool, per-image, etc, please refer to the rbd config commands.

### Cache Status¶

The persistent write-back cache is enabled when the exclusive lock is acquired, and it is closed when the exclusive lock is released. To check the transient cache status, users may use the command rbd status.

rbd status {pool-name}/{image-name}


The status of the cache is shown, including present, clean, cache size and the position.

For example: