angrr(5)

💖 NAME 💖

okay so angrr(5) — from the File Formats Manual — is literally the configuration file page for angrr, and it's giving “read me before you touch the GC roots” energy. angrr — configuration file. Periodt. 🎀

🦋 DESCRIPTION 🦋

The angrr configuration file is written in TOML format — the original points at https://toml.io — and the global config lives at /etc/angrr/config.toml. You can also point at a custom configuration file with the --config command-line option. Slay. ✨

🌸 EXAMPLE 🌸

Run angrr example-config to extract the example configuration from the angrr binary. Here's the whole thing, copied exactly because we do not mess with config snippets:

# Example configuration for angrr

# Only roots point into the store will be removed
# store = "/nix/store"

# Only monitor GC roots owned by the current user
# Defaults to "auto"
# owned-only = "auto"

# Remove GC root in `directory` instead of the symbolic link target of them.
# remove-root = false

# Directory contains GC roots to monitor.
# directory = ["/nix/var/nix/gcroots/auto"]

[temporary-root-policies.direnv]
enable = true
priority = 90             # lower priority number takes precedence
path-regex = '/\.direnv/'
period = "14d"

[temporary-root-policies.result]
enable = true
# priority defaults to 100 if not specified
path-regex = '/result[^/]*$'
period = "7d"

[profile-policies.system]
enable = false
profile-paths = ["/nix/var/nix/profiles/system"]
keep-since = "14d"
keep-latest-n = 3
keep-booted-system = true
keep-current-system = true
keep-n-per-bucket = [
  { bucket-window = "1 day", bucket-amount = 7 },
  { bucket-window = "1 week", bucket-amount = 4 },
]

[profile-policies.user]
enable = false
profile-paths = [
  "~/.local/state/nix/profiles/profile",
  "/nix/var/nix/profiles/per-user/root/profile",
]
keep-since = "0d"
keep-latest-n = 3
keep-booted-system = false
keep-current-system = false

[touch]
# ignore `.git` in `angrr touch --project` command
project-globs = ["!.git"]

👑 OPTIONS 👑

• store = <path> — Store path for validation. Default is /nix/store. Only GC roots pointing to store will be monitored. 🔥
• owned-only = "auto"|"true"|"false" — Only monitors owned symbolic link target of GC roots. The example config comment says it defaults to "auto".
  • "auto": behaves like true for normal users, false for root.
  • "true": only monitor GC roots owned by the current user.
  • "false": monitor all GC roots.
• remove-root = <bool> — Remove GC root in directory instead of the symbolic link target of them. Default is false.
• directory = [<path1>, <path2>, ...] — Directories containing auto GC roots. Default is ["/nix/var/nix/gcroots/auto"].
• temporary-root-policies = [<policy1>, <policy2>, ...] — List of temporary root policies. See TEMPORARY ROOT POLICY OPTIONS for details.
• profile-policies = [<policy1>, <policy2>, ...] — List of temporary root policies. See PROFILE POLICY OPTIONS for details.
• touch = <touch-options> — Options for angrr touch command. See TOUCH OPTIONS for details.

🎀 COMMMON POLICY OPTIONS 🎀

three Ms in the original heading — we don't fix it, we celebrate it 💅

• enable = <bool> — Enable or disable this policy. Default is true.

⭐ TEMPORARY ROOT POLICY OPTIONS ⭐

See COMMON POLICY OPTIONS for common options.

• priority = <int> — Priority of this policy. Lower number means higher priority. If multiple policies monitor the same path, the one with higher priority will be applied. If multiple policies have the same priority, name in lexicographical order will be applied. That is, a policy named "A" with priority 100 will have higher priority than a policy named "B" with priority 100.
• path-regex = <regex> — Only paths (absolute) matching the regex will be monitored by this policy.
• filter = <filter> — An external program to filter paths that will be applied after all the other filter options. A JSON object containing the path information will be passed to the stdin of the program. If the program exits with code 0, then the path will be monitored; otherwise it will be ignored. See FILTER OPTIONS for more information.
• ignore-prefixes = [<prefix1>, <prefix2>, ...] — A list of path prefixes (absolute) to ignore. Default is ["/nix/var/nix/profiles"].
• ignore-prefixes-in-home = [<prefix1>, <prefix2>, ...] — A list of path prefixes (relative to home directory) to ignore. Default is:

