ZFS user/group quotas & space accounting [PSARC/2009/204 FastTrack timeout 04/08/2009]

Tue Apr 14 16:50:16 PDT 2009

No outstanding issues, timer expired last Wednesday.  I'm marking this case 
closed approved.

--matt

Matthew Ahrens wrote:
> Template Version: @(#)sac_nextcase 1.68 02/23/09 SMI
> This information is Copyright 2009 Sun Microsystems
> 1. Introduction
>     1.1. Project/Component Working Name:
> 	 ZFS user/group quotas & space accounting
>     1.2. Name of Document Author/Supplier:
> 	 Author:  Matthew Ahrens
>     1.3  Date of This Document:
> 	30 March, 2009
> 4. Technical Description
> ZFS user/group space accounting
> 
> A. SUMMARY
> 
> This case adds support to ZFS for user/group quotas & per-uid/gid space
> tracking.
> 
> B. PROBLEM
> 
> Enterprise customers often want to know who is using space, based on
> what uid and gid owns each file.
> 
> Education customers often want to apply per-user quotas to hundreds of
> thousands of users.  In these situations, the number of users and/or
> existing infrastructure prohibits using one filesystem per user and
> setting filesystem-wide quotas.
> 
> C. PROPOSED SOLUTION
> 
> 1. Overview
> 
> Each filesystem keeps track of how much space inside it is owned by each
> user (uid) and group (gid).  This is the amount of space "referenced",
> so relationships between filesystems, descendents, clones, and snapshots
> are ignored, and each tracks their "user used" and "group used"
> independently.  This is the same policy behind the "referenced",
> "refquota", and "refreservation" properties.  The amount of space
> charged is the amount of space reported by struct stat's st_blocks and
> du(1).
> 
> Both POSIX ids (uid & gid) and untranslated SIDs are supported (eg, when
> sharing filesystems over SMB without a name service translation set up).
> 
> ZFS will now enforce quotas on the amount of space referenced by files
> owned by particular users and groups.  Enforcement may be delayed by
> several seconds.  In other words, users may go a bit over their quota
> before the system notices that they are over quota and begins to refuse
> additional writes with EDQUOT.  This decision was made to get the
> feature to market in a reasonable time, with a minimum of engineering
> resources expended.  The design and implementation do not preclude
> implementing strict enforcement at a later date.
> 
> User space accounting and quotas "stick with" each dataset (snapshot,
> filesystem, and clone).  This means that user quotas (and space
> accounting) are not inherited.  They will be "copied" to a new snapshot,
> and keep the values they had at the time the snapshot was taken.
> Likewise, user quotas will be "copied" to a clone (from its origin
> snapshot), and they will be copied with "zfs send" (even without -R).
> (User accounting and quota information is not actually copied to
> snapshots and clones, just referenced and copied-on-write like other
> filesystem contents.)
> 
> The user space accounting and quotas is reported by the new
> userused@<user>, groupused@<group>, userquota@<user>, and
> groupquota@<group> properties, and by the new "zfs userspace" and "zfs
> groupspace" subcommands, which are detailed below.
> 
> 2. Version Compatibility
> 
> To use these features, the pool must be upgraded to a new on-disk
> version (15). Old filesystems must have their space accounting
> information initialized by running "zfs userspace <fs>" or upgrading the
> old filesystem to a new on-disk version (4).  To set user quotas, the
> pool and filesystem must both be upgraded.
> 
> 3. Permissions
> 
> Setting or changing user quotas are administrative actions, subject to
> the same privilege requirements as other zfs subcommands.  There are new
> "userquota" and "groupquota" permissions which can be granted with "zfs
> allow", to allow those properties to be viewed and changed.
> 
> Unprivileged users can only view their own userquota and userused, and
> the groupquota and groupused of any groups they belong to.  The new
> "userused" and "groupused" permissions can be granted with "zfs allow"
> to permit users to view these properties.
> 
> The existing "version" permission (granted with "zfs allow") permits the
> accounting information to be initialized by "zfs userspace".
> 
> 4. New Properties
> 
> user/group space accounting information and quotas can be manipulated
> with 4 new properties:
> 
> zfs get userused@<user> <fs|snap>
> zfs get groupused@<group> <fs|snap>
> 
> zfs get userquota@<user> <fs|snap>
> zfs get groupquota@<group> <fs|snap>
> 
> zfs set userquota@<user>=<quota> <fs>
> zfs set groupquota@<user>=<quota> <fs>
> 
> The <user> or <group> is specified using one of the following forms:
> posix name (eg. ahrens)
> posix numeric id (eg. 126829)
> sid name (eg. ahrens at sun)
> sid numeric id (eg. S-1-12345-12423-125829)
> 
> For "zfs set", if a nonexistent name is specified, an error is
> generated.  Any numeric ID is permitted.  For "zfs get", if a
> nonexistent name is specified, "-" is printed for the value, indicating
> that there is no value available (like "zfs get nonexistent:userproperty").
> 
> As with filesystem quotas ("quota" and "refquota" properties), user
> quotas can be set to a value larger than the available space.
> 
> User quotas can also be set to a value less than the amount of space
> used by that user, effectively forcing that user to reduce their space
> utilization.
> 
> These new properties are not printed by "zfs get all", since that could
> generate a huge amount of output, which would not be very well
> organized.  The new "zfs userspace" subcommand should be used instead.
> 
> 5. New Subcommands
> 
> Two new subcommands are added: "zfs userspace" and "zfs groupspace":
> 
> zfs {user|group}space [-hniHp] [-o field[,...]] [-sS field] ...
>     [-t type [,...]] <filesystem|snapshot>
> 
> Typical output is like this:
> TYPE        NAME         USED  QUOTA  
> POSIX User  ahrens        14M     1G  
> POSIX User  george      56.5M   none  
> POSIX User  lling        258M   500M  
> SMB User    marks at sun    103M   none
> 
> Option flags:
> 
> -h	Show help message and exit.
> 
> -n	Print numeric ID instead of user/group name (like "ls -n")
> 
> -i	Translate SID to POSIX ID.  The POSIX ID may be ephemeral if no
> 	mapping exists.  Normal POSIX interfaces (eg, stat(2), "ls -l")
> 	perform this translation, so the -i option allows the output
> 	from "zfs userspace" to be compared directly with those
> 	utilities.  However, -i may lead to confusion if some files were
> 	created by a SMB user before a SMB -> POSIX name mapping was
> 	established.  In that case some files are owned by the SMB
> 	entity and some by the POSIX entity.  The -i flag will report
> 	that the POSIX entity has the total usage and quota for both
> 	entities.
> 
> -H	Do not print headers, use tab-delimited output (like "zfs list/get -H")
> 
> -p	Use exact (parsable) numeric output (like "zfs get -p")
> 
> -o field[,...]
> 	Print only the specified fields (like "zfs list/get -o"), from
> 	the following set: type,name,used,quota.  The default is to
> 	print all fields.
> 
> -s field
> 	Sort output by this field (like "zfs list -s").  The -s (and -S)
> 	flag may be specified multiple times to sort first by one field,
> 	then by another.  The default is "-s type -s name".
> 
> -S field
> 	Sort by this field in reverse order, see -s.
> 
> -t type[,...]
> 	Print only the specified types (like "zfs list -t"), from the
> 	following set: all,posixuser,smbuser,posixgroup,smbgroup.  The
> 	default for "zfs userspace" is "-t posixuser,smbuser".  The
> 	default for "zfs groupspace" is "-t posixgroup,smbgroup".  This
> 	is the only difference between the two subcommands, and in fact
> 	"zfs userspace -t posixgroup" is perfectly valid.
> 
> 6. Stability
> 
> This case requests patch/micro release binding.  The new interfaces are
> committed.
> 
> 
> 6. Resources and Schedule
>     6.4. Steering Committee requested information
>    	6.4.1. Consolidation C-team Name:
> 		ON
>     6.5. ARC review type: FastTrack
>     6.6. ARC Exposure: open