git.sesse.net Git - bcachefs-tools-debian/blob - doc/bcachefs.5.txt

   1 BCACHEFS(5)
   2 ===========
   3
   4 NAME
   5 ----
   6 bcachefs - bcachefs overview, user's manual and configuration
   7
   8 DESCRIPTION
   9 -----------
  10 Bcachefs is a multi device copy on write filesystem that supports
  11
  12  Checksumming
  13  Compression
  14  Encryption
  15  Reflink
  16  Caching
  17  Replication
  18  Erasure coding (reed-solomon)
  19
  20 And more. This document is intended to be an overview of the various features
  21 and use cases.
  22
  23 Configuration
  24 -------------
  25 Most configuration is done via filesystem options that can be set at format
  26 time, mount time (as mount -o parameters), or changed at runtime via sysfs (via
  27 the /sys/fs/bcachefs/<UUID>/options/ directory).
  28
  29 Many of those options (particularly those that control the IO path) can also be
  30 set on individual files and directories, via the bcachefs setattr command (which
  31 internally mostly works via the extended attribute interface, but the setattr
  32 command takes care to propagate options to children correctly).
  33
  34  * TODO: include master list of options from opts.h
  35 #include "opts.mdwn"
  36
  37 Device management
  38 -----------------
  39 Devices can be added, removed, and resized at will, at runtime. There is no
  40 fixed topology or data layout, as with hardware RAID or ZFS, and devices need
  41 not be the same size - the allocator will stripe across multiple disks,
  42 preferring to allocate from disks with more free space so that disks all fill up
  43 at the same time.
  44
  45 We generally avoid per-device options, preferring instead options that can be
  46 overridden on files or directories, but there are some:
  47
  48  *durability*
  49
  50 Device labels, targets
  51 ----------------------
  52
  53 Configuration options that point to targets (i.e. a disk or group of disks) may
  54 be passed either a device (i.e. /dev/sda), or a label. Labels are assigned to
  55 disks (and need not be unique), and these labels form a nested heirarchy: this
  56 allows disks to be grouped together and referred to either individually or as a
  57 group.
  58
  59 For example, given disks formatted with these labels:
  60
  61   bcachefs format -g controller1.hdd.hdd1 /dev/sda      \
  62                   -g controller1.hdd.hdd2 /dev/sdb      \
  63                   -g controller1.ssd.ssd1 /dev/sdc      \
  64                   -g controller1.ssd.ssd1 /dev/sdd      \
  65                   -g controller2.hdd1     /dev/sde      \
  66                   -g controller2.hdd2     /dev/sdf
  67
  68 Configuration options such as foreground_target may then refer to controller1,
  69 or controller1.hdd, or controller1.hdd1 - or to /dev/sda directly.
  70
  71 Data placement, caching
  72 -----------------------
  73
  74 The following options control which disks data is written to:
  75
  76  * foreground_target
  77  * background_target
  78  * promote_target
  79
  80 The foreground_target option is used to direct writes from applications. The
  81 background_target option, if set, will cause data to be moved to that target in
  82 the background by the rebalance thread some time after it has been initially
  83 written - leaving behind the original copy, but marking it cached so that it can
  84 be discarded by the allocator. The promote_target will will cause reads to write
  85 a cached copy of the data being read to that target, if it doesn't exist.
  86
  87 Together, these options can be used for writeback caching, like so:
  88
  89   foregroud_target=ssd
  90   background_target=hdd
  91   promote_target=ssd
  92
  93 Writethrough caching requires telling bcachefs not to trust the cache device,
  94 which does require a per-device option and thus can't completely be done with
  95 per-file options. This is done by setting the device's durability to 0.
  96
  97 These options can all be set on individual files or directories. They can also
  98 be used to pin a specific file or directory to a specific device or target:
  99
 100   foreground_target=ssd
 101   background_target=
 102   promote_target=
 103
 104 Note that if the target specified is full, the write will spill over to the rest
 105 of the filesystem.
 106
 107 Data protection
 108 ---------------
 109
 110 foo