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

   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 OPTIONS
  37 -------
  38 OPTIONS_TABLE
  39
  40 Device management
  41 -----------------
  42 Devices can be added, removed, and resized at will, at runtime. There is no
  43 fixed topology or data layout, as with hardware RAID or ZFS, and devices need
  44 not be the same size - the allocator will stripe across multiple disks,
  45 preferring to allocate from disks with more free space so that disks all fill up
  46 at the same time.
  47
  48 We generally avoid per-device options, preferring instead options that can be
  49 overridden on files or directories, but there are some:
  50
  51  *durability*
  52
  53 Device labels, targets
  54 ----------------------
  55
  56 Configuration options that point to targets (i.e. a disk or group of disks) may
  57 be passed either a device (i.e. /dev/sda), or a label. Labels are assigned to
  58 disks (and need not be unique), and these labels form a nested heirarchy: this
  59 allows disks to be grouped together and referred to either individually or as a
  60 group.
  61
  62 For example, given disks formatted with these labels:
  63
  64 .. code-block:: bash
  65
  66   bcachefs format -g controller1.hdd.hdd1 /dev/sda      \
  67                   -g controller1.hdd.hdd2 /dev/sdb      \
  68                   -g controller1.ssd.ssd1 /dev/sdc      \
  69                   -g controller1.ssd.ssd1 /dev/sdd      \
  70                   -g controller2.hdd1     /dev/sde      \
  71                   -g controller2.hdd2     /dev/sdf
  72
  73 Configuration options such as foreground_target may then refer to controller1,
  74 or controller1.hdd, or controller1.hdd1 - or to /dev/sda directly.
  75
  76 Data placement, caching
  77 -----------------------
  78
  79 The following options control which disks data is written to:
  80
  81 - foreground_target
  82 - background_target
  83 - promote_target
  84
  85 The foreground_target option is used to direct writes from applications. The
  86 background_target option, if set, will cause data to be moved to that target in
  87 the background by the rebalance thread some time after it has been initially
  88 written - leaving behind the original copy, but marking it cached so that it can
  89 be discarded by the allocator. The promote_target will will cause reads to write
  90 a cached copy of the data being read to that target, if it doesn't exist.
  91
  92 Together, these options can be used for writeback caching, like so:
  93
  94 .. code-block:: bash
  95
  96   foreground_target=ssd
  97   background_target=hdd
  98   promote_target=ssd
  99
 100 Writethrough caching requires telling bcachefs not to trust the cache device,
 101 which does require a per-device option and thus can't completely be done with
 102 per-file options. This is done by setting the device's durability to 0.
 103
 104 These options can all be set on individual files or directories. They can also
 105 be used to pin a specific file or directory to a specific device or target:
 106
 107 .. code-block:: bash
 108
 109   foreground_target=ssd
 110   background_target=
 111   promote_target=
 112
 113 Note that if the target specified is full, the write will spill over to the rest
 114 of the filesystem.
 115
 116 Data protection
 117 ---------------
 118
 119 foo