Page MenuHomeFreeBSD

Use ada device names in ZFS handbook chapter instead of legacy da or ad
Needs ReviewPublic

Authored by bcr on Fri, May 30, 8:13 AM.
Tags
None
Referenced Files
Unknown Object (File)
Thu, Jun 5, 3:55 PM
Unknown Object (File)
Tue, Jun 3, 3:09 AM
Unknown Object (File)
Sun, Jun 1, 1:32 AM

Details

Reviewers
delphij
Group Reviewers
Doc Committers
Summary

The ZFS handbook chapter originated from a time when we used different device names like da or ad (with or without partitions). Newer sections added of the chapter used the current device name (ada). To avoid confusion, use the same device naming scheme throughout the chapter.

Reflow the df outputs to match the tabular output again. Removed some outdated sentence that still differentiated between the new and old device names.

See also Bug 287148

Test Plan
  1. Apply the patch
  2. build the handbook
  3. Review the output

Diff Detail

Repository
R9 FreeBSD doc repository
Lint
Lint Skipped
Unit
Tests Skipped

Event Timeline

bcr requested review of this revision.Fri, May 30, 8:13 AM

Removed a sentence fragment which is no longer relevant since it deals with one of the old device names.

Show how to create the GPT partitions of type freebsd-zfs in the quickstart section first. Use the GPT partitions to create pools as well as all zpool status outputs.

Than you for taking action on this! However, this only addresses one issue with the chapter in question and FreeBSD uses labels for zpool creation by default with bsdinstall(8), which is considered a best practice. I have a draft article in the PR for inspiration on a broader approach.

delphij requested changes to this revision.Sat, May 31, 1:09 PM
delphij added inline comments.
content/en/books/handbook/zfs/_index.adoc
101

I think it's worth mentioning that SCSI/SAS devices would show up as da devices (not to be confused to the old ata(4) driver's ad devices).

107–108

It's probably worth mentioning _why_ one may or may not want to create partition for ZFS.

One potentially useful scenario is that the administrator is not sure if they would be able to get replacement drives at a later time that is at least the same size of the current hard drive, this happens for some consumer grade hard drives (for example, different manufactures may have different opinion on how big 4TB is), so it used to be helpful to create a slightly smaller partition, let's say use a few gigabytes as spare space or even as a swap partition for each drive, to give the administrator a peace of mind that when they purchased a replacement drive they are guaranteed to have the partition properly sized (and when one replaces drive, it's likely because the current drive is failing or already failed, and getting something that can't be used would create more stress in such situations). This, however, may be seen as a waste of space by some other people, because one can always purchase a larger drive to replace the smaller, older drive.

Another potential use case is to make it easier to utilize GPT's label feature, for example one can name the partition in a more meaningful way, like '/dev/gpt/disk0' or '/dev/gpt/<SERIAL>-data', etc. when the administrator deliberately wanted to avoid using /dev/diskid/ devices.

That's said, there are indeed some legitimate reasons to create partition, but it's not really required. I personally create partitions on my own systems, usually because I want to do full disk encryption for the data storage and also have redundant boot devices at the same time (so I must use two or even three partitions per drive), but for single drive pools, creating partitions is probably not particularly helpful.

117

maybe zpool list / zpool status here instead of df?

This revision now requires changes to proceed.Sat, May 31, 1:09 PM

On @delphij's suggestion, I've changed a sentence below the SATA examples to use da in case of SCSI/SAS devices.