Resource icon

Terminology and Abbreviations Primer

We realize that new users have a lot to learn when they come to FreeNAS. There's a certain amount of confusion added to discussions when users pick random/approximate terms to describe things. I've spent a lot of time quietly trying to translate terms on the reader's side when reading posts, and that's probably a bad thing, so instead I'm going to refer people here and ask them to fix their posts.

Here's a short guide to common errors and proper terminology. This isn't really intended to be a full discussion of these issues, and there are full primers for some of the underlying topics. This is more of a "what not to say."


ZFS uses a parity strategy that has some superficial similarities to RAID5 and RAID6. These are NOT actually RAID5 or RAID6, though. RAID5/6 store parity data in precomputed sectors on each hard disk. ZFS computes parity data for each block of data stored and tacks it on along with the block being stored. ZFS blocks are variable length and can be up to 128KB. Since it is theoretically possible (but very bad) to create a ZFS system on top of a hardware RAID controller that uses RAID5, saying "RAID5" when you mean "RAIDZ1" is very confusing.

RAID5 and RAIDZ1 have a single disk worth of parity.
RAID6 and RAIDZ2 have two disks worth of parity.
RAIDZ3 is a ZFS vdev with three disks worth of parity.


Try to avoid saying "ZRAID" (meaningless), and "RAIDZ" by itself is often also confusing and is often wrong, because there are differences between "RAIDZ1", "RAIDZ2", and "RAIDZ3." It is fine to refer to "RAIDZ" if you're discussing pool design at a high level compared to mirrors or something like that. "ZFS1" and "ZFS2" are strange terms at best; do you mean a ZFS version 1 pool?

GOOD: mirror vdev

ZFS uses a mirror virtual device ("vdev") to perform the same function as a RAID1 mirror. A mirror vdev consists of two or more disks with identical content. Once again, avoid "RAID1" if you mean "mirror vdev" because it is theoretically possible to create a ZFS system on top of a hardware RAID controller that uses RAID1.

BETTER: striped vdevs

RAID controllers are built around trying to provide a unified LBA device view to the host that looks like a hard disk. They need to be able to compute stripe sizes in order to understand how to retrieve blocks from their underlying disks. ZFS doesn't need to be so uptight, and merely sees a pool that is a collection of vdevs. In general, ZFS will try to balance writes between vdevs, and in the ideal case appears to be something similar to striping. It is not, however, strictly striping. It is intelligent allocation and retrieval. Nevertheless, we frequently refer to it as "striped vdevs." While this is a poor term, it is what we've got.

Once again, avoid "RAID10/RAID50/RAID60" if you mean "striped vdevs" because it is theoretically possible to create a ZFS system on top of a hardware RAID controller that uses RAID.

BAD (when misused): ZIL

Every ZFS pool contains a ZFS Intent Log to comply with POSIX sync write commit requirements. ZFS uses a transaction group to commit writes, and it is impractical to commit a transaction group for every synchronous write.

Many new users, and even some experienced ZFS pros, mistakenly use the term "ZIL" to refer to a separate ZFS intent log device (such as an SSD). The ZIL can be separated from the pool and moved to a separate log (SLOG) device, which greatly increases performance, but every pool has a ZIL regardless of whether it is in-pool or a separate device. Sync writes are always committed to the ZIL unless sync writes are disabled.

It's fine and dandy to say ZIL if you're talking about the mechanism ZFS uses to commit a sync write to the pool outside the transaction group mechanism. But almost no one discusses that without also meaning that they've moved it to an external device, which should be referred to as a SLOG. They are related-but-separate terms.

BAD: GB/s, MB/s, Gb/s, Mb/s, mb, meg, gig
GOOD: GByte/sec, MByte/sec, Gbit/sec, Mbit/sec, etc.

So many people get this wrong. Big "B" means bytes. Little "b" means bits. But too many people cannot get that right, and we have numerous examples of people meaning "megabytes/sec" and saying "Mb/s," etc. My favorite has to be "mb". Is that megabytes? Megabits? Motherboard?

Be specific and type out the word. We're not snobs and you can type "megabit/sec" or "Megabytes/sec" or any nonambiguous term and it's happy days. But I'm going to scream if I see one more guy with a Realtek ethernet come in and describe his problem as "I only get 70Mb/s", which'd be a problem if he was only getting 70 megabits/sec (what he SAID), but is actually getting 70 megabytes/sec (what he's GETTING and what the stupid chip is probably maxxing out at). Networking people often talk about "Mbps" and "Gbps" which are megabits per second and gigabits per second, which is fine as long as nobody screws those abbreviations up.

Don't be lazy. Type it out enough to be unambiguous.

MEH: zpool
YEAH: pool

A lot of people add unnecessary Z's with ZFS. It's a little overwhelming at first. "zpool" is actually a command to manipulate a ZFS pool. You can refer to a ZFS pool as a "zpool," and in the early days of ZFS a lot of people (including the designers) did, but you can safely omit the Z on zpool.

Got a suggestion to add to this list of terminology fails? Feel free to post in the discussion thread, accessible via the tabs above.
First release
Last update
4.50 star(s) 2 ratings

More resources from jgreco

Latest reviews

Great for beginners.

Perhaps adding ARC is similar to, but not the same as OS level file system cache. And explain the difference in straight forward wording.

Plus, after the ARC section, perhaps adding a L2ARC paragraph.

Then add a section on Special Metadata vDevs.

Last mention De-duplication. My suggestion here would be to state if you don't know how to design and implement, so that you have to ask beginner questions, then you should NOT be using De-duplication.

I am not saying these new sections should be all encompassing, but adding the general description and pointers to more detailed information, I would think would be help full.
As a total noob, I appreciate the effort and am very grateful for the clarity. I didn't feel it deserves 5 stars because the title is misleading; it suggests much broader coverage than just RAID terms.
I am not sure anyone would expect it to have a scope greater than the things on this forum. The general problem we've faced is that users will come in and start talking about their RAID5 ZFS setup. Does that mean the user has actually set up ZFS on top of a RAID5 hardware volume (not as uncommon as you'd think), or really meant RAIDZ(1), or even RAIDZ2 (seen it). The problem is that you can waste a lot of time starting to talk about why you shouldn't run ZFS on top of RAID5 only to find out the user was simply using incorrect terminology.

There are a lot of other areas where there are multiple words (disk/drive, motherboard/mainboard/system board, NIC/ethernet, etc) but where the choice of words does not result in actual miscommunication. If there's something that's missing from the primer that you feel ought to be there, let me know.