654 lines · plain
1============================2A block layer cache (bcache)3============================4 5Say you've got a big slow raid 6, and an ssd or three. Wouldn't it be6nice if you could use them as cache... Hence bcache.7 8The bcache wiki can be found at:9 https://bcache.evilpiepirate.org10 11This is the git repository of bcache-tools:12 https://git.kernel.org/pub/scm/linux/kernel/git/colyli/bcache-tools.git/13 14The latest bcache kernel code can be found from mainline Linux kernel:15 https://git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux.git/16 17It's designed around the performance characteristics of SSDs - it only allocates18in erase block sized buckets, and it uses a hybrid btree/log to track cached19extents (which can be anywhere from a single sector to the bucket size). It's20designed to avoid random writes at all costs; it fills up an erase block21sequentially, then issues a discard before reusing it.22 23Both writethrough and writeback caching are supported. Writeback defaults to24off, but can be switched on and off arbitrarily at runtime. Bcache goes to25great lengths to protect your data - it reliably handles unclean shutdown. (It26doesn't even have a notion of a clean shutdown; bcache simply doesn't return27writes as completed until they're on stable storage).28 29Writeback caching can use most of the cache for buffering writes - writing30dirty data to the backing device is always done sequentially, scanning from the31start to the end of the index.32 33Since random IO is what SSDs excel at, there generally won't be much benefit34to caching large sequential IO. Bcache detects sequential IO and skips it;35it also keeps a rolling average of the IO sizes per task, and as long as the36average is above the cutoff it will skip all IO from that task - instead of37caching the first 512k after every seek. Backups and large file copies should38thus entirely bypass the cache.39 40In the event of a data IO error on the flash it will try to recover by reading41from disk or invalidating cache entries. For unrecoverable errors (meta data42or dirty data), caching is automatically disabled; if dirty data was present43in the cache it first disables writeback caching and waits for all dirty data44to be flushed.45 46Getting started:47You'll need bcache util from the bcache-tools repository. Both the cache device48and backing device must be formatted before use::49 50 bcache make -B /dev/sdb51 bcache make -C /dev/sdc52 53`bcache make` has the ability to format multiple devices at the same time - if54you format your backing devices and cache device at the same time, you won't55have to manually attach::56 57 bcache make -B /dev/sda /dev/sdb -C /dev/sdc58 59If your bcache-tools is not updated to latest version and does not have the60unified `bcache` utility, you may use the legacy `make-bcache` utility to format61bcache device with same -B and -C parameters.62 63bcache-tools now ships udev rules, and bcache devices are known to the kernel64immediately. Without udev, you can manually register devices like this::65 66 echo /dev/sdb > /sys/fs/bcache/register67 echo /dev/sdc > /sys/fs/bcache/register68 69Registering the backing device makes the bcache device show up in /dev; you can70now format it and use it as normal. But the first time using a new bcache71device, it'll be running in passthrough mode until you attach it to a cache.72If you are thinking about using bcache later, it is recommended to setup all your73slow devices as bcache backing devices without a cache, and you can choose to add74a caching device later.75See 'ATTACHING' section below.76 77The devices show up as::78 79 /dev/bcache<N>80 81As well as (with udev)::82 83 /dev/bcache/by-uuid/<uuid>84 /dev/bcache/by-label/<label>85 86To get started::87 88 mkfs.ext4 /dev/bcache089 mount /dev/bcache0 /mnt90 91You can control bcache devices through sysfs at /sys/block/bcache<N>/bcache .92You can also control them through /sys/fs//bcache/<cset-uuid>/ .93 94Cache devices are managed as sets; multiple caches per set isn't supported yet95but will allow for mirroring of metadata and dirty data in the future. Your new96cache set shows up as /sys/fs/bcache/<UUID>97 98Attaching99---------100 101After your cache device and backing device are registered, the backing device102must be attached to your cache set to enable caching. Attaching a backing103device to a cache set is done thusly, with the UUID of the cache set in104/sys/fs/bcache::105 106 echo <CSET-UUID> > /sys/block/bcache0/bcache/attach107 108This only has to be done once. The next time you reboot, just reregister all109your bcache devices. If a backing device has data in a cache somewhere, the110/dev/bcache<N> device won't be created until the cache shows up - particularly111important if you have writeback caching turned on.112 113If you're booting up and your cache device is gone and never coming back, you114can force run the backing device::115 116 echo 1 > /sys/block/sdb/bcache/running117 118(You need to use /sys/block/sdb (or whatever your backing device is called), not119/sys/block/bcache0, because bcache0 doesn't exist yet. If you're using a120partition, the bcache directory would be at /sys/block/sdb/sdb2/bcache)121 122The backing device will still use that cache set if it shows up in the future,123but all the cached data will be invalidated. If there was dirty data in the124cache, don't expect the filesystem to be recoverable - you will have massive125filesystem corruption, though ext4's fsck does work miracles.126 127Error Handling128--------------129 130Bcache tries to transparently handle IO errors to/from the cache device without131affecting normal operation; if it sees too many errors (the threshold is132configurable, and defaults to 0) it shuts down the cache device and switches all133the backing devices to passthrough mode.134 135 - For reads from the cache, if they error we just retry the read from the136 backing device.137 138 - For writethrough writes, if the write to the cache errors we just switch to139 invalidating the data at that lba in the cache (i.e. the same thing we do for140 a write that bypasses the cache)141 142 - For writeback writes, we currently pass that error back up to the143 filesystem/userspace. This could be improved - we could retry it as a write144 that skips the cache so we don't have to error the write.145 146 - When we detach, we first try to flush any dirty data (if we were running in147 writeback mode). It currently doesn't do anything intelligent if it fails to148 read some of the dirty data, though.149 150 151Howto/cookbook152--------------153 154A) Starting a bcache with a missing caching device155 156If registering the backing device doesn't help, it's already there, you just need157to force it to run without the cache::158 159 host:~# echo /dev/sdb1 > /sys/fs/bcache/register160 [ 119.844831] bcache: register_bcache() error opening /dev/sdb1: device already registered161 162Next, you try to register your caching device if it's present. However163if it's absent, or registration fails for some reason, you can still164start your bcache without its cache, like so::165 166 host:/sys/block/sdb/sdb1/bcache# echo 1 > running167 168Note that this may cause data loss if you were running in writeback mode.169 170 171B) Bcache does not find its cache::172 173 host:/sys/block/md5/bcache# echo 0226553a-37cf-41d5-b3ce-8b1e944543a8 > attach174 [ 1933.455082] bcache: bch_cached_dev_attach() Couldn't find uuid for md5 in set175 [ 1933.478179] bcache: __cached_dev_store() Can't attach 0226553a-37cf-41d5-b3ce-8b1e944543a8176 [ 1933.478179] : cache set not found177 178In this case, the caching device was simply not registered at boot179or disappeared and came back, and needs to be (re-)registered::180 181 host:/sys/block/md5/bcache# echo /dev/sdh2 > /sys/fs/bcache/register182 183 184C) Corrupt bcache crashes the kernel at device registration time:185 186This should never happen. If it does happen, then you have found a bug!187Please report it to the bcache development list: linux-bcache@vger.kernel.org188 189Be sure to provide as much information that you can including kernel dmesg190output if available so that we may assist.191 192 193D) Recovering data without bcache:194 195If bcache is not available in the kernel, a filesystem on the backing196device is still available at an 8KiB offset. So either via a loopdev197of the backing device created with --offset 8K, or any value defined by198--data-offset when you originally formatted bcache with `bcache make`.199 200For example::201 202 losetup -o 8192 /dev/loop0 /dev/your_bcache_backing_dev203 204This should present your unmodified backing device data in /dev/loop0205 206If your cache is in writethrough mode, then you can safely discard the207cache device without losing data.208 209 210E) Wiping a cache device211 212::213 214 host:~# wipefs -a /dev/sdh2215 16 bytes were erased at offset 0x1018 (bcache)216 they were: c6 85 73 f6 4e 1a 45 ca 82 65 f5 7f 48 ba 6d 81217 218After you boot back with bcache enabled, you recreate the cache and attach it::219 220 host:~# bcache make -C /dev/sdh2221 UUID: 7be7e175-8f4c-4f99-94b2-9c904d227045222 Set UUID: 5bc072a8-ab17-446d-9744-e247949913c1223 version: 0224 nbuckets: 106874225 block_size: 1226 bucket_size: 1024227 nr_in_set: 1228 nr_this_dev: 0229 first_bucket: 1230 [ 650.511912] bcache: run_cache_set() invalidating existing data231 [ 650.549228] bcache: register_cache() registered cache device sdh2232 233start backing device with missing cache::234 235 host:/sys/block/md5/bcache# echo 1 > running236 237attach new cache::238 239 host:/sys/block/md5/bcache# echo 5bc072a8-ab17-446d-9744-e247949913c1 > attach240 [ 865.276616] bcache: bch_cached_dev_attach() Caching md5 as bcache0 on set 5bc072a8-ab17-446d-9744-e247949913c1241 242 243F) Remove or replace a caching device::244 245 host:/sys/block/sda/sda7/bcache# echo 1 > detach246 [ 695.872542] bcache: cached_dev_detach_finish() Caching disabled for sda7247 248 host:~# wipefs -a /dev/nvme0n1p4249 wipefs: error: /dev/nvme0n1p4: probing initialization failed: Device or resource busy250 Ooops, it's disabled, but not unregistered, so it's still protected251 252We need to go and unregister it::253 254 host:/sys/fs/bcache/b7ba27a1-2398-4649-8ae3-0959f57ba128# ls -l cache0255 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/256 host:/sys/fs/bcache/b7ba27a1-2398-4649-8ae3-0959f57ba128# echo 1 > stop257 kernel: [ 917.041908] bcache: cache_set_free() Cache set b7ba27a1-2398-4649-8ae3-0959f57ba128 unregistered258 259Now we can wipe it::260 261 host:~# wipefs -a /dev/nvme0n1p4262 /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 81263 264 265G) dm-crypt and bcache266 267First setup bcache unencrypted and then install dmcrypt on top of268/dev/bcache<N> This will work faster than if you dmcrypt both the backing269and caching devices and then install bcache on top. [benchmarks?]270 271 272H) Stop/free a registered bcache to wipe and/or recreate it273 274Suppose that you need to free up all bcache references so that you can275fdisk run and re-register a changed partition table, which won't work276if there are any active backing or caching devices left on it:277 2781) Is it present in /dev/bcache* ? (there are times where it won't be)279 280 If so, it's easy::281 282 host:/sys/block/bcache0/bcache# echo 1 > stop283 2842) But if your backing device is gone, this won't work::285 286 host:/sys/block/bcache0# cd bcache287 bash: cd: bcache: No such file or directory288 289 In this case, you may have to unregister the dmcrypt block device that290 references this bcache to free it up::291 292 host:~# dmsetup remove oldds1293 bcache: bcache_device_free() bcache0 stopped294 bcache: cache_set_free() Cache set 5bc072a8-ab17-446d-9744-e247949913c1 unregistered295 296 This causes the backing bcache to be removed from /sys/fs/bcache and297 then it can be reused. This would be true of any block device stacking298 where bcache is a lower device.299 3003) In other cases, you can also look in /sys/fs/bcache/::301 302 host:/sys/fs/bcache# ls -l */{cache?,bdev?}303 lrwxrwxrwx 1 root root 0 Mar 5 09:39 0226553a-37cf-41d5-b3ce-8b1e944543a8/bdev1 -> ../../../devices/virtual/block/dm-1/bcache/304 lrwxrwxrwx 1 root root 0 Mar 5 09:39 0226553a-37cf-41d5-b3ce-8b1e944543a8/cache0 -> ../../../devices/virtual/block/dm-4/bcache/305 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/306 307 The device names will show which UUID is relevant, cd in that directory308 and stop the cache::309 310 host:/sys/fs/bcache/5bc072a8-ab17-446d-9744-e247949913c1# echo 1 > stop311 312 This will free up bcache references and let you reuse the partition for313 other purposes.314 315 316 317Troubleshooting performance318---------------------------319 320Bcache has a bunch of config options and tunables. The defaults are intended to321be reasonable for typical desktop and server workloads, but they're not what you322want for getting the best possible numbers when benchmarking.323 324 - Backing device alignment325 326 The default metadata size in bcache is 8k. If your backing device is327 RAID based, then be sure to align this by a multiple of your stride328 width using `bcache make --data-offset`. If you intend to expand your329 disk array in the future, then multiply a series of primes by your330 raid stripe size to get the disk multiples that you would like.331 332 For example: If you have a 64k stripe size, then the following offset333 would provide alignment for many common RAID5 data spindle counts::334 335 64k * 2*2*2*3*3*5*7 bytes = 161280k336 337 That space is wasted, but for only 157.5MB you can grow your RAID 5338 volume to the following data-spindle counts without re-aligning::339 340 3,4,5,6,7,8,9,10,12,14,15,18,20,21 ...341 342 - Bad write performance343 344 If write performance is not what you expected, you probably wanted to be345 running in writeback mode, which isn't the default (not due to a lack of346 maturity, but simply because in writeback mode you'll lose data if something347 happens to your SSD)::348 349 # echo writeback > /sys/block/bcache0/bcache/cache_mode350 351 - Bad performance, or traffic not going to the SSD that you'd expect352 353 By default, bcache doesn't cache everything. It tries to skip sequential IO -354 because you really want to be caching the random IO, and if you copy a 10355 gigabyte file you probably don't want that pushing 10 gigabytes of randomly356 accessed data out of your cache.357 358 But if you want to benchmark reads from cache, and you start out with fio359 writing an 8 gigabyte test file - so you want to disable that::360 361 # echo 0 > /sys/block/bcache0/bcache/sequential_cutoff362 363 To set it back to the default (4 mb), do::364 365 # echo 4M > /sys/block/bcache0/bcache/sequential_cutoff366 367 - Traffic's still going to the spindle/still getting cache misses368 369 In the real world, SSDs don't always keep up with disks - particularly with370 slower SSDs, many disks being cached by one SSD, or mostly sequential IO. So371 you want to avoid being bottlenecked by the SSD and having it slow everything372 down.373 374 To avoid that bcache tracks latency to the cache device, and gradually375 throttles traffic if the latency exceeds a threshold (it does this by376 cranking down the sequential bypass).377 378 You can disable this if you need to by setting the thresholds to 0::379 380 # echo 0 > /sys/fs/bcache/<cache set>/congested_read_threshold_us381 # echo 0 > /sys/fs/bcache/<cache set>/congested_write_threshold_us382 383 The default is 2000 us (2 milliseconds) for reads, and 20000 for writes.384 385 - Still getting cache misses, of the same data386 387 One last issue that sometimes trips people up is actually an old bug, due to388 the way cache coherency is handled for cache misses. If a btree node is full,389 a cache miss won't be able to insert a key for the new data and the data390 won't be written to the cache.391 392 In practice this isn't an issue because as soon as a write comes along it'll393 cause the btree node to be split, and you need almost no write traffic for394 this to not show up enough to be noticeable (especially since bcache's btree395 nodes are huge and index large regions of the device). But when you're396 benchmarking, if you're trying to warm the cache by reading a bunch of data397 and there's no other traffic - that can be a problem.398 399 Solution: warm the cache by doing writes, or use the testing branch (there's400 a fix for the issue there).401 402 403Sysfs - backing device404----------------------405 406Available at /sys/block/<bdev>/bcache, /sys/block/bcache*/bcache and407(if attached) /sys/fs/bcache/<cset-uuid>/bdev*408 409attach410 Echo the UUID of a cache set to this file to enable caching.411 412cache_mode413 Can be one of either writethrough, writeback, writearound or none.414 415clear_stats416 Writing to this file resets the running total stats (not the day/hour/5 minute417 decaying versions).418 419detach420 Write to this file to detach from a cache set. If there is dirty data in the421 cache, it will be flushed first.422 423dirty_data424 Amount of dirty data for this backing device in the cache. Continuously425 updated unlike the cache set's version, but may be slightly off.426 427label428 Name of underlying device.429 430readahead431 Size of readahead that should be performed. Defaults to 0. If set to e.g.432 1M, it will round cache miss reads up to that size, but without overlapping433 existing cache entries.434 435running436 1 if bcache is running (i.e. whether the /dev/bcache device exists, whether437 it's in passthrough mode or caching).438 439sequential_cutoff440 A sequential IO will bypass the cache once it passes this threshold; the441 most recent 128 IOs are tracked so sequential IO can be detected even when442 it isn't all done at once.443 444sequential_merge445 If non zero, bcache keeps a list of the last 128 requests submitted to compare446 against all new requests to determine which new requests are sequential447 continuations of previous requests for the purpose of determining sequential448 cutoff. This is necessary if the sequential cutoff value is greater than the449 maximum acceptable sequential size for any single request.450 451state452 The backing device can be in one of four different states:453 454 no cache: Has never been attached to a cache set.455 456 clean: Part of a cache set, and there is no cached dirty data.457 458 dirty: Part of a cache set, and there is cached dirty data.459 460 inconsistent: The backing device was forcibly run by the user when there was461 dirty data cached but the cache set was unavailable; whatever data was on the462 backing device has likely been corrupted.463 464stop465 Write to this file to shut down the bcache device and close the backing466 device.467 468writeback_delay469 When dirty data is written to the cache and it previously did not contain470 any, waits some number of seconds before initiating writeback. Defaults to471 30.472 473writeback_percent474 If nonzero, bcache tries to keep around this percentage of the cache dirty by475 throttling background writeback and using a PD controller to smoothly adjust476 the rate.477 478writeback_rate479 Rate in sectors per second - if writeback_percent is nonzero, background480 writeback is throttled to this rate. Continuously adjusted by bcache but may481 also be set by the user.482 483writeback_running484 If off, writeback of dirty data will not take place at all. Dirty data will485 still be added to the cache until it is mostly full; only meant for486 benchmarking. Defaults to on.487 488Sysfs - backing device stats489~~~~~~~~~~~~~~~~~~~~~~~~~~~~490 491There are directories with these numbers for a running total, as well as492versions that decay over the past day, hour and 5 minutes; they're also493aggregated in the cache set directory as well.494 495bypassed496 Amount of IO (both reads and writes) that has bypassed the cache497 498cache_hits, cache_misses, cache_hit_ratio499 Hits and misses are counted per individual IO as bcache sees them; a500 partial hit is counted as a miss.501 502cache_bypass_hits, cache_bypass_misses503 Hits and misses for IO that is intended to skip the cache are still counted,504 but broken out here.505 506cache_miss_collisions507 Counts instances where data was going to be inserted into the cache from a508 cache miss, but raced with a write and data was already present (usually 0509 since the synchronization for cache misses was rewritten)510 511Sysfs - cache set512~~~~~~~~~~~~~~~~~513 514Available at /sys/fs/bcache/<cset-uuid>515 516average_key_size517 Average data per key in the btree.518 519bdev<0..n>520 Symlink to each of the attached backing devices.521 522block_size523 Block size of the cache devices.524 525btree_cache_size526 Amount of memory currently used by the btree cache527 528bucket_size529 Size of buckets530 531cache<0..n>532 Symlink to each of the cache devices comprising this cache set.533 534cache_available_percent535 Percentage of cache device which doesn't contain dirty data, and could536 potentially be used for writeback. This doesn't mean this space isn't used537 for clean cached data; the unused statistic (in priority_stats) is typically538 much lower.539 540clear_stats541 Clears the statistics associated with this cache542 543dirty_data544 Amount of dirty data is in the cache (updated when garbage collection runs).545 546flash_vol_create547 Echoing a size to this file (in human readable units, k/M/G) creates a thinly548 provisioned volume backed by the cache set.549 550io_error_halflife, io_error_limit551 These determines how many errors we accept before disabling the cache.552 Each error is decayed by the half life (in # ios). If the decaying count553 reaches io_error_limit dirty data is written out and the cache is disabled.554 555journal_delay_ms556 Journal writes will delay for up to this many milliseconds, unless a cache557 flush happens sooner. Defaults to 100.558 559root_usage_percent560 Percentage of the root btree node in use. If this gets too high the node561 will split, increasing the tree depth.562 563stop564 Write to this file to shut down the cache set - waits until all attached565 backing devices have been shut down.566 567tree_depth568 Depth of the btree (A single node btree has depth 0).569 570unregister571 Detaches all backing devices and closes the cache devices; if dirty data is572 present it will disable writeback caching and wait for it to be flushed.573 574Sysfs - cache set internal575~~~~~~~~~~~~~~~~~~~~~~~~~~576 577This directory also exposes timings for a number of internal operations, with578separate files for average duration, average frequency, last occurrence and max579duration: garbage collection, btree read, btree node sorts and btree splits.580 581active_journal_entries582 Number of journal entries that are newer than the index.583 584btree_nodes585 Total nodes in the btree.586 587btree_used_percent588 Average fraction of btree in use.589 590bset_tree_stats591 Statistics about the auxiliary search trees592 593btree_cache_max_chain594 Longest chain in the btree node cache's hash table595 596cache_read_races597 Counts instances where while data was being read from the cache, the bucket598 was reused and invalidated - i.e. where the pointer was stale after the read599 completed. When this occurs the data is reread from the backing device.600 601trigger_gc602 Writing to this file forces garbage collection to run.603 604Sysfs - Cache device605~~~~~~~~~~~~~~~~~~~~606 607Available at /sys/block/<cdev>/bcache608 609block_size610 Minimum granularity of writes - should match hardware sector size.611 612btree_written613 Sum of all btree writes, in (kilo/mega/giga) bytes614 615bucket_size616 Size of buckets617 618cache_replacement_policy619 One of either lru, fifo or random.620 621discard622 Boolean; if on a discard/TRIM will be issued to each bucket before it is623 reused. Defaults to off, since SATA TRIM is an unqueued command (and thus624 slow).625 626freelist_percent627 Size of the freelist as a percentage of nbuckets. Can be written to to628 increase the number of buckets kept on the freelist, which lets you629 artificially reduce the size of the cache at runtime. Mostly for testing630 purposes (i.e. testing how different size caches affect your hit rate), but631 since buckets are discarded when they move on to the freelist will also make632 the SSD's garbage collection easier by effectively giving it more reserved633 space.634 635io_errors636 Number of errors that have occurred, decayed by io_error_halflife.637 638metadata_written639 Sum of all non data writes (btree writes and all other metadata).640 641nbuckets642 Total buckets in this cache643 644priority_stats645 Statistics about how recently data in the cache has been accessed.646 This can reveal your working set size. Unused is the percentage of647 the cache that doesn't contain any data. Metadata is bcache's648 metadata overhead. Average is the average priority of cache buckets.649 Next is a list of quantiles with the priority threshold of each.650 651written652 Sum of all data that has been written to the cache; comparison with653 btree_written gives the amount of write inflation in bcache.654