Bug 177514 - [handbook] ZFS examples do not cover dataset creation within /home to permit quotas or mention possible overwrite w/ "zfs create"
Summary: [handbook] ZFS examples do not cover dataset creation within /home to permit ...
Status: Closed FIXED
Alias: None
Product: Documentation
Classification: Unclassified
Component: Documentation (show other bugs)
Version: Latest
Hardware: Any Any
: Normal Affects Only Me
Assignee: freebsd-doc (Nobody)
URL:
Keywords:
Depends on:
Blocks:
 
Reported: 2013-03-30 22:20 UTC by Bryan Bosworth
Modified: 2020-05-23 12:33 UTC (History)
1 user (show)

See Also:


Attachments

Note You need to log in before you can comment on or make changes to this bug.
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 freebsd_triage 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.