From d9c788d30a20a52a49e0eaa72e2d46f3ce6d76a5 Mon Sep 17 00:00:00 2001 From: Zygo Blaxell Date: Sat, 17 Nov 2018 00:46:58 -0500 Subject: [PATCH] docs: reorganize options, add workaround for btrfs send options.md was a disorganized mess that markdown couldn't parse properly. Break the options list down into sections by theme. Add the new '--workaround-btrfs-send' option to the new 'Workarounds' section. Clean up the rest of the text and fix some inconsistencies. Signed-off-by: Zygo Blaxell --- docs/btrfs-kernel.md | 16 +++++- docs/btrfs-other.md | 8 +-- docs/options.md | 130 ++++++++++++++++++++++++++++--------------- 3 files changed, 101 insertions(+), 53 deletions(-) diff --git a/docs/btrfs-kernel.md b/docs/btrfs-kernel.md index 2396604..64c0343 100644 --- a/docs/btrfs-kernel.md +++ b/docs/btrfs-kernel.md @@ -38,9 +38,6 @@ Unfixed kernel bugs (as of 4.14.71): `rsync` is copying from, while `rsync` will rename the new file over the old file to replace it. -* **btrfs send** has various problems when bees is deduping RO snapshots, - especially if the snapshot is used as a parent for incremental send. - Minor kernel problems with workarounds: * **Slow backrefs** (aka toxic extents): Under certain conditions, @@ -52,6 +49,19 @@ Minor kernel problems with workarounds: to get slow. In the bees log, such blocks are labelled as 'toxic' hash/block addresses. +* **btrfs send** has various bugs that are triggered when bees is + deduping snapshots. bees provides the [`--workaround-btrfs-send` + option](options.md) which should be used whenever `btrfs send` and + bees are run on the same filesystem. + + This issue affects: + * `btrfs send` (any mode) and bees active at the same time. + * `btrfs send` in incremental mode (using `-p` option) with bees + active at the same or different times. + + Note `btrfs receive` is not affected. It is OK to run bees with no + workarounds on a filesystem that receives btrfs snapshots. + Older kernels: * Older kernels have various data corruption and deadlock/hang issues diff --git a/docs/btrfs-other.md b/docs/btrfs-other.md index 0ca961f..3b5982b 100644 --- a/docs/btrfs-other.md +++ b/docs/btrfs-other.md @@ -28,11 +28,9 @@ bees has been tested in combination with the following, and various problems are * bcache, lvmcache: **severe (filesystem-destroying) metadata corruption issues** observed in testing and reported by users, apparently only when used with bees. Plain SSD and HDD seem to be OK. -* btrfs send: some kernel versions have bugs in btrfs send that can be - triggered by bees. The send can be restarted and will work if bees - has finished processing the snapshot being sent. No data corruption - observed other than the truncated send. Incremental send doesn't seem - to work with bees running on the sending side. +* btrfs send: there are bugs in `btrfs send` that can be triggered by bees. + The [`--workaround-btrfs-send` option](options.md) works around this issue, + but possibly at great cost. * btrfs qgroups: very slow, sometimes hangs...and it's even worse when bees is running. * btrfs autodefrag mount option: hangs and high CPU usage problems diff --git a/docs/options.md b/docs/options.md index 741f680..4af08d9 100644 --- a/docs/options.md +++ b/docs/options.md @@ -1,52 +1,92 @@ # bees Command Line Options - - - - - +## Load management options - - - - +* `--thread-count COUNT` or `-c` - - + Minimizes temporary space usage. + * Mode 1: scan extents from all subvols in parallel. Good performance + on non-spinning media when subvols are unrelated. + * Mode 2: scan all extents from one subvol at a time. Good sequential + read performance for spinning media. Maximizes temporary space usage. - - - - - - - - - - +## Workarounds -
--thread-count COUNT-cSpecify maximum number of worker threads for scanning. Overrides ---thread-factor (-C) and default/autodetected values. -
--thread-factor FACTOR-CSpecify ratio of worker threads to CPU cores. Overridden by --thread-count (-c). - Default is 1.0, i.e. 1 worker thread per detected CPU. Use values - below 1.0 to leave some cores idle, or above 1.0 if there are more - disks than CPUs in the filesystem. -
--loadavg-target LOADAVG-gSpecify load average target for dynamic worker threads. - Threads will be started or stopped subject to the upper limit imposed - by thread-factor, thread-min and thread-count until the load average - is within +/- 0.5 of LOADAVG. -
--thread-min COUNT-GSpecify minimum number of worker threads for scanning. - Ignored unless -g option is used to specify a target load.
--scan-mode MODE-m -Specify extent scanning algorithm. Default mode is 0. -EXPERIMENTAL feature that may go away. -
    -
  • Mode 0: scan extents in ascending order of (inode, subvol, offset). + Specify maximum number of worker threads. Overrides `--thread-factor` + (`-C`) and default/autodetected values. + +* `--thread-factor FACTOR` or `-C` + + Specify ratio of worker threads to detected CPU cores. Overridden by + `--thread-count` (`-c`). + + Default is 1.0, i.e. 1 worker thread per detected CPU. Use values + below 1.0 to leave some cores idle, or above 1.0 if there are more + disks than CPUs in the filesystem. + +* `--loadavg-target LOADAVG` or `-g` + + Specify load average target for dynamic worker threads. Default is + to run the maximum number of worker threads all the time. + + Worker threads will be started or stopped subject to the upper limit + imposed by `--thread-factor`, `--thread-min` and `--thread-count` + until the load average is within +/- 0.5 of `LOADAVG`. + +* `--thread-min COUNT` or `-G` + + Specify minimum number of dynamic worker threads. This can be used + to force a minimum number of threads to continue running while using + `--loadavg-target` to manage load. + + Default is 0, i.e. all bees worker threads will stop when the system + load exceeds the target. + + Has no effect unless `--loadavg-target` is used to specify a target load. + +## Filesystem tree traversal options + +* `--scan-mode MODE` or `-m` + + Specify extent scanning algorithm. Default `MODE` is 0. + **EXPERIMENTAL** feature that may go away. + + * Mode 0: scan extents in ascending order of (inode, subvol, offset). Keeps shared extents between snapshots together. Reads files sequentially. -Minimizes temporary space usage.
    • -
  • Mode 1: scan extents from all subvols in parallel. Good performance - on non-spinning media when subvols are unrelated.
    • -
  • Mode 2: scan all extents from one subvol at a time. Good sequential - read performance for spinning media. Maximizes temporary space usage.
    • -
