Template Version: @(#)sac_nextcase 1.61 05/24/07 SMI
This information is Copyright 2007 Sun Microsystems
1. Introduction
1.1. Project/Component Working Name:
Enhanced ZFS Pool Properties
1.2. Name of Document Author/Supplier:
Author: Eric Schrock
1.3 Date of This Document:
12 June, 2007
4. Technical Description
This case clarifies and expands the functionality of ZFS pool
properties. The stability of the options is committed, and the release
binding is patch/micro.
1. INTRODUCTION
As part of PSARC 2006/577, the concept of 'pool properties' was created.
This was implemented with 2007/083 to allow the 'bootfs' property to be
set via 'zpool set' and the value retrieved via 'zpool get'. A second
property will be introduced as part of PSARC 2006/465 to control
delegated administration. The original proposal was amended as part of
PSARC 2007/228 to allow properties to be set generically on import using
'zpool import -p'.
The current property interfaces are limited in several ways when
compared with their zfs(1M) equivalents:
- There is no 'zpool list -o' option corresponding to these
properties. Only the existing static properties (name, used,
available, capacity, health) can be specified with this
option.
- The existing static properties are not represented as
pool properties, and cannot be retrieved through 'zpool get'.
- There is no 'zpool create -o' option to set properties at
creation time.
- The 'altroot' field is really a combination of two distinct
properties: temporary (do not auto-import on reboot) and
altroot (prepend the path to all mountpoints).
- There are several properties that should exist but currently
do not, including 'version', and 'guid'.
This case fixes these deficiencies and clarifies the use of properties
when dealing with ZFS pools.
2. DETAILS
All existing static properties described in 'zpool list -o' (name, size,
used, available, capacity, and health) will be documented as 'readonly
properties'. These properties can be retrieved with 'zpool get' or
'zpool list -o' but not set through 'zpool set'.
A new option, '-o', will be added to 'zpool create' to allow properties
to be set at create-time. Only writable properties can be set at create
time.
The 'altroot' field of 'zpool list' will be broken into two distinct
properties. The first is 'temporary', which indicates that the pool is
not persistent and should not be re-opened on reboot. In implementation
terms, the pool is not kept in /etc/zfs/zpool.cache. The second
property is 'altroot', which is prepended to the mountpoint of all
datasets. The existing 'zpool create -R' and 'zpool import -R' will
retain the same behavior, but correspond to setting both 'temporary=on'
and 'alroot=<path>'. This separation is useful in clustering and other
custom scenarios where more control is needed over the way pools are
imported, without conflating the need for an alternate root. These
properties can be set at create or import time but are otherwise
readonly.
Two new properties, 'version' and 'guid', will be introduced. The
'version' property can be set at creation time and increased via 'zpool
set', but never decresed. This allows for testing of older pool
versions and also creating pools on newer systems that can be used on
older systems. The existing 'zpool upgrade' will continue to exist, as
it also provides mechanisms for listing pool versions, as well as
updating to the current version (whatever that may be). The 'guid'
property is readonly and will return the GUID for a pool. This number
is reported in 'zpool import' when listing available pools to import but
is currently unavailable for active pools.
3. FUTURE WORK
Future work could make some of these properties more dynamic. Examples
include changing the 'temporary' or 'altroot' property, as well as
allowing the guid to be specified on import to avoid conflicts. Support
could also be added for arbitrary user properties as with zfs(1M).
Another possibility is to allow pools to be renamed via 'zpool set name'.
These extensions are left as future work since there is little current
demand and the implementation is non-trivial.
4. EXAMPLES
# zpool create -o version=3 oldpool c0t0d0
# zpool get version oldpool
3
# zpool export oldpool
# zpool import -o temporary=on oldpool
# zpool create newpool c0t1d0
# zpool list -o name,version
newpool 6
oldpool 3
5. MANPAGE CHANGES
Note that the current manpages do not include the 'zpool get' and
'zpool set' commands (bug 6539452), nor are the changes for
PSARC 2007/228 included here.
--- zpool.1m Mon Jun 4 17:13:18 2007
+++ zpool.new Mon Jun 4 19:07:49 2007
@@ -9,19 +9,20 @@
zpool - configures ZFS storage pools
SYNOPSIS
zpool [-?]
- zpool create [-fn] [-R root] [-m mountpoint] pool vdev ...
+ zpool create [-fn] [-R root] [-m mountpoint] [-o property=value]
+ pool vdev ...
zpool destroy [-f] pool
zpool add [-fn] pool vdev
zpool remove pool vdev
- zpool list [-H] [-o field[,field]*] [pool] ...
+ zpool list [-H] [-o property[,property]*] [pool] ...
zpool iostat [-v] [pool] ... [interval [count]]
zpool status [-xv] [pool] ...
@@ -52,10 +53,14 @@
zpool upgrade -v
zpool upgrade [-a | pool]
+ zpool get <all | property[,property]...> [pool] ...
+
+ zpool set <property=value> <pool>
+
DESCRIPTION
The zpool command configures ZFS storage pools. A storage
pool is a collection of devices that provides physical
@@ -244,22 +249,12 @@
ing the hot spare. If the original faulted device is
detached, then the hot spare assumes its place in the confi-
guration, and is removed from the spare list of all active
pools.
- Alternate Root Pools
- The "zpool create -R" and "zpool import -R" commands allow
- users to create and import a pool with a different root
- path. By default, whenever a pool is created or imported on
- a system, it is permanently added so that it is available
- whenever the system boots. For removable media, or when in
- recovery situations, this may not always be desirable. An
- alternate root pool does not persist on the system. Instead,
- it exists only until exported or the system is rebooted, at
-
SunOS 5.10 Last change: 6 Jun 2006 4
@@ -267,21 +262,75 @@
System Administration Commands zpool(1M)
- which point it will have to be imported again.
+ Properties
+ Each pool has several properties associated with it. Some
+ properties are read-only statistics while others are
+ configurable and change the behavior of the pool. The
+ following are read-only properties:
- In addition, all mount points in the pool are prefixed with
- the given root, so a pool can be constrained to a particular
- area of the file system. This is most useful when importing
- unknown pools from removable media, as the mount points of
- any file systems cannot be trusted.
+ name Name of the storage pool.
- When creating an alternate root pool, the default mount
- point is "/", rather than the normal default "/pool".
+ size Total size of the storage pool.
+ used Amount of storage used within the pool.
+
+ available Amount of storage available within the pool.
+
+ capacity Capacity of storage pool expressed as a percentage.
+
+ health The current health of the pool, either 'ONLINE',
+ 'DEGRADED', or 'FAULTED'.
+
+ guid A unique identifier for the pool.
+
+ This space usage properties report actual physical space
+ available to the storage pool. The physical space can be
+ different from the total amount of space that any
+ contained datasets can actually use. The amount of space
+ used in a raidz configuration depends on the characteristics
+ of the data being written. In addition, ZFS reserves some
+ space for internal accounting that the zfs(1M) command
+ takes into account, but the zpool command does not. For
+ non-full pools of a reasonable size, these effects
+ should be invisible. For small pools, or pools that are
+ close to being completely full, these discrepancies may
+ become more noticeable.
+
+ The following properties can be set at creation time but not
+ modified:
+
+ temporary By default, all pools are persistent, and will
+ automatically be opened when the system is
+ rebooted. Setting this boolean property to
+ 'on' will cause the pool to exist only while
+ the system is up. If the system is rebooted,
+ the pool will have to be manually imported via
+ 'zpool import'. This is often useful when
+ using pools on removable media, where the
+ devices may not be present when the system
+ reboots.
+
+ altroot Alternate root directory. If set, then this
+ directory is prepended to any mountpoints within
+ the pool. This can be used when examining an
+ unknown pool where the mountpoints cannot be
+ trusted, or in an alternate boot environment
+ where the typical paths are not valid.
+
+ The following properties can be set be set at creation time
+ and later changed via 'zpool set':
+
+ version The current on-disk version of the pool. This
+ can be increased, but never decreased. The
+ preferred method of updating pools is via
+ 'zpool upgrade', though this can be used when
+ a specific version is needed for backwards
+ compatibility. This property can be any number
+ between 1 and the current version reported by
+ 'zpool upgrade -v'. The special value 'current'
+ is an alias for the latest supported version.
+
Subcommands
The zpool command provides subcommands to create and destroy
storage pools, add capacity to storage pools, and provide
information about the storage pools. The following subcom-
mands are supported:
@@ -353,20 +402,22 @@
without actually creating the pool. The actual pool
creation can still fail due to insufficient
privileges or device sharing.
+ -o property=value[,property=value]
- -R root
+ Sets the given pool properties. See the 'Properties'
+ section for a list of valid properties that can be
+ set.
- Creates the pool with an alternate root. See the
- "Alternate Root Pools" section. The root dataset has
- its mount point set to "/" as part of this opera-
- tion.
+ -R root
+ Equivalent to '-o temporary=on,altroot=<root>'.
+
-m mountpoint
Sets the mount point for the root dataset. The
default mount point is "/pool". The mount point must
be an absolute path, "legacy", or "none". For more
@@ -445,19 +496,17 @@
arbitrary space.
- -o field Comma-separated list of fields to display. Each
- field must be one of:
+ -o props Comma-separated list of properties to display.
+ See the 'Properties' section for a list of
+ valid properties. The default list is
+ 'name,size,used,available,capacity,health,altroot'
- name Pool name
- size Total size
-
-
SunOS 5.10 Last change: 6 Jun 2006 7
@@ -465,33 +514,10 @@
System Administration Commands zpool(1M)
- used Amount of space used
- available Amount of space available
- capacity Percentage of pool space used
- health Health status
-
- The default is all fields.
-
-
-
- This command reports actual physical space available to
- the storage pool. The physical space can be different
- from the total amount of space that any contained
- datasets can actually use. The amount of space used in a
- raidz configuration depends on the characteristics of
- the data being written. In addition, ZFS reserves some
- space for internal accounting that the zfs(1M) command
- takes into account, but the zpool command does not. For
- non-full pools of a reasonable size, these effects
- should be invisible. For small pools, or pools that are
- close to being completely full, these discrepancies may
- become more noticeable.
-
-
zpool iostat [-v] [pool] ... [interval [count]]
Displays I/O statistics for the given pools. When given
an interval, the statistics are printed every interval
seconds until Ctrl-C is pressed. If no pools are speci-
@@ -802,12 +828,12 @@
zfs(1M) for a description of dataset properties
and mount options.
- -R root Imports pool(s) with an alternate root. See the
- "Alternate Root Pools" section.
+ -R root Sets the 'temporary' property to 'on' and the
+ 'altroot' property to '<root>'.
@@ -877,12 +903,35 @@
on systems running older versions of the software.
-a Upgrades all pools.
+ zpool get <all | property[,property]*> <pool> ...
+ Retrieves the given list of properties (or all properties
+ if 'all' is used) for the specified storage pool(s). These
+ properties are displayed with the following fields:
+ name Name of storage pool.
+
+ property Property name
+
+ value Property value
+
+ source Property source, either 'default' or 'local'.
+
+ See the 'Properties' section for more information on the
+ available pool properties.
+
+
+ zpool set property=value <pool>
+
+ Sets the given property on the specified pool. See the
+ 'Properties' section for a list of properties that can
+ be changed once the pool has been created.
+
+
EXAMPLES
Example 1: Creating a RAID-Z Storage Pool
The following command creates a pool with a single raidz
6. Resources and Schedule
6.4. Steering Committee requested information
6.4.1. Consolidation C-team Name:
ON
6.5. ARC review type: FastTrack