[
    ".local/state/nix/profiles",
    ".local/state/home-manager/gcroots",
    ".cache/nix/flake-registry.json"
]

• period = <duration> — Retention period for temporary GC roots.

🦋 PROFILE POLICY OPTIONS 🦋

See COMMON POLICY OPTIONS for common options.

• profile-paths = [<path1>, <path2>, ...] — Paths to the profile. When owned-only = true, if the option begins with ~, it will be expanded to the home directory of the current user. When owned-only = false, if the options begins with ~, it will be expanded to the home of all users discovered respectively.
• keep-since = <duration> — Keep generations created within this duration.
• keep-latest-n = <number> — Keep the latest <number> GC roots in this profile.
• keep-current-system = <bool> — Whether to keep the current activated system generation. Only useful for system profiles. Default is false.
• keep-booted-system = <bool> — Whether to keep the currently booted generation. Only useful for system profiles. Default is false.
• keep-n-per-bucket = list of { n: <usize>, bucket-window: <duration>, bucket-amount: <u32> } — Specify a list of rules having n, bucket-window, and bucket-amount attributes.
  • Each rule retains n generations every bucket-window duration for bucket-amount buckets.
  • n defaults to 1.
  • This can be useful for server configurations such that there will be sparse but available older generations to rollback to.
  • This attribute is inspired by the grandfather-father-son backup scheme (https://en.wikipedia.org/wiki/Backup_rotation_scheme#Grandfather-father-son).
  • Take the configuration {n = 1; bucket-window = "1 Month"; bucket-amount = 2;} as an example. Angrr will group past generations into buckets such that each bucket contains generations of the same month (bucket-window). It then retains 1 (n) most recent generation out of each bucket, for first two buckets (bucket-amount).
  • Rules are processed in order. bucket-window is defined in humantime::parse_duration specified in the DURATION section (#DURATION).
  • bucket-window is used with regard to the moment angrr is run and doesn't reflect calendar. For example, a period of one week represents the seven days before the run time, not the number of days since the start of the calendar week.
  • Rules can have overlapping bucket-window. When a generation of a bucket satisfying a rule is already kept by a previous rule, we take the next most recent one of the same bucket and give up if there are no more in the same bucket. In other words: when looking for generations within a bucket that are not yet handled and none are found, we do not look into the next youngest bucket for them. Separate rules for that next bucket will still be applied.

💅 FILTER OPTIONS 💅

• program = <path> — Path to the external filter program.
• arguments = [<arg1>, <arg2>, ...] — Arguments to pass to the external filter program.

🌈 TOUCH OPTIONS 🌈

• project-globs = [<glob1>, <glob2>, ...] — List of glob patterns to include or exclude files when touching GC roots. Only applied when angrr touch is invoked with the --project flag. Patterns use an inverted gitignore-style semantics (see below). Globs provided here have precisely the same semantics as a single line in a gitignore file, where the meaning of ! is inverted: namely, ! at the beginning of a glob will ignore a file. Without !, all matches of the glob provided are treated as whitelist matches. [1]

[1] https://docs.rs/ignore/latest/ignore/overrides/struct.OverrideBuilder.html#method.add

⏳ DURATION ⏳

For syntax of <duration>, see the documentation of humantime::parse_duration[1].

[1] https://docs.rs/humantime/latest/humantime/fn.parse_duration.html

🫶 SEE ALSO 🫶

• angrr(1)

---

okay that's the whole page, bestie — the header says File Formats Manual, the footer tag is angrr(5), and there's no extra version/date line hiding down here. Stay slay, keep your GC roots clean 💖🎀✨