Bug 177514

Summary:	[handbook] ZFS examples do not cover dataset creation within /home to permit quotas or mention possible overwrite w/ "zfs create"
Product:	Documentation	Reporter:	Bryan Bosworth <bryan.bosworth>
Component:	Books & Articles	Assignee:	freebsd-doc (Nobody) <doc>
Status:	Closed FIXED
Severity:	Affects Only Me	CC:	bcr
Priority:	Normal
Version:	Latest
Hardware:	Any
OS:	Any

Description Bryan Bosworth 2013-03-30 22:20:00 UTC

Section 21.2 of the Handbook is excellent and very helpful for setting up ZFS, but  in 21.2.2.5 ZFS Quotas it does not create a dataset for storage/home/bob. When I followed the instructions in a virtual machine, ZFS initially complained that there is no dataset for bob. 

When I did create a dataset with "zfs create storage/home/bob" it overwrote the user's home directory with a new one with root:root permissions. I have seen people report the same problem online (overwriting a directory by creating a dataset at the same location).

Fix: 

As far as I know, a dataset is required for ZFS to enforce a quota. Thus, a dataset for each /home/username directory must be created with "zfs create poolname/home/username" preferably before the user is added. 

In my experience, adding the user after dataset creation sets the correct permissions for the directory and the quota appears as the drive size e.g. when /home/bob is mounted as a Samba share.
How-To-Repeat: Create ZFS pool storage with dataset storage/home mounted on /home
Create user bob with home: /home/bob
"zfs create storage/home/bob" to permit quotas on storage/home/bob
"zfs set quota=5G storage/home/bob" now works, but the user directory has been overwritten

Comment 1 Eitan Adler freebsd_committer

2017-12-31 07:59:33 UTC

For bugs matching the following criteria:

Status: In Progress Changed: (is less than) 2014-06-01

Reset to default assignee and clear in-progress tags.

Mail being skipped

Comment 2 Benedict Reuschling freebsd_committer

2020-05-19 09:59:49 UTC

I've added a review here for a potential fix:
https://reviews.freebsd.org/D24913

Comment 3 commit-hook freebsd_committer

2020-05-23 12:32:28 UTC

A commit references this bug:

Author: bcr
Date: Sat May 23 12:31:38 UTC 2020
New revision: 54178
URL: https://svnweb.freebsd.org/changeset/doc/54178

Log:
  Add explanation to the ZFS quota examples about /home.

  The ZFS quota examples started with setting quotas for a user that was not
  created in the chapter. This led to some confusion for (new) people who tried
  out the example and got an error message about the missing user.
  Add a small paragraph to explain this concept and that ideally, when creating
  a user, the /home dataset should be created first to not shadow it afterwards.

  PR:		    177514
  Submitted by:	    Bryan Bosworth
  Reviewed by:	    noone (5 day review timeout)
  Differential Revision:	https://reviews.freebsd.org/D24913

Changes:
  head/en_US.ISO8859-1/books/handbook/zfs/chapter.xml

Comment 4 Benedict Reuschling freebsd_committer

2020-05-23 12:33:40 UTC

I added a small paragraph to the beginning of the zfs quota examples to explain that the user must exist before trying them. Thanks for filing the PR and sorry it took so long to fix it.