• This site uses cookies. By continuing to use this site, you are agreeing to our use of cookies. Learn more.

Excellent ZFS section in FreeBSD handbook



Thanks: 419
Messages: 1,210

It's definitely an improvement on the old ZFS page it has replaced. I just wish they'd changed the following text rather that copying it pretty much intact from the original:

This output shows that the example pool has been created and mounted. It is now accessible as a file system. Files can be created on it and users can browse it:

[snip example file creation]

However, this pool is not taking advantage of any ZFS features. To create a dataset on this pool with compression enabled:
When I first started with ZFS and didn't fully understand all the concepts and wording, I really thought that the actual pool itself was mounted on /poolname, and that to make use of ZFS features/properties I needed to create a dataset manually. Now I know that the pool itself is basically a 'virtual storage volume' entirely managed by ZFS. You cannot access this and it is not possible to put files on it directly. When the pool is created, a single "root" ZFS dataset is created with the exact same name as the pool, and mounted. This dataset supports all the normal ZFS features, in fact you can set them at pool creation time using the -O option.

They continue to reinforce this misunderstanding further down:

The pool and file system may also be observed by viewing the output from mount:

# mount
/dev/ad0s1a on / (ufs, local)
devfs on /dev (devfs, local)
/dev/ad0s1d on /usr (ufs, local, soft-updates)
example on /example (zfs, local)
example/data on /example/data (zfs, local)
example/compressed on /example/compressed (zfs, local)
The mount output does not show the "pool and file system", it shows 3 file systems (ZFS datasets) that have been created on top of the pool.

I'd raise a bug report but the last (and only) doc bug I raised a few months ago hasn't been touched, even to acknowledge it or assign to the correct team, and this isn't really serious enough to start chasing people on the mailing lists. It just was one thing that really confused me when I was first trying to understand the whole ZFS storage concept.


Staff member

Thanks: 3,558
Messages: 13,856

@usdmatt, please enter a PR, and send me the number of the earlier one. I can't promise anyone will take the old PR, these are all handled by only a few volunteers, but I can look at it.

I'm certain there are one or two people who will be very interested in PRs for this new chapter.
Last edited by a moderator:


Active Member

Messages: 122

I found mention of this new section in another post and went over and read some of it; I found it informative.
Having run PC-BSD10 for a while, I decided against it because I didn't know anything about ZFS, and it would have been too difficult for me to get it set up with UFS.
I now have an understanding of the basics, thanks entirely to this new chapter; I think it explains things well.