From sacadmin Wed Aug 23 13:28:12 2006 Received: from pacifica.sfbay.sun.com (pacifica.SFBay.Sun.COM [129.146.228.204]) by sac.sfbay.sun.com (8.13.6+Sun/8.13.6) with ESMTP id k7NKSBt0024059; Wed, 23 Aug 2006 13:28:12 -0700 (PDT) Received: from pacifica.sfbay.sun.com (localhost [127.0.0.1]) by pacifica.sfbay.sun.com (8.13.7+Sun/8.13.7) with ESMTP id k7NKOuOU108644; Wed, 23 Aug 2006 13:24:56 -0700 (PDT) Received: (from ahrens@localhost) by pacifica.sfbay.sun.com (8.13.7+Sun/8.13.7/Submit) id k7NKOutF108640; Wed, 23 Aug 2006 13:24:56 -0700 (PDT) Date: Wed, 23 Aug 2006 13:24:56 -0700 (PDT) From: Matthew Ahrens Message-Id: <200608232024.k7NKOutF108640@pacifica.sfbay.sun.com> To: PSARC@sac.sfbay.sun.com Cc: eric.schrock@sun.com Subject: ZFS user properties [PSARC/2006/504 Timeout: 08/31/2006] Status: RO Content-Length: 8928 Subject: PSARC FastTrack [08/31/2006]: ZFS user properties Template Version: @(#)sac_nextcase %I% %G% SMI This information Copyright 2006 Sun Microsystems 1. Introduction 1.1. Project/Component Working Name: ZFS user properties 1.2. Name of Document Author/Supplier: Author: Eric Schrock 1.3 Date of This Document: 23 August, 2006 4. Technical Description This case introduces a new class of user-defined properties for ZFS. The stability of the options is committed, and the release binding is patch/micro. The proposal has been discussed with the community at: http://www.opensolaris.org/jive/thread.jspa?threadID=12405 A. INTRODUCTION ZFS currently supports a well-defined set of properties for managing ZFS datasets. These properties represent either read-only statistics exported by the ZFS framework ('available', 'compressratio', etc), or editable properties which affect the behavior of ZFS ('compression', 'readonly', etc). While these properties provide a structured way to interact with ZFS, a common request is to allow unstructured properties to be attached to ZFS datasets. This is covered by the following RFE: 6281585 user defined properties This would allow administrators to add annotations to datasets, as well as allowing ISVs to store application-specific settings that apply to individual datasets. B. DETAILS This proposal adds a new classification of ZFS properties known as 'user properties'. The existing native properties will remain as-is, as they provide additional semantics (mainly validation) which are closely tied to the underlying implementation. Any property which contains a colon (':') is defined as a 'user property'. The name can contain lowercase characters, numbers, and the following special characters: ':', '-', '.', '_'. User properties are always strings, and are always inherited. No additional validation is done on the contents. Properties are set and retrieved through the standard mechanisms: 'zfs set', 'zfs get', and 'zfs inherit'. Inheriting a property which is not set in any parent is equivalent to clearing the property, as there is no default value for user-defined properties. The empty string is a valid setting for a user-defined property. It is expected that the colon will serve two purposes: to distinguish between native properties and provide an (unenforced) namespace for user properties. For example, it is hoped that properties are defined as ':', to group properties together and to provide a larger namespace for logical separation of properties. No enforcement of this namespace is done by ZFS, however, and the empty string is valid on both sides of the colon. C. EXAMPLES # zfs set local:department=12345 test # zfs get -r local:department test NAME PROPERTY VALUE SOURCE test local:department 12345 local test local:department 12345 local test/foo local:department 12345 inherited from test # zfs list -o name,local:department NAME LOCAL:DEPARTMENT test 12345 test/foo 12345 # zfs set local:department=67890 test/foo # zfs inherit local:department test # zfs get -s local -r all test NAME PROPERTY VALUE SOURCE test/foo local:department 12345 local # zfs list -o name,local:department NAME LOCAL:DEPARTMENT test - test/foo 12345 D. MANPAGE CHANGES --- zfs.old Mon Aug 21 10:12:52 2006 +++ zfs.new Wed Aug 23 10:18:02 2006 @@ -249,11 +249,19 @@ The global administrator can forcibly clear the "zoned" pro- perty, though this should be done with extreme care. The global administrator should verify that all the mount points are acceptable before clearing the property. - Properties + Native Properties + Properties are divided into two types, native properties and + user defined properties. Native properties export internal + statistics or control ZFS behavior. + User properties have no effect on ZFS behavior. For more + information on user properties, see the 'User Properties' + section, below. + Every dataset has a set of properties that export statistics about the dataset as well as control various behavior. Pro- perties are inherited from the parent unless overridden by @@ -283,12 +291,12 @@ Non-numeric properties are case sensitive and must be lower- case, except for "mountpoint" and "sharenfs". The first set of properties consist of read-only statistics about the dataset. These properties cannot be set, nor are - they inherited. Properties apply to all dataset types unless - otherwise noted. + they inherited. Native properties apply to all dataset types + unless otherwise noted. type The type of dataset: "filesystem", "volume", or "snapshot". @@ -761,10 +769,32 @@ option is an alias for "nodevices,nosetuid". These proper- ties are reported as "temporary" by the "zfs get" command. If the properties are changed while the dataset is mounted, the new setting overrides any temporary settings. + + User Properites + In addition to the standard native properties, ZFS + supports arbitrary user properties. User properties have no + effect on ZFS behavior, but applications or administrators can use + them to annotate datasets. + + User property names must contain + a colon (':') character, to distinguish them from native + properties. They may contain lowercase letters, + numbers, and the following punctuation characters: ':', '-', + '.', '_'. The expected convention is that the property name + will be divided into two portions such as ':', + but this namespace is not enforced by ZFS. + + The values of user properties are arbitrary strings, are always + inherited, and are never validated. All of the commands which + operate on properties ('zfs list', 'zfs get', 'zfs set', etc.) + can be used to manipulate both native properties and user + properties. To clear a user property, use 'zfs inherit'. If + the property is not defined in any parent dataset, it will be + removed entirely. + + Volumes as Swap or Dump Devices To set up a swap area, create a ZFS volume of a specific size and then enable swap on that device. For more informa- tion, see the EXAMPLES section. @@ -816,20 +846,20 @@ of blocks regardless of blocksize. -s Creates a sparse volume with no reservation. See - "volsize" in the Properties section for more infor- - mation about sparse volumes. + "volsize" in the Native Properties section for more + information about sparse volumes. -b blocksize Sets the "volblocksize" property, as described in - the Properties section. + the Native Properties section. zfs destroy [-rRf] filesystem|volume|snapshot @@ -969,13 +999,13 @@ -o prop A comma-separated list of properties to display. Must be one of the properties - described in the "Properties" section, - or the special value "name" to display - the dataset name. + described in the "Native Properties" + section, or the special value "name" to + display the dataset name. -t type A comma-separated list of types to display, where "type" is one of @@ -1029,11 +1059,11 @@ temporary, inherited, or none (-). All columns are displayed by default, though this can be controlled by using the -o option. This command takes a comma-separated list of properties as described in the - "Properties" section. + "Native Properties" and "User Properties" sections. The special value "all" can be used to display all pro- perties for the given dataset. @@ -1543,10 +1573,18 @@ # zfs create -V 5gb tank/vol # swap -a /dev/zvol/dsk/tank/vol + Example 13: Setting User Properties + + The following example sets the user defined + 'local:department' property for a dataset. + + # zfs set local:department=12345 tank/accounting + + EXIT STATUS The following exit values are returned: 0 Successful completion. 6. Resources and Schedule 6.4. Steering Committee requested information 6.4.1. Consolidation C-team Name: ON 6.5. ARC review type: FastTrack From sacadmin Wed Aug 23 13:38:33 2006 Received: from eastmail1bur.East.Sun.COM (eastmail1bur.East.Sun.COM [129.148.9.49]) by sac.sfbay.sun.com (8.13.6+Sun/8.13.6) with ESMTP id k7NKcXph024657 for ; Wed, 23 Aug 2006 13:38:33 -0700 (PDT) Received: from thunk.east.sun.com (thunk.East.Sun.COM [129.148.174.66]) by eastmail1bur.East.Sun.COM (8.13.6+Sun/8.13.6/ENSMAIL,v2.2) with ESMTP id k7NKcVNP005140; Wed, 23 Aug 2006 16:38:31 -0400 (EDT) Received: from localhost (localhost [127.0.0.1]) by thunk.east.sun.com (8.13.7+Sun/8.13.7) with ESMTP id k7NKcVTr023014; Wed, 23 Aug 2006 16:38:31 -0400 (EDT) Subject: Re: ZFS user properties [PSARC/2006/504 Timeout: 08/31/2006] From: Bill Sommerfeld To: Matthew Ahrens Cc: PSARC@sac.sfbay.sun.com, eric.schrock@sun.com In-Reply-To: <200608232024.k7NKOutF108640@pacifica.sfbay.sun.com> References: <200608232024.k7NKOutF108640@pacifica.sfbay.sun.com> Content-Type: text/plain Date: Wed, 23 Aug 2006 16:38:30 -0400 Message-Id: <1156365510.20770.108.camel@thunk> Mime-Version: 1.0 X-Mailer: Evolution 2.6.2 Content-Transfer-Encoding: 7bit Status: RO Content-Length: 1021 On Wed, 2006-08-23 at 13:24 -0700, Matthew Ahrens wrote: > It is expected that the colon will serve two purposes: to distinguish > between native properties and provide an (unenforced) namespace for user > properties. For example, it is hoped that properties are defined as > ':', to group properties together and to provide a > larger namespace for logical separation of properties. No enforcement > of this namespace is done by ZFS, however, and the empty string is valid > on both sides of the colon. We've been hurt in the past by not pre-reserving parts of an open-ended namespace like this one. (I'm specifically thinking of reserving namespace for other sun projects/products, which might want to use ZFS dataset properties, rather than reserving properties for ZFS's use itself, which is handled by the name-with-colon vs name-without-colon usage). Perhaps we could use a naming convention akin to the reversed-domain-name conventions used by Java (com.sun.foo:bar) ? - Bill From sacadmin Wed Aug 23 13:44:04 2006 Received: from zion.eng.sun.com (zion.SFBay.Sun.COM [129.146.17.75]) by sac.sfbay.sun.com (8.13.6+Sun/8.13.6) with ESMTP id k7NKi4Fw024840 for ; Wed, 23 Aug 2006 13:44:04 -0700 (PDT) Received: from zion.eng.sun.com (localhost [127.0.0.1]) by zion.eng.sun.com (8.13.7+Sun/8.13.7) with ESMTP id k7NKi3RJ009784; Wed, 23 Aug 2006 13:44:03 -0700 (PDT) Received: (from eschrock@localhost) by zion.eng.sun.com (8.13.7+Sun/8.13.7/Submit) id k7NKi3GF009783; Wed, 23 Aug 2006 13:44:03 -0700 (PDT) Date: Wed, 23 Aug 2006 13:44:03 -0700 From: Eric Schrock To: Bill Sommerfeld Cc: Matthew Ahrens , PSARC@sac.sfbay.sun.com Subject: Re: ZFS user properties [PSARC/2006/504 Timeout: 08/31/2006] Message-ID: <20060823204403.GB6462@eng.sun.com> References: <200608232024.k7NKOutF108640@pacifica.sfbay.sun.com> <1156365510.20770.108.camel@thunk> Mime-Version: 1.0 Content-Type: text/plain; charset=us-ascii Content-Disposition: inline In-Reply-To: <1156365510.20770.108.camel@thunk> User-Agent: Mutt/1.4.2.1i Status: RO Content-Length: 1165 On Wed, Aug 23, 2006 at 04:38:30PM -0400, Bill Sommerfeld wrote: > > We've been hurt in the past by not pre-reserving parts of an open-ended > namespace like this one. > > (I'm specifically thinking of reserving namespace for other sun > projects/products, which might want to use ZFS dataset properties, > rather than reserving properties for ZFS's use itself, which is handled > by the name-with-colon vs name-without-colon usage). > > Perhaps we could use a naming convention akin to the > reversed-domain-name conventions used by Java (com.sun.foo:bar) ? I'm perfectly happy stating that 'com.sun.' is a reserved prefix for user properties, but it's impossible for ZFS to actually enforce this rule, since we don't know from the ZFS level whether the consumer is a Sun product or not. We can expand on the 'suggested format', but there's really no way to programmatically enforce such a rule, apart from 'every local property must have a period before the first colon', but it seems rather silly to do this when we can't actually establish any namespace beyond that. - Eric -- Eric Schrock, Solaris Kernel Development http://blogs.sun.com/eschrock From sacadmin Wed Aug 23 13:50:43 2006 Received: from eastmail1bur.East.Sun.COM (eastmail1bur.East.Sun.COM [129.148.9.49]) by sac.sfbay.sun.com (8.13.6+Sun/8.13.6) with ESMTP id k7NKogX3024888 for ; Wed, 23 Aug 2006 13:50:43 -0700 (PDT) Received: from thunk.east.sun.com (thunk.East.Sun.COM [129.148.174.66]) by eastmail1bur.East.Sun.COM (8.13.6+Sun/8.13.6/ENSMAIL,v2.2) with ESMTP id k7NKofEU008558; Wed, 23 Aug 2006 16:50:41 -0400 (EDT) Received: from localhost (localhost [127.0.0.1]) by thunk.east.sun.com (8.13.7+Sun/8.13.7) with ESMTP id k7NKof34023064; Wed, 23 Aug 2006 16:50:41 -0400 (EDT) Subject: Re: ZFS user properties [PSARC/2006/504 Timeout: 08/31/2006] From: Bill Sommerfeld To: Eric Schrock Cc: Matthew Ahrens , PSARC@sac.sfbay.sun.com In-Reply-To: <20060823204403.GB6462@eng.sun.com> References: <200608232024.k7NKOutF108640@pacifica.sfbay.sun.com> <1156365510.20770.108.camel@thunk> <20060823204403.GB6462@eng.sun.com> Content-Type: text/plain Date: Wed, 23 Aug 2006 16:50:40 -0400 Message-Id: <1156366240.20770.118.camel@thunk> Mime-Version: 1.0 X-Mailer: Evolution 2.6.2 Content-Transfer-Encoding: 7bit Status: RO Content-Length: 1239 On Wed, 2006-08-23 at 13:44 -0700, Eric Schrock wrote: > I'm perfectly happy stating that 'com.sun.' is a reserved prefix for > user properties, but it's impossible for ZFS to actually enforce this > rule, since we don't know from the ZFS level whether the consumer is a > Sun product or not. Not every interface we define needs to be enforcable in code. All I want some way for a developer to pick a property name that they can use with the expectation that nobody else will pick the same name to mean something different. > We can expand on the 'suggested format', but there's really no way to > programmatically enforce such a rule, apart from 'every local property > must have a period before the first colon', but it seems rather silly to > do this when we can't actually establish any namespace beyond that. Naming conventions like this (or the alternate stock ticker convention used in package names) can't be programmatically enforced -- they can only be established via documentation. I just want to see it documented, preferably by using either "com.sun" or (better yet) using one of the example domain names reserved by RFC2606 ( http://www.rfc-editor.org/rfc/rfc2606.txt ) for examples in documentation. - Bill From sacadmin Wed Aug 23 13:58:54 2006 Received: from zion.eng.sun.com (zion.SFBay.Sun.COM [129.146.17.75]) by sac.sfbay.sun.com (8.13.6+Sun/8.13.6) with ESMTP id k7NKwsIe025663 for ; Wed, 23 Aug 2006 13:58:54 -0700 (PDT) Received: from zion.eng.sun.com (localhost [127.0.0.1]) by zion.eng.sun.com (8.13.7+Sun/8.13.7) with ESMTP id k7NKwrEr011925; Wed, 23 Aug 2006 13:58:53 -0700 (PDT) Received: (from eschrock@localhost) by zion.eng.sun.com (8.13.7+Sun/8.13.7/Submit) id k7NKwrMH011924; Wed, 23 Aug 2006 13:58:53 -0700 (PDT) Date: Wed, 23 Aug 2006 13:58:53 -0700 From: Eric Schrock To: Bill Sommerfeld Cc: Matthew Ahrens , PSARC@sac.sfbay.sun.com Subject: Re: ZFS user properties [PSARC/2006/504 Timeout: 08/31/2006] Message-ID: <20060823205853.GC6462@eng.sun.com> References: <200608232024.k7NKOutF108640@pacifica.sfbay.sun.com> <1156365510.20770.108.camel@thunk> <20060823204403.GB6462@eng.sun.com> <1156366240.20770.118.camel@thunk> Mime-Version: 1.0 Content-Type: text/plain; charset=us-ascii Content-Disposition: inline In-Reply-To: <1156366240.20770.118.camel@thunk> User-Agent: Mutt/1.4.2.1i Status: RO Content-Length: 969 On Wed, Aug 23, 2006 at 04:50:40PM -0400, Bill Sommerfeld wrote: > > Naming conventions like this (or the alternate stock ticker convention > used in package names) can't be programmatically enforced -- they can > only be established via documentation. I just want to see it > documented, preferably by using either "com.sun" or (better yet) using > one of the example domain names reserved by RFC2606 > ( http://www.rfc-editor.org/rfc/rfc2606.txt ) for examples in > documentation. > I'm happy to oblige here, but it would help if someone could propose an actual rule definition (i.e. manpage diffs), since it's not clear to me how to explain this in a satisfactory manner. Nor is it clear whether we need to enforce (via documentation) this rule to the point where the only 'safe' way of setting local properties is 'localhost:foo=bar' (or one of the other reserved names). - Eric -- Eric Schrock, Solaris Kernel Development http://blogs.sun.com/eschrock From sacadmin Thu Aug 24 15:34:37 2006 Received: from eastmail4bur.east.Sun.COM (eastmail4bur.East.Sun.COM [129.148.13.1]) by sac.sfbay.sun.com (8.13.6+Sun/8.13.6) with ESMTP id k7OMYaKY002542 for ; Thu, 24 Aug 2006 15:34:37 -0700 (PDT) Received: from thunk.east.sun.com (thunk.East.Sun.COM [129.148.174.66]) by eastmail4bur.east.Sun.COM (8.13.6+Sun/8.13.6/ENSMAIL,v2.2) with ESMTP id k7OMYZxS023406; Thu, 24 Aug 2006 18:34:35 -0400 (EDT) Received: from localhost (localhost [127.0.0.1]) by thunk.east.sun.com (8.13.7+Sun/8.13.7) with ESMTP id k7OMYZ3J029193; Thu, 24 Aug 2006 18:34:35 -0400 (EDT) Subject: Re: ZFS user properties [PSARC/2006/504 Timeout: 08/31/2006] From: Bill Sommerfeld To: Eric Schrock Cc: Matthew Ahrens , PSARC@sac.sfbay.sun.com In-Reply-To: <20060823205853.GC6462@eng.sun.com> References: <200608232024.k7NKOutF108640@pacifica.sfbay.sun.com> <1156365510.20770.108.camel@thunk> <20060823204403.GB6462@eng.sun.com> <1156366240.20770.118.camel@thunk> <20060823205853.GC6462@eng.sun.com> Content-Type: text/plain Date: Thu, 24 Aug 2006 18:34:34 -0400 Message-Id: <1156458874.26717.46.camel@thunk> Mime-Version: 1.0 X-Mailer: Evolution 2.6.2 Content-Transfer-Encoding: 7bit Status: RO Content-Length: 1927 On Wed, 2006-08-23 at 13:58 -0700, Eric Schrock wrote: > I'm happy to oblige here, but it would help if someone could propose an > actual rule definition (i.e. manpage diffs), since it's not clear to me > how to explain this in a satisfactory manner. After: + User property names must contain + a colon (':') character, to distinguish them from native + properties. They may contain lowercase letters, + numbers, and the following punctuation characters: ':', '-', + '.', '_'. The expected convention is that the property name + will be divided into two portions such as ':', + but this namespace is not enforced by ZFS. Insert: When making programmatic use of user properties, we strongly suggest the use of a reversed DNS domain name for the component of property names to reduce the chance that two independently-developed packages will use the same property name for different purposes. Module names beginning with "com.sun." are reserved for use by Sun Microsystems. And change Example 13 to: + Example 13: Setting User Properties + + The following example sets the user defined + 'com.example:department' property for a dataset. + + # zfs set com.example:department=12345 tank/accounting + + > Nor is it clear whether > we need to enforce (via documentation) this rule to the point where the > only 'safe' way of setting local properties is 'localhost:foo=bar' (or > one of the other reserved names). as a practical matter, the "local" top level domain has been used by enough different systems that it's also free for use in this context. BTW, other examples of how this naming convention has been documented can be found at: http://java.sun.com/docs/books/jls/second_edition/html/packages.doc.html (section 7.7, "Unique Package Names") http://developer2.apple.com/macosx/launchd.html ("Namespace clashes") - Bill From sacadmin Wed Aug 30 09:29:49 2006 Received: from engmail3mpk.sfbay.Sun.COM (engmail3mpk.SFBay.Sun.COM [129.146.11.26]) by sac.sfbay.sun.com (8.13.6+Sun/8.13.6) with ESMTP id k7UGTn4W019498 for ; Wed, 30 Aug 2006 09:29:49 -0700 (PDT) Received: from marduk.eng.sun.com (marduk.SFBay.Sun.COM [129.146.108.224]) by engmail3mpk.sfbay.Sun.COM (8.13.6+Sun/8.13.6/ENSMAIL,v2.2) with ESMTP id k7UGTmR5022605; Wed, 30 Aug 2006 09:29:48 -0700 (PDT) Received: from marduk.eng.sun.com (localhost [127.0.0.1]) by marduk.eng.sun.com (8.13.6+Sun/8.12.11) with ESMTP id k7UGVLgb007813; Wed, 30 Aug 2006 09:31:21 -0700 (PDT) Received: (from gww@localhost) by marduk.eng.sun.com (8.13.6+Sun/8.12.11/Submit) id k7UGVLbM007812; Wed, 30 Aug 2006 09:31:21 -0700 (PDT) Date: Wed, 30 Aug 2006 09:31:21 -0700 (PDT) From: Gary Winiger Message-Id: <200608301631.k7UGVLbM007812@marduk.eng.sun.com> To: eric.schrock@sun.com, sommerfeld@sun.com Cc: PSARC@sac.sfbay.sun.com, ahrens@pacifica.sfbay.sun.com Subject: Re: ZFS user properties [PSARC/2006/504 Timeout: 08/31/2006] Status: RO Content-Length: 317 Commenting on Bill's let's reserve some name space. I agree the proposal has merrit in avoiding 3rd party collisions. As I read the spec Sun has the Native Properties name space exclusively for its use. And my question for spec clarification: Is there any length limit on user property names and values? Gary.. From sacadmin Wed Aug 30 09:33:08 2006 Received: from zion.eng.sun.com (zion.SFBay.Sun.COM [129.146.17.75]) by sac.sfbay.sun.com (8.13.6+Sun/8.13.6) with ESMTP id k7UGX8RJ020182 for ; Wed, 30 Aug 2006 09:33:08 -0700 (PDT) Received: from zion.eng.sun.com (localhost [127.0.0.1]) by zion.eng.sun.com (8.13.7+Sun/8.13.7) with ESMTP id k7UGX7rT008735; Wed, 30 Aug 2006 09:33:07 -0700 (PDT) Received: (from eschrock@localhost) by zion.eng.sun.com (8.13.7+Sun/8.13.7/Submit) id k7UGX7qG008734; Wed, 30 Aug 2006 09:33:07 -0700 (PDT) Date: Wed, 30 Aug 2006 09:33:07 -0700 From: Eric Schrock To: Gary Winiger Cc: sommerfeld@sun.com, PSARC@sac.sfbay.sun.com, ahrens@pacifica.sfbay.sun.com Subject: Re: ZFS user properties [PSARC/2006/504 Timeout: 08/31/2006] Message-ID: <20060830163307.GB8305@eng.sun.com> References: <200608301631.k7UGVLbM007812@marduk.eng.sun.com> Mime-Version: 1.0 Content-Type: text/plain; charset=us-ascii Content-Disposition: inline In-Reply-To: <200608301631.k7UGVLbM007812@marduk.eng.sun.com> User-Agent: Mutt/1.4.2.1i Status: RO Content-Length: 633 On Wed, Aug 30, 2006 at 09:31:21AM -0700, Gary Winiger wrote: > Commenting on Bill's let's reserve some name space. I agree the > proposal has merrit in avoiding 3rd party collisions. As I read the > spec Sun has the Native Properties name space exclusively for its use. > > And my question for spec clarification: > Is there any length limit on user property names and values? Yes, these are currently limited to ZAP_MAXNAMELEN (256) and ZAP_MAXVALUELEN (1024), respectively. I'll add these, along with Bill's suggested namespace text. - Eric -- Eric Schrock, Solaris Kernel Development http://blogs.sun.com/eschrock From sacadmin Wed Aug 30 09:40:32 2006 Received: from zion.eng.sun.com (zion.SFBay.Sun.COM [129.146.17.75]) by sac.sfbay.sun.com (8.13.6+Sun/8.13.6) with ESMTP id k7UGeW86021249 for ; Wed, 30 Aug 2006 09:40:32 -0700 (PDT) Received: from zion.eng.sun.com (localhost [127.0.0.1]) by zion.eng.sun.com (8.13.7+Sun/8.13.7) with ESMTP id k7UGeVhg009095; Wed, 30 Aug 2006 09:40:31 -0700 (PDT) Received: (from eschrock@localhost) by zion.eng.sun.com (8.13.7+Sun/8.13.7/Submit) id k7UGeV3d009094; Wed, 30 Aug 2006 09:40:31 -0700 (PDT) Date: Wed, 30 Aug 2006 09:40:31 -0700 From: Eric Schrock To: Gary Winiger Cc: sommerfeld@sun.com, PSARC@sac.sfbay.sun.com, ahrens@pacifica.sfbay.sun.com Subject: Re: ZFS user properties [PSARC/2006/504 Timeout: 08/31/2006] Message-ID: <20060830164031.GC8305@eng.sun.com> References: <200608301631.k7UGVLbM007812@marduk.eng.sun.com> Mime-Version: 1.0 Content-Type: text/plain; charset=us-ascii Content-Disposition: inline In-Reply-To: <200608301631.k7UGVLbM007812@marduk.eng.sun.com> User-Agent: Mutt/1.4.2.1i Status: RO Content-Length: 8819 The updated spec and manpage diffs are below, addressing Bill and Gary's comments. - Eric A. INTRODUCTION ZFS currently supports a well-defined set of properties for managing ZFS datasets. These properties represent either read-only statistics exported by the ZFS framework ('available', 'compressratio', etc), or editable properties which affect the behavior of ZFS ('compression', 'readonly', etc). While these properties provide a structured way to interact with ZFS, a common request is to allow unstructured properties to be attached to ZFS datasets. This is covered by the following RFE: 6281585 user defined properties This would allow administrators to add annotations to datasets, as well as allowing ISVs to store application-specific settings that apply to individual datasets. B. DETAILS This proposal adds a new classification of ZFS properties known as 'user properties'. The existing native properties will remain as-is, as they provide additional semantics (mainly validation) which are closely tied to the underlying implementation. Any property which contains a colon (':') is defined as a 'user property'. The name can contain lowercase characters, numbers, and the following special characters: ':', '-', '.', '_'. User properties are always strings, and are always inherited. No additional validation is done on the contents. Properties are set and retrieved through the standard mechanisms: 'zfs set', 'zfs get', and 'zfs inherit'. Inheriting a property which is not set in any parent is equivalent to clearing the property, as there is no default value for user-defined properties. The empty string is a valid setting for a user-defined property. It is expected that the colon will serve two purposes: to distinguish between native properties and provide an (unenforced) namespace for user properties. The documentation will stress that properties should be defined as ':', to group properties together and to provide a larger namespace for logical separation of properties. Use of reversed DNS domain names will be encouraged for the 'module' portion. No enforcement of this namespace is done by ZFS, however, and the empty string is valid on both sides of the colon. C. EXAMPLES # zfs set local:department=12345 test # zfs get -r local:department test NAME PROPERTY VALUE SOURCE test local:department 12345 local test local:department 12345 local test/foo local:department 12345 inherited from test # zfs list -o name,local:department NAME LOCAL:DEPARTMENT test 12345 test/foo 12345 # zfs set local:department=67890 test/foo # zfs inherit local:department test # zfs get -s local -r all test NAME PROPERTY VALUE SOURCE test/foo local:department 12345 local # zfs list -o name,local:department NAME LOCAL:DEPARTMENT test - test/foo 12345 D. MANPAGE CHANGES --- zfs.old Mon Aug 21 10:12:52 2006 +++ zfs.new Wed Aug 23 10:18:02 2006 @@ -249,11 +249,19 @@ The global administrator can forcibly clear the "zoned" pro- perty, though this should be done with extreme care. The global administrator should verify that all the mount points are acceptable before clearing the property. - Properties + Native Properties + Properties are divided into two types, native properties and + user defined properties. Native properties export internal + statistics or control ZFS behavior. + User properties have no effect on ZFS behavior. For more + information on user properties, see the 'User Properties' + section, below. + Every dataset has a set of properties that export statistics about the dataset as well as control various behavior. Pro- perties are inherited from the parent unless overridden by @@ -283,12 +291,12 @@ Non-numeric properties are case sensitive and must be lower- case, except for "mountpoint" and "sharenfs". The first set of properties consist of read-only statistics about the dataset. These properties cannot be set, nor are - they inherited. Properties apply to all dataset types unless - otherwise noted. + they inherited. Native properties apply to all dataset types + unless otherwise noted. type The type of dataset: "filesystem", "volume", or "snapshot". @@ -761,10 +769,32 @@ option is an alias for "nodevices,nosetuid". These proper- ties are reported as "temporary" by the "zfs get" command. If the properties are changed while the dataset is mounted, the new setting overrides any temporary settings. + + User Properites + In addition to the standard native properties, ZFS + supports arbitrary user properties. User properties have no + effect on ZFS behavior, but applications or administrators can use + them to annotate datasets. + + User property names must contain + a colon (':') character, to distinguish them from native + properties. They may contain lowercase letters, + numbers, and the following punctuation characters: ':', '-', + '.', '_'. The expected convention is that the property name + will be divided into two portions such as ':', + but this namespace is not enforced by ZFS. User property names + can be at most 256 characters. + + When making programmatic use of user properties, it is strongly + suggested to use a reversed DNS domain name for the + component of property names to reduce the chance that two + independently-developed packages will use the same property name + for different purposes. Property names beginning with "com.sun." + are reserved for use by Sun Microsystems. + + The values of user properties are arbitrary strings, are always + inherited, and are never validated. All of the commands which + operate on properties ('zfs list', 'zfs get', 'zfs set', etc.) + can be used to manipulate both native properties and user + properties. To clear a user property, use 'zfs inherit'. If + the property is not defined in any parent dataset, it will be + removed entirely. Property values are limited to 1024 characters. + + Volumes as Swap or Dump Devices To set up a swap area, create a ZFS volume of a specific size and then enable swap on that device. For more informa- tion, see the EXAMPLES section. @@ -816,20 +846,20 @@ of blocks regardless of blocksize. -s Creates a sparse volume with no reservation. See - "volsize" in the Properties section for more infor- - mation about sparse volumes. + "volsize" in the Native Properties section for more + information about sparse volumes. -b blocksize Sets the "volblocksize" property, as described in - the Properties section. + the Native Properties section. zfs destroy [-rRf] filesystem|volume|snapshot @@ -969,13 +999,13 @@ -o prop A comma-separated list of properties to display. Must be one of the properties - described in the "Properties" section, - or the special value "name" to display - the dataset name. + described in the "Native Properties" + section, or the special value "name" to + display the dataset name. -t type A comma-separated list of types to display, where "type" is one of @@ -1029,11 +1059,11 @@ temporary, inherited, or none (-). All columns are displayed by default, though this can be controlled by using the -o option. This command takes a comma-separated list of properties as described in the - "Properties" section. + "Native Properties" and "User Properties" sections. The special value "all" can be used to display all pro- perties for the given dataset. @@ -1543,10 +1573,18 @@ # zfs create -V 5gb tank/vol # swap -a /dev/zvol/dsk/tank/vol + Example 13: Setting User Properties + + The following example sets the user defined + 'com.example:department' property for a dataset. + + # zfs set com.example:department=12345 tank/accounting + + EXIT STATUS The following exit values are returned: 0 Successful completion. From sacadmin Tue Sep 5 10:10:40 2006 Received: from zion.eng.sun.com (zion.SFBay.Sun.COM [129.146.17.75]) by sac.sfbay.sun.com (8.13.6+Sun/8.13.6) with ESMTP id k85HAern003473 for ; Tue, 5 Sep 2006 10:10:40 -0700 (PDT) Received: from [129.146.17.75] (zion [129.146.17.75]) by zion.eng.sun.com (8.13.7+Sun/8.13.7) with ESMTP id k85HAdGP013621; Tue, 5 Sep 2006 10:10:39 -0700 (PDT) Message-ID: <44FDAF8F.6030506@sun.com> Date: Tue, 05 Sep 2006 10:10:39 -0700 From: Matthew Ahrens User-Agent: Mail/News 1.5.0.4 (X11/20060613) MIME-Version: 1.0 To: Eric Schrock CC: Gary Winiger , sommerfeld@sun.com, PSARC@sac.sfbay.sun.com, ahrens@pacifica.sfbay.sun.com Subject: Re: ZFS user properties [PSARC/2006/504 Timeout: 08/31/2006] References: <200608301631.k7UGVLbM007812@marduk.eng.sun.com> <20060830164031.GC8305@eng.sun.com> In-Reply-To: <20060830164031.GC8305@eng.sun.com> Content-Type: text/plain; charset=ISO-8859-1; format=flowed Content-Transfer-Encoding: 7bit Status: RO Content-Length: 171 Eric Schrock wrote: > The updated spec and manpage diffs are below, addressing Bill and Gary's > comments. The case has timed out without any further discussion. --matt