1 ============================
2 A block layer cache (bcache)
3 ============================
4
5 Say you've got a big slow raid 6, and an ssd o
6 nice if you could use them as cache... Hence b
7
8 The bcache wiki can be found at:
9 https://bcache.evilpiepirate.org
10
11 This is the git repository of bcache-tools:
12 https://git.kernel.org/pub/scm/linux/kernel/
13
14 The latest bcache kernel code can be found fro
15 https://git.kernel.org/pub/scm/linux/kernel/
16
17 It's designed around the performance character
18 in erase block sized buckets, and it uses a hy
19 extents (which can be anywhere from a single s
20 designed to avoid random writes at all costs;
21 sequentially, then issues a discard before reu
22
23 Both writethrough and writeback caching are su
24 off, but can be switched on and off arbitraril
25 great lengths to protect your data - it reliab
26 doesn't even have a notion of a clean shutdown
27 writes as completed until they're on stable st
28
29 Writeback caching can use most of the cache fo
30 dirty data to the backing device is always don
31 start to the end of the index.
32
33 Since random IO is what SSDs excel at, there g
34 to caching large sequential IO. Bcache detects
35 it also keeps a rolling average of the IO size
36 average is above the cutoff it will skip all I
37 caching the first 512k after every seek. Backu
38 thus entirely bypass the cache.
39
40 In the event of a data IO error on the flash i
41 from disk or invalidating cache entries. For
42 or dirty data), caching is automatically disab
43 in the cache it first disables writeback cachi
44 to be flushed.
45
46 Getting started:
47 You'll need bcache util from the bcache-tools
48 and backing device must be formatted before us
49
50 bcache make -B /dev/sdb
51 bcache make -C /dev/sdc
52
53 `bcache make` has the ability to format multip
54 you format your backing devices and cache devi
55 have to manually attach::
56
57 bcache make -B /dev/sda /dev/sdb -C /dev/sdc
58
59 If your bcache-tools is not updated to latest
60 unified `bcache` utility, you may use the lega
61 bcache device with same -B and -C parameters.
62
63 bcache-tools now ships udev rules, and bcache
64 immediately. Without udev, you can manually r
65
66 echo /dev/sdb > /sys/fs/bcache/register
67 echo /dev/sdc > /sys/fs/bcache/register
68
69 Registering the backing device makes the bcach
70 now format it and use it as normal. But the fi
71 device, it'll be running in passthrough mode u
72 If you are thinking about using bcache later,
73 slow devices as bcache backing devices without
74 a caching device later.
75 See 'ATTACHING' section below.
76
77 The devices show up as::
78
79 /dev/bcache<N>
80
81 As well as (with udev)::
82
83 /dev/bcache/by-uuid/<uuid>
84 /dev/bcache/by-label/<label>
85
86 To get started::
87
88 mkfs.ext4 /dev/bcache0
89 mount /dev/bcache0 /mnt
90
91 You can control bcache devices through sysfs a
92 You can also control them through /sys/fs//bca
93
94 Cache devices are managed as sets; multiple ca
95 but will allow for mirroring of metadata and d
96 cache set shows up as /sys/fs/bcache/<UUID>
97
98 Attaching
99 ---------
100
101 After your cache device and backing device are
102 must be attached to your cache set to enable c
103 device to a cache set is done thusly, with the
104 /sys/fs/bcache::
105
106 echo <CSET-UUID> > /sys/block/bcache0/bcache
107
108 This only has to be done once. The next time y
109 your bcache devices. If a backing device has d
110 /dev/bcache<N> device won't be created until t
111 important if you have writeback caching turned
112
113 If you're booting up and your cache device is
114 can force run the backing device::
115
116 echo 1 > /sys/block/sdb/bcache/running
117
118 (You need to use /sys/block/sdb (or whatever y
119 /sys/block/bcache0, because bcache0 doesn't ex
120 partition, the bcache directory would be at /s
121
122 The backing device will still use that cache s
123 but all the cached data will be invalidated. I
124 cache, don't expect the filesystem to be recov
125 filesystem corruption, though ext4's fsck does
126
127 Error Handling
128 --------------
129
130 Bcache tries to transparently handle IO errors
131 affecting normal operation; if it sees too man
132 configurable, and defaults to 0) it shuts down
133 the backing devices to passthrough mode.
134
135 - For reads from the cache, if they error we
136 backing device.
137
138 - For writethrough writes, if the write to th
139 invalidating the data at that lba in the ca
140 a write that bypasses the cache)
141
142 - For writeback writes, we currently pass tha
143 filesystem/userspace. This could be improve
144 that skips the cache so we don't have to er
145
146 - When we detach, we first try to flush any d
147 writeback mode). It currently doesn't do an
148 read some of the dirty data, though.
149
150
151 Howto/cookbook
152 --------------
153
154 A) Starting a bcache with a missing caching de
155
156 If registering the backing device doesn't help
157 to force it to run without the cache::
158
159 host:~# echo /dev/sdb1 > /sys/fs/bcach
160 [ 119.844831] bcache: register_bcache
161
162 Next, you try to register your caching device
163 if it's absent, or registration fails for some
164 start your bcache without its cache, like so::
165
166 host:/sys/block/sdb/sdb1/bcache# echo
167
168 Note that this may cause data loss if you were
169
170
171 B) Bcache does not find its cache::
172
173 host:/sys/block/md5/bcache# echo 02265
174 [ 1933.455082] bcache: bch_cached_dev_
175 [ 1933.478179] bcache: __cached_dev_st
176 [ 1933.478179] : cache set not found
177
178 In this case, the caching device was simply no
179 or disappeared and came back, and needs to be
180
181 host:/sys/block/md5/bcache# echo /dev/
182
183
184 C) Corrupt bcache crashes the kernel at device
185
186 This should never happen. If it does happen,
187 Please report it to the bcache development lis
188
189 Be sure to provide as much information that yo
190 output if available so that we may assist.
191
192
193 D) Recovering data without bcache:
194
195 If bcache is not available in the kernel, a fi
196 device is still available at an 8KiB offset. S
197 of the backing device created with --offset 8K
198 --data-offset when you originally formatted bc
199
200 For example::
201
202 losetup -o 8192 /dev/loop0 /dev/your_b
203
204 This should present your unmodified backing de
205
206 If your cache is in writethrough mode, then yo
207 cache device without losing data.
208
209
210 E) Wiping a cache device
211
212 ::
213
214 host:~# wipefs -a /dev/sdh2
215 16 bytes were erased at offset 0x1018
216 they were: c6 85 73 f6 4e 1a 45 ca 82
217
218 After you boot back with bcache enabled, you r
219
220 host:~# bcache make -C /dev/sdh2
221 UUID: 7be7e175-8f4c-
222 Set UUID: 5bc072a8-ab17-
223 version: 0
224 nbuckets: 106874
225 block_size: 1
226 bucket_size: 1024
227 nr_in_set: 1
228 nr_this_dev: 0
229 first_bucket: 1
230 [ 650.511912] bcache: run_cache_set()
231 [ 650.549228] bcache: register_cache(
232
233 start backing device with missing cache::
234
235 host:/sys/block/md5/bcache# echo 1 > r
236
237 attach new cache::
238
239 host:/sys/block/md5/bcache# echo 5bc07
240 [ 865.276616] bcache: bch_cached_dev_
241
242
243 F) Remove or replace a caching device::
244
245 host:/sys/block/sda/sda7/bcache# echo
246 [ 695.872542] bcache: cached_dev_deta
247
248 host:~# wipefs -a /dev/nvme0n1p4
249 wipefs: error: /dev/nvme0n1p4: probing
250 Ooops, it's disabled, but not unregist
251
252 We need to go and unregister it::
253
254 host:/sys/fs/bcache/b7ba27a1-2398-4649
255 lrwxrwxrwx 1 root root 0 Feb 25 18:33
256 host:/sys/fs/bcache/b7ba27a1-2398-4649
257 kernel: [ 917.041908] bcache: cache_s
258
259 Now we can wipe it::
260
261 host:~# wipefs -a /dev/nvme0n1p4
262 /dev/nvme0n1p4: 16 bytes were erased a
263
264
265 G) dm-crypt and bcache
266
267 First setup bcache unencrypted and then instal
268 /dev/bcache<N> This will work faster than if y
269 and caching devices and then install bcache on
270
271
272 H) Stop/free a registered bcache to wipe and/o
273
274 Suppose that you need to free up all bcache re
275 fdisk run and re-register a changed partition
276 if there are any active backing or caching dev
277
278 1) Is it present in /dev/bcache* ? (there are
279
280 If so, it's easy::
281
282 host:/sys/block/bcache0/bcache# echo 1
283
284 2) But if your backing device is gone, this wo
285
286 host:/sys/block/bcache0# cd bcache
287 bash: cd: bcache: No such file or dire
288
289 In this case, you may have to unregister th
290 references this bcache to free it up::
291
292 host:~# dmsetup remove oldds1
293 bcache: bcache_device_free() bcache0 s
294 bcache: cache_set_free() Cache set 5bc
295
296 This causes the backing bcache to be remove
297 then it can be reused. This would be true
298 where bcache is a lower device.
299
300 3) In other cases, you can also look in /sys/f
301
302 host:/sys/fs/bcache# ls -l */{cache?,b
303 lrwxrwxrwx 1 root root 0 Mar 5 09:39
304 lrwxrwxrwx 1 root root 0 Mar 5 09:39
305 lrwxrwxrwx 1 root root 0 Mar 5 09:39
306
307 The device names will show which UUID is re
308 and stop the cache::
309
310 host:/sys/fs/bcache/5bc072a8-ab17-446d
311
312 This will free up bcache references and let
313 other purposes.
314
315
316
317 Troubleshooting performance
318 ---------------------------
319
320 Bcache has a bunch of config options and tunab
321 be reasonable for typical desktop and server w
322 want for getting the best possible numbers whe
323
324 - Backing device alignment
325
326 The default metadata size in bcache is 8k.
327 RAID based, then be sure to align this by a
328 width using `bcache make --data-offset`. If
329 disk array in the future, then multiply a s
330 raid stripe size to get the disk multiples
331
332 For example: If you have a 64k stripe size
333 would provide alignment for many common RAI
334
335 64k * 2*2*2*3*3*5*7 bytes = 161280k
336
337 That space is wasted, but for only 157.5MB
338 volume to the following data-spindle counts
339
340 3,4,5,6,7,8,9,10,12,14,15,18,20,21 ...
341
342 - Bad write performance
343
344 If write performance is not what you expect
345 running in writeback mode, which isn't the
346 maturity, but simply because in writeback m
347 happens to your SSD)::
348
349 # echo writeback > /sys/block/bcache0/
350
351 - Bad performance, or traffic not going to th
352
353 By default, bcache doesn't cache everything
354 because you really want to be caching the r
355 gigabyte file you probably don't want that
356 accessed data out of your cache.
357
358 But if you want to benchmark reads from cac
359 writing an 8 gigabyte test file - so you wa
360
361 # echo 0 > /sys/block/bcache0/bcache/s
362
363 To set it back to the default (4 mb), do::
364
365 # echo 4M > /sys/block/bcache0/bcache/
366
367 - Traffic's still going to the spindle/still
368
369 In the real world, SSDs don't always keep u
370 slower SSDs, many disks being cached by one
371 you want to avoid being bottlenecked by the
372 down.
373
374 To avoid that bcache tracks latency to the
375 throttles traffic if the latency exceeds a
376 cranking down the sequential bypass).
377
378 You can disable this if you need to by sett
379
380 # echo 0 > /sys/fs/bcache/<cache set>/
381 # echo 0 > /sys/fs/bcache/<cache set>/
382
383 The default is 2000 us (2 milliseconds) for
384
385 - Still getting cache misses, of the same dat
386
387 One last issue that sometimes trips people
388 the way cache coherency is handled for cach
389 a cache miss won't be able to insert a key
390 won't be written to the cache.
391
392 In practice this isn't an issue because as
393 cause the btree node to be split, and you n
394 this to not show up enough to be noticeable
395 nodes are huge and index large regions of t
396 benchmarking, if you're trying to warm the
397 and there's no other traffic - that can be
398
399 Solution: warm the cache by doing writes, o
400 a fix for the issue there).
401
402
403 Sysfs - backing device
404 ----------------------
405
406 Available at /sys/block/<bdev>/bcache, /sys/bl
407 (if attached) /sys/fs/bcache/<cset-uuid>/bdev*
408
409 attach
410 Echo the UUID of a cache set to this file to
411
412 cache_mode
413 Can be one of either writethrough, writeback
414
415 clear_stats
416 Writing to this file resets the running tota
417 decaying versions).
418
419 detach
420 Write to this file to detach from a cache se
421 cache, it will be flushed first.
422
423 dirty_data
424 Amount of dirty data for this backing device
425 updated unlike the cache set's version, but
426
427 label
428 Name of underlying device.
429
430 readahead
431 Size of readahead that should be performed.
432 1M, it will round cache miss reads up to tha
433 existing cache entries.
434
435 running
436 1 if bcache is running (i.e. whether the /de
437 it's in passthrough mode or caching).
438
439 sequential_cutoff
440 A sequential IO will bypass the cache once i
441 most recent 128 IOs are tracked so sequentia
442 it isn't all done at once.
443
444 sequential_merge
445 If non zero, bcache keeps a list of the last
446 against all new requests to determine which
447 continuations of previous requests for the p
448 cutoff. This is necessary if the sequential
449 maximum acceptable sequential size for any s
450
451 state
452 The backing device can be in one of four dif
453
454 no cache: Has never been attached to a cache
455
456 clean: Part of a cache set, and there is no
457
458 dirty: Part of a cache set, and there is cac
459
460 inconsistent: The backing device was forcibl
461 dirty data cached but the cache set was unav
462 backing device has likely been corrupted.
463
464 stop
465 Write to this file to shut down the bcache d
466 device.
467
468 writeback_delay
469 When dirty data is written to the cache and
470 any, waits some number of seconds before ini
471 30.
472
473 writeback_percent
474 If nonzero, bcache tries to keep around this
475 throttling background writeback and using a
476 the rate.
477
478 writeback_rate
479 Rate in sectors per second - if writeback_pe
480 writeback is throttled to this rate. Continu
481 also be set by the user.
482
483 writeback_running
484 If off, writeback of dirty data will not tak
485 still be added to the cache until it is most
486 benchmarking. Defaults to on.
487
488 Sysfs - backing device stats
489 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~
490
491 There are directories with these numbers for a
492 versions that decay over the past day, hour an
493 aggregated in the cache set directory as well.
494
495 bypassed
496 Amount of IO (both reads and writes) that ha
497
498 cache_hits, cache_misses, cache_hit_ratio
499 Hits and misses are counted per individual I
500 partial hit is counted as a miss.
501
502 cache_bypass_hits, cache_bypass_misses
503 Hits and misses for IO that is intended to s
504 but broken out here.
505
506 cache_miss_collisions
507 Counts instances where data was going to be
508 cache miss, but raced with a write and data
509 since the synchronization for cache misses w
510
511 Sysfs - cache set
512 ~~~~~~~~~~~~~~~~~
513
514 Available at /sys/fs/bcache/<cset-uuid>
515
516 average_key_size
517 Average data per key in the btree.
518
519 bdev<0..n>
520 Symlink to each of the attached backing devi
521
522 block_size
523 Block size of the cache devices.
524
525 btree_cache_size
526 Amount of memory currently used by the btree
527
528 bucket_size
529 Size of buckets
530
531 cache<0..n>
532 Symlink to each of the cache devices compris
533
534 cache_available_percent
535 Percentage of cache device which doesn't con
536 potentially be used for writeback. This doe
537 for clean cached data; the unused statistic
538 much lower.
539
540 clear_stats
541 Clears the statistics associated with this c
542
543 dirty_data
544 Amount of dirty data is in the cache (update
545
546 flash_vol_create
547 Echoing a size to this file (in human readab
548 provisioned volume backed by the cache set.
549
550 io_error_halflife, io_error_limit
551 These determines how many errors we accept b
552 Each error is decayed by the half life (in #
553 reaches io_error_limit dirty data is written
554
555 journal_delay_ms
556 Journal writes will delay for up to this man
557 flush happens sooner. Defaults to 100.
558
559 root_usage_percent
560 Percentage of the root btree node in use. I
561 will split, increasing the tree depth.
562
563 stop
564 Write to this file to shut down the cache se
565 backing devices have been shut down.
566
567 tree_depth
568 Depth of the btree (A single node btree has
569
570 unregister
571 Detaches all backing devices and closes the
572 present it will disable writeback caching an
573
574 Sysfs - cache set internal
575 ~~~~~~~~~~~~~~~~~~~~~~~~~~
576
577 This directory also exposes timings for a numb
578 separate files for average duration, average f
579 duration: garbage collection, btree read, btre
580
581 active_journal_entries
582 Number of journal entries that are newer tha
583
584 btree_nodes
585 Total nodes in the btree.
586
587 btree_used_percent
588 Average fraction of btree in use.
589
590 bset_tree_stats
591 Statistics about the auxiliary search trees
592
593 btree_cache_max_chain
594 Longest chain in the btree node cache's hash
595
596 cache_read_races
597 Counts instances where while data was being
598 was reused and invalidated - i.e. where the
599 completed. When this occurs the data is rere
600
601 trigger_gc
602 Writing to this file forces garbage collecti
603
604 Sysfs - Cache device
605 ~~~~~~~~~~~~~~~~~~~~
606
607 Available at /sys/block/<cdev>/bcache
608
609 block_size
610 Minimum granularity of writes - should match
611
612 btree_written
613 Sum of all btree writes, in (kilo/mega/giga)
614
615 bucket_size
616 Size of buckets
617
618 cache_replacement_policy
619 One of either lru, fifo or random.
620
621 discard
622 Boolean; if on a discard/TRIM will be issued
623 reused. Defaults to off, since SATA TRIM is
624 slow).
625
626 freelist_percent
627 Size of the freelist as a percentage of nbuc
628 increase the number of buckets kept on the f
629 artificially reduce the size of the cache at
630 purposes (i.e. testing how different size ca
631 since buckets are discarded when they move o
632 the SSD's garbage collection easier by effec
633 space.
634
635 io_errors
636 Number of errors that have occurred, decayed
637
638 metadata_written
639 Sum of all non data writes (btree writes and
640
641 nbuckets
642 Total buckets in this cache
643
644 priority_stats
645 Statistics about how recently data in the ca
646 This can reveal your working set size. Unus
647 the cache that doesn't contain any data. Me
648 metadata overhead. Average is the average p
649 Next is a list of quantiles with the priorit
650
651 written
652 Sum of all data that has been written to the
653 btree_written gives the amount of write infl
Linux® is a registered trademark of Linus Torvalds in the United States and other countries.
TOMOYO® is a registered trademark of NTT DATA CORPORATION.