1 =======================
3 =======================
5 See `Block Device`_ for additional details.
8 =======================
10 .. sidebar:: Kernel Caching
12 The kernel driver for Ceph block devices can use the Linux page cache to
15 The user space implementation of the Ceph block device (i.e., ``librbd``) cannot
16 take advantage of the Linux page cache, so it includes its own in-memory
17 caching, called "RBD caching." RBD caching behaves just like well-behaved hard
18 disk caching. When the OS sends a barrier or a flush request, all dirty data is
19 written to the OSDs. This means that using write-back caching is just as safe as
20 using a well-behaved physical hard disk with a VM that properly sends flushes
21 (i.e. Linux kernel >= 2.6.32). The cache uses a Least Recently Used (LRU)
22 algorithm, and in write-back mode it can coalesce contiguous requests for
25 .. versionadded:: 0.46
27 Ceph supports write-back caching for RBD. To enable it, add ``rbd cache =
28 true`` to the ``[client]`` section of your ``ceph.conf`` file. By default
29 ``librbd`` does not perform any caching. Writes and reads go directly to the
30 storage cluster, and writes return only when the data is on disk on all
31 replicas. With caching enabled, writes return immediately, unless there are more
32 than ``rbd cache max dirty`` unflushed bytes. In this case, the write triggers
33 writeback and blocks until enough bytes are flushed.
35 .. versionadded:: 0.47
37 Ceph supports write-through caching for RBD. You can set the size of
38 the cache, and you can set targets and limits to switch from
39 write-back caching to write through caching. To enable write-through
40 mode, set ``rbd cache max dirty`` to 0. This means writes return only
41 when the data is on disk on all replicas, but reads may come from the
42 cache. The cache is in memory on the client, and each RBD image has
43 its own. Since the cache is local to the client, there's no coherency
44 if there are others accessing the image. Running GFS or OCFS on top of
45 RBD will not work with caching enabled.
47 The ``ceph.conf`` file settings for RBD should be set in the ``[client]``
48 section of your configuration file. The settings include:
53 :Description: Enable caching for RADOS Block Device (RBD).
61 :Description: The RBD cache size in bytes.
67 ``rbd cache max dirty``
69 :Description: The ``dirty`` limit in bytes at which the cache triggers write-back. If ``0``, uses write-through caching.
72 :Constraint: Must be less than ``rbd cache size``.
76 ``rbd cache target dirty``
78 :Description: The ``dirty target`` before the cache begins writing data to the data storage. Does not block writes to the cache.
81 :Constraint: Must be less than ``rbd cache max dirty``.
85 ``rbd cache max dirty age``
87 :Description: The number of seconds dirty data is in the cache before writeback starts.
92 .. versionadded:: 0.60
94 ``rbd cache writethrough until flush``
96 :Description: Start out in write-through mode, and switch to write-back after the first flush request is received. Enabling this is a conservative but safe setting in case VMs running on rbd are too old to send flushes, like the virtio driver in Linux before 2.6.32.
101 .. _Block Device: ../../rbd
105 =======================
107 .. versionadded:: 0.86
109 RBD supports read-ahead/prefetching to optimize small, sequential reads.
110 This should normally be handled by the guest OS in the case of a VM,
111 but boot loaders may not issue efficient reads.
112 Read-ahead is automatically disabled if caching is disabled.
115 ``rbd readahead trigger requests``
117 :Description: Number of sequential read requests necessary to trigger read-ahead.
123 ``rbd readahead max bytes``
125 :Description: Maximum size of a read-ahead request. If zero, read-ahead is disabled.
126 :Type: 64-bit Integer
128 :Default: ``512 KiB``
131 ``rbd readahead disable after bytes``
133 :Description: After this many bytes have been read from an RBD image, read-ahead is disabled for that image until it is closed. This allows the guest OS to take over read-ahead once it is booted. If zero, read-ahead stays enabled.
134 :Type: 64-bit Integer