Differential D774 Diff 6227 en_US.ISO8859-1/books/handbook/zfs/chapter.xml

Changeset View

Standalone View

en_US.ISO8859-1/books/handbook/zfs/chapter.xml

Show First 20 Lines • Show All 137 Lines • ▼ Show 20 Lines	<para>The examples in this section assume three
<acronym>SCSI</acronym> disks with the device names		<acronym>SCSI</acronym> disks with the device names
<filename><replaceable>da0</replaceable></filename>,		<filename><replaceable>da0</replaceable></filename>,
<filename><replaceable>da1</replaceable></filename>, and		<filename><replaceable>da1</replaceable></filename>, and
<filename><replaceable>da2</replaceable></filename>. Users		<filename><replaceable>da2</replaceable></filename>. Users
of <acronym>SATA</acronym> hardware should instead use		of <acronym>SATA</acronym> hardware should instead use
<filename><replaceable>ada</replaceable></filename> device		<filename><replaceable>ada</replaceable></filename> device
names.</para>		names.</para>

		<para>The first step in creating a new <acronym>ZFS</acronym> pool
		is deciding on the disk layout. There are a number of options
		wblockUnsubmitted Not Done Inline Actions Too many sentences starting with "The", and this can be reversed: Deciding on a disk layout is the first step in creating a new <acronym>ZFS</acronym> pool. wblock: Too many sentences starting with "The", and this can be reversed: Deciding on a disk layout is…
		and once the pool is created, the layout cannot be changed.
		wblockUnsubmitted Not Done Inline Actions This sentence is a little unclear. It's trying to say that choosing correctly is both complex and impossible to undo. Maybe: Because there are many options and the choices cannot be changed after a pool has been created, it is important to take care when creating a pool. wblock: This sentence is a little unclear. It's trying to say that choosing correctly is both complex…
		For more information see <link
		linkend="zfs-advanced-layout">Advanced Topics - Pool
		Layout</link>.</para>

<sect2 xml:id="zfs-quickstart-single-disk-pool">		<sect2 xml:id="zfs-quickstart-single-disk-pool">
<title>Single Disk Pool</title>		<title>Single Disk Pool</title>

<para>To create a simple, non-redundant pool using a single		<para>To create a simple, non-redundant pool using a single
disk device:</para>		disk device:</para>

<screen>&prompt.root; <userinput>zpool create <replaceable>example</replaceable> <replaceable>/dev/da0</replaceable></userinput></screen>		<screen>&prompt.root; <userinput>zpool create <replaceable>example</replaceable> <replaceable>/dev/da0</replaceable></userinput></screen>

<para>To view the new pool, review the output of		<para>To view the new pool, review the output of
<command>df</command>:</para>		<command>df</command>:</para>

<screen>&prompt.root; <userinput>df</userinput>		<screen>&prompt.root; <userinput>df</userinput>
Filesystem 1K-blocks Used Avail Capacity Mounted on		Filesystem 1K-blocks Used Avail Capacity Mounted on
/dev/ad0s1a 2026030 235230 1628718 13% /		/dev/ad0s1a 2026030 235230 1628718 13% /
devfs 1 1 0 100% /dev		devfs 1 1 0 100% /dev
/dev/ad0s1d 54098308 1032846 48737598 2% /usr		/dev/ad0s1d 54098308 1032846 48737598 2% /usr
example 17547136 0 17547136 0% /example</screen>		example 17547136 0 17547136 0% /example</screen>

<para>This output shows that the <literal>example</literal> pool		<para>This output shows that the <literal>example</literal> pool
has been created and mounted. It is now accessible as a file		has been created and mounted. It is now accessible as a file
system. Files can be created on it and users can browse		system. Files can be created on it and users can browse
it:</para>		it:</para>

		wblockUnsubmitted Done Inline Actions This is redundant. Actually, I'm pretty sure it was this way and I removed the "like in this example" part. wblock: This is redundant. Actually, I'm pretty sure it was this way and I removed the "like in this…
<screen>&prompt.root; <userinput>cd /example</userinput>		<screen>&prompt.root; <userinput>cd /example</userinput>
&prompt.root; <userinput>ls</userinput>		&prompt.root; <userinput>ls</userinput>
&prompt.root; <userinput>touch testfile</userinput>		&prompt.root; <userinput>touch testfile</userinput>
&prompt.root; <userinput>ls -al</userinput>		&prompt.root; <userinput>ls -al</userinput>
total 4		total 4
drwxr-xr-x 2 root wheel 3 Aug 29 23:15 .		drwxr-xr-x 2 root wheel 3 Aug 29 23:15 .
drwxr-xr-x 21 root wheel 512 Aug 29 23:12 ..		drwxr-xr-x 21 root wheel 512 Aug 29 23:12 ..
-rw-r--r-- 1 root wheel 0 Aug 29 23:15 testfile</screen>		-rw-r--r-- 1 root wheel 0 Aug 29 23:15 testfile</screen>

<para>However, this pool is not taking advantage of any		<para>However, this pool is not taking advantage of any
<acronym>ZFS</acronym> features. To create a dataset on this		<acronym>ZFS</acronym> features. To create a dataset on this
pool with compression enabled:</para>		pool with compression enabled:</para>

<screen>&prompt.root; <userinput>zfs create example/compressed</userinput>		<screen>&prompt.root; <userinput>zfs create example/compressed</userinput>
&prompt.root; <userinput>zfs set compression=gzip example/compressed</userinput></screen>		&prompt.root; <userinput>zfs set compression=gzip example/compressed</userinput></screen>
		delphijUnsubmitted Not Done Inline Actions It's probably worth replacing this with lz4 and leave gzip for those who know what they are doing. delphij: It's probably worth replacing this with lz4 and leave gzip for those who know what they are…

<para>The <literal>example/compressed</literal> dataset is now a		<para>The <literal>example/compressed</literal> dataset is now a
<acronym>ZFS</acronym> compressed file system. Try copying		<acronym>ZFS</acronym> compressed file system. Try copying
some large files to		some large files to
<filename>/example/compressed</filename>.</para>		<filename>/example/compressed</filename>.</para>

<para>Compression can be disabled with:</para>		<para>Compression can be disabled with:</para>

Show All 35 Lines
example/compressed on /example/compressed (zfs, local)</screen>		example/compressed on /example/compressed (zfs, local)</screen>

