GCACHE(8)

💅 GCACHE — control utility for CACHE GEOM class

okay so bestie, welcome to gcache(8), the system manager's manual page you didn't know you needed 💖 this little icon controls the GEOM cache, and by the end of this you're gonna be obsessed, no cap.

---

✨ SYNOPSIS ✨

gcache create [-v] [-b blocksize] [-s size] name prov
gcache configure [-v] [-b blocksize] [-s size] name
gcache destroy [-fv] name
gcache label [-v] [-b blocksize] [-s size] name prov
gcache stop [-fv] name ...
gcache clear [-v] prov ...
gcache dump prov ...
gcache list
gcache status [-s name]
gcache load [-v]
gcache unload [-v]

---

🌸 DESCRIPTION 🌸

The gcache utility is literally the control room for GEOM cache, which speeds up read performance by sending fixed size read requests to its consumer. 🚀

ngl it was built to fix a genuinely tragic situation: a 64 KiB blocksize FS sitting on a RAID3 array with 8 data components, where a single disk component would only get 8 KiB read requests — which effectively killed disk performance under high load 😭 like, rip.

Caching can be configured two ways, and yes you have to pick: “manual” or “automatic” 🎀

• With the “manual” method, no metadata are stored on the devices, so the cached device has to be configured by hand every single time it is needed. highkey labor.
• With the “automatic” method, on-disk metadata are used to detect devices. Once devices are labeled, they'll be automatically detected and configured. slay, it does the work for you ✨

The first argument to gcache indicates an action to be performed:

• create — Cache the given devices with specified name. This is the “manual” method. The kernel module geom_cache.ko will be loaded if it is not loaded already. 💫
• label — Cache the given devices with the specified name. This is the “automatic” method, where metadata are stored in every device's last sector. The kernel module geom_cache.ko will be loaded if it is not loaded already. 💫
• stop — Turn off existing cache device by its name. This command does not touch on-disk metadata! 🙈
• destroy — Same as stop.
• clear — Clear metadata on the given devices.
• dump — Dump metadata stored on the given devices.
• list — See geom(8).
• status — See geom(8).
• load — See geom(8).
• unload — See geom(8).

Additional options:

• -f — Force the removal of the specified cache device.
• -v — Be more verbose. 🗣️

---

🦋 SYSCTL VARIABLES 🦋

The following sysctl(8) variables can be used to control the behavior of the CACHE GEOM class. The default value is shown next to each variable. 👑

• kern.geom.cache.used_hi: 20
• kern.geom.cache.used_lo: 5
• kern.geom.cache.idletime: 5
• kern.geom.cache.timeout: 10
• kern.geom.cache.enable: 1
• kern.geom.cache.debug: 0
  • Debug level of the CACHE GEOM class. This can be set to a number between 0 and 3 inclusive. If set to 0 minimal debug information is printed, and if set to 3 the maximum amount of debug information is printed. 🔍

---

⭐ EXIT STATUS ⭐

Exit status is 0 on success, and 1 if the command fails. simple as that, periodt 💅

---

🌈 SEE ALSO 🌈

• geom(4)
• geom(8)

---

🎀 HISTORY 🎀

The gcache utility appeared in FreeBSD 7.0. vintage but iconic 🫶

---

👑 AUTHORS 👑

Ruslan Ermilov <ru@FreeBSD.org>

---

bestie reminder: stop and destroy don't touch on-disk metadata, so if you were expecting them to clean up after themselves… they don't 🙈 plan accordingly.

---

💖 and that's the whole vibe! this page is from the Debian camp, dated January 3, 2010, covering GCACHE(8) — go forth and cache responsibly, mwah 🧚✨