* **`version`**
Locks the version of default values so upgrades do not silently change behavior.
If an option’s default value changes in a new bees release, `config.version` must be bumped to pick it up.
- Selecting a version pins the defaults of the keys it defines; keys added after it take the value they were introduced with, so pinning an old version stays possible as bees gains options.
+ Selecting a version pins every default: a key resolves through the selected version and the versions before it, never a newer one. Options added after a version are given a value in it that keeps that version's behavior.
Accepted values:
* Numeric version (e.g. `1`)
Do not set `no` unless you have confirmed your kernel is not affected.
- Default: `auto`.
+ Default: `auto` (config version 1 and `v0.11`: `no`).
## [throttle] section
The `[resolve]` section controls how bees maps a physical btrfs address back to the files that reference it, using the `LOGICAL_INO_V2` ioctl.
* **`commit-root`**
- Resolve references against the filesystem's commit roots instead of the live tree. Default: `yes`.
+ Resolve references against the filesystem's commit roots instead of the live tree. Default: `yes` (config version 1 and `v0.11`: `no`).
With `no`, the kernel walks the running transaction's trees, so the reference list reflects the filesystem as it is at the moment of the call. To keep that view consistent, the kernel holds a tree mod log sequence for the whole duration of the walk. While any sequence is live, every node-level change anywhere on the filesystem is journalled into unreclaimable slab, and the journal is only trimmed below the oldest live sequence. Walks of heavily-shared extents take the longest and therefore hold a sequence the longest, which is also when other work — balance, snapshot deletion — is most likely to be generating tree changes to journal.
The output is what `VERSION` *resolves to*, not the contents of the schema
file that carries its name. A schema states only the keys it changes, and
- everything else comes from the rest of the inheritance chain, so the dump
- is the whole chain flattened: every key any version defines, each with the
- value `VERSION` resolves for it.
-
- That means asking for an older version still lists options added after it,
- which is the point — a daemon pinned to that version resolves them too,
- each to the value it was introduced with. Where the selected version has
- an opinion of its own, that opinion wins: on a build where version 2
- changes `state.point.defer` to `yes`, `--show-builtin-config 1` lists the
- key with version 1's `no`, alongside every option version 2 added.
+ everything else comes from the schemas before it, so the dump is that
+ chain flattened: every key, each with the value `VERSION` resolves for it.
+ Newer schemas are never consulted, so on a build where version 2 changes
+ `state.point.defer` to `yes`, `--show-builtin-config 1` lists the key with
+ version 1's `no`.
This command does not load a filesystem, global config file, local config
file, environment-derived paths, or `--config` / `--option` input. It is
// they get on their next upgrade, which is the one thing versioning the schema
// exists to prevent.
//
-// New options and changed defaults belong in the highest-numbered
-// bees-config-v*.cc either way.
+// A version never resolves a key through a newer schema, so every key the
+// code reads must be defined here. A new option gets a key here too, set to
+// the value that keeps v0.11 behaviour; its new default goes in the
+// highest-numbered bees-config-v*.cc. Existing keys here are only ever
+// added to, never changed.
static const char bees_config_v1[] = R"--v1-config--(
# The [config] section controls config file sources and versioning.
return resolved;
}
-string
-BeesConfig::next_version(const string &version)
-{
- THROW_CHECK0(runtime_error, s_previous);
- string rv;
- for (const auto &i : *s_previous) {
- if (previous_version(i.first) != version) {
- continue;
- }
- // Two schemas inheriting from one would leave no single answer to
- // what comes after it, and the descendant walk needs exactly one.
- if (!rv.empty()) {
- THROW_ERROR(runtime_error, "config versions '" << rv << "' and '"
- << i.first << "' both inherit from '" << version << "'");
- }
- rv = i.first;
- }
- return rv;
-}
-
vector<string>
BeesConfig::version_chain(const string &version)
{
for (auto v = previous_version(version); !v.empty(); v = previous_version(v)) {
push(v);
}
- for (auto v = next_version(version); !v.empty(); v = next_version(v)) {
- push(v);
- }
return rv;
}
/// what CURRENT resolves to.
static constexpr const char *s_current_version = "2";
/// Most recently released config schema, and what STABLE resolves to.
- /// Version 1 holds the defaults that reproduce v0.11 behaviour. It may
- /// come to define fewer keys than this build queries, and stays
- /// selectable anyway because a version resolves through version_chain():
- /// the keys added since come from the schemas that added them. At a
+ /// Version 1 holds the defaults that reproduce v0.11 behaviour. At a
/// release the two constants meet again, and part company as development
/// resumes.
static constexpr const char *s_stable_version = "1";
/// The version @p version inherits from, resolved through the alias
/// table and checked, or "" when @p version is the oldest schema.
static string previous_version(const string &version);
- /// The version that inherits from @p version, or "" when none does.
- static string next_version(const string &version);
/** \brief Versions consulted for @p version, in resolution order.
- @p version first, then its ancestors nearest-first, then its
- descendants nearest-first. The two directions answer two different
- questions and the sets are disjoint, so there is no ambiguity.
-
- Ancestors are what let a schema state only the keys it changes.
- Descendants are what let a selected version go on working as the
- code grows past it: a key added after that version resolves to the
- value it was introduced with, rather than throwing as missing.
- Ancestors come first so that a later schema cannot reach back and
- change a value the selected version already inherited.
+ @p version first, then its ancestors nearest-first. Ancestors are
+ what let a schema state only the keys it changes. A schema newer
+ than @p version is never consulted, so nothing added after it can
+ change what it resolves. Every key the code reads must therefore be
+ defined by the oldest schema, with the value that reproduces its
+ behaviour.
*/
static vector<string> version_chain(const string &version);