<para>After creation, <acronym>ZFS</acronym> datasets can be		<para>After creation, <acronym>ZFS</acronym> datasets can be
used like any file systems. However, many other features are		used like any file systems. However, many other features are
available which can be set on a per-dataset basis. In the		available which can be set on a per-dataset basis. In the
example below, a new file system called		example below, a new file system called
<literal>data</literal> is created. Important files will be		<literal>data</literal> is created. Important files will be
stored here, so it is configured to keep two copies of each		stored here, so it is configured to keep two copies of each
data block:</para>		data block:</para>
		delphijUnsubmitted Not Done Inline Actions It would be worth mentioning why one wants to do it (e.g. for single disk pool, additional copies of data would provide more redundancy; in the case there is bad block on the hard drive, this gives more opportunity to recover data). delphij: It would be worth mentioning why one wants to do it (e.g. for single disk pool, additional…

<screen>&prompt.root; <userinput>zfs create example/data</userinput>		<screen>&prompt.root; <userinput>zfs create example/data</userinput>
&prompt.root; <userinput>zfs set copies=2 example/data</userinput></screen>		&prompt.root; <userinput>zfs set copies=2 example/data</userinput></screen>

<para>It is now possible to see the data and space utilization		<para>It is now possible to see the data and space utilization
by issuing <command>df</command>:</para>		by issuing <command>df</command>:</para>

<screen>&prompt.root; <userinput>df</userinput>		<screen>&prompt.root; <userinput>df</userinput>
Show All 13 Lines	example/data 17547008 0 17547008 0% /example/data</screen>
concepts such as volumes and partitions, and allows multiple		concepts such as volumes and partitions, and allows multiple
file systems to occupy the same pool.</para>		file systems to occupy the same pool.</para>

<para>To destroy the file systems and then destroy the pool as		<para>To destroy the file systems and then destroy the pool as
it is no longer needed:</para>		it is no longer needed:</para>

<screen>&prompt.root; <userinput>zfs destroy example/compressed</userinput>		<screen>&prompt.root; <userinput>zfs destroy example/compressed</userinput>
&prompt.root; <userinput>zfs destroy example/data</userinput>		&prompt.root; <userinput>zfs destroy example/data</userinput>
&prompt.root; <userinput>zpool destroy example</userinput></screen>		&prompt.root; <userinput>zpool destroy example</userinput></screen>
		delphijUnsubmitted Not Done Inline Actions One do not really need to destroy individual datasets when destroying the whole pool -- do we really want to demonstrate how to destroy the pool here? delphij: One do not really need to destroy individual datasets when destroying the whole pool -- do we…
</sect2>		</sect2>

<sect2 xml:id="zfs-quickstart-raid-z">		<sect2 xml:id="zfs-quickstart-raid-z">
<title>RAID-Z</title>		<title>RAID-Z</title>

<para>Disks fail. One method of avoiding data loss from disk		<para>Disks fail. One method of avoiding data loss from disk
failure is to implement <acronym>RAID</acronym>.		failure is to implement <acronym>RAID</acronym>.
<acronym>ZFS</acronym> supports this feature in its pool		<acronym>ZFS</acronym> supports this feature in its pool
Show All 23 Lines	&prompt.root; <userinput>zpool destroy example</userinput></screen>
pool:</para>		pool:</para>

<screen>&prompt.root; <userinput>zfs create storage/home</userinput></screen>		<screen>&prompt.root; <userinput>zfs create storage/home</userinput></screen>

<para>Compression and keeping extra copies of directories		<para>Compression and keeping extra copies of directories
and files can be enabled:</para>		and files can be enabled:</para>

<screen>&prompt.root; <userinput>zfs set copies=2 storage/home</userinput>		<screen>&prompt.root; <userinput>zfs set copies=2 storage/home</userinput>
&prompt.root; <userinput>zfs set compression=gzip storage/home</userinput></screen>		&prompt.root; <userinput>zfs set compression=gzip storage/home</userinput></screen>
		delphijUnsubmitted Not Done Inline Actions Similar -- we probably want to tell the users to use compression=lz4 instead. delphij: Similar -- we probably want to tell the users to use compression=lz4 instead.

<para>To make this the new home directory for users, copy the		<para>To make this the new home directory for users, copy the
user data to this directory and create the appropriate		user data to this directory and create the appropriate
symbolic links:</para>		symbolic links:</para>

<screen>&prompt.root; <userinput>cp -rp /home/* /storage/home</userinput>		<screen>&prompt.root; <userinput>cp -rp /home/* /storage/home</userinput>
&prompt.root; <userinput>rm -rf /home /usr/home</userinput>		&prompt.root; <userinput>rm -rf /home /usr/home</userinput>
&prompt.root; <userinput>ln -s /storage/home /home</userinput>		&prompt.root; <userinput>ln -s /storage/home /home</userinput>
Show All 12 Lines	&prompt.root; <userinput>ln -s /storage/home /usr/home</userinput></screen>
single directory or file.</para>		single directory or file.</para>

<para>The <literal>@</literal> character is a delimiter between		<para>The <literal>@</literal> character is a delimiter between
the file system name or the volume name. If an important		the file system name or the volume name. If an important
directory has been accidentally deleted, the file system can		directory has been accidentally deleted, the file system can
be backed up, then rolled back to an earlier snapshot when the		be backed up, then rolled back to an earlier snapshot when the
directory still existed:</para>		directory still existed:</para>

<screen>&prompt.root; <userinput>zfs rollback storage/home@08-30-08</userinput></screen>		<screen>&prompt.root; <userinput>zfs rollback storage/home@08-30-08</userinput></screen>
		delphijUnsubmitted Not Done Inline Actions Should we mention that rollback would destroy all data that is newer than the snapshot here? delphij: Should we mention that rollback would destroy all data that is newer than the snapshot here?

<para>To list all available snapshots, run		<para>To list all available snapshots, run
<command>ls</command> in the file system's		<command>ls</command> in the file system's
<filename>.zfs/snapshot</filename> directory. For example, to		<filename>.zfs/snapshot</filename> directory. For example, to
see the previously taken snapshot:</para>		see the previously taken snapshot:</para>

<screen>&prompt.root; <userinput>ls /storage/home/.zfs/snapshot</userinput></screen>		<screen>&prompt.root; <userinput>ls /storage/home/.zfs/snapshot</userinput></screen>

<para>It is possible to write a script to perform regular		<para>It is possible to write a script to perform regular
snapshots on user data. However, over time, snapshots can		snapshots on user data. However, over time, snapshots can
consume a great deal of disk space. The previous snapshot can		consume a great deal of disk space. The previous snapshot can
be removed using the command:</para>		be removed using the command:</para>

<screen>&prompt.root; <userinput>zfs destroy storage/home@08-30-08</userinput></screen>		<screen>&prompt.root; <userinput>zfs destroy storage/home@08-30-08</userinput></screen>

<para>After testing, <filename>/storage/home</filename> can be		<para>After testing, <filename>/storage/home</filename> can be
made the real <filename>/home</filename> using this		made the real <filename>/home</filename> using this
command:</para>		command:</para>

<screen>&prompt.root; <userinput>zfs set mountpoint=/home storage/home</userinput></screen>		<screen>&prompt.root; <userinput>zfs set mountpoint=/home storage/home</userinput></screen>
		delphijUnsubmitted Not Done Inline Actions Since we have already created a symlink, do we still want to set the mountpoint? Setting the property may confuse replica (zfs send -R would send these properties) and cause undesirable results. delphij: Since we have already created a symlink, do we still want to set the mountpoint? Setting the…

<para>Run <command>df</command> and <command>mount</command> to		<para>Run <command>df</command> and <command>mount</command> to
confirm that the system now treats the file system as the real		confirm that the system now treats the file system as the real
<filename>/home</filename>:</para>		<filename>/home</filename>:</para>

<screen>&prompt.root; <userinput>mount</userinput>		<screen>&prompt.root; <userinput>mount</userinput>
/dev/ad0s1a on / (ufs, local)		/dev/ad0s1a on / (ufs, local)
devfs on /dev (devfs, local)		devfs on /dev (devfs, local)
▲ Show 20 Lines • Show All 91 Lines • ▼ Show 20 Lines	errors: No known data errors</screen>

<sect2 xml:id="zfs-quickstart-data-verification">		<sect2 xml:id="zfs-quickstart-data-verification">
<title>Data Verification</title>		<title>Data Verification</title>

<para><acronym>ZFS</acronym> uses checksums to verify the		<para><acronym>ZFS</acronym> uses checksums to verify the
integrity of stored data. These are enabled automatically		integrity of stored data. These are enabled automatically
upon creation of file systems.</para>		upon creation of file systems.</para>

<warning>		<warning>
<para>Checksums can be disabled, but it is		<para>Checksums can be, but should never be disabled. The
		wblockUnsubmitted Done Inline Actions This sentence is somewhat passive. How about just "Do not disable checksums!" wblock: This sentence is somewhat passive. How about just "Do not disable checksums!"
<emphasis>not</emphasis> recommended! Checksums take very		storage space for the checksum is a fixed part of the
little storage space and provide data integrity. Many		metadata, so no space is saved by disabling checksums.
<acronym>ZFS</acronym> features will not work properly with		Many features will not work properly without checksums and
checksums disabled. There is no noticeable performance gain		there is also no noticeable performance gain
from disabling these checksums.</para>		from disabling these checksums.</para>
</warning>		</warning>
		wblockUnsubmitted Done Inline Actions Combine and simplify: "Many features will not work properly without checksums, and there is no noticeable performance improvement gained by disabling them." wblock: Combine and simplify: "Many features will not work properly without checksums, and there is no…

<para>Checksum verification is known as		<para>Checksum verification is known as
<emphasis>scrubbing</emphasis>. Verify the data integrity of		<emphasis>scrubbing</emphasis>. Verify the data integrity of
the <literal>storage</literal> pool with this command:</para>		the <literal>storage</literal> pool with this command:</para>

<screen>&prompt.root; <userinput>zpool scrub storage</userinput></screen>		<screen>&prompt.root; <userinput>zpool scrub storage</userinput></screen>

<para>The duration of a scrub depends on the amount of data		<para>The duration of a scrub depends on the amount of data
Show All 19 Lines
errors: No known data errors</screen>		errors: No known data errors</screen>

<para>The completion date of the last scrub operation is		<para>The completion date of the last scrub operation is
displayed to help track when another scrub is required.		displayed to help track when another scrub is required.
Routine scrubs help protect data from silent corruption and		Routine scrubs help protect data from silent corruption and
ensure the integrity of the pool.</para>		ensure the integrity of the pool.</para>

<para>Refer to &man.zfs.8; and &man.zpool.8; for other		<para>Refer to &man.zfs.8; and &man.zpool.8; for other
<acronym>ZFS</acronym> options.</para>		<acronym>ZFS</acronym> options.</para>
		delphijUnsubmitted Not Done Inline Actions I think we should also mention the periodic zpool scrub tasks. It's part of maintaining a storage pool, just like RAID card's "patrol scanning". delphij: I think we should also mention the periodic zpool scrub tasks. It's part of maintaining a…
</sect2>		</sect2>
</sect1>		</sect1>

<sect1 xml:id="zfs-zpool">		<sect1 xml:id="zfs-zpool">
<title><command>zpool</command> Administration</title>		<title><command>zpool</command> Administration</title>

<para><acronym>ZFS</acronym> administration is divided between two		<para><acronym>ZFS</acronym> administration is divided between two
main utilities. The <command>zpool</command> utility controls		main utilities. The <command>zpool</command> utility controls
▲ Show 20 Lines • Show All 73 Lines • ▼ Show 20 Lines	errors: No known data errors</screen>
administrator to <emphasis>under-provision</emphasis> the		administrator to <emphasis>under-provision</emphasis> the
disks, using less than the full capacity. If a future		disks, using less than the full capacity. If a future
replacement disk of the same nominal size as the original		replacement disk of the same nominal size as the original
actually has a slightly smaller capacity, the smaller		actually has a slightly smaller capacity, the smaller
partition will still fit, and the replacement disk can still		partition will still fit, and the replacement disk can still
be used.</para>		be used.</para>

<para>Create a		<para>Create a
<link linkend="zfs-term-vdev-raidz">RAID-Z2</link> pool using		<link linkend="zfs-term-vdev-raidz">RAID-Z2</link> pool using
		delphijUnsubmitted Not Done Inline Actions Should we move the description of RAID-Z2 earlier? It could be confusing for readers as they have no idea what RAID-Z2 is at this point, even with a link. delphij: Should we move the description of RAID-Z2 earlier? It could be confusing for readers as they…
partitions:</para>		partitions:</para>

<screen>&prompt.root; <userinput>zpool create <replaceable>mypool</replaceable> raidz2 <replaceable>/dev/ada0p3</replaceable> <replaceable>/dev/ada1p3</replaceable> <replaceable>/dev/ada2p3</replaceable> <replaceable>/dev/ada3p3</replaceable> <replaceable>/dev/ada4p3</replaceable> <replaceable>/dev/ada5p3</replaceable></userinput>		<screen>&prompt.root; <userinput>zpool create <replaceable>mypool</replaceable> raidz2 <replaceable>/dev/ada0p3</replaceable> <replaceable>/dev/ada1p3</replaceable> <replaceable>/dev/ada2p3</replaceable> <replaceable>/dev/ada3p3</replaceable> <replaceable>/dev/ada4p3</replaceable> <replaceable>/dev/ada5p3</replaceable></userinput>
&prompt.root; <userinput>zpool status</userinput>		&prompt.root; <userinput>zpool status</userinput>
pool: mypool		pool: mypool
state: ONLINE		state: ONLINE
scan: none requested		scan: none requested
config:		config:
▲ Show 20 Lines • Show All 106 Lines • ▼ Show 20 Lines	config:
ada1p3 ONLINE 0 0 0		ada1p3 ONLINE 0 0 0

errors: No known data errors</screen>		errors: No known data errors</screen>

<para>When adding disks to the existing vdev is not an option,		<para>When adding disks to the existing vdev is not an option,
as for <acronym>RAID-Z</acronym>, an alternative method is to		as for <acronym>RAID-Z</acronym>, an alternative method is to
add another vdev to the pool. Additional vdevs provide higher		add another vdev to the pool. Additional vdevs provide higher
performance, distributing writes across the vdevs. Each vdev		performance, distributing writes across the vdevs. Each vdev
is responsible for providing its own redundancy. It is		is responsible for providing its own redundancy. Do not mix
possible, but discouraged, to mix vdev types, like		different vdev types, like
		wblockUnsubmitted Done Inline Actions Good! wblock: Good!
<literal>mirror</literal> and <literal>RAID-Z</literal>.		<literal>mirror</literal> and <literal>RAID-Z</literal>.
Adding a non-redundant vdev to a pool containing mirror or		Adding a non-redundant vdev to a pool containing mirror or
<acronym>RAID-Z</acronym> vdevs risks the data on the entire		<acronym>RAID-Z</acronym> vdevs risks the data on the entire
pool. Writes are distributed, so the failure of the		pool. Writes are distributed, so the failure of the
non-redundant disk will result in the loss of a fraction of		non-redundant vdev will result in the loss of a fraction of
every block that has been written to the pool.</para>		every block that has been written to the pool.</para>

<para>Data is striped across each of the vdevs. For example,		<para>Data is striped across each of the vdevs. For example,
with two mirror vdevs, this is effectively a		with two mirror vdevs, this is effectively a
<acronym>RAID</acronym> 10 that stripes writes across two sets		<acronym>RAID</acronym> 10 that stripes writes across two sets
of mirrors. Space is allocated so that each vdev reaches 100%		of mirrors. Space is allocated so that each vdev reaches 100%
full at the same time. There is a performance penalty if the		full at the same time. There is a performance penalty if the
vdevs have different amounts of free space, as a		vdevs have different amounts of free space, as a
disproportionate amount of the data is written to the less		disproportionate amount of the data is written to the vdev
full vdev.</para>		that is less full.</para>

<para>When attaching additional devices to a boot pool, remember		<para>When attaching additional devices to a boot pool, remember
to update the bootcode.</para>		to update the bootcode.</para>

<para>Attach a second mirror group (<filename>ada2p3</filename>		<para>Attach a second mirror group (<filename>ada2p3</filename>
and <filename>ada3p3</filename>) to the existing		and <filename>ada3p3</filename>) to the existing
mirror:</para>		mirror:</para>

▲ Show 20 Lines • Show All 548 Lines • ▼ Show 20 Lines	errors: No known data errors</screen>
available to the pool.</para>		available to the pool.</para>
</sect2>		</sect2>

<sect2 xml:id="zfs-zpool-import">		<sect2 xml:id="zfs-zpool-import">
<title>Importing and Exporting Pools</title>		<title>Importing and Exporting Pools</title>

<para>Pools are <emphasis>exported</emphasis> before moving them		<para>Pools are <emphasis>exported</emphasis> before moving them
to another system. All datasets are unmounted, and each		to another system. All datasets are unmounted, and each
device is marked as exported but still locked so it cannot be		device is marked as exported but still locked so it cannot be
		delphijUnsubmitted Not Done Inline Actions This doesn't seem right. These devices can be used (open for write) after export but zfs would give a warning if they are being used to create additional pool. delphij: This doesn't seem right. These devices can be used (open for write) after export but zfs would…
used by other disk subsystems. This allows pools to be		used by other disk subsystems. This allows pools to be
<emphasis>imported</emphasis> on other machines, other		<emphasis>imported</emphasis> on other machines, other
operating systems that support <acronym>ZFS</acronym>, and		operating systems that support <acronym>ZFS</acronym>, and
even different hardware architectures (with some caveats, see		even different hardware architectures (with some caveats, see
&man.zpool.8;). When a dataset has open files,		&man.zpool.8;). When a dataset has open files,
<command> zpool export -f</command> can be used to force the		<command> zpool export -f</command> can be used to force the
export of a pool. Use this with caution. The datasets are		export of a pool. Use this with caution. The datasets are
forcibly unmounted, potentially resulting in unexpected		forcibly unmounted, potentially resulting in unexpected
▲ Show 20 Lines • Show All 85 Lines • ▼ Show 20 Lines

Use 'zpool upgrade -v' for a list of available legacy versions.		Use 'zpool upgrade -v' for a list of available legacy versions.
Every feature flags pool has all supported features enabled.		Every feature flags pool has all supported features enabled.
&prompt.root; <userinput>zpool upgrade mypool</userinput>		&prompt.root; <userinput>zpool upgrade mypool</userinput>
This system supports ZFS pool feature flags.		This system supports ZFS pool feature flags.

Successfully upgraded 'mypool' from version 28 to feature flags.		Successfully upgraded 'mypool' from version 28 to feature flags.
Enabled the following features on 'mypool':		Enabled the following features on 'mypool':
async_destroy		async_destroy
		delphijUnsubmitted Not Done Inline Actions The current ZFS code would say: async_destroy empty_bpobj lz4_compress multi_vdev_crash_dump spacemap_histogram enabled_txg hole_birth extensible_dataset embedded_data bookmarks filesystem_limits large_blocks delphij: The current ZFS code would say: async_destroy empty_bpobj lz4_compress…
empty_bpobj		empty_bpobj
lz4_compress		lz4_compress
multi_vdev_crash_dump</screen>		multi_vdev_crash_dump</screen>

<para>The newer features of <acronym>ZFS</acronym> will not be		<para>The newer features of <acronym>ZFS</acronym> will not be
available until <command>zpool upgrade</command> has		available until <command>zpool upgrade</command> has
completed. <command>zpool upgrade -v</command> can be used to		completed. <command>zpool upgrade -v</command> can be used to
see what new features will be provided by upgrading, as well		see what new features will be provided by upgrading, as well
▲ Show 20 Lines • Show All 47 Lines • ▼ Show 20 Lines	Enabled the following features on 'mypool':
enabled_txg		enabled_txg
hole_birth		hole_birth
extensible_dataset		extensible_dataset
bookmarks		bookmarks
filesystem_limits</screen>		filesystem_limits</screen>

<warning>		<warning>
<para>The boot code on systems that boot from a pool must be		<para>The boot code on systems that boot from a pool must be
updated to support the new pool version. Use		updated to support the new pool version. Use
		delphijUnsubmitted Not Done Inline Actions and some features, for instance large blocks, must not be used on the boot pool. delphij: and some features, for instance large blocks, must not be used on the boot pool.
<command>gpart bootcode</command> on the partition that		<command>gpart bootcode</command> on the partition that
contains the boot code. See &man.gpart.8; for more		contains the boot code. See &man.gpart.8; for more
information.</para>		information.</para>
</warning>		</warning>
</sect2>		</sect2>

<sect2 xml:id="zfs-zpool-history">		<sect2 xml:id="zfs-zpool-history">
<title>Displaying Recorded Pool History</title>		<title>Displaying Recorded Pool History</title>
▲ Show 20 Lines • Show All 454 Lines • ▼ Show 20 Lines	&prompt.root;</screen>
the time required to copy the data from backup. Snapshots are		the time required to copy the data from backup. Snapshots are
not a replacement for a complete backup of a pool, but can be		not a replacement for a complete backup of a pool, but can be
used as a quick and easy way to store a copy of the dataset at		used as a quick and easy way to store a copy of the dataset at
a specific point in time.</para>		a specific point in time.</para>

<sect3 xml:id="zfs-zfs-snapshot-creation">		<sect3 xml:id="zfs-zfs-snapshot-creation">
<title>Creating Snapshots</title>		<title>Creating Snapshots</title>

<para>Snapshots are created with <command>zfs snapshot		<para>Snapshots are created with <command>zfs snapshot
		wblockUnsubmitted Done Inline Actions This is a whitespace change. wblock: This is a whitespace change.
<replaceable>dataset</replaceable>@<replaceable>snapshotname</replaceable></command>.		<replaceable>dataset</replaceable>@<replaceable>snapshotname</replaceable></command>.
Adding <option>-r</option> creates a snapshot recursively,		Adding <option>-r</option> creates a snapshot recursively,
with the same name on all child datasets.</para>		with the same name on all child datasets.</para>

<para>Create a recursive snapshot of the entire pool:</para>		<para>Create a recursive snapshot of the entire pool:</para>

<screen>&prompt.root; <userinput>zfs list -t all</userinput>		<screen>&prompt.root; <userinput>zfs list -t all</userinput>
NAME USED AVAIL REFER MOUNTPOINT		NAME USED AVAIL REFER MOUNTPOINT
▲ Show 20 Lines • Show All 221 Lines • ▼ Show 20 Lines	passwd passwd.copy vi.recover</screen>

<para>The rollback operation restored the dataset to the state		<para>The rollback operation restored the dataset to the state
of the last snapshot. It is also possible to roll back to a		of the last snapshot. It is also possible to roll back to a
snapshot that was taken much earlier and has other snapshots		snapshot that was taken much earlier and has other snapshots
that were created after it. When trying to do this,		that were created after it. When trying to do this,
<acronym>ZFS</acronym> will issue this warning:</para>		<acronym>ZFS</acronym> will issue this warning:</para>

<screen>&prompt.root; <userinput>zfs list -rt snapshot <replaceable>mypool/var/tmp</replaceable></userinput>		<screen>&prompt.root; <userinput>zfs list -rt snapshot <replaceable>mypool/var/tmp</replaceable></userinput>
AME USED AVAIL REFER MOUNTPOINT		NAME USED AVAIL REFER MOUNTPOINT
mypool/var/tmp@my_recursive_snapshot 88K - 152K -		mypool/var/tmp@my_recursive_snapshot 88K - 152K -
mypool/var/tmp@after_cp 53.5K - 118K -		mypool/var/tmp@after_cp 53.5K - 118K -
mypool/var/tmp@diff_snapshot 0 - 120K -		mypool/var/tmp@diff_snapshot 0 - 120K -
&prompt.root; <userinput>zfs rollback <replaceable>mypool/var/tmp@my_recursive_snapshot</replaceable></userinput>		&prompt.root; <userinput>zfs rollback <replaceable>mypool/var/tmp@my_recursive_snapshot</replaceable></userinput>
cannot rollback to 'mypool/var/tmp@my_recursive_snapshot': more recent snapshots exist		cannot rollback to 'mypool/var/tmp@my_recursive_snapshot': more recent snapshots exist
use '-r' to force deletion of the following snapshots:		use '-r' to force deletion of the following snapshots:
mypool/var/tmp@after_cp		mypool/var/tmp@after_cp
mypool/var/tmp@diff_snapshot</screen>		mypool/var/tmp@diff_snapshot</screen>
▲ Show 20 Lines • Show All 77 Lines • ▼ Show 20 Lines	<para>When <command>ls .zfs/snapshot</command> was issued, the
others. Copying files or directories from this hidden		others. Copying files or directories from this hidden
<filename>.zfs/snapshot</filename> is simple enough. Trying		<filename>.zfs/snapshot</filename> is simple enough. Trying
it the other way around results in this error:</para>		it the other way around results in this error:</para>

<screen>&prompt.root; <userinput>cp <replaceable>/etc/rc.conf</replaceable> /var/tmp/.zfs/snapshot/<replaceable>after_cp/</replaceable></userinput>		<screen>&prompt.root; <userinput>cp <replaceable>/etc/rc.conf</replaceable> /var/tmp/.zfs/snapshot/<replaceable>after_cp/</replaceable></userinput>
cp: /var/tmp/.zfs/snapshot/after_cp/rc.conf: Read-only file system</screen>		cp: /var/tmp/.zfs/snapshot/after_cp/rc.conf: Read-only file system</screen>

<para>The error reminds the user that snapshots are read-only		<para>The error reminds the user that snapshots are read-only
and can not be changed after creation. No files can be		and cannot be changed after creation. No files can be
copied into or removed from snapshot directories because		copied into or removed from snapshot directories because
that would change the state of the dataset they		that would change the state of the dataset they
represent.</para>		represent.</para>

<para>Snapshots consume space based on how much the parent		<para>Snapshots consume space based on how much the parent
file system has changed since the time of the snapshot. The		file system has changed since the time of the snapshot. The
<literal>written</literal> property of a snapshot tracks how		<literal>written</literal> property of a snapshot tracks how
much space is being used by the snapshot.</para>		much space is being used by the snapshot.</para>

<para>Snapshots are destroyed and the space reclaimed with		<para>Snapshots are destroyed and the space reclaimed with
<command>zfs destroy		<command>zfs destroy
<replaceable>dataset</replaceable>@<replaceable>snapshot</replaceable></command>.		<replaceable>dataset</replaceable>@<replaceable>snapshot</replaceable></command>.
Adding <option>-r</option> recursively removes all snapshots		Adding <option>-r</option> recursively removes all snapshots
with the same name under the parent dataset. Adding		with the same name under the parent dataset. Adding
<option>-n -v</option> to the command displays a list of the		<option>-n -v</option> to the command displays a list of the
snapshots that would be deleted and an estimate of how much		snapshots that would be deleted and an estimate of how much
space would be reclaimed without performing the actual		space would be reclaimed without performing the actual
destroy operation.</para>		destroy operation.</para>
</sect3>		</sect3>
</sect2>		</sect2>

<sect2 xml:id="zfs-zfs-clones">		<sect2 xml:id="zfs-zfs-clones">
<title>Managing Clones</title>		<title>Managing Clones</title>

<para>A clone is a copy of a snapshot that is treated more like		<para>A clone is an exact copy of a snapshot that is treated
		wblockUnsubmitted Done Inline Actions "more like" is vague. wblock: "more like" is vague.
a regular dataset. Unlike a snapshot, a clone is not read		like a regular dataset. Unlike a snapshot, the clone can
		wblockUnsubmitted Done Inline Actions "be powerful" is weird, and "in the case of" is wordy. "Clones can also be useful for databases, ..." wblock: "be powerful" is weird, and "in the case of" is wordy. "Clones can also be useful for…
only, is mounted, and can have its own properties. Once a		be changed independently from its originating dataset. A
		wblockUnsubmitted Done Inline Actions "can" is not needed. wblock: "can" is not needed.
clone has been created using <command>zfs clone</command>, the		clone can be written to, mounted, and have its own dataset
		wblockUnsubmitted Not Done Inline Actions "Similar to snapshots, a clone shares unmodified blocks with the <literal>origin</literal> snapshot from which it was created." Should "origin" be literal, or emphasis? wblock: "Similar to snapshots, a clone shares unmodified blocks with the <literal>origin</literal>…
		allanjudeAuthorUnsubmitted Not Done Inline Actions In this case 'origin' is the name of a ZFS property, indicating the parent dataset. You read it with 'zfs get origin <dataset>' allanjude: In this case 'origin' is the name of a ZFS property, indicating the parent dataset. You read it…
snapshot it was created from cannot be destroyed. The		properties. Similar to how snapshots works, a clone shares
		bjkUnsubmitted Done Inline Actions Clones, plural. bjk: Clones, plural.
		wblockUnsubmitted Not Done Inline Actions Maybe Phabricator helping, but this reads "how snapshots works". Fix that, and simplify: Similar to snapshots, clones share wblock: Maybe Phabricator helping, but this reads "how snapshots works". Fix that, and simplify…
child/parent relationship between the clone and the snapshot		unmodified blocks with the <literal>origin</literal> snapshot
		bjkUnsubmitted Done Inline Actions "indefinitely" bjk: "indefinitely"
		wblockUnsubmitted Done Inline Actions Break the sentence here. "This conserves space, and the clone only grows when it is modified." wblock: Break the sentence here. "This conserves space, and the clone only grows when it is modified."
can be reversed using <command>zfs promote</command>. After a		it was created from. This converves space, as the clone only consumes additional space when it is
clone has been promoted, the snapshot becomes a child of the		modified. A clone can only be created from a snapshot.</para>
		wblockUnsubmitted Done Inline Actions This is also pretty complicated. "Clones can be kept indefinitely. If the clone achieves the desired result, it can be promoted to the parent dataset. The original file system can them be destroyed." wblock: This is also pretty complicated. "Clones can be kept indefinitely. If the clone achieves the…
clone, rather than of the original parent dataset. This will
change how the space is accounted, but not actually change the
amount of space consumed. The clone can be mounted at any
point within the <acronym>ZFS</acronym> file system hierarchy,
not just below the original location of the snapshot.</para>

<para>To demonstrate the clone feature, this example dataset is		<para>Create a snapshot of a file system, then clone it:</para>
used:</para>

<screen>&prompt.root; <userinput>zfs list -rt all <replaceable>camino/home/joe</replaceable></userinput>		<screen>&prompt.root; <userinput>echo "first message" > <filename>/var/tmp/my_message</filename></userinput>
		&prompt.root; <userinput>ls /var/tmp</userinput>
		my_message vi.recover
		&prompt.root; <userinput>zfs snapshot <replaceable>mypool/var/tmp@first_snapshot</replaceable></userinput>
		&prompt.root; <userinput>zfs list -rt all <replaceable>mypool/var/tmp</replaceable></userinput>
NAME USED AVAIL REFER MOUNTPOINT		NAME USED AVAIL REFER MOUNTPOINT
camino/home/joe 108K 1.3G 87K /usr/home/joe		mypool/var/tmp 249K 30.5G 249K /var/tmp
camino/home/joe@plans 21K - 85.5K -		mypool/var/tmp@first_snapshot 0 - 249K -
camino/home/joe@backup 0K - 87K -</screen>		&prompt.root; <userinput>zfs clone <replaceable>mypool/var/tmp@first_snapshot</replaceable> <replaceable>mypool/var/clone</replaceable></userinput>
		&prompt.root; <userinput>zfs list -rt all <replaceable>mypool/var/clone</replaceable> <replaceable>mypool/var/tmp</replaceable></userinput>
		NAME USED AVAIL REFER MOUNTPOINT
		mypool/var/clone 12.8K 30.5G 249K /var/clone
		mypool/var/tmp 249K 30.5G 249K /var/tmp
		mypool/var/tmp@first_snapshot 0 - 249K -
		&prompt.root; <userinput>ls /var/clone</userinput>
		my_message vi.recover</screen>

<para>A typical use for clones is to experiment with a specific		<para>A clone is essentially a fork of a file system, a common
dataset while keeping the snapshot around to fall back to in		base set of blocks that are shared by two file systems. When
case something goes wrong. Since snapshots can not be		a file is modified in a clone, additional space is consumed.
changed, a read/write clone of a snapshot is created. After		The original blocks are kept intact because they are still
		bjkUnsubmitted Done Inline Actions "counted" may have undesired connotations here. The traditional idiom involves "accounted", but I don't immediately see a way for that to work here. (The current text is probably okay if we don't find anything better.) bjk: "counted" may have undesired connotations here. The traditional idiom involves "accounted"…
		bcrUnsubmitted Done Inline Actions I think we should avoid these braces. Maybe something like: "... because they are still being used by the first file system, and snapshots that belong to it." bcr: I think we should avoid these braces. Maybe something like: "... because they are still being…
		wblockUnsubmitted Done Inline Actions Agreed. "snapshots" means any number of them, including 1. Also agreed that "its" is nonspecific. The comma after "system," is not needed. wblock: Agreed. "snapshots" means any number of them, including 1. Also agreed that "its" is…
		wblockUnsubmitted Done Inline Actions Maybe "The way that space usage is recorded..."? wblock: Maybe "The way that space usage is recorded..."?
the desired result is achieved in the clone, the clone can be		being used by the first file system and any snapshots that belong to it.
promoted to a dataset and the old file system removed. This		When a file is modified in the first file system, additional
is not strictly necessary, as the clone and dataset can		space is consumed again, this time allocated to the snapshot.
		wblockUnsubmitted Not Done Inline Actions "but the blocks that are owned by the parent and child change." wblock: "but the blocks that are owned by the parent and child change."
		allanjudeAuthorUnsubmitted Not Done Inline Actions This reads like the blocks are being changed, which is not the case. It is just the accounting that changes. allanjude: This reads like the blocks are being changed, which is not the case. It is just the accounting…
coexist without problems.</para>		The original blocks are still in use, now only by the
		snapshot. The system now contains all three versions of the
		file.</para>

		wblockUnsubmitted Done Inline Actions "The connection is recorded in the <literal>origin</literal> property." wblock: "The connection is recorded in the <literal>origin</literal> property."
<screen>&prompt.root; <userinput>zfs clone <replaceable>camino/home/joe</replaceable>@<replaceable>backup</replaceable> <replaceable>camino/home/joenew</replaceable></userinput>		<para>One common use case for clones is for experimenting with a
&prompt.root; <userinput>ls /usr/home/joe*</userinput>		dataset while preverving the original.
/usr/home/joe:		Clones can also be useful for
		wblockUnsubmitted Done Inline Actions The multiple if/thens make this sentence confusing. "The dependency between the clone and the original dataset is reversed by <command>zfs promote</command>. The original dataset becomes the clone." wblock: The multiple if/thens make this sentence confusing. "The dependency between the clone and the…
backup.txz plans.txt		databases, jails, and virtual machines. Clones allow the
		administrator to create multiple nearly identical versions of
		wblockUnsubmitted Done Inline Actions Break sentence at "blank". wblock: Break sentence at "blank".
		the original without consuming additional space. Clones can be
		wblockUnsubmitted Done Inline Actions Active, not passive: s/will now point/now points/ wblock: Active, not passive: s/will now point/now points/
		kept indefinitely. If the clone achieves the desired result,
		it can be promoted to be the parent dataset. The original
		file system can then be destroyed.</para>

/usr/home/joenew:		<para>Make a change to the clone, and then the parent:</para>
backup.txz plans.txt
&prompt.root; <userinput>df -h /usr/home</userinput>
Filesystem Size Used Avail Capacity Mounted on
usr/home/joe 1.3G 31k 1.3G 0% /usr/home/joe
usr/home/joenew 1.3G 31k 1.3G 0% /usr/home/joenew</screen>

<para>After a clone is created it is an exact copy of the state		<screen>&prompt.root; <userinput>echo "clone message" > <filename>/var/clone/my_message</filename></userinput>
the dataset was in when the snapshot was taken. The clone can		&prompt.root; <userinput>zfs list -rt all <replaceable>mypool/var/clone</replaceable> <replaceable>mypool/var/tmp</replaceable></userinput>
now be changed independently from its originating dataset.		NAME USED AVAIL REFER MOUNTPOINT
The only connection between the two is the snapshot.		mypool/var/clone 134K 30.5G 249K /var/clone
<acronym>ZFS</acronym> records this connection in the property		mypool/var/tmp 249K 30.5G 249K /var/tmp
<literal>origin</literal>. Once the dependency between the		mypool/var/tmp@first_snapshot 0 - 249K -
snapshot and the clone has been removed by promoting the clone		&prompt.root; <userinput>echo "new message" > <filename>/var/tmp/my_message</filename></userinput>
using <command>zfs promote</command>, the		&prompt.root; <userinput>zfs list -rt all <replaceable>mypool/var/clone</replaceable> <replaceable>mypool/var/tmp</replaceable></userinput>
<literal>origin</literal> of the clone is removed as it is now		NAME USED AVAIL REFER MOUNTPOINT
an independent dataset. This example demonstrates it:</para>		mypool/var/clone 134K 30.5G 249K /var/clone
		mypool/var/tmp 383K 30.5G 249K /var/tmp
		mypool/var/tmp@first_snapshot 134K - 249K -</screen>

<screen>&prompt.root; <userinput>zfs get origin <replaceable>camino/home/joenew</replaceable></userinput>		<para>After a clone has been created, the snapshot it was
		created from cannot be destroyed because the clone only
		contains the blocks that have been modified. The child/parent
		relationship between the clone and the snapshot can be
		reversed using <command>zfs promote</command>. The snapshot
		then becomes a child of the clone, rather than of the original
		parent dataset. The original dataset can then be destroyed if
		wblockUnsubmitted Done Inline Actions Delete "some". wblock: Delete "some".
		desired. The way that space usage is recorded changes when a clone
		wblockUnsubmitted Done Inline Actions "the state wanted by the administrator. The old dataset is obsolete" wblock: "the state wanted by the administrator. The old dataset is obsolete"
		is promoted. The same amount of space is used, but which of
		the blocks are owned by the parent and the child
		changes.</para>
		wblockUnsubmitted Done Inline Actions s/by/with/ wblock: s/by/with/

		<para>The only connection between the clone and the original
		dataset is the snapshot. The
		connection is recorded in the <literal>origin</literal> property.
		The dependency between the clone and the original dataset is
		reversed by
		<command>zfs promote</command>. The original dataset becomes
		the clone. The <literal>origin</literal> property on the
		clone will then be blank. The <literal>origin</literal>
		property on the original dataset now point to the
		snapshot under the dataset that was formerly the clone.</para>

		<para>Promote the clone:</para>

		<screen>&prompt.root; <userinput>zfs list -rt all <replaceable>mypool/var/clone</replaceable> <replaceable>mypool/var/tmp</replaceable></userinput>
		NAME USED AVAIL REFER MOUNTPOINT
		wblockUnsubmitted Done Inline Actions "Any changes made the original dataset after the snapshot the clone was based off of have been destroyed." That is... complicated. "The clone is based on a snapshot. Any changes made to the original dataset after that snapshot was created will be destroyed." wblock: "Any changes made the original dataset after the snapshot the clone was based off of have been…
		mypool/var/clone 134K 30.5G 249K /var/clone
		mypool/var/tmp 383K 30.5G 249K /var/tmp
		bcrUnsubmitted Done Inline Actions it can be destroyed as well now. My english teacher would say that each time we didn't put the tense at the end (or the beginning) of the sentence. A minor thing... bcr: it can be destroyed as well now. My english teacher would say that each time we didn't put the…
		wblockUnsubmitted Done Inline Actions "Now" is already used at the beginning of the sentence, but I'd change the plurals: "Now that there are no other datasets depending on the snapshot, it can be destroyed as well." wblock: "Now" is already used at the beginning of the sentence, but I'd change the plurals: "Now that…
		mypool/var/tmp@first_snapshot 134K - 249K -
		&prompt.root; <userinput>zfs get origin <replaceable>mypool/var/clone</replaceable></userinput>
NAME PROPERTY VALUE SOURCE		NAME PROPERTY VALUE SOURCE
camino/home/joenew origin camino/home/joe@backup -		mypool/var/clone origin mypool/var/tmp@first_snapshot -
&prompt.root; <userinput>zfs promote <replaceable>camino/home/joenew</replaceable></userinput>		&prompt.root; <userinput>zfs promote <replaceable>mypool/var/clone</replaceable></userinput>
&prompt.root; <userinput>zfs get origin <replaceable>camino/home/joenew</replaceable></userinput>		&prompt.root; <userinput>zfs list -rt all <replaceable>mypool/var/clone</replaceable> <replaceable>mypool/var/tmp</replaceable></userinput>
		NAME USED AVAIL REFER MOUNTPOINT
		mypool/var/clone 383K 30.5G 249K /var/clone
		mypool/var/clone@first_snapshot 134K - 249K -
		mypool/var/tmp 134K 30.5G 249K /var/tmp
		&prompt.root; <userinput>zfs get origin <replaceable>mypool/var/clone</replaceable></userinput>
NAME PROPERTY VALUE SOURCE		NAME PROPERTY VALUE SOURCE
camino/home/joenew origin - -</screen>		mypool/var/clone origin - -
		&prompt.root; <userinput>zfs get origin <replaceable>mypool/var/tmp</replaceable></userinput>
		NAME PROPERTY VALUE SOURCE
		mypool/var/tmp origin mypool/var/clone@first_snapshot -</screen>

<para>After making some changes like copying		<para>After making changes to the clone, it is now in
<filename>loader.conf</filename> to the promoted clone, for		the state wanted by the administrator. The old dataset has
example, the old directory becomes obsolete in this case.		is obsolete and the administrator wants to replace it
Instead, the promoted clone can replace it. This can be		with the clone. After the clone is promoted, this can be
achieved by two consecutive commands: <command>zfs		achieved with two additional commands: <command>zfs
destroy</command> on the old dataset and <command>zfs		destroy</command> the old dataset and <command>zfs
rename</command> on the clone to name it like the old		rename</command> the clone to the name of the old dataset.
dataset (it could also get an entirely different name).</para>		The clone could also keep its original name, and only change
		its <literal>mountpoint</literal> property instead.</para>

<screen>&prompt.root; <userinput>cp <replaceable>/boot/defaults/loader.conf</replaceable> <replaceable>/usr/home/joenew</replaceable></userinput>		<screen>&prompt.root; <userinput>zfs destroy -f <replaceable>mypool/var/tmp</replaceable></userinput>
&prompt.root; <userinput>zfs destroy -f <replaceable>camino/home/joe</replaceable></userinput>		&prompt.root; <userinput>zfs rename <replaceable>mypool/var/clone</replaceable> <replaceable>mypool/var/tmp</replaceable></userinput>
&prompt.root; <userinput>zfs rename <replaceable>camino/home/joenew</replaceable> <replaceable>camino/home/joe</replaceable></userinput>		&prompt.root; <userinput>zfs list -rt all <replaceable>mypool/var/tmp</replaceable></userinput>
&prompt.root; <userinput>ls /usr/home/joe</userinput>		NAME USED AVAIL REFER MOUNTPOINT
backup.txz loader.conf plans.txt		mypool/var/tmp 383K 30.5G 249K /var/tmp
&prompt.root; <userinput>df -h <replaceable>/usr/home</replaceable></userinput>		mypool/var/tmp@first_snapshot 134K - 249K -</screen>
Filesystem Size Used Avail Capacity Mounted on
usr/home/joe 1.3G 128k 1.3G 0% /usr/home/joe</screen>

<para>The cloned snapshot is now handled like an ordinary		<para>The original clone is now an ordinary dataset. It
dataset. It contains all the data from the original snapshot		contains all the data from the original snapshot plus the
plus the files that were added to it like		files that were added or modified. Any changes made to the
<filename>loader.conf</filename>. Clones can be used in		original dataset after the snapshot was created will be
different scenarios to provide useful features to ZFS users.		destroyed. Now that there are no other datasets
For example, jails could be provided as snapshots containing		depending on the snapshot, it can be destroyed as
different sets of installed applications. Users can clone		well.</para>
		wblockUnsubmitted Done Inline Actions This sentence is really complicated. "Clones are typically used for experimenting with a dataset while preserving the original." wblock: This sentence is really complicated. "Clones are typically used for experimenting with a…
these snapshots and add their own applications as they see
fit. Once they are satisfied with the changes, the clones can
be promoted to full datasets and provided to end users to work
with like they would with a real dataset. This saves time and
administrative overhead when providing these jails.</para>
</sect2>		</sect2>

<sect2 xml:id="zfs-zfs-send">		<sect2 xml:id="zfs-zfs-send">
<title>Replication</title>		<title>Replication</title>

<para>Keeping data on a single pool in one location exposes		<para>Keeping data on a single pool in one location exposes
it to risks like theft and natural or human disasters. Making		it to risks like theft and natural or human disasters. Making
regular backups of the entire pool is vital.		regular backups of the entire pool is vital.
▲ Show 20 Lines • Show All 413 Lines • ▼ Show 20 Lines	&prompt.root; <userinput>zfs get refreservation storage/home/bob</userinput></screen>
<sect2 xml:id="zfs-zfs-compression">		<sect2 xml:id="zfs-zfs-compression">
<title>Compression</title>		<title>Compression</title>

<para><acronym>ZFS</acronym> provides transparent compression.		<para><acronym>ZFS</acronym> provides transparent compression.
Compressing data at the block level as it is written not only		Compressing data at the block level as it is written not only
saves space, but can also increase disk throughput. If data		saves space, but can also increase disk throughput. If data
is compressed by 25%, but the compressed data is written to		is compressed by 25%, but the compressed data is written to
the disk at the same rate as the uncompressed version,		the disk at the same rate as the uncompressed version,
resulting in an effective write speed of 125%. Compression		resulting in an effective write speed of 125%. Compression
		delphijUnsubmitted Not Done Inline Actions Why it's 125% not 133%? (Assuming compressed data is 1-25% = 75% of old size, we have S=1/(75%)=4/3). delphij: Why it's 125% not 133%? (Assuming compressed data is 1-25% = 75% of old size, we have S=1/…
can also be a great alternative to		can also be a great alternative to
<link linkend="zfs-zfs-deduplication">Deduplication</link>		<link linkend="zfs-zfs-deduplication">Deduplication</link>
because it does not require additional memory.</para>		because it does not require additional memory.</para>
		delphijUnsubmitted Not Done Inline Actions Compression does require additional memory (to stash compressed data before writing) but it's not as much as deduplication does. delphij: Compression does require additional memory (to stash compressed data before writing) but it's…

<para><acronym>ZFS</acronym> offers several different		<para><acronym>ZFS</acronym> offers several different
compression algorithms, each with different trade-offs. With		compression algorithms, each with different trade-offs. With
the introduction of <acronym>LZ4</acronym> compression in		the introduction of <acronym>LZ4</acronym> compression in
<acronym>ZFS</acronym> v5000, it is possible to enable		<acronym>ZFS</acronym> v5000, it is possible to enable
		delphijUnsubmitted Not Done Inline Actions v5000 should not be mentioned anywhere because it's not a meaningful number. Maybe describe this as "feature flags" or just "With the introduction of ..lz4.. compression, it is possible...? delphij: v5000 should not be mentioned anywhere because it's not a meaningful number. Maybe describe…
compression for the entire pool without the large performance		compression for the entire pool without the large performance
trade-off of other algorithms. The biggest advantage to		trade-off of other algorithms. The biggest advantage to
<acronym>LZ4</acronym> is the <emphasis>early abort</emphasis>		<acronym>LZ4</acronym> is the <emphasis>early abort</emphasis>
feature. If <acronym>LZ4</acronym> does not achieve at least		feature. If <acronym>LZ4</acronym> does not achieve at least
12.5% compression in the first part of the data, the block is		12.5% compression in the first part of the data, the block is
written uncompressed to avoid wasting CPU cycles trying to		written uncompressed to avoid wasting CPU cycles trying to
compress data that is either already compressed or		compress data that is either already compressed or
uncompressible. For details about the different compression		uncompressible. For details about the different compression
algorithms available in <acronym>ZFS</acronym>, see the		algorithms available in <acronym>ZFS</acronym>, see the
<link linkend="zfs-term-compression">Compression</link> entry		<link linkend="zfs-term-compression">Compression</link> entry
in the terminology section.</para>		in the terminology section.</para>

<para>The administrator can monitor the effectiveness of		<para>The administrator can monitor the effectiveness of
compression using a number of dataset properties.</para>		compression using a number of dataset properties.</para>

<screen>&prompt.root; <userinput>zfs get used,compressratio,compression,logicalused <replaceable>mypool/compressed_dataset</replaceable></userinput>		<screen>&prompt.root; <userinput>zfs get used,compressratio,compression,logicalused <replaceable>mypool/compressed_dataset</replaceable></userinput>
		delphijUnsubmitted Not Done Inline Actions Personally I would prefer using 'zfs list -o name,used,compressratio,compression,logicalused ...' instead. Just my $0.02. delphij: Personally I would prefer using 'zfs list -o name,used,compressratio,compression,logicalused ...
NAME PROPERTY VALUE SOURCE		NAME PROPERTY VALUE SOURCE
mypool/compressed_dataset used 449G -		mypool/compressed_dataset used 449G -
mypool/compressed_dataset compressratio 1.11x -		mypool/compressed_dataset compressratio 1.11x -
mypool/compressed_dataset compression lz4 local		mypool/compressed_dataset compression lz4 local
mypool/compressed_dataset logicalused 496G -</screen>		mypool/compressed_dataset logicalused 496G -</screen>

<para>The dataset is currently using 449 GB of space (the		<para>The dataset is currently using 449 GB of space (the
used property). Without compression, it would have taken		used property). Without compression, it would have taken
Show All 35 Lines	mypool/compressed_dataset logicalused 496G -</screen>
existing data instead of the whole duplicate block.		existing data instead of the whole duplicate block.
Tremendous space savings are possible if the data contains		Tremendous space savings are possible if the data contains
many duplicated files or repeated information. Be warned:		many duplicated files or repeated information. Be warned:
deduplication requires an extremely large amount of memory,		deduplication requires an extremely large amount of memory,
and most of the space savings can be had without the extra		and most of the space savings can be had without the extra
cost by enabling compression instead.</para>		cost by enabling compression instead.</para>

<para>To activate deduplication, set the		<para>To activate deduplication, set the
<literal>dedup</literal> property on the target pool:</para>		<literal>dedup</literal> property on the target pool:</para>
		delphijUnsubmitted Not Done Inline Actions perhaps target dataset here? delphij: perhaps target dataset here?

<screen>&prompt.root; <userinput>zfs set dedup=on <replaceable>pool</replaceable></userinput></screen>		<screen>&prompt.root; <userinput>zfs set dedup=on <replaceable>pool</replaceable></userinput></screen>

<para>Only new data being written to the pool will be		<para>Only new data being written to the pool will be
deduplicated. Data that has already been written to the pool		deduplicated. Data that has already been written to the pool
will not be deduplicated merely by activating this option. A		will not be deduplicated merely by activating this option. A
pool with a freshly activated deduplication property will look		pool with a freshly activated deduplication property will look
like this example:</para>		like this example:</para>
▲ Show 20 Lines • Show All 136 Lines • ▼ Show 20 Lines	dedup = 1.05, compress = 1.11, copies = 1.00, dedup * compress / copies = 1.16</screen>
the <literal>snapshot</literal> permission to other		the <literal>snapshot</literal> permission to other
users.</para>		users.</para>
</sect2>		</sect2>
</sect1>		</sect1>

<sect1 xml:id="zfs-advanced">		<sect1 xml:id="zfs-advanced">
<title>Advanced Topics</title>		<title>Advanced Topics</title>

		<sect2 xml:id="zfs-advanced-layout">
		<title>Pool Layout</title>

		<para>Choosing the type of <link
		wblockUnsubmitted Done Inline Actions "Choosing the type of vdevs for constructing a pool requires..." wblock: "Choosing the type of vdevs for constructing a pool requires..."
		linkend="zfs-term-vdev">vdevs</link> for construct a
		wblockUnsubmitted Not Done Inline Actions s/construct/constructing/ wblock: s/construct/constructing/
		pool requires deciding which factors are most important. The
		wblockUnsubmitted Not Done Inline Actions Complex sentence: "Choosing the type" "constructing a pool" "requires deciding" Maybe rearrange and rewrite these two sentences: The main considerations for a pool are redundancy, capacity, and performance. These factors influence the choice of vdevs used to create a pool. wblock: Complex sentence: "Choosing the type" "constructing a pool" "requires deciding" Maybe…
		main considerations for a pool are: redundancy, capacity, and
		performance.</para>

		<para><link linkend="zfs-term-vdev-mirror">Mirrors</link>
		provide the best performance in terms of operations per second
		(<acronym>IOPS</acronym>). With a mirror, every disk in a
		vdev can be used to service reads, because each disk in the vdev
		wblockUnsubmitted Done Inline Actions Too many "since"s in this paragraph. s/since/because/ here. wblock: Too many "since"s in this paragraph. s/since/because/ here.
		contains a complete copy of the data. Mirrors provide good
		redundancy. Each disk in a vdev contains a complete copy
		wblockUnsubmitted Done Inline Actions Break the sentence: "Mirrors provide good redundancy. Each disk in a vdev contains a complete copy of the data..." wblock: Break the sentence: "Mirrors provide good redundancy. Each disk in a vdev contains a complete…
		of the data and a mirror vdev can consist of many disks. The
		downside to mirrors is that they provide the worst space efficiency and total capacity.
		wblockUnsubmitted Done Inline Actions Break the sentence: "The downside to mirrors is that they provide the worst capacity. Each mirror vdev, no matter how many disks it contains..." wblock: Break the sentence: "The downside to mirrors is that they provide the worst capacity. Each…
		Each mirror vdev, no matter how many disks it contains,
		provides only the capacity of the smallest disk. Multiple
		mirror vdevs can be striped together (similar to RAID-10) to
		wblockUnsubmitted Not Done Inline Actions <acronym> on RAID. wblock: <acronym> on RAID.
		allanjudeAuthorUnsubmitted Not Done Inline Actions Should these be treated as whitespace changes? I imagine it would be easier on the translators if I didn't mix bulk markup changes with content changes. allanjude: Should these be treated as whitespace changes? I imagine it would be easier on the translators…
		wblockUnsubmitted Not Done Inline Actions I'd say no, this is not like a whitespace change. The point to separating out whitespace changes is so translators can avoid dealing with them at all--there is nothing in them to put in the translated version. New markup does need to be in the translated version. wblock: I'd say no, this is not like a whitespace change. The point to separating out whitespace…
		provide more capacity, but the usable capacity will usually be
		less than the same number of disks in RAID-Z.</para>

		<para><link linkend="zfs-term-vdev-raidz">RAID-Z</link> comes in
		wblockUnsubmitted Not Done Inline Actions <acronym> wblock: <acronym>
		a number of levels of redundancy. RAID-Z1 provides enough
		wblockUnsubmitted Not Done Inline Actions <acronym> wblock: <acronym>
		redundancy to withstand the failure of a single disk in each
		vdev. RAID-Z2 can withstand two disks failing at the same time, and Z3
		wblockUnsubmitted Not Done Inline Actions <acronym> on RAID-Z2, and s/Z3/-Z3/ wblock: <acronym> on RAID-Z2, and s/Z3/-Z3/
		can withstand three, without any data loss.
		wblockUnsubmitted Done Inline Actions "concurrent" is a little unclear. "two failed disks" and "three failed disks" is clearer. wblock: "concurrent" is a little unclear. "two failed disks" and "three failed disks" is clearer.
		Choosing between these levels allows the
		wblockUnsubmitted Done Inline Actions "of redundancy" is itself redundant. wblock: "of redundancy" is itself redundant.
		administrator to balance redundancy against
		wblockUnsubmitted Done Inline Actions Remove "the level of" and "the amount of". wblock: Remove "the level of" and "the amount of".
		usable capacity. Each RAID-Z vdev will provide
		wblockUnsubmitted Not Done Inline Actions <acronym> wblock: <acronym>
		storage capacity equal to the number of disks, less the level
		of redundancy, multiplied by the size of the smallest disk.
		Examples of the storage calculations are provided in the
		<link linkend="zfs-term-vdev-raidz">RAID-Z</link> definition
		wblockUnsubmitted Not Done Inline Actions <acronym> in the rest of the paragraph for RAID wblock: <acronym> in the rest of the paragraph for RAID
		in the terminology section. Multiple RAID-Z vdevs can be
		striped together to create an effective RAID-50 or RAID-60
		type array.</para>

		<para>Using more vdevs will increase performance.
		wblockUnsubmitted Done Inline Actions "more separate" is weird and unclear. Just "more" is probably good. wblock: "more separate" is weird and unclear. Just "more" is probably good.
		Each vdev is operated as a unit. The effective speed of an
		bjkUnsubmitted Done Inline Actions comma splice bjk: comma splice
		individual vdev is determined by the speed of the slowest
		device. For the best performance, the recommended layout is
		many mirror vdevs, but this provides the worst effective
		capacity of the possible configurations. For increased
		redundancy, an administrator can choose between using RAID-Z2,
		Z3, or adding more member disks to each mirror vdev.</para>
		</sect2>

<sect2 xml:id="zfs-advanced-tuning">		<sect2 xml:id="zfs-advanced-tuning">
<title>Tuning</title>		<title>Tuning</title>

<para>There are a number of tunables that can be adjusted to		<para>There are a number of tunables that can be adjusted to
make <acronym>ZFS</acronym> perform best for different		make <acronym>ZFS</acronym> perform best for different
workloads.</para>		workloads.</para>

<itemizedlist>		<itemizedlist>
▲ Show 20 Lines • Show All 116 Lines • ▼ Show 20 Lines	<para
device has already been secure erased, disabling this		device has already been secure erased, disabling this
setting will make the addition of the new device faster.		setting will make the addition of the new device faster.
This value can be adjusted at any time with		This value can be adjusted at any time with
&man.sysctl.8;.</para>		&man.sysctl.8;.</para>
</listitem>		</listitem>

<listitem>		<listitem>
<para		<para
xml:id="zfs-advanced-tuning-vdev-max_pending"><emphasis><varname>vfs.zfs.vdev.max_pending</varname></emphasis>
- Limit the number of pending I/O requests per device.
A higher value will keep the device command queue full
and may give higher throughput. A lower value will reduce
latency. This value can be adjusted at any time with
&man.sysctl.8;.</para>
</listitem>

<listitem>
<para
xml:id="zfs-advanced-tuning-top_maxinflight"><emphasis><varname>vfs.zfs.top_maxinflight</varname></emphasis>		xml:id="zfs-advanced-tuning-top_maxinflight"><emphasis><varname>vfs.zfs.top_maxinflight</varname></emphasis>
- Maxmimum number of outstanding I/Os per top-level		- Maxmimum number of outstanding I/Os per top-level
<link linkend="zfs-term-vdev">vdev</link>. Limits the		<link linkend="zfs-term-vdev">vdev</link>. Limits the
		wblockUnsubmitted Not Done Inline Actions sysctl should have markup, probably &man.sysctl.8; <acronym> on ZFS. wblock: sysctl should have markup, probably &man.sysctl.8; <acronym> on ZFS.
depth of the command queue to prevent high latency. The		depth of the command queue to prevent high latency. The
limit is per top-level vdev, meaning the limit applies to		limit is per top-level vdev, meaning the limit applies to
		wblockUnsubmitted Not Done Inline Actions "unless it has no redundancy." wblock: "unless it has no redundancy."
each <link linkend="zfs-term-vdev-mirror">mirror</link>,		each <link linkend="zfs-term-vdev-mirror">mirror</link>,
<link linkend="zfs-term-vdev-raidz">RAID-Z</link>, or		<link linkend="zfs-term-vdev-raidz">RAID-Z</link>, or
other vdev independently. This value can be adjusted at		other vdev independently. This value can be adjusted at
any time with &man.sysctl.8;.</para>		any time with &man.sysctl.8;.</para>
</listitem>		</listitem>

<listitem>		<listitem>
<para		<para
▲ Show 20 Lines • Show All 95 Lines • ▼ Show 20 Lines	<para
disabled. This value can be adjusted at any time with		disabled. This value can be adjusted at any time with
&man.sysctl.8;.</para>		&man.sysctl.8;.</para>
</listitem>		</listitem>

<listitem>		<listitem>
<para		<para
xml:id="zfs-advanced-tuning-txg-timeout"><emphasis><varname>vfs.zfs.txg.timeout</varname></emphasis>		xml:id="zfs-advanced-tuning-txg-timeout"><emphasis><varname>vfs.zfs.txg.timeout</varname></emphasis>
- Maximum number of seconds between		- Maximum number of seconds between
<link linkend="zfs-term-txg">transaction group</link>s.		<link linkend="zfs-term-txg">transaction groups</link>.
The current transaction group will be written to the pool		The current transaction group will be written to the pool
and a fresh transaction group started if this amount of		and a fresh transaction group started if this amount of
time has elapsed since the previous transaction group. A		time has elapsed since the previous transaction group. A
transaction group my be triggered earlier if enough data		transaction group my be triggered earlier if enough data
is written. The default value is 5 seconds. A larger		is written. The default value is 5 seconds. A larger
value may improve read performance by delaying		value may improve read performance by delaying
asynchronous writes, but this may cause uneven performance		asynchronous writes, but this may cause uneven performance
when the transaction group is written. This value can be		when the transaction group is written. This value can be
▲ Show 20 Lines • Show All 292 Lines • ▼ Show 20 Lines	<listitem>
<acronym>RAID-Z</acronym> group's storage capacity		<acronym>RAID-Z</acronym> group's storage capacity
is approximately the size of the smallest disk		is approximately the size of the smallest disk
multiplied by the number of non-parity disks.		multiplied by the number of non-parity disks.
Four 1 TB disks in <acronym>RAID-Z1</acronym>		Four 1 TB disks in <acronym>RAID-Z1</acronym>
has an effective size of approximately 3 TB,		has an effective size of approximately 3 TB,
and an array of eight 1 TB disks in		and an array of eight 1 TB disks in
<acronym>RAID-Z3</acronym> will yield 5 TB of		<acronym>RAID-Z3</acronym> will yield 5 TB of
usable space.</para>		usable space.</para>

		<para xml:id="zfs-term-vdev-raidz-optimal">For
		delphijUnsubmitted Not Done Inline Actions This information is obsolete, please remove. See: http://blog.delphix.com/matt/2014/06/06/zfs-stripe-width/ delphij: This information is obsolete, please remove. See: http://blog.delphix.com/matt/2014/06/06/zfs…
		optimal performance, it is best to have a power of
		2 (2, 4, 8) number of non-parity drives so that
		writes can be distributed evenly. The recommended
		configurations are: RAID-Z1: 3, 5, or 9 disks.
		wblockUnsubmitted Not Done Inline Actions This should probably be a table. wblock: This should probably be a table.
		RAID-Z2: 6 or 10 disks. RAID-Z3: 5, 7 or 11
		disks.</para>
</listitem>		</listitem>

<listitem>		<listitem>
<para		<para
xml:id="zfs-term-vdev-spare"><emphasis>Spare</emphasis>		xml:id="zfs-term-vdev-spare"><emphasis>Spare</emphasis>
- <acronym>ZFS</acronym> has a special pseudo-vdev		- <acronym>ZFS</acronym> has a special pseudo-vdev
type for keeping track of available hot spares.		type for keeping track of available hot spares.
Note that installed hot spares are not deployed		Note that installed hot spares are not deployed
▲ Show 20 Lines • Show All 368 Lines • ▼ Show 20 Lines	<row>
compressed. Beyond a reduction in space used, read and		compressed. Beyond a reduction in space used, read and
write throughput often increases because fewer blocks		write throughput often increases because fewer blocks
are read or written.		are read or written.

<itemizedlist>		<itemizedlist>
<listitem xml:id="zfs-term-compression-lz4">		<listitem xml:id="zfs-term-compression-lz4">
<para><emphasis><acronym>LZ4</acronym></emphasis> -		<para><emphasis><acronym>LZ4</acronym></emphasis> -
Added in <acronym>ZFS</acronym> pool version		Added in <acronym>ZFS</acronym> pool version
5000 (feature flags), <acronym>LZ4</acronym> is		5000 (feature flags), <acronym>LZ4</acronym> is
		delphijUnsubmitted Not Done Inline Actions There is no "version 5000", 5000 is only a magic number and is not intended to be visible by user. delphij: There is no "version 5000", 5000 is only a magic number and is not intended to be visible by…
now the recommended compression algorithm.		now the recommended compression algorithm.
<acronym>LZ4</acronym> compresses approximately		<acronym>LZ4</acronym> compresses approximately
50% faster than <acronym>LZJB</acronym> when		50% faster than <acronym>LZJB</acronym> when
operating on compressible data, and is over three		operating on compressible data, and is over three
times faster when operating on uncompressible		times faster when operating on uncompressible
data. <acronym>LZ4</acronym> also decompresses		data. <acronym>LZ4</acronym> also decompresses
approximately 80% faster than		approximately 80% faster than
<acronym>LZJB</acronym>. On modern		<acronym>LZJB</acronym>. On modern
▲ Show 20 Lines • Show All 55 Lines • ▼ Show 20 Lines	<row>
<literal>copies</literal> property instructs		<literal>copies</literal> property instructs
<acronym>ZFS</acronym> to maintain multiple copies of		<acronym>ZFS</acronym> to maintain multiple copies of
each block in the		each block in the
<link linkend="zfs-term-filesystem">File System</link>		<link linkend="zfs-term-filesystem">File System</link>
or		or
<link linkend="zfs-term-volume">Volume</link>. Setting		<link linkend="zfs-term-volume">Volume</link>. Setting
this property on important datasets provides additional		this property on important datasets provides additional
redundancy from which to recover a block that does not		redundancy from which to recover a block that does not
match its checksum. In pools without redundancy, the		match its checksum. In pools without redundancy, the
copies feature is the only form of redundancy. The		<literal>copies</literal> feature is the only form of redundancy. The
		wblockUnsubmitted Done Inline Actions Should be markup on "copies". wblock: Should be markup on "copies".
copies feature can recover from a single bad sector or		<literal>copies</literal> feature can recover from a single bad sector or
other forms of minor corruption, but it does not protect		other forms of minor corruption, but it does not protect
the pool from the loss of an entire disk.</entry>		the pool from the loss of an entire disk. Each
		copy of a block consumes that much additional space in
		the file system, but also in any snapshots where that
		block has been modified.</entry>
</row>		</row>

<row>		<row>
<entry		<entry
xml:id="zfs-term-deduplication">Deduplication</entry>		xml:id="zfs-term-deduplication">Deduplication</entry>

<entry>Checksums make it possible to detect duplicate		<entry>Checksums make it possible to detect duplicate
blocks of data as they are written. With deduplication,		blocks of data as they are written. With deduplication,
▲ Show 20 Lines • Show All 239 Lines • Show Last 20 Lines