AUTOTIER(8)

📦 version 1.2.0, in nixos 26.05, nixpkgs unstable

💅 AUTOTIER(8) — like, the autotier manual page, bestie

okay so this is AUTOTIER(8) from the System Manager's Manual section — yes it's a section 8 page, that means it's a system admin situation, and yes you're gonna read all of it because I said so 🫶

✨ NAME ✨

autotier — a passthrough FUSE filesystem that intelligently moves files between storage tiers based on frequency of use, file age, and tier fullness.

that's the whole vibe. it shuffles your files around so the ones you actually touch live on the fast stuff and the dusty ones go chill in the back. main character file placement energy 👑

🌈 SYNOPSIS 🌈

🧚 MOUNTING FILESYSTEM

autotierfs [-choqvV] mountpoint [-o fuse,options,...]

🎀 AD HOC COMMANDS

autotier [-chqvV] command [arg1 arg2 ...]

two different binaries, two different moods. autotierfs mounts stuff, autotier does the one-off lil errands. iykyk 💅

🦋 DESCRIPTION 🦋

so autotier is a passthrough fuse filesystem — meaning it sits in front of your real filesystems and pretends to be one big one. it combines multiple underlying filesystems, a.k.a. tiers, into one pool of storage. literally gluing them together but make it elegant ✨

each tier should be a separate filesystem, ok? not optional, that's the whole point. any number of tiers can be defined in the configuration file for autotier — go off, add as many as you want 🎀

files get moved between each tier based on their popularity, and autotier will attempt to keep the percent usage of each tier below the tier's watermark. it's out here doing vibe checks on your data fr fr 🔥

💖 OPTIONS 💖

  • -c, --config path/to/config/file — override configuration file path (default /etc/autotier.conf). you wanna point it somewhere else? this is your girl.
  • -h, --help — display usage message and cancel current command. it's giving "help me help you" 😭
  • -o, --fuse-options comma,separated,list — options for fuse filsystem. see fuse(8) for details. (yes the original says "filsystem", we're keeping her, she's iconic 💀)
  • -q, --quiet — mute log output, other than warnings and errors. overrides Log Level in the configuration file to 0. silence is golden bestie 🤫
  • -v, --verbose — print debug level output. overrides Log Level in the configuration file to 2. it's gonna tell you EVERYTHING. not me getting the full lore 🙈
  • -V, --version — print autotier version and exit. prints unicode logo as well if log level is 1 or higher. combine with -q to mute logo output. (a logo! in a terminal! we love a brand moment 🌸)

👑 MOUNTING 👑

💅 MANUALLY

autotierfs [flags] mountpoint [-o fuse,options,...]

just you, your hands, and a mountpoint. go off.

🍓 IN FSTAB

autotierfs mountpoint fuse,options,...  0 0

drop it in /etc/fstab and let the boot process handle it, periodt.

autotierfs mountpoint default_permissions,allow_other 0 0

this is the one. the glow-up config. use this 🫶

🌸 AD HOC COMMANDS 🌸

  • config — print current configuration values. receipts, basically 🧾
  • help — display usage message and cancel current command.
  • list-pins — show all pinned files along with the tier they are pinned to. 📌 iconic behaviour, honestly
  • list-popularity — print all files in filesystem along with their popularity scores (accesses per hour). this is the leaderboard, and yes we're ranking files now 💀
  • oneshot — execute tiering of files immediately. no waiting, we're doing it NOW 🔥
  • pin “tier name” path/to/file [path/to/file ...] — move files into the given tier and keep them there regardless of their popularity scores. locked in. no cap 💜
  • status — print info about each tier, including the tier name, path, usage, and watermark. the tier gossip session 👀
  • unpin path/to/file [path/to/file ...] — remove the "pinned" flag from each file to allow the tiering process to move it. freedom 🦋
  • which-tier path/to/file [path/to/file ...] — display a table of each file passed in the argument list with the name of the tier containing the file and the full backend path to that file. to see where each file is in a given directory, use find path/to/directory -type f | xargs autotier which-tier

