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:
zfs upgrade
1.2. Name of Document Author/Supplier:
Author: Matthew Ahrens
1.3 Date of This Document:
04 June, 2007
4. Technical Description
A. INTRODUCTION
Internally, ZFS has both a "pool version" (ie, SPA/DSL/DMU) and
"filesystem version" (ie, ZPL), which describe the on-disk format. Old
software can not access newer pools or filesystems.
'zpool upgrade' changes the pool version. The filesystem version has
not changed since ZFS was integrated, so there is currently no mechanism
for changing it. This case introduces a filesystem on-disk version
change and the mechanism for controlling when that change happens.
Note, we could piggyback the filesystem version on the pool version.
However, 'zfs send' allows a filesystem to be "moved" to another system,
where it may be inaccessible if the other system's software does not
support the filesystem version.
Therefore, the administrator should be able to determine independently
when to upgrade the pool and each filesystem within it. For example,
they may want to use a new pool feature which requires a 'zpool
upgrade', but still be able to 'zfs send' their filesystems to other
machines which are running old software.
This case adds a 'zfs upgrade' subcommand and 'version' property which
allows the filesystem version to be upgraded independently of the pool
version.
B. DESCRIPTION
A new zfs property will be added:
version The on-disk version of this filesystem, which is
independent of the pool version. Can only be
set to later supported versions. See 'zfs
upgrade'. The shorthand value "current" can be
used for the most recent supported version.
This property can be manipulated the same as other properties:
zfs create -o version=...
zfs list -o version...
zfs get version ...
zfs set version=...
A new subcommand will be added to zfs(1m):
zfs upgrade
Display a list of filesystems which are not the most recent
version.
zfs upgrade -v
Display information about filesystem versions supported by the
current software.
zfs upgrade [-r] [-V <version>] [-a | <filesystem>]
Upgrade filesystems to a new on-disk version. Once this is
done, the filesystems will no longer be accessible on systems
running older versions of the software. Furthermore, 'zfs send'
streams generated from new snapshots of these filesystems can
not be accessed on systems running older versions of the
software.
Note that the filesystem version is independent of the pool
version (see zpool(1m) section on 'zpool upgrade').
-a Upgrade all filesystems on all imported pools.
filesystem Upgrade the named filesystem
-r Upgrade the named filesystem and all descendent
filesystems
-V <version> Upgrade to the specified version. If the -V
flag is not specified, upgrade to the most
recent version. Can only be used to increase
the version number, and only up to the most
recent version supported by this software.
The filesystem version need not be upgraded when the pool version is
upgraded, and vice versa. (However, there may be an unforseen fs
upgrade in the future which may require that the pool be upgraded as
well.)
Note, as part of a different PSARC case, the zpool version/upgrade
interface will be enhanced to have these same options (zpool set
version=<version>, zpool upgrade -V <version>).
C. FILESYSTEM VERSIONS
This case will deliver a new filesystem version, which adds support for
type information stored in directory entries. This is for compatability
with other operating systems (eg, MacOS) which return this information
in their stat structure.
Another filesystem version upgrade is planned as part of the CIFS work,
but that is not part of this case.
Expected output from 'zfs upgrade' will be something like:
<quote>
# zfs upgrade
This system is currently running ZFS filesystem version 3.
The following versions are supported:
VER DESCRIPTION
--- --------------------------------------------------------
1 Initial ZFS filesystem version
2 Type-ful directory entries
3 Support for CIFS-style ACLs
For more information on a particular version, including supported releases, see:
http://www.opensolaris.org/os/community/zfs/version/zpl/N
Where 'N' is the version number.
</quote>
Although as mentioned, version 3 will not be delivered as part of this
case.
D. MANPAGE CHANGES
TBD, but very similar to the text in the above DESCRIPTION.
Furthermore, the zpool(1m) manpage and output of 'zpool upgrade ...'
will be modified to make clear the distinction between zpool (pool) and
zfs (filesystem) on-disk versions.
6. Resources and Schedule
6.4. Steering Committee requested information
6.4.1. Consolidation C-team Name:
ON
6.5. ARC review type: FastTrack
