5 --------------------------------------------------
6 bcachefs overview, user's manual and configuration
7 --------------------------------------------------
12 Bcachefs is a multi device copy on write filesystem that supports
20 - Erasure coding (reed-solomon)
22 And more. This document is intended to be an overview of the various features
27 Most configuration is done via filesystem options that can be set at format
28 time, mount time (as mount -o parameters), or changed at runtime via sysfs (via
29 the /sys/fs/bcachefs/<UUID>/options/ directory).
31 Many of those options (particularly those that control the IO path) can also be
32 set on individual files and directories, via the bcachefs setattr command (which
33 internally mostly works via the extended attribute interface, but the setattr
34 command takes care to propagate options to children correctly).
36 .. csv-table:: Options
43 Devices can be added, removed, and resized at will, at runtime. There is no
44 fixed topology or data layout, as with hardware RAID or ZFS, and devices need
45 not be the same size - the allocator will stripe across multiple disks,
46 preferring to allocate from disks with more free space so that disks all fill up
49 We generally avoid per-device options, preferring instead options that can be
50 overridden on files or directories, but there are some:
54 Device labels, targets
55 ----------------------
57 Configuration options that point to targets (i.e. a disk or group of disks) may
58 be passed either a device (i.e. /dev/sda), or a label. Labels are assigned to
59 disks (and need not be unique), and these labels form a nested heirarchy: this
60 allows disks to be grouped together and referred to either individually or as a
63 For example, given disks formatted with these labels:
67 bcachefs format -g controller1.hdd.hdd1 /dev/sda \
68 -g controller1.hdd.hdd2 /dev/sdb \
69 -g controller1.ssd.ssd1 /dev/sdc \
70 -g controller1.ssd.ssd1 /dev/sdd \
71 -g controller2.hdd1 /dev/sde \
72 -g controller2.hdd2 /dev/sdf
74 Configuration options such as foreground_target may then refer to controller1,
75 or controller1.hdd, or controller1.hdd1 - or to /dev/sda directly.
77 Data placement, caching
78 -----------------------
80 The following options control which disks data is written to:
86 The foreground_target option is used to direct writes from applications. The
87 background_target option, if set, will cause data to be moved to that target in
88 the background by the rebalance thread some time after it has been initially
89 written - leaving behind the original copy, but marking it cached so that it can
90 be discarded by the allocator. The promote_target will will cause reads to write
91 a cached copy of the data being read to that target, if it doesn't exist.
93 Together, these options can be used for writeback caching, like so:
101 Writethrough caching requires telling bcachefs not to trust the cache device,
102 which does require a per-device option and thus can't completely be done with
103 per-file options. This is done by setting the device's durability to 0.
105 These options can all be set on individual files or directories. They can also
106 be used to pin a specific file or directory to a specific device or target:
110 foreground_target=ssd
114 Note that if the target specified is full, the write will spill over to the rest