From 21ade396535e51503511f42ea06d58e25c0646c5 Mon Sep 17 00:00:00 2001 From: Kent Overstreet Date: Sat, 25 Jul 2020 16:20:56 -0400 Subject: [PATCH] Initial WIP new user's manual --- Makefile | 3 ++ doc/bcachefs.5.txt | 110 +++++++++++++++++++++++++++++++++++++++++++++ 2 files changed, 113 insertions(+) create mode 100644 doc/bcachefs.5.txt diff --git a/Makefile b/Makefile index 9c762cb..728bce6 100644 --- a/Makefile +++ b/Makefile @@ -114,6 +114,9 @@ endif # Rebuild the 'version' command any time the version string changes cmd_version.o : .version +doc/bcachefs.5: doc/bcachefs.5.txt + a2x -f manpage doc/bcachefs.5.txt + .PHONY: install install: INITRAMFS_HOOK=$(INITRAMFS_DIR)/hooks/bcachefs install: INITRAMFS_SCRIPT=$(INITRAMFS_DIR)/scripts/local-premount/bcachefs diff --git a/doc/bcachefs.5.txt b/doc/bcachefs.5.txt new file mode 100644 index 0000000..291e2e3 --- /dev/null +++ b/doc/bcachefs.5.txt @@ -0,0 +1,110 @@ +BCACHEFS(5) +=========== + +NAME +---- +bcachefs - bcachefs overview, user's manual and configuration + +DESCRIPTION +----------- +Bcachefs is a multi device copy on write filesystem that supports + + Checksumming + Compression + Encryption + Reflink + Caching + Replication + Erasure coding (reed-solomon) + +And more. This document is intended to be an overview of the various features +and use cases. + +Configuration +------------- +Most configuration is done via filesystem options that can be set at format +time, mount time (as mount -o parameters), or changed at runtime via sysfs (via +the /sys/fs/bcachefs//options/ directory). + +Many of those options (particularly those that control the IO path) can also be +set on individual files and directories, via the bcachefs setattr command (which +internally mostly works via the extended attribute interface, but the setattr +command takes care to propagate options to children correctly). + + * TODO: include master list of options from opts.h +#include "opts.mdwn" + +Device management +----------------- +Devices can be added, removed, and resized at will, at runtime. There is no +fixed topology or data layout, as with hardware RAID or ZFS, and devices need +not be the same size - the allocator will stripe across multiple disks, +preferring to allocate from disks with more free space so that disks all fill up +at the same time. + +We generally avoid per-device options, preferring instead options that can be +overridden on files or directories, but there are some: + + *durability* + +Device labels, targets +---------------------- + +Configuration options that point to targets (i.e. a disk or group of disks) may +be passed either a device (i.e. /dev/sda), or a label. Labels are assigned to +disks (and need not be unique), and these labels form a nested heirarchy: this +allows disks to be grouped together and referred to either individually or as a +group. + +For example, given disks formatted with these labels: + + bcachefs format -g controller1.hdd.hdd1 /dev/sda \ + -g controller1.hdd.hdd2 /dev/sdb \ + -g controller1.ssd.ssd1 /dev/sdc \ + -g controller1.ssd.ssd1 /dev/sdd \ + -g controller2.hdd1 /dev/sde \ + -g controller2.hdd2 /dev/sdf + +Configuration options such as foreground_target may then refer to controller1, +or controller1.hdd, or controller1.hdd1 - or to /dev/sda directly. + +Data placement, caching +----------------------- + +The following options control which disks data is written to: + + * foreground_target + * background_target + * promote_target + +The foreground_target option is used to direct writes from applications. The +background_target option, if set, will cause data to be moved to that target in +the background by the rebalance thread some time after it has been initially +written - leaving behind the original copy, but marking it cached so that it can +be discarded by the allocator. The promote_target will will cause reads to write +a cached copy of the data being read to that target, if it doesn't exist. + +Together, these options can be used for writeback caching, like so: + + foregroud_target=ssd + background_target=hdd + promote_target=ssd + +Writethrough caching requires telling bcachefs not to trust the cache device, +which does require a per-device option and thus can't completely be done with +per-file options. This is done by setting the device's durability to 0. + +These options can all be set on individual files or directories. They can also +be used to pin a specific file or directory to a specific device or target: + + foreground_target=ssd + background_target= + promote_target= + +Note that if the target specified is full, the write will spill over to the rest +of the filesystem. + +Data protection +--------------- + +foo -- 2.39.2