GEOM_FOX(4)

💖 GEOM_FOX(4) 💖

okay bestie, welcome to geom_fox, the FreeBSD 4th-section manual page about GEOM based basic disk multipathing. yes it's a real thing, yes it's obsolete, and yes we're gonna read the whole thing together because that's just who we are 🎀

---

✨ NAME ✨

geom_fox — GEOM based basic disk multipathing

---

🌸 SYNOPSIS 🌸

so to get this driver baked into your kernel, you drop this line into your kernel configuration file:

options GEOM_FOX

or, if you'd rather load it as a module at boot time (iconic behavior tbh), you put this in loader.conf(5):

geom_fox_load="YES"

---

🦋 DESCRIPTION 🦋

bestie, I need you to sit down for this one. This driver is obsolete. like, the manpage literally says users are advised to use gmultipath(8) instead, and it also says this driver will be removed in FreeBSD 12. so. yeah. we're reading a ghost's diary here 💀

The whole intent of the geom_fox framework is to give you basic multipathing support for accessing direct access devices. And when it says "basic"? read that as: geom_fox only provides path failover functionality, it does not do load balancing over the available paths or anything extra like that. periodt.

With suitable hardware — think SCSI or FibreChannel disks — you can have multiple (typically 2) host bus adapters all accessing the same physical disk drive. very main character, very redundant ✨

But here's the problem, and it's giving chaos: without a multipathing driver, the FreeBSD kernel would probe those disks multiple times, which results in the creation of multiple /dev entries for the same underlying physical device. 😭 a whole mess.

Enter the glow-up: a unique label written in the GEOM label area lets geom_fox detect multiple paths. Using that info, it creates a unique da#.fox device. 💅

That geom_fox device is then used by the FreeBSD kernel to access the disks. And multiple physical access paths mean that even if a path fails, the FreeBSD kernel can keep on accessing the data. resilient queen 👑

One more thing: the geom_fox driver will disallow write operations to the underlying devices once the fox device has been opened for writing. noted. 🫶

---

🎀 EXAMPLES 🎀

• geom_fox needs a label on the disk as follows in order to work properly:

"0123456789abcdef0123456789abcdef"
"GEOM::FOX       <--unique--id-->"

For the unique ID, 16 bytes are available. The "GEOM::FOX" is the magic that marks a geom_fox device. ✨

The actual labelling is accomplished by

echo "GEOM::FOX       someid" | dd of=/dev/da2 conv=sync

For FibreChannel devices it is suggested to use the Node World Wide Name (Node WWN), because that's guaranteed by the FibreChannel standard to be worldwide unique. The use of the Port WWN is not recommended, since each port of a given device has a different WWN, which just confuses things. 🙈

The Node WWN can be obtained from a verbose boot, like for example

isp1: Target 1 (Loop 0x1) Port ID 0xe8 (role Target) Arrived
 Port WWN 0x21000004cfc8aca2
 Node WWN 0x20000004cfc8aca2

This Node WWN would then be used like so:

echo "GEOM::FOX       20000004cfc8aca2" | dd of=/dev/da2 conv=sync

For non-FibreChannel devices you could for example use the serial number of the device. Regardless of what you use, make sure the label is unique. no cap.

Once the labelling has been performed, and assuming the geom_fox module is loaded, the kernel will inform you that it has found a new geom_fox device with a message similar to

Creating new fox (da2)
fox da2.fox lock 0xfffffc0000fdba20

• To check which physical devices match a given geom_fox device:

# geom fox list
Geom name: da2.fox
Providers:
1. Name: da2.fox
   Mediasize: 73407865344 (68G)
   Sectorsize: 512
   Mode: r0w0e0
Consumers:
1. Name: da2
   Mediasize: 73407865856 (68G)
   Sectorsize: 512
   Mode: r0w0e0
2. Name: da6
   Mediasize: 73407865856 (68G)
   Sectorsize: 512
   Mode: r0w0e0

• To check the status of the geom_fox components:

# geom fox status
   Name  Status  Components
da2.fox     N/A  da2
                 da6

---

🌈 SEE ALSO 🌈

GEOM(4), geom(8), gmultipath(8)

---

👑 AUTHORS 👑

The geom_fox driver was written by Poul-Henning Kamp <phk@FreeBSD.org>.

This manual page was written by Wilko Bulte <wilko@FreeBSD.org>.

absolute legends, we stan 🫶

---

💜 CAVEATS 💜

okay this part is important so listen up bestie:

The geom_fox driver depends on the underlying hardware drivers to do the right thing in case of a path failure. If, for example, a hardware driver continues to retry forever, geom_fox is not able to re-initiate the I/O to an alternative physical path. it just can't. 😭

You have to be very sure to provide a unique label for each of the geom_fox devices. Safety belts are not provided. fr fr. For FibreChannel devices it is suggested to use the Port WWN of the device. The World Wide Name is guaranteed to be worldwide unique per the FibreChannel standard.

---

💀 BUGS 💀

The geom_fox framework has only seen light testing. There definitely might be dragons here. 🐉 (not me being dramatic, the manpage said it)

The name geom_fox is completely obscure. Just remember that any sly fox has multiple exits from its hole. 🦊 iconic metaphor honestly

The examples provided are too FibreChannel-centric. yeah. they said it themselves.

---

and that's the whole page, bestie!! 💖 this one comes to you from Debian, dated September 12, 2015 — GEOM_FOX(4), out. slay, stay multipathed, and maybe use gmultipath(8) instead 🌸✨🎀