bcache: documentation formatting, edited for clarity, stripe alignment notes

HOWTO/COOKBOOK

--------------

A) Your bcache doesn't start.

   Starting and starting a bcache with a missing caching device

A) Starting a bcache with a missing caching device

Registering the backing device doesn't help, it's already there, you just need

If registering the backing device doesn't help, it's already there, you just need

to force it to run without the cache:

	host:~# echo /dev/sdb1 > /sys/fs/bcache/register

	[  119.844831] bcache: register_bcache() error opening /dev/sdb1: device already registered

Next, you try to register your caching device if it's present. However if it's

absent, or registration fails for some reason, you can still start your bcache

without its cache, like so:

Next, you try to register your caching device if it's present. However

if it's absent, or registration fails for some reason, you can still

start your bcache without its cache, like so:

	host:/sys/block/sdb/sdb1/bcache# echo 1 > running

Note that this may cause data loss if you were running in writeback mode.

B) Bcache not finding its cache and not starting

This does not work:

B) Bcache does not find its cache

	host:/sys/block/md5/bcache# echo 0226553a-37cf-41d5-b3ce-8b1e944543a8 > attach

	[ 1933.455082] bcache: bch_cached_dev_attach() Couldn't find uuid for md5 in set

	[ 1933.478179] bcache: __cached_dev_store() Can't attach 0226553a-37cf-41d5-b3ce-8b1e944543a8

	[ 1933.478179] : cache set not found

In this case, the caching device was simply not registered at boot or

disappeared and came back, and needs to be (re-)registered:

In this case, the caching device was simply not registered at boot

or disappeared and came back, and needs to be (re-)registered:

	host:/sys/block/md5/bcache# echo /dev/sdh2 > /sys/fs/bcache/register

C) Corrupt bcache caching device crashes the kernel on startup/boot

C) Corrupt bcache crashes the kernel at device registration time:

This should never happen.  If it does happen, then you have found a bug!

Please report it to the bcache development list: linux-bcache@vger.kernel.org

Be sure to provide as much information that you can including kernel dmesg

output if available so that we may assist.

D) Recovering data without bcache:

If bcache is not available in the kernel, a filesystem on the backing

device is still available at an 8KiB offset. So either via a loopdev

of the backing device created with --offset 8K, or any value defined by

--data-offset when you originally formatted bcache with `make-bcache`.

For example:

	losetup -o 8192 /dev/loop0 /dev/your_bcache_backing_dev

This should present your unmodified backing device data in /dev/loop0

If your cache is in writethrough mode, then you can safely discard the

cache device without loosing data.

You'll have to wipe the caching device, start the backing device without the

cache, and you can re-attach the cleaned up caching device then. This does

require booting with a kernel/rescue media where bcache is disabled

since it will otherwise try to access your device and probably crash

again before you have a chance to wipe it.

(or if you plan ahead, compile a backup kernel with bcache disabled and keep it

in your grub config for a rainy day)

If bcache is not available in the kernel, a filesystem on the backing device is

still available at an 8KiB offset. So either via a loopdev of the backing device

created with --offset 8K or by temporarily increasing the start sector of the

partition by 16 (512byte sectors).

This is how you wipe the caching device:

E) Wiping a cache device

host:~# wipefs -a /dev/sdh2

16 bytes were erased at offset 0x1018 (bcache)

they were: c6 85 73 f6 4e 1a 45 ca 82 65 f5 7f 48 ba 6d 81

[  865.276616] bcache: bch_cached_dev_attach() Caching md5 as bcache0 on set 5bc072a8-ab17-446d-9744-e247949913c1

D) Remove or replace a caching device

F) Remove or replace a caching device

	host:/sys/block/sda/sda7/bcache# echo 1 > detach

	[  695.872542] bcache: cached_dev_detach_finish() Caching disabled for sda7

	/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

E) dmcrypt and bcache

G) dm-crypt and bcache

First setup bcache unencrypted and then install dmcrypt on top of

/dev/bcache<N> This will work faster than if you dmcrypt both the backing

and caching devices and then install bcache on top. [benchmarks?]

First setup bcache unencrypted and then install dmcrypt on top of /dev/bcache<N>

This will work faster than if you dmcrypt both the backing and caching

devices and then install bcache on top.

H) Stop/free a registered bcache to wipe and/or recreate it

F) Stop/free a registered bcache to wipe and/or recreate it

(or maybe you need to free up all bcache references so that you can have fdisk

run and re-register a changed partition table, which won't work if there are any

active backing or caching devices left on it)

Suppose that you need to free up all bcache references so that you can

fdisk run and re-register a changed partition table, which won't work

if there are any active backing or caching devices left on it:

1) Is it present in /dev/bcache* ? (there are times where it won't be)

If so, it's easy:

	host:/sys/block/bcache0/bcache# echo 1 > stop

	bcache: bcache_device_free() bcache0 stopped

	bcache: cache_set_free() Cache set 5bc072a8-ab17-446d-9744-e247949913c1 unregistered

This causes the backing bcache to be removed from /sys/fs/bcache and then it can

be reused

This causes the backing bcache to be removed from /sys/fs/bcache and

then it can be reused.  This would be true of any block device stacking

where bcache is a lower device.

3) In other cases, you can also look in /sys/fs/bcache/:

host:/sys/fs/bcache# ls -l */{cache?,bdev?}

lrwxrwxrwx 1 root root 0 Mar  5 09:39 0226553a-37cf-41d5-b3ce-8b1e944543a8/bdev1 -> ../../../devices/virtual/block/dm-1/bcache/

lrwxrwxrwx 1 root root 0 Mar  5 09:39 0226553a-37cf-41d5-b3ce-8b1e944543a8/cache0 -> ../../../devices/virtual/block/dm-4/bcache/

The device names will show which UUID is relevant, cd in that directory

and stop the cache:

	host:/sys/fs/bcache/5bc072a8-ab17-446d-9744-e247949913c1# echo 1 > stop

this will free up bcache references and let you reuse the partition for other

purposes.

This will free up bcache references and let you reuse the partition for

other purposes.

be reasonable for typical desktop and server workloads, but they're not what you

want for getting the best possible numbers when benchmarking.

 - Backing device alignment

   The default metadata size in bcache is 8k.  If your backing device is

   RAID based, then be sure to align this by a multiple of your stride

   width using `make-bcache --data-offset`. If you intend to expand your

   disk array in the future, then multiply a series of primes by your

   raid stripe size to get the disk multiples that you would like.

   For example:  If you have a 64k stripe size, then the following offset

   would provide alignment for many common RAID5 data spindle counts:

	64k * 2*2*2*3*3*5*7 bytes = 161280k

   That space is wasted, but for only 157.5MB you can grow your RAID 5

   volume to the following data-spindle counts without re-aligning:

	3,4,5,6,7,8,9,10,12,14,15,18,20,21 ...

 - Bad write performance

   If write performance is not what you expected, you probably wanted to be