-
--timestamps-tEnable timestamps in log output.
--no-timestamps-TDisable timestamps in log output.
--absolute-paths-pPaths in log output will be absolute.
--strip-paths-PPaths in log output will have the working directory at bees startup - stripped.
--verbose-vSet log verbosity (0 = no output, 8 = all output, default 8).
+* `--workaround-btrfs-send` or `-a` + + Pretend that read-only snapshots are empty and silently discard any +request to dedupe files referenced through them. This is a workaround for +[problems with the kernel implementation of `btrfs send` and `btrfs send +-p`](btrfs-kernel.md) which make these btrfs features unusable with bees. + + This option should be used to avoid breaking `btrfs send` on the same +filesystem. + + **Note:** There is a _significant_ space tradeoff when using this option: +it is likely no space will be recovered--and possibly significant extra +space used--until the read-only snapshots are deleted. On the other +hand, if snapshots are rotated frequently then bees will spend less time +scanning them. + +## Logging options + +* `--timestamps` or `-t` + + Enable timestamps in log output. + +* `--no-timestamps` or `-T` + + Disable timestamps in log output. + +* `--absolute-paths` or `-p` + + Paths in log output will be absolute. + +* `--strip-paths` or `-P` + + Paths in log output will have the working directory at bees startup stripped. + +* `--verbose` or `-v` + + Set log verbosity (0 = no output, 8 = all output, default 8).