🎀 CONFIGURATION 🎀

the default location of the configuration file is /etc/autotier.conf.

🧚 FORMAT

autotier configuration contains sections and parameters. sections are groupings of parameters that begin with a header name in square brackets. there is one special section header name, global, which contains global autotier configuration parameters. sections with headers containing anything other than global are tiers. the parameters of each section take the form of Key = value.

so like: bracket, name, bracket, then key equals value. that's the whole grammar, we stan a simple syntax ✨

💖 GLOBAL PARAMETERS

the following parameters are to be put under the [Global] header.

  • Log Level = 0|1|2 — the level at which to print log messages. if the value is 0, all informational messages are muted and only warnings and errors are printed. if the value is 1, normal informational log messages are printed. if the value is 2, debug messages will also be printed. this value is overridden by the --verbose and --quiet flags.
  • Tier Period = n — number of seconds between each tiering of files. must be an integer in the range [0, INT64_MAX]. yes that's a big range, live your truth 😌
  • Strict Period = true|false — if true, file tiering strictly happens once per period. if false, tiering can be triggered after writing to a file when the tier is past it's quota. default value is false.
  • Metadata Path = /full/path/to/metadata — optional. if undefined, autotier defaults to using /var/lib/autotier as the path to store metadata in. to mount autotier as an unprivileged user, set this path to somewhere with write permissions for that user.
  • Copy Buffer Size = n [prefix][i]B — size of buffer to use while moving a file from one tier to another. smaller buffers will use less memory, but larger buffers may be more efficient while tiering. n is a positive real number and prefix = K|M|G|T|P|E|Z|Y. include i between the prefix and B to use base-1024 units instead of base-1000. default size is 1 MiB.

🦋 TIER DEFINITIONS

pick a friendly name for the tier and use that as the header name. there needs to be at least two tiers, however there is no upper limit. that said, keep the number of tiers reasonable. the following parameters are to be put in each tier section.

  • Path = /full/path/to/tier — the path to the tier mountpoint/directory. keep in mind that each tier should be in a separate filesystem for intended functionality. (say it with me: separate. filesystem. 💅)
  • Quota = n unit — the tier's quota. tier usage is kept under this value. it can either be a percent of the tier's capacity, or an absolute value. to set it to a percent, use Quota = n %, where n is a positive integer in the range [0, 100]. to use an absolute value, use Quota = n [prefix][i]B, where n is a positive real number and prefix = K|M|G|T|P|E|Z|Y. include i between the prefix and B to use base-1024 units instead of base-1000. while moving files around, autotier attempts to keep the percent usage of each tier below this level.

🌈 EXAMPLE CONFIGURATION

bestie. look at this. it's giving art 🎨

# autotier config
[Global]               # global settings
Log Level = 1          # 0 = none, 1 = normal, 2 = debug
Tier Period = 10       # number of seconds between file move batches

[SSDs]                 # tier name
Path = /mnt/ssd_pool   # full path to tier storage pool
Quota = 15 TiB         # abs usage at which to stop filling tier

[HDDs]
Path = /mnt/hdd_pool
Quota = 70 %       # % usage at which to stop filling tier

[Cold Storage]
Path = /mnt/cold_storage
Quota = 100 %

three tiers, three vibes: fast, medium, and "we forgot this exists" 🧊 i'm obsessed.

🫶 AUTHOR 🫶

autotier was created by Josh Boudreau <jboudreau@45drives.com> and is maintained by the Research and Development team at 45Drives.

shoutout to the devs, absolute legends, no cap 👑

ok that's the whole page, go forth and tier your files 💖

and that's a wrap on this edition, babe — autotier 1.1.6, dated May 12 2021 ✨ if you made it this far you're officially a filesystem girlie now, welcome to the club 🎀💅

📦 where this page comes from