docs/177514: Handbook ZFS examples do not cover dataset creation within /home to permit quotas or mention possible overwrite w/ "zfs create"

[Bryan Bosworth]

>Number:         177514
>Category:       docs
>Synopsis:       Handbook ZFS examples do not cover dataset creation within /home to permit quotas or mention possible overwrite w/ "zfs create"
>Confidential:   no
>Severity:       non-critical
>Priority:       low
>Responsible:    freebsd-doc
>State:          open
>Quarter:        
>Keywords:       
>Date-Required:
>Class:          change-request
>Submitter-Id:   current-users
>Arrival-Date:   Sat Mar 30 22:20:00 UTC 2013
>Closed-Date:
>Last-Modified:
>Originator:     Bryan Bosworth
>Release:        9.0-release
>Organization:
Johns Hopkins University
>Environment:
FreeBSD FREEBSD 9.0-RELEASE FreeBSD 9.0-RELEASE #0: Tue Jan  3 07:46:30 UTC 2012     root at farrell.cse.buffalo.edu:/usr/obj/usr/src/sys/GENERIC  amd64
>Description:
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). 
>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
>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.

>Release-Note:
>Audit-Trail:
>Unformatted: