blob: c0ce64d75bbf7cfe02fa0a99af136f3ae02ba60c [file] [log] [blame]
Mauro Carvalho Chehaba966ac72017-05-14 07:49:15 -03001============================
2A block layer cache (bcache)
3============================
4
Marc MERLINc9b2ffc2016-03-11 23:04:19 -08005Say you've got a big slow raid 6, and an ssd or three. Wouldn't it be
Kent Overstreetcafe5632013-03-23 16:11:31 -07006nice if you could use them as cache... Hence bcache.
7
8Wiki and git repositories are at:
Mauro Carvalho Chehaba966ac72017-05-14 07:49:15 -03009
10 - http://bcache.evilpiepirate.org
11 - http://evilpiepirate.org/git/linux-bcache.git
12 - http://evilpiepirate.org/git/bcache-tools.git
Kent Overstreetcafe5632013-03-23 16:11:31 -070013
14It's designed around the performance characteristics of SSDs - it only allocates
15in erase block sized buckets, and it uses a hybrid btree/log to track cached
Marc MERLINc9b2ffc2016-03-11 23:04:19 -080016extents (which can be anywhere from a single sector to the bucket size). It's
Kent Overstreetcafe5632013-03-23 16:11:31 -070017designed to avoid random writes at all costs; it fills up an erase block
18sequentially, then issues a discard before reusing it.
19
20Both writethrough and writeback caching are supported. Writeback defaults to
21off, but can be switched on and off arbitrarily at runtime. Bcache goes to
22great lengths to protect your data - it reliably handles unclean shutdown. (It
23doesn't even have a notion of a clean shutdown; bcache simply doesn't return
24writes as completed until they're on stable storage).
25
26Writeback caching can use most of the cache for buffering writes - writing
27dirty data to the backing device is always done sequentially, scanning from the
28start to the end of the index.
29
30Since random IO is what SSDs excel at, there generally won't be much benefit
31to caching large sequential IO. Bcache detects sequential IO and skips it;
32it also keeps a rolling average of the IO sizes per task, and as long as the
33average is above the cutoff it will skip all IO from that task - instead of
34caching the first 512k after every seek. Backups and large file copies should
35thus entirely bypass the cache.
36
37In the event of a data IO error on the flash it will try to recover by reading
38from disk or invalidating cache entries. For unrecoverable errors (meta data
39or dirty data), caching is automatically disabled; if dirty data was present
40in the cache it first disables writeback caching and waits for all dirty data
41to be flushed.
42
43Getting started:
44You'll need make-bcache from the bcache-tools repository. Both the cache device
Mauro Carvalho Chehaba966ac72017-05-14 07:49:15 -030045and backing device must be formatted before use::
46
Kent Overstreetcafe5632013-03-23 16:11:31 -070047 make-bcache -B /dev/sdb
48 make-bcache -C /dev/sdc
49
50make-bcache has the ability to format multiple devices at the same time - if
51you format your backing devices and cache device at the same time, you won't
Mauro Carvalho Chehaba966ac72017-05-14 07:49:15 -030052have to manually attach::
53
Kent Overstreetcafe5632013-03-23 16:11:31 -070054 make-bcache -B /dev/sda /dev/sdb -C /dev/sdc
55
Gabriel de Perthuiscecd6282013-06-27 02:12:07 +020056bcache-tools now ships udev rules, and bcache devices are known to the kernel
Mauro Carvalho Chehaba966ac72017-05-14 07:49:15 -030057immediately. Without udev, you can manually register devices like this::
Kent Overstreetcafe5632013-03-23 16:11:31 -070058
59 echo /dev/sdb > /sys/fs/bcache/register
60 echo /dev/sdc > /sys/fs/bcache/register
61
Gabriel de Perthuiscecd6282013-06-27 02:12:07 +020062Registering the backing device makes the bcache device show up in /dev; you can
63now format it and use it as normal. But the first time using a new bcache
64device, it'll be running in passthrough mode until you attach it to a cache.
Marc MERLINc9b2ffc2016-03-11 23:04:19 -080065If you are thinking about using bcache later, it is recommended to setup all your
66slow devices as bcache backing devices without a cache, and you can choose to add
67a caching device later.
68See 'ATTACHING' section below.
Kent Overstreetcafe5632013-03-23 16:11:31 -070069
Mauro Carvalho Chehaba966ac72017-05-14 07:49:15 -030070The devices show up as::
Kent Overstreetcafe5632013-03-23 16:11:31 -070071
Gabriel de Perthuiscecd6282013-06-27 02:12:07 +020072 /dev/bcache<N>
Kent Overstreetcafe5632013-03-23 16:11:31 -070073
Mauro Carvalho Chehaba966ac72017-05-14 07:49:15 -030074As well as (with udev)::
Kent Overstreetcafe5632013-03-23 16:11:31 -070075
Gabriel de Perthuiscecd6282013-06-27 02:12:07 +020076 /dev/bcache/by-uuid/<uuid>
77 /dev/bcache/by-label/<label>
78
Mauro Carvalho Chehaba966ac72017-05-14 07:49:15 -030079To get started::
Kent Overstreetcafe5632013-03-23 16:11:31 -070080
81 mkfs.ext4 /dev/bcache0
82 mount /dev/bcache0 /mnt
83
Gabriel de Perthuiscecd6282013-06-27 02:12:07 +020084You can control bcache devices through sysfs at /sys/block/bcache<N>/bcache .
Marc MERLINc9b2ffc2016-03-11 23:04:19 -080085You can also control them through /sys/fs//bcache/<cset-uuid>/ .
Gabriel de Perthuiscecd6282013-06-27 02:12:07 +020086
Kent Overstreetcafe5632013-03-23 16:11:31 -070087Cache devices are managed as sets; multiple caches per set isn't supported yet
88but will allow for mirroring of metadata and dirty data in the future. Your new
89cache set shows up as /sys/fs/bcache/<UUID>
90
Mauro Carvalho Chehaba966ac72017-05-14 07:49:15 -030091Attaching
Marc MERLINc9b2ffc2016-03-11 23:04:19 -080092---------
Kent Overstreetcafe5632013-03-23 16:11:31 -070093
94After your cache device and backing device are registered, the backing device
95must be attached to your cache set to enable caching. Attaching a backing
96device to a cache set is done thusly, with the UUID of the cache set in
Mauro Carvalho Chehaba966ac72017-05-14 07:49:15 -030097/sys/fs/bcache::
Kent Overstreetcafe5632013-03-23 16:11:31 -070098
Gabriel de Perthuiscecd6282013-06-27 02:12:07 +020099 echo <CSET-UUID> > /sys/block/bcache0/bcache/attach
Kent Overstreetcafe5632013-03-23 16:11:31 -0700100
101This only has to be done once. The next time you reboot, just reregister all
102your bcache devices. If a backing device has data in a cache somewhere, the
Gabriel de Perthuiscecd6282013-06-27 02:12:07 +0200103/dev/bcache<N> device won't be created until the cache shows up - particularly
Kent Overstreetcafe5632013-03-23 16:11:31 -0700104important if you have writeback caching turned on.
105
106If you're booting up and your cache device is gone and never coming back, you
Mauro Carvalho Chehaba966ac72017-05-14 07:49:15 -0300107can force run the backing device::
Kent Overstreetcafe5632013-03-23 16:11:31 -0700108
109 echo 1 > /sys/block/sdb/bcache/running
110
111(You need to use /sys/block/sdb (or whatever your backing device is called), not
112/sys/block/bcache0, because bcache0 doesn't exist yet. If you're using a
113partition, the bcache directory would be at /sys/block/sdb/sdb2/bcache)
114
115The backing device will still use that cache set if it shows up in the future,
116but all the cached data will be invalidated. If there was dirty data in the
117cache, don't expect the filesystem to be recoverable - you will have massive
118filesystem corruption, though ext4's fsck does work miracles.
119
Mauro Carvalho Chehaba966ac72017-05-14 07:49:15 -0300120Error Handling
Marc MERLINc9b2ffc2016-03-11 23:04:19 -0800121--------------
Kent Overstreet7b41b512013-03-27 12:24:17 -0700122
123Bcache tries to transparently handle IO errors to/from the cache device without
124affecting normal operation; if it sees too many errors (the threshold is
125configurable, and defaults to 0) it shuts down the cache device and switches all
126the backing devices to passthrough mode.
127
128 - For reads from the cache, if they error we just retry the read from the
129 backing device.
130
131 - For writethrough writes, if the write to the cache errors we just switch to
132 invalidating the data at that lba in the cache (i.e. the same thing we do for
133 a write that bypasses the cache)
134
135 - For writeback writes, we currently pass that error back up to the
136 filesystem/userspace. This could be improved - we could retry it as a write
137 that skips the cache so we don't have to error the write.
138
139 - When we detach, we first try to flush any dirty data (if we were running in
140 writeback mode). It currently doesn't do anything intelligent if it fails to
141 read some of the dirty data, though.
142
Marc MERLINc9b2ffc2016-03-11 23:04:19 -0800143
Mauro Carvalho Chehaba966ac72017-05-14 07:49:15 -0300144Howto/cookbook
Marc MERLINc9b2ffc2016-03-11 23:04:19 -0800145--------------
146
Eric Wheelerc0b8c9a2016-03-11 23:43:47 -0800147A) Starting a bcache with a missing caching device
Marc MERLINc9b2ffc2016-03-11 23:04:19 -0800148
Eric Wheelerc0b8c9a2016-03-11 23:43:47 -0800149If registering the backing device doesn't help, it's already there, you just need
Mauro Carvalho Chehaba966ac72017-05-14 07:49:15 -0300150to force it to run without the cache::
151
Eric Wheelerc0b8c9a2016-03-11 23:43:47 -0800152 host:~# echo /dev/sdb1 > /sys/fs/bcache/register
153 [ 119.844831] bcache: register_bcache() error opening /dev/sdb1: device already registered
Marc MERLINc9b2ffc2016-03-11 23:04:19 -0800154
Eric Wheelerc0b8c9a2016-03-11 23:43:47 -0800155Next, you try to register your caching device if it's present. However
156if it's absent, or registration fails for some reason, you can still
Mauro Carvalho Chehaba966ac72017-05-14 07:49:15 -0300157start your bcache without its cache, like so::
158
Eric Wheelerc0b8c9a2016-03-11 23:43:47 -0800159 host:/sys/block/sdb/sdb1/bcache# echo 1 > running
160
161Note that this may cause data loss if you were running in writeback mode.
Marc MERLINc9b2ffc2016-03-11 23:04:19 -0800162
163
Mauro Carvalho Chehaba966ac72017-05-14 07:49:15 -0300164B) Bcache does not find its cache::
Marc MERLINc9b2ffc2016-03-11 23:04:19 -0800165
Eric Wheelerc0b8c9a2016-03-11 23:43:47 -0800166 host:/sys/block/md5/bcache# echo 0226553a-37cf-41d5-b3ce-8b1e944543a8 > attach
167 [ 1933.455082] bcache: bch_cached_dev_attach() Couldn't find uuid for md5 in set
168 [ 1933.478179] bcache: __cached_dev_store() Can't attach 0226553a-37cf-41d5-b3ce-8b1e944543a8
169 [ 1933.478179] : cache set not found
Marc MERLINc9b2ffc2016-03-11 23:04:19 -0800170
Eric Wheelerc0b8c9a2016-03-11 23:43:47 -0800171In this case, the caching device was simply not registered at boot
Mauro Carvalho Chehaba966ac72017-05-14 07:49:15 -0300172or disappeared and came back, and needs to be (re-)registered::
173
Eric Wheelerc0b8c9a2016-03-11 23:43:47 -0800174 host:/sys/block/md5/bcache# echo /dev/sdh2 > /sys/fs/bcache/register
Marc MERLINc9b2ffc2016-03-11 23:04:19 -0800175
176
Eric Wheelerc0b8c9a2016-03-11 23:43:47 -0800177C) Corrupt bcache crashes the kernel at device registration time:
Marc MERLINc9b2ffc2016-03-11 23:04:19 -0800178
Eric Wheelerc0b8c9a2016-03-11 23:43:47 -0800179This should never happen. If it does happen, then you have found a bug!
180Please report it to the bcache development list: linux-bcache@vger.kernel.org
Marc MERLINc9b2ffc2016-03-11 23:04:19 -0800181
Eric Wheelerc0b8c9a2016-03-11 23:43:47 -0800182Be sure to provide as much information that you can including kernel dmesg
183output if available so that we may assist.
184
185
186D) Recovering data without bcache:
187
188If bcache is not available in the kernel, a filesystem on the backing
189device is still available at an 8KiB offset. So either via a loopdev
190of the backing device created with --offset 8K, or any value defined by
191--data-offset when you originally formatted bcache with `make-bcache`.
192
Mauro Carvalho Chehaba966ac72017-05-14 07:49:15 -0300193For example::
194
Eric Wheelerc0b8c9a2016-03-11 23:43:47 -0800195 losetup -o 8192 /dev/loop0 /dev/your_bcache_backing_dev
196
197This should present your unmodified backing device data in /dev/loop0
198
199If your cache is in writethrough mode, then you can safely discard the
200cache device without loosing data.
201
202
203E) Wiping a cache device
204
Mauro Carvalho Chehaba966ac72017-05-14 07:49:15 -0300205::
Marc MERLINc9b2ffc2016-03-11 23:04:19 -0800206
Mauro Carvalho Chehaba966ac72017-05-14 07:49:15 -0300207 host:~# wipefs -a /dev/sdh2
208 16 bytes were erased at offset 0x1018 (bcache)
209 they were: c6 85 73 f6 4e 1a 45 ca 82 65 f5 7f 48 ba 6d 81
Marc MERLINc9b2ffc2016-03-11 23:04:19 -0800210
Mauro Carvalho Chehaba966ac72017-05-14 07:49:15 -0300211After you boot back with bcache enabled, you recreate the cache and attach it::
Marc MERLINc9b2ffc2016-03-11 23:04:19 -0800212
Mauro Carvalho Chehaba966ac72017-05-14 07:49:15 -0300213 host:~# make-bcache -C /dev/sdh2
214 UUID: 7be7e175-8f4c-4f99-94b2-9c904d227045
215 Set UUID: 5bc072a8-ab17-446d-9744-e247949913c1
216 version: 0
217 nbuckets: 106874
218 block_size: 1
219 bucket_size: 1024
220 nr_in_set: 1
221 nr_this_dev: 0
222 first_bucket: 1
223 [ 650.511912] bcache: run_cache_set() invalidating existing data
224 [ 650.549228] bcache: register_cache() registered cache device sdh2
225
226start backing device with missing cache::
227
228 host:/sys/block/md5/bcache# echo 1 > running
229
230attach new cache::
231
232 host:/sys/block/md5/bcache# echo 5bc072a8-ab17-446d-9744-e247949913c1 > attach
233 [ 865.276616] bcache: bch_cached_dev_attach() Caching md5 as bcache0 on set 5bc072a8-ab17-446d-9744-e247949913c1
Marc MERLINc9b2ffc2016-03-11 23:04:19 -0800234
235
Mauro Carvalho Chehaba966ac72017-05-14 07:49:15 -0300236F) Remove or replace a caching device::
Marc MERLINc9b2ffc2016-03-11 23:04:19 -0800237
Eric Wheelerc0b8c9a2016-03-11 23:43:47 -0800238 host:/sys/block/sda/sda7/bcache# echo 1 > detach
239 [ 695.872542] bcache: cached_dev_detach_finish() Caching disabled for sda7
Marc MERLINc9b2ffc2016-03-11 23:04:19 -0800240
Eric Wheelerc0b8c9a2016-03-11 23:43:47 -0800241 host:~# wipefs -a /dev/nvme0n1p4
242 wipefs: error: /dev/nvme0n1p4: probing initialization failed: Device or resource busy
243 Ooops, it's disabled, but not unregistered, so it's still protected
Marc MERLINc9b2ffc2016-03-11 23:04:19 -0800244
Mauro Carvalho Chehaba966ac72017-05-14 07:49:15 -0300245We need to go and unregister it::
246
Eric Wheelerc0b8c9a2016-03-11 23:43:47 -0800247 host:/sys/fs/bcache/b7ba27a1-2398-4649-8ae3-0959f57ba128# ls -l cache0
248 lrwxrwxrwx 1 root root 0 Feb 25 18:33 cache0 -> ../../../devices/pci0000:00/0000:00:1d.0/0000:70:00.0/nvme/nvme0/nvme0n1/nvme0n1p4/bcache/
249 host:/sys/fs/bcache/b7ba27a1-2398-4649-8ae3-0959f57ba128# echo 1 > stop
250 kernel: [ 917.041908] bcache: cache_set_free() Cache set b7ba27a1-2398-4649-8ae3-0959f57ba128 unregistered
Marc MERLINc9b2ffc2016-03-11 23:04:19 -0800251
Mauro Carvalho Chehaba966ac72017-05-14 07:49:15 -0300252Now we can wipe it::
253
Eric Wheelerc0b8c9a2016-03-11 23:43:47 -0800254 host:~# wipefs -a /dev/nvme0n1p4
255 /dev/nvme0n1p4: 16 bytes were erased at offset 0x00001018 (bcache): c6 85 73 f6 4e 1a 45 ca 82 65 f5 7f 48 ba 6d 81
Marc MERLINc9b2ffc2016-03-11 23:04:19 -0800256
257
Eric Wheelerc0b8c9a2016-03-11 23:43:47 -0800258G) dm-crypt and bcache
Marc MERLINc9b2ffc2016-03-11 23:04:19 -0800259
Eric Wheelerc0b8c9a2016-03-11 23:43:47 -0800260First setup bcache unencrypted and then install dmcrypt on top of
261/dev/bcache<N> This will work faster than if you dmcrypt both the backing
262and caching devices and then install bcache on top. [benchmarks?]
Marc MERLINc9b2ffc2016-03-11 23:04:19 -0800263
264
Eric Wheelerc0b8c9a2016-03-11 23:43:47 -0800265H) Stop/free a registered bcache to wipe and/or recreate it
266
267Suppose that you need to free up all bcache references so that you can
268fdisk run and re-register a changed partition table, which won't work
269if there are any active backing or caching devices left on it:
Marc MERLINc9b2ffc2016-03-11 23:04:19 -0800270
2711) Is it present in /dev/bcache* ? (there are times where it won't be)
Eric Wheelerc0b8c9a2016-03-11 23:43:47 -0800272
Mauro Carvalho Chehaba966ac72017-05-14 07:49:15 -0300273 If so, it's easy::
274
Eric Wheelerc0b8c9a2016-03-11 23:43:47 -0800275 host:/sys/block/bcache0/bcache# echo 1 > stop
Marc MERLINc9b2ffc2016-03-11 23:04:19 -0800276
Mauro Carvalho Chehaba966ac72017-05-14 07:49:15 -03002772) But if your backing device is gone, this won't work::
278
Eric Wheelerc0b8c9a2016-03-11 23:43:47 -0800279 host:/sys/block/bcache0# cd bcache
280 bash: cd: bcache: No such file or directory
Marc MERLINc9b2ffc2016-03-11 23:04:19 -0800281
Mauro Carvalho Chehaba966ac72017-05-14 07:49:15 -0300282 In this case, you may have to unregister the dmcrypt block device that
283 references this bcache to free it up::
284
Eric Wheelerc0b8c9a2016-03-11 23:43:47 -0800285 host:~# dmsetup remove oldds1
286 bcache: bcache_device_free() bcache0 stopped
287 bcache: cache_set_free() Cache set 5bc072a8-ab17-446d-9744-e247949913c1 unregistered
Marc MERLINc9b2ffc2016-03-11 23:04:19 -0800288
Mauro Carvalho Chehaba966ac72017-05-14 07:49:15 -0300289 This causes the backing bcache to be removed from /sys/fs/bcache and
290 then it can be reused. This would be true of any block device stacking
291 where bcache is a lower device.
Marc MERLINc9b2ffc2016-03-11 23:04:19 -0800292
Mauro Carvalho Chehaba966ac72017-05-14 07:49:15 -03002933) In other cases, you can also look in /sys/fs/bcache/::
Eric Wheelerc0b8c9a2016-03-11 23:43:47 -0800294
Mauro Carvalho Chehaba966ac72017-05-14 07:49:15 -0300295 host:/sys/fs/bcache# ls -l */{cache?,bdev?}
296 lrwxrwxrwx 1 root root 0 Mar 5 09:39 0226553a-37cf-41d5-b3ce-8b1e944543a8/bdev1 -> ../../../devices/virtual/block/dm-1/bcache/
297 lrwxrwxrwx 1 root root 0 Mar 5 09:39 0226553a-37cf-41d5-b3ce-8b1e944543a8/cache0 -> ../../../devices/virtual/block/dm-4/bcache/
298 lrwxrwxrwx 1 root root 0 Mar 5 09:39 5bc072a8-ab17-446d-9744-e247949913c1/cache0 -> ../../../devices/pci0000:00/0000:00:01.0/0000:01:00.0/ata10/host9/target9:0:0/9:0:0:0/block/sdl/sdl2/bcache/
Marc MERLINc9b2ffc2016-03-11 23:04:19 -0800299
Mauro Carvalho Chehaba966ac72017-05-14 07:49:15 -0300300 The device names will show which UUID is relevant, cd in that directory
301 and stop the cache::
302
Eric Wheelerc0b8c9a2016-03-11 23:43:47 -0800303 host:/sys/fs/bcache/5bc072a8-ab17-446d-9744-e247949913c1# echo 1 > stop
304
Mauro Carvalho Chehaba966ac72017-05-14 07:49:15 -0300305 This will free up bcache references and let you reuse the partition for
306 other purposes.
Marc MERLINc9b2ffc2016-03-11 23:04:19 -0800307
308
309
Mauro Carvalho Chehaba966ac72017-05-14 07:49:15 -0300310Troubleshooting performance
Marc MERLINc9b2ffc2016-03-11 23:04:19 -0800311---------------------------
Kent Overstreet7b41b512013-03-27 12:24:17 -0700312
313Bcache has a bunch of config options and tunables. The defaults are intended to
314be reasonable for typical desktop and server workloads, but they're not what you
315want for getting the best possible numbers when benchmarking.
316
Eric Wheelerc0b8c9a2016-03-11 23:43:47 -0800317 - Backing device alignment
318
319 The default metadata size in bcache is 8k. If your backing device is
320 RAID based, then be sure to align this by a multiple of your stride
321 width using `make-bcache --data-offset`. If you intend to expand your
322 disk array in the future, then multiply a series of primes by your
323 raid stripe size to get the disk multiples that you would like.
324
325 For example: If you have a 64k stripe size, then the following offset
Mauro Carvalho Chehaba966ac72017-05-14 07:49:15 -0300326 would provide alignment for many common RAID5 data spindle counts::
327
Eric Wheelerc0b8c9a2016-03-11 23:43:47 -0800328 64k * 2*2*2*3*3*5*7 bytes = 161280k
329
330 That space is wasted, but for only 157.5MB you can grow your RAID 5
Mauro Carvalho Chehaba966ac72017-05-14 07:49:15 -0300331 volume to the following data-spindle counts without re-aligning::
332
Eric Wheelerc0b8c9a2016-03-11 23:43:47 -0800333 3,4,5,6,7,8,9,10,12,14,15,18,20,21 ...
334
Kent Overstreet7b41b512013-03-27 12:24:17 -0700335 - Bad write performance
336
337 If write performance is not what you expected, you probably wanted to be
338 running in writeback mode, which isn't the default (not due to a lack of
339 maturity, but simply because in writeback mode you'll lose data if something
Mauro Carvalho Chehaba966ac72017-05-14 07:49:15 -0300340 happens to your SSD)::
Kent Overstreet7b41b512013-03-27 12:24:17 -0700341
Mauro Carvalho Chehaba966ac72017-05-14 07:49:15 -0300342 # echo writeback > /sys/block/bcache0/bcache/cache_mode
Kent Overstreet7b41b512013-03-27 12:24:17 -0700343
344 - Bad performance, or traffic not going to the SSD that you'd expect
345
346 By default, bcache doesn't cache everything. It tries to skip sequential IO -
347 because you really want to be caching the random IO, and if you copy a 10
348 gigabyte file you probably don't want that pushing 10 gigabytes of randomly
349 accessed data out of your cache.
350
351 But if you want to benchmark reads from cache, and you start out with fio
Mauro Carvalho Chehaba966ac72017-05-14 07:49:15 -0300352 writing an 8 gigabyte test file - so you want to disable that::
Kent Overstreet7b41b512013-03-27 12:24:17 -0700353
Mauro Carvalho Chehaba966ac72017-05-14 07:49:15 -0300354 # echo 0 > /sys/block/bcache0/bcache/sequential_cutoff
Kent Overstreet7b41b512013-03-27 12:24:17 -0700355
Mauro Carvalho Chehaba966ac72017-05-14 07:49:15 -0300356 To set it back to the default (4 mb), do::
Kent Overstreet7b41b512013-03-27 12:24:17 -0700357
Mauro Carvalho Chehaba966ac72017-05-14 07:49:15 -0300358 # echo 4M > /sys/block/bcache0/bcache/sequential_cutoff
Kent Overstreet7b41b512013-03-27 12:24:17 -0700359
360 - Traffic's still going to the spindle/still getting cache misses
361
362 In the real world, SSDs don't always keep up with disks - particularly with
363 slower SSDs, many disks being cached by one SSD, or mostly sequential IO. So
364 you want to avoid being bottlenecked by the SSD and having it slow everything
365 down.
366
367 To avoid that bcache tracks latency to the cache device, and gradually
368 throttles traffic if the latency exceeds a threshold (it does this by
369 cranking down the sequential bypass).
370
Mauro Carvalho Chehaba966ac72017-05-14 07:49:15 -0300371 You can disable this if you need to by setting the thresholds to 0::
Kent Overstreet7b41b512013-03-27 12:24:17 -0700372
Mauro Carvalho Chehaba966ac72017-05-14 07:49:15 -0300373 # echo 0 > /sys/fs/bcache/<cache set>/congested_read_threshold_us
374 # echo 0 > /sys/fs/bcache/<cache set>/congested_write_threshold_us
Kent Overstreet7b41b512013-03-27 12:24:17 -0700375
376 The default is 2000 us (2 milliseconds) for reads, and 20000 for writes.
377
378 - Still getting cache misses, of the same data
379
380 One last issue that sometimes trips people up is actually an old bug, due to
381 the way cache coherency is handled for cache misses. If a btree node is full,
382 a cache miss won't be able to insert a key for the new data and the data
383 won't be written to the cache.
384
385 In practice this isn't an issue because as soon as a write comes along it'll
386 cause the btree node to be split, and you need almost no write traffic for
Masanari Iidabd206b52013-05-20 00:04:35 +0900387 this to not show up enough to be noticeable (especially since bcache's btree
Kent Overstreet7b41b512013-03-27 12:24:17 -0700388 nodes are huge and index large regions of the device). But when you're
389 benchmarking, if you're trying to warm the cache by reading a bunch of data
390 and there's no other traffic - that can be a problem.
391
392 Solution: warm the cache by doing writes, or use the testing branch (there's
393 a fix for the issue there).
394
Marc MERLINc9b2ffc2016-03-11 23:04:19 -0800395
Mauro Carvalho Chehaba966ac72017-05-14 07:49:15 -0300396Sysfs - backing device
Marc MERLINc9b2ffc2016-03-11 23:04:19 -0800397----------------------
Kent Overstreetcafe5632013-03-23 16:11:31 -0700398
Gabriel de Perthuiscecd6282013-06-27 02:12:07 +0200399Available at /sys/block/<bdev>/bcache, /sys/block/bcache*/bcache and
400(if attached) /sys/fs/bcache/<cset-uuid>/bdev*
401
Kent Overstreetcafe5632013-03-23 16:11:31 -0700402attach
403 Echo the UUID of a cache set to this file to enable caching.
404
405cache_mode
406 Can be one of either writethrough, writeback, writearound or none.
407
408clear_stats
409 Writing to this file resets the running total stats (not the day/hour/5 minute
410 decaying versions).
411
412detach
413 Write to this file to detach from a cache set. If there is dirty data in the
414 cache, it will be flushed first.
415
416dirty_data
417 Amount of dirty data for this backing device in the cache. Continuously
418 updated unlike the cache set's version, but may be slightly off.
419
420label
421 Name of underlying device.
422
423readahead
424 Size of readahead that should be performed. Defaults to 0. If set to e.g.
425 1M, it will round cache miss reads up to that size, but without overlapping
426 existing cache entries.
427
428running
429 1 if bcache is running (i.e. whether the /dev/bcache device exists, whether
430 it's in passthrough mode or caching).
431
432sequential_cutoff
Masanari Iidabd206b52013-05-20 00:04:35 +0900433 A sequential IO will bypass the cache once it passes this threshold; the
Kent Overstreetcafe5632013-03-23 16:11:31 -0700434 most recent 128 IOs are tracked so sequential IO can be detected even when
435 it isn't all done at once.
436
437sequential_merge
438 If non zero, bcache keeps a list of the last 128 requests submitted to compare
439 against all new requests to determine which new requests are sequential
440 continuations of previous requests for the purpose of determining sequential
441 cutoff. This is necessary if the sequential cutoff value is greater than the
Eric Wheelerc0b8c9a2016-03-11 23:43:47 -0800442 maximum acceptable sequential size for any single request.
Kent Overstreetcafe5632013-03-23 16:11:31 -0700443
444state
445 The backing device can be in one of four different states:
446
447 no cache: Has never been attached to a cache set.
448
449 clean: Part of a cache set, and there is no cached dirty data.
450
451 dirty: Part of a cache set, and there is cached dirty data.
452
453 inconsistent: The backing device was forcibly run by the user when there was
454 dirty data cached but the cache set was unavailable; whatever data was on the
455 backing device has likely been corrupted.
456
457stop
458 Write to this file to shut down the bcache device and close the backing
459 device.
460
461writeback_delay
462 When dirty data is written to the cache and it previously did not contain
463 any, waits some number of seconds before initiating writeback. Defaults to
464 30.
465
466writeback_percent
467 If nonzero, bcache tries to keep around this percentage of the cache dirty by
468 throttling background writeback and using a PD controller to smoothly adjust
469 the rate.
470
471writeback_rate
472 Rate in sectors per second - if writeback_percent is nonzero, background
473 writeback is throttled to this rate. Continuously adjusted by bcache but may
474 also be set by the user.
475
476writeback_running
477 If off, writeback of dirty data will not take place at all. Dirty data will
478 still be added to the cache until it is mostly full; only meant for
479 benchmarking. Defaults to on.
480
Mauro Carvalho Chehaba966ac72017-05-14 07:49:15 -0300481Sysfs - backing device stats
482~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Kent Overstreetcafe5632013-03-23 16:11:31 -0700483
484There are directories with these numbers for a running total, as well as
485versions that decay over the past day, hour and 5 minutes; they're also
486aggregated in the cache set directory as well.
487
488bypassed
489 Amount of IO (both reads and writes) that has bypassed the cache
490
Mauro Carvalho Chehaba966ac72017-05-14 07:49:15 -0300491cache_hits, cache_misses, cache_hit_ratio
Kent Overstreetcafe5632013-03-23 16:11:31 -0700492 Hits and misses are counted per individual IO as bcache sees them; a
493 partial hit is counted as a miss.
494
Mauro Carvalho Chehaba966ac72017-05-14 07:49:15 -0300495cache_bypass_hits, cache_bypass_misses
Kent Overstreetcafe5632013-03-23 16:11:31 -0700496 Hits and misses for IO that is intended to skip the cache are still counted,
497 but broken out here.
498
499cache_miss_collisions
500 Counts instances where data was going to be inserted into the cache from a
501 cache miss, but raced with a write and data was already present (usually 0
502 since the synchronization for cache misses was rewritten)
503
504cache_readaheads
Masanari Iidabd206b52013-05-20 00:04:35 +0900505 Count of times readahead occurred.
Kent Overstreetcafe5632013-03-23 16:11:31 -0700506
Mauro Carvalho Chehaba966ac72017-05-14 07:49:15 -0300507Sysfs - cache set
508~~~~~~~~~~~~~~~~~
Kent Overstreetcafe5632013-03-23 16:11:31 -0700509
Gabriel de Perthuiscecd6282013-06-27 02:12:07 +0200510Available at /sys/fs/bcache/<cset-uuid>
511
Kent Overstreetcafe5632013-03-23 16:11:31 -0700512average_key_size
513 Average data per key in the btree.
514
515bdev<0..n>
516 Symlink to each of the attached backing devices.
517
518block_size
519 Block size of the cache devices.
520
521btree_cache_size
522 Amount of memory currently used by the btree cache
523
524bucket_size
525 Size of buckets
526
527cache<0..n>
Eric Wheelerc0b8c9a2016-03-11 23:43:47 -0800528 Symlink to each of the cache devices comprising this cache set.
Kent Overstreetcafe5632013-03-23 16:11:31 -0700529
530cache_available_percent
Gabrielfe0a7972013-04-24 19:51:02 +0200531 Percentage of cache device which doesn't contain dirty data, and could
532 potentially be used for writeback. This doesn't mean this space isn't used
533 for clean cached data; the unused statistic (in priority_stats) is typically
534 much lower.
Kent Overstreetcafe5632013-03-23 16:11:31 -0700535
536clear_stats
537 Clears the statistics associated with this cache
538
539dirty_data
540 Amount of dirty data is in the cache (updated when garbage collection runs).
541
542flash_vol_create
543 Echoing a size to this file (in human readable units, k/M/G) creates a thinly
544 provisioned volume backed by the cache set.
545
Mauro Carvalho Chehaba966ac72017-05-14 07:49:15 -0300546io_error_halflife, io_error_limit
Kent Overstreetcafe5632013-03-23 16:11:31 -0700547 These determines how many errors we accept before disabling the cache.
548 Each error is decayed by the half life (in # ios). If the decaying count
549 reaches io_error_limit dirty data is written out and the cache is disabled.
550
551journal_delay_ms
552 Journal writes will delay for up to this many milliseconds, unless a cache
553 flush happens sooner. Defaults to 100.
554
555root_usage_percent
556 Percentage of the root btree node in use. If this gets too high the node
557 will split, increasing the tree depth.
558
559stop
560 Write to this file to shut down the cache set - waits until all attached
561 backing devices have been shut down.
562
563tree_depth
564 Depth of the btree (A single node btree has depth 0).
565
566unregister
567 Detaches all backing devices and closes the cache devices; if dirty data is
568 present it will disable writeback caching and wait for it to be flushed.
569
Mauro Carvalho Chehaba966ac72017-05-14 07:49:15 -0300570Sysfs - cache set internal
571~~~~~~~~~~~~~~~~~~~~~~~~~~
Kent Overstreetcafe5632013-03-23 16:11:31 -0700572
573This directory also exposes timings for a number of internal operations, with
Masanari Iidabd206b52013-05-20 00:04:35 +0900574separate files for average duration, average frequency, last occurrence and max
Kent Overstreetcafe5632013-03-23 16:11:31 -0700575duration: garbage collection, btree read, btree node sorts and btree splits.
576
577active_journal_entries
578 Number of journal entries that are newer than the index.
579
580btree_nodes
581 Total nodes in the btree.
582
583btree_used_percent
584 Average fraction of btree in use.
585
586bset_tree_stats
587 Statistics about the auxiliary search trees
588
589btree_cache_max_chain
590 Longest chain in the btree node cache's hash table
591
592cache_read_races
593 Counts instances where while data was being read from the cache, the bucket
594 was reused and invalidated - i.e. where the pointer was stale after the read
595 completed. When this occurs the data is reread from the backing device.
596
597trigger_gc
598 Writing to this file forces garbage collection to run.
599
Mauro Carvalho Chehaba966ac72017-05-14 07:49:15 -0300600Sysfs - Cache device
601~~~~~~~~~~~~~~~~~~~~
Kent Overstreetcafe5632013-03-23 16:11:31 -0700602
Gabriel de Perthuiscecd6282013-06-27 02:12:07 +0200603Available at /sys/block/<cdev>/bcache
604
Kent Overstreetcafe5632013-03-23 16:11:31 -0700605block_size
606 Minimum granularity of writes - should match hardware sector size.
607
608btree_written
609 Sum of all btree writes, in (kilo/mega/giga) bytes
610
611bucket_size
612 Size of buckets
613
614cache_replacement_policy
615 One of either lru, fifo or random.
616
617discard
618 Boolean; if on a discard/TRIM will be issued to each bucket before it is
619 reused. Defaults to off, since SATA TRIM is an unqueued command (and thus
620 slow).
621
622freelist_percent
623 Size of the freelist as a percentage of nbuckets. Can be written to to
624 increase the number of buckets kept on the freelist, which lets you
625 artificially reduce the size of the cache at runtime. Mostly for testing
626 purposes (i.e. testing how different size caches affect your hit rate), but
627 since buckets are discarded when they move on to the freelist will also make
628 the SSD's garbage collection easier by effectively giving it more reserved
629 space.
630
631io_errors
Masanari Iidabd206b52013-05-20 00:04:35 +0900632 Number of errors that have occurred, decayed by io_error_halflife.
Kent Overstreetcafe5632013-03-23 16:11:31 -0700633
634metadata_written
635 Sum of all non data writes (btree writes and all other metadata).
636
637nbuckets
638 Total buckets in this cache
639
640priority_stats
Gabrielfe0a7972013-04-24 19:51:02 +0200641 Statistics about how recently data in the cache has been accessed.
642 This can reveal your working set size. Unused is the percentage of
643 the cache that doesn't contain any data. Metadata is bcache's
644 metadata overhead. Average is the average priority of cache buckets.
645 Next is a list of quantiles with the priority threshold of each.
Kent Overstreetcafe5632013-03-23 16:11:31 -0700646
647written
648 Sum of all data that has been written to the cache; comparison with
649 btree_written gives the amount of write inflation in bcache.