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

   1 ========
   2 bcachefs
   3 ========
   4
   5 --------------------------------------------------
   6 bcachefs overview, user's manual and configuration
   7 --------------------------------------------------
   8 :Manual section: 5
   9
  10 DESCRIPTION
  11 -----------
  12 Bcachefs is a multi device copy on write filesystem that supports
  13
  14 - Checksumming
  15 - Compression
  16 - Encryption
  17 - Reflink
  18 - Caching
  19 - Replication
  20 - Erasure coding (reed-solomon)
  21
  22 And more. This document is intended to be an overview of the various features
  23 and use cases.
  24
  25 Configuration
  26 -------------
  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).
  30
  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).
  35
  36 .. csv-table:: Options
  37    :file: gen.csv
  38    :header-rows: 1
  39    :delim: ;
  40
  41 Device management
  42 -----------------
  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
  47 at the same time.
  48
  49 We generally avoid per-device options, preferring instead options that can be
  50 overridden on files or directories, but there are some:
  51
  52  *durability*
  53
  54 Device labels, targets
  55 ----------------------
  56
  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
  61 group.
  62
  63 For example, given disks formatted with these labels:
  64
  65 .. code-block:: bash
  66
  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
  73
  74 Configuration options such as foreground_target may then refer to controller1,
  75 or controller1.hdd, or controller1.hdd1 - or to /dev/sda directly.
  76
  77 Data placement, caching
  78 -----------------------
  79
  80 The following options control which disks data is written to:
  81
  82 - foreground_target
  83 - background_target
  84 - promote_target
  85
  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.
  92
  93 Together, these options can be used for writeback caching, like so:
  94
  95 .. code-block:: bash
  96
  97   foreground_target=ssd
  98   background_target=hdd
  99   promote_target=ssd
 100
 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.
 104
 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:
 107
 108 .. code-block:: bash
 109
 110   foreground_target=ssd
 111   background_target=
 112   promote_target=
 113
 114 Note that if the target specified is full, the write will spill over to the rest
 115 of the filesystem.
 116
 117 Data protection
 118 ---------------
 119
 120 foo