zfs discuss - Mar 2006 - Proposal: ''zpool upgrade'' and version management

The following case is under review by PSARC.  Any comments from the
community are welcome.

- Eric


A. DESCRIPTION

It is anticipated that over the course of ZFS development, a need will
arise to change the on-disk format.  Prior to its release as supported
software, this was dealt with by a suitable flag day.  Moving forward,
this is no longer acceptable.  The user should still be able to use
older versions of ZFS when possible, and upgrading to a newer version
must be a deliberate act.

While every attempt will be made to keep ZFS capable of reading and
writing older on-disk versions, there may be changes which cannot be
accomplished while maintaining this compatability.  While no such
changes are anticipated, the architecture is designed such that pools
will appear as faulted, but can still be upgraded via an explicit
action.

B. NEW SUBCOMMANDS

A new subcommand will be added to zpool(1M), ''zpool upgrade'':

	zpool upgrade
	zpool upgrade -v
	zpool upgrade <-a | pool>

The first form displays all pools formatted with a different on-disk
version.  The output of this command will show pools which are out of
date as well as those with a newer version:

	# zpool upgrade
	This system is currently running ZFS version 2.

	The following pools are out of date, and can be upgraded.  After
	being upgraded, these pools will no longer be accessible by
	older software versions.

	VER  POOL
        ---  ----------------------
	 1   tank

	The following pools are formatted using a newer software version
	and cannot be accessed on the current system.

	VER  POOL
	---  -----------------------
	 3   dozer

	Use ''zpool upgrade -v'' for a detailed description of
supported
	versions and their associated features.

If no pools are available for upgrade, the command simply prints a
message and returns success.

The second form of the command, ''zpool upgrade -v'', displays a
detailed
list of supported on-disk versions, along with a description of the
features each provides.  A hypothetical example:

	# zpool upgrade -v
	This system is currently running ZFS version 2.  The following
	versions are supported:

	VER  DESCRIPTION
	---  ---------------------------------------------------------------
	 2   Provides metadata redundancy independent of pool
	     configuration.  Allows replication to be controlled on a
	     per-filesystem basis using ''zfs set replication''.
	 1   Initial ZFS version.

The final form of the command is used to upgrade pools on the system.
If a particular pool is specified, then only that pool is upgraded.  If
''-a'' is specified, then all currently out of date pools are
upgraded.
For example:

	# zpool upgrade -a
	This system is currently running ZFS version 2.

	Upgraded pool ''tank''
	Upgraded pool ''dozer''

If all pools are running the current version, then ''zpool upgrade
-a'' does
nothing, printing a message and returning sucess.  If a pool is
specified then only that pool is upgraded, and it is an error if the
pool is already the latest version.

C. CHANGES TO EXISTING SUBCOMMANDS

The ''zpool status'' output will be altered to understand when a
pool is
formatted with an older or newer version.  If a pool is currently
formatted using an older version, then ''zpool status'' will
display
the pool as ONLINE, but the status will show that the pool is formatted
using an older version, and the user should upgrade the pool in order to
take advantage of the latest features.

If a pool is formatted using a newer on-disk format version, then the
pool will be faulted and ''zpool status'' will indicate the pool
is
inaccessible, and recommend the user either access the pool from a
system with newer software, or restore the pool from backup.

The ''zpool import'' subcommand will also be altered to display
a warning
when a pool is of an older version, but otherwise allow it to be
imported.  Pools formatted with a newer version will not be importable.

D. MANPAGE CHANGES

***************
*** 46,51 ****
--- 46,57 ----
  
       zpool import [-d dir] [-f]	[-o opts] [-R root] [-a]
  
+      zpool upgrade
+ 
+      zpool upgrade -v
+ 
+      zpool upgrade <-a | pool>
+ 
  DESCRIPTION
       The zpool command configures ZFS storage  pools.  A  storage
       pool  is  a  collection  of  devices  that	provides physical
***************
*** 743,748 ****
--- 749,781 ----
  
  
  
+      zpool upgrade
+ 
+          Displays all pools formatted using a different ZFS on-
+          disk version.  Older versions can continue to be used,
+          but some feeatures may not be available.  These pools
+          can be upgraded using ''zpool upgrade -a''.  Pools
+          formatted with a more recent version are also displayed,
+          although these pools will be inaccessible on the
+          system.
+ 
+ 
+      zpool upgrade -v
+ 
+          Display ZFS versions supported by the current software.
+          The current ZFS versions and all previous supported
+          versions are displayed, along with an explanation of the
+          features provided with each version.
+          
+ 
+      zpool upgrade <-a | pool>
+ 
+          Upgrades the given pool (or all pools if ''-a'' is
+ 	 specified) to the latest on-disk version.  Once this is
+          done, the pool will no longer be accessible on systems
+          running older versions of the software.
+ 
+ 
  
  EXAMPLES
       Example 1:	Creating a RAID-Z ZFS Storage Pool

a couple questions

1) How long will an upgrade take?

2) Will the pool be accessible during the upgrade?

3) What are the free space requirements for an upgrade?

thanks!

On Fri, Mar 31, 2006 at 09:52:43AM +1100, Barry Robison
wrote:
> a couple questions
> 
> 1) How long will an upgrade take?
> 
> 2) Will the pool be accessible during the upgrade?
> 
> 3) What are the free space requirements for an upgrade?
This all depends on the type of upgrade.  For all the version changes we
can envision, the answers will be:

1) Instantaneous

2) Yes

3) Zero

- Eric

--
Eric Schrock, Solaris Kernel Development       http://blogs.sun.com/eschrock