OS-1566 filesystem limits for ZFS datasets

          --- old/usr/src/man/man5/zpool-features.5
          +++ new/usr/src/man/man5/zpool-features.5
   1    1  '\" te
   2    2  .\" Copyright (c) 2012 by Delphix. All rights reserved.
        3 +.\" Copyright (c) 2012 Joyent, Inc. All rights reserved.
   3    4  .\" The contents of this file are subject to the terms of the Common Development
   4    5  .\" and Distribution License (the "License").  You may not use this file except
   5    6  .\" in compliance with the License. You can obtain a copy of the license at
   6    7  .\" usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing.
   7    8  .\"
   8    9  .\" See the License for the specific language governing permissions and
   9   10  .\" limitations under the License. When distributing Covered Code, include this
  10   11  .\" CDDL HEADER in each file and include the License file at
  11   12  .\" usr/src/OPENSOLARIS.LICENSE.  If applicable, add the following below this
  12   13  .\" CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your
  13   14  .\" own identifying information:
  14   15  .\" Portions Copyright [yyyy] [name of copyright owner]
  15      -.TH ZPOOL-FEATURES 5 "Mar 16, 2012"
       16 +.TH ZPOOL-FEATURES 5 "Oct 24, 2012"
  16   17  .SH NAME
  17   18  zpool\-features \- ZFS pool feature descriptions
  18   19  .SH DESCRIPTION
  19   20  .sp
  20   21  .LP
  21   22  ZFS pool on\-disk format versions are specified via "features" which replace
  22   23  the old on\-disk format numbers (the last supported on\-disk format number is
  23   24  28). To enable a feature on a pool use the \fBupgrade\fR subcommand of the
  24   25  \fBzpool\fR(1M) command, or set the \fBfeature@\fR\fIfeature_name\fR property
  25   26  to \fBenabled\fR.

  26   27  .sp
  27   28  .LP
  28   29  The pool format does not affect file system version compatibility or the ability
  29   30  to send file systems between pools.
  30   31  .sp
  31   32  .LP
  32   33  Since most features can be enabled independently of each other the on\-disk
  33   34  format of the pool is specified by the set of all features marked as
  34   35  \fBactive\fR on the pool. If the pool was created by another software version
  35   36  this set may include unsupported features.
  36   37  .SS "Identifying features"
  37   38  .sp
  38   39  .LP
  39   40  Every feature has a guid of the form \fIcom.example:feature_name\fR. The reverse
  40   41  DNS name ensures that the feature's guid is unique across all ZFS
  41   42  implementations. When unsupported features are encountered on a pool they will
  42   43  be identified by their guids. Refer to the documentation for the ZFS
  43   44  implementation that created the pool for information about those features.
  44   45  .sp
  45   46  .LP
  46   47  Each supported feature also has a short name. By convention a feature's short
  47   48  name is the portion of its guid which follows the ':' (e.g.
  48   49  \fIcom.example:feature_name\fR would have the short name \fIfeature_name\fR),
  49   50  however a feature's short name may differ across ZFS implementations if
  50   51  following the convention would result in name conflicts.
  51   52  .SS "Feature states"
  52   53  .sp
  53   54  .LP
  54   55  Features can be in one of three states:
  55   56  .sp
  56   57  .ne 2
  57   58  .na
  58   59  \fB\fBactive\fR\fR
  59   60  .ad
  60   61  .RS 12n
  61   62  This feature's on\-disk format changes are in effect on the pool. Support for
  62   63  this feature is required to import the pool in read\-write mode. If this
  63   64  feature is not read-only compatible, support is also required to import the pool
  64   65  in read\-only mode (see "Read\-only compatibility").
  65   66  .RE
  66   67  
  67   68  .sp
  68   69  .ne 2
  69   70  .na
  70   71  \fB\fBenabled\fR\fR
  71   72  .ad
  72   73  .RS 12n
  73   74  An administrator has marked this feature as enabled on the pool, but the
  74   75  feature's on\-disk format changes have not been made yet. The pool can still be
  75   76  imported by software that does not support this feature, but changes may be made
  76   77  to the on\-disk format at any time which will move the feature to the
  77   78  \fBactive\fR state. Some features may support returning to the \fBenabled\fR
  78   79  state after becoming \fBactive\fR. See feature\-specific documentation for
  79   80  details.
  80   81  .RE
  81   82  
  82   83  .sp
  83   84  .ne 2
  84   85  .na
  85   86  \fBdisabled\fR
  86   87  .ad
  87   88  .RS 12n
  88   89  This feature's on\-disk format changes have not been made and will not be made
  89   90  unless an administrator moves the feature to the \fBenabled\fR state. Features
  90   91  cannot be disabled once they have been enabled.
  91   92  .RE
  92   93  
  93   94  .sp
  94   95  .LP
  95   96  The state of supported features is exposed through pool properties of the form
  96   97  \fIfeature@short_name\fR.
  97   98  .SS "Read\-only compatibility"
  98   99  .sp
  99  100  .LP
 100  101  Some features may make on\-disk format changes that do not interfere with other
 101  102  software's ability to read from the pool. These features are referred to as
 102  103  "read\-only compatible". If all unsupported features on a pool are read\-only
 103  104  compatible, the pool can be imported in read\-only mode by setting the
 104  105  \fBreadonly\fR property during import (see \fBzpool\fR(1M) for details on
 105  106  importing pools).
 106  107  .SS "Unsupported features"
 107  108  .sp
 108  109  .LP
 109  110  For each unsupported feature enabled on an imported pool a pool property
 110  111  named \fIunsupported@feature_guid\fR will indicate why the import was allowed
 111  112  despite the unsupported feature. Possible values for this property are:
 112  113  
 113  114  .sp
 114  115  .ne 2
 115  116  .na
 116  117  \fB\fBinactive\fR\fR
 117  118  .ad
 118  119  .RS 12n
 119  120  The feature is in the \fBenabled\fR state and therefore the pool's on\-disk
 120  121  format is still compatible with software that does not support this feature.
 121  122  .RE
 122  123  
 123  124  .sp
 124  125  .ne 2
 125  126  .na
 126  127  \fB\fBreadonly\fR\fR
 127  128  .ad
 128  129  .RS 12n
 129  130  The feature is read\-only compatible and the pool has been imported in
 130  131  read\-only mode.
 131  132  .RE
 132  133  
 133  134  .SS "Feature dependencies"
 134  135  .sp
 135  136  .LP
 136  137  Some features depend on other features being enabled in order to function
 137  138  properly. Enabling a feature will automatically enable any features it
 138  139  depends on.
 139  140  .SH FEATURES
 140  141  .sp
 141  142  .LP
 142  143  The following features are supported on this system:
 143  144  .sp
 144  145  .ne 2
 145  146  .na
 146  147  \fB\fBasync_destroy\fR\fR
 147  148  .ad
 148  149  .RS 4n
 149  150  .TS
 150  151  l l .
 151  152  GUID    com.delphix:async_destroy
 152  153  READ\-ONLY COMPATIBLE   yes
 153  154  DEPENDENCIES    none
 154  155  .TE
 155  156  
 156  157  Destroying a file system requires traversing all of its data in order to
 157  158  return its used space to the pool. Without \fBasync_destroy\fR the file system
 158  159  is not fully removed until all space has been reclaimed. If the destroy
 159  160  operation is interrupted by a reboot or power outage the next attempt to open
 160  161  the pool will need to complete the destroy operation synchronously.
 161  162  
 162  163  When \fBasync_destroy\fR is enabled the file system's data will be reclaimed
 163  164  by a background process, allowing the destroy operation to complete without
 164  165  traversing the entire file system. The background process is able to resume
 165  166  interrupted destroys after the pool has been opened, eliminating the need
 166  167  to finish interrupted destroys as part of the open operation. The amount
 167  168  of space remaining to be reclaimed by the background process is available
 168  169  through the \fBfreeing\fR property.
 169  170  
 170  171  This feature is only \fBactive\fR while \fBfreeing\fR is non\-zero.
 171  172  .RE
 172  173  
 173  174  .sp
 174  175  .ne 2
 175  176  .na
 176  177  \fB\fBempty_bpobj\fR\fR
 177  178  .ad
 178  179  .RS 4n
 179  180  .TS
 180  181  l l .
 181  182  GUID    com.delphix:empty_bpobj
 182  183  READ\-ONLY COMPATIBLE   yes
 183  184  DEPENDENCIES    none
 184  185  .TE
 185  186  
 186  187  This feature increases the performance of creating and using a large
 187  188  number of snapshots of a single filesystem or volume, and also reduces
 188  189  the disk space required.
 189  190  

 190  191  When there are many snapshots, each snapshot uses many Block Pointer
 191  192  Objects (bpobj's) to track blocks associated with that snapshot.
 192  193  However, in common use cases, most of these bpobj's are empty.  This
 193  194  feature allows us to create each bpobj on-demand, thus eliminating the
 194  195  empty bpobjs.
 195  196  
 196  197  This feature is \fBactive\fR while there are any filesystems, volumes,
 197  198  or snapshots which were created after enabling this feature.
 198  199  .RE
 199  200  
      201 +.sp
      202 +.ne 2
      203 +.na
      204 +\fB\fBfilesystem_limits\fR\fR
      205 +.ad
      206 +.RS 4n
      207 +.TS
      208 +l l .
      209 +GUID    com.joyent:filesystem_limits
      210 +READ\-ONLY COMPATIBLE   yes
      211 +DEPENDENCIES    none
      212 +.TE
      213 +
      214 +This feature enables filesystem and snapshot limits. These limits can be used
      215 +to control how many filesystems and/or snapshots can be created at the point in
      216 +the tree on which the limits are set.
      217 +
      218 +This feature is \fBactive\fR once either of the limit properties has been
      219 +set on a dataset and is deactivated when the last limit is removed.
      220 +.RE
      221 +
 200  222  .SH "SEE ALSO"
 201  223  \fBzpool\fR(1M)
    

XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX