Resource icon

Terminology and Abbreviations Primer

jgreco

Resident Grinch
Joined
May 29, 2011
Messages
18,681
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."


BAD: RAID5, RAID6
GOOD: RAIDZ1, RAIDZ2, RAIDZ3

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.

BAD: ZRAID, RAIDZ, ZFS1, ZFS2
GOOD: RAIDZ1, RAIDZ2, RAIDZ3

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?

BAD: RAID1
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.

BAD: RAID10, RAID50, RAID60
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
GOOD: SLOG

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 (when misused): cache, SSD cache, etc.
GOOD: ARC, L2ARC, SLOG (SLOG is not even a cache!)

The term "cache" ("cache drive" etc) is widely misused by people coming from other storage systems. The worst of this is when a poster misunderstands the way ZFS works ("write cache drive").

ZFS has no "write cache" device. ZFS caches writes in system RAM as part of a transaction group that will be written out to disk. This happens at system RAM write speed. Some new to the community have misunderstood SLOG to be a "write cache" device. It isn't. It's a write log device. The ZIL and SLOG are explained in this linked article. Turning sync writes on is a significant performance hit for most applications, and a SLOG device is intended to speed that up, but there is no case where it makes it faster than simply turning off sync writes.

ZFS has massive read caching capabilities. The primary ZFS cache is in RAM and called the Adaptive Read Cache (ARC). A secondary level of cache, L2ARC, can be handled by SSD. Using the terms "ARC", "L2ARC", and "SLOG" appropriately helps avoid ambiguity over the hideously vague term "SSD cache".

BAD: GB/s, GBps, MB/s, MBps, 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.

BAD: "150 MB", "SATA 1", "SATA 2", "SATA 3", and to a lesser extent, "SAS 1", "SAS 2", "SAS 3"
GOOD: "SATA I", "SATA II", "SATA III", or "SATA 1.5Gbps", "SATA 150MByte/sec", "SAS 3Gbps", etc.

I don't know about anyone else, but I had trouble parsing "Transfers of 150 MB only" in a thread recently. The possibility that the poster meant that the drive had only negotiated at 150 MBytes/sec wasn't even in my top 5 list of "wtf might this mean." This is worse because "SATA I" is 1.5Gbps whereas SAS-1 is 3Gbps, SATA-II is 3Gbps whereas SAS-2 is 6Gbps. I know it's confusing! I didn't create the versioning for these things. But if you really want to get your point across with less chance of misunderstanding, go for more detail where possible. No one can credibly misunderstand if you type "SAS-2 (6Gbps)", but you can get away with somewhat less and still be unambiguous.

BAD: array
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 a followup. I'll probably nuke responses and integrate suitable suggestions into the first post.
 

jgreco

Resident Grinch
Joined
May 29, 2011
Messages
18,681
Sure, of course they are familiar with them, but the problem is that they might not understand them and they definitely do not reliably WRITE them. Part of the confusion is exactly that networking describes things in Mbps or Gbps but disk copies and many other operations are measured in MBytes/sec. My favorite is ... what idiot utility is it that displays speed in "mb/s" (all lowercase)? Can't remember.
 

Bidule0hm

Server Electronics Sorcerer
Joined
Aug 5, 2013
Messages
3,710
I find it's simpler to use the ratio (the value is easy to remember) --> TB * 0.909 = TiB. But the point was to explain the difference in the first post, but jgreco doesn't like the idea :P
 

jgreco

Resident Grinch
Joined
May 29, 2011
Messages
18,681
My original idea was more along the lines of a "what not to write" but I'm contemplating your comment.
 

Bidule0hm

Server Electronics Sorcerer
Joined
Aug 5, 2013
Messages
3,710
Ok, I see ;)

What the hell happened to the others posts on this thread? you've done some cleaning or?
 

jgreco

Resident Grinch
Joined
May 29, 2011
Messages
18,681
Yeah, I've been more aggressively cleaning up stickies lately, and sometimes locking them. It doesn't do us a lot of good to have pages of tangentially related or sometimes irrelevant posts attached. I do like people to be able to provide feedback though. I could also move it to a discussion thread if that's more palatable.
 

Ericloewe

Server Wrangler
Moderator
Joined
Feb 15, 2014
Messages
20,175
Yeah, I've been more aggressively cleaning up stickies lately, and sometimes locking them. It doesn't do us a lot of good to have pages of tangentially related or sometimes irrelevant posts attached. I do like people to be able to provide feedback though. I could also move it to a discussion thread if that's more palatable.

What we really need is a working "Resources" section, where we can move the important stickies, leaving the discussions in a different thread.
 

Bidule0hm

Server Electronics Sorcerer
Joined
Aug 5, 2013
Messages
3,710
Ah ok, no problem ;)

@Ericloewe Yeah, I totally agree, there is already the section "How-To Guides" for that but the stickies are spread everywhere (and as a member you can't post in this section so you're forced to post elsewhere and then ask a moderator/admin to move your how-to). And the section "Resources" should really be named "External Resources" I think. Just my two cents :)
 

Ericloewe

Server Wrangler
Moderator
Joined
Feb 15, 2014
Messages
20,175
What we really need is a working "Resources" section, where we can move the important stickies, leaving the discussions in a different thread.
Two years later, this is actually a thing! This is now available in the Resources section.
 

scwst

Explorer
Joined
Sep 23, 2016
Messages
59
I would like to suggest a new point - either here or in the FreeNAS FAQ - that explains why FreeNAS has decided to ditch standard ZFS terminology and calls a "pool" a "volume", though ZFS actually already uses "volume" for something totally different ("zvol"). Given the way ZFS is taking off with Linux, this is bound to get very confusing really fast for people who are familiar with ZFS and come to FreeNAS, which admittedly was probably a very small number until now.

Now ideally, I'd actually want suggest replacing "volume" by "pool" to confirm to standard ZFS terminology, but I'm assuming that somebody made this change for a good reason, though I can't seem to find that reason in the docs (sorry if I missed). This Terminology Primer might be a good place to explain the change.
 

Ericloewe

Server Wrangler
Moderator
Joined
Feb 15, 2014
Messages
20,175
I would like to suggest a new point - either here or in the FreeNAS FAQ - that explains why FreeNAS has decided to ditch standard ZFS terminology and calls a "pool" a "volume", though ZFS actually already uses "volume" for something totally different ("zvol"). Given the way ZFS is taking off with Linux, this is bound to get very confusing really fast for people who are familiar with ZFS and come to FreeNAS, which admittedly was probably a very small number until now.

Now ideally, I'd actually want suggest replacing "volume" by "pool" to confirm to standard ZFS terminology, but I'm assuming that somebody made this change for a good reason, though I can't seem to find that reason in the docs (sorry if I missed). This Terminology Primer might be a good place to explain the change.
IIRC, the docs team insisted on this change way back in the day. I don't remember what the reason was supposed to be, but I remember that I found it unconvincing, for reasons similar to the ones you state.
 

wblock

Documentation Engineer
Joined
Nov 14, 2014
Messages
1,506
Pretty sure this was not a docs team thing. A lot of stuff has been... let's be charitable and say "credited" to us.
 

jgreco

Resident Grinch
Joined
May 29, 2011
Messages
18,681
I would like to suggest a new point - either here or in the FreeNAS FAQ - that explains why FreeNAS has decided to ditch standard ZFS terminology and calls a "pool" a "volume", though ZFS actually already uses "volume" for something totally different ("zvol"). Given the way ZFS is taking off with Linux, this is bound to get very confusing really fast for people who are familiar with ZFS and come to FreeNAS, which admittedly was probably a very small number until now.

Now ideally, I'd actually want suggest replacing "volume" by "pool" to confirm to standard ZFS terminology, but I'm assuming that somebody made this change for a good reason, though I can't seem to find that reason in the docs (sorry if I missed). This Terminology Primer might be a good place to explain the change.

I didn't realize this was happening. But I'm an equal opportunity kind of guy, and I'm fine with calling whoever decided to call it a volume in FreeNAS wrong and confusing. The whole point of this post would be to encourage harmonization of terminology, to encourage better communication, and I'd say that @scwst is right and that FreeNAS probably shouldn't be calling it a volume.

"Volume" is like the worst term. It is used by different storage technologies to refer to a variety of things. Maybe @dlavigne can shed some light?
 

joeschmuck

Old Man
Moderator
Joined
May 28, 2011
Messages
10,970
Why not just do the right thing here and plan to make a change to correct all the terminology in a future change. It would need to be planned out for say release 11.2 or something. This means the docs would need to be changed as well. Maybe in the docs you could say "pool (volume)" during the transition period and then on FreeNAS 12 call it "pool". You get my point. I too would like it to be common terminology.

As for the history of this, I'm almost positive that this was the terminology used in FreeNAS 0.7, our origin.
 

Ericloewe

Server Wrangler
Moderator
Joined
Feb 15, 2014
Messages
20,175
As for the history of this, I'm almost positive that this was the terminology used in FreeNAS 0.7, our origin.
Maybe it was a compromise to unify ZFS and GEOM/UFS terminology.
 

joeschmuck

Old Man
Moderator
Joined
May 28, 2011
Messages
10,970

Chris Moore

Hall of Famer
Joined
May 2, 2015
Messages
10,080

Ericloewe

Server Wrangler
Moderator
Joined
Feb 15, 2014
Messages
20,175
Yeah, that is wrong.
 

Chris Moore

Hall of Famer
Joined
May 2, 2015
Messages
10,080
Top