Sending and Receiving ZFS Data

The zfs send command creates a stream representation of a snapshot that is written
to standard output. By default, a full stream is generated. You can redirect
the output to a file or to a different system. The zfs receive command
creates a snapshot whose contents are specified in the stream that is provided
on standard input. If a full stream is received, a new file system
is created as well. You can send ZFS snapshot data and receive ZFS
snapshot data and file systems with these commands. See the examples in the
next section.

Enterprise backup products – If you need the following features, then consider an enterprise backup solution:

Per-file restoration

Backup media verification

Media management

File system snapshots and rolling back snapshots – Use the zfs snapshot and zfs rollback commands if you want to easily create a copy of a file system and revert to a previous file system version, if necessary. For example, to restore a file or files from a previous version of a file system, you could use this solution.

Saving snapshots – Use the zfs send and zfs receive commands to send and receive a ZFS snapshot. You can save incremental changes between snapshots, but you cannot restore files individually. You must restore the entire file system snapshot. These commands do not provide a complete backup solution for saving your ZFS data.

Remote replication – Use the zfs send and zfs receive commands to copy a file system from one system to another system. This process is different from a traditional volume management product that might mirror devices across a WAN. No special configuration or hardware is required. The advantage of replicating a ZFS file system is that you can re-create a file system on a storage pool on another system, and specify different levels of configuration for the newly created pool, such as RAID-Z, but with identical file system data.

Saving ZFS Data With Other Backup Products

In addition to the zfs send and zfs receive commands, you can also use archive
utilities, such as the tar and cpio commands, to save ZFS files.
These utilities save and restore ZFS file attributes and ACLs. Check the appropriate
options for both the tar and cpio commands.

For up-to-date information about issues with ZFS and third-party backup products, see the
Oracle Solaris 11 Release Notes.

Identifying ZFS Snapshot Streams

A snapshot of a ZFS file system or volume is converted into
a snapshot stream by using the zfs send command. Then, you can use the snapshot
stream to re-create a ZFS file system or volume by using the
zfs receive command.

Depending on the zfs send options that were used to create the snapshot stream,
different types of stream formats are generated.

Full stream – Consists of all dataset content from the time that the dataset was created up to the specified snapshot.

The default stream generated by the zfs send command is a full stream. It contains one file system or volume, up to and including the specified snapshot. The stream does not contain snapshots other than the snapshot specified on the command line.

Incremental stream – Consists of the differences between one snapshot and another snapshot.

A stream package is a stream type that contains one or more
full or incremental streams. Three types of stream packages exist:

Replication stream package – Consists of the specified dataset and its descendents. It includes all intermediate snapshots. If the origin of a cloned dataset is not a descendent of the snapshot specified on the command line, that origin dataset is not included in the stream package. To receive the stream, the origin dataset must exist in the destination storage pool.

Consider the following list of datasets and their origins. Assume that they were created in the order that they appear below.

In the preceding output, the pool/a/1@clone snapshot is not included in the replication stream package. As such, this replication stream package can only be received in a pool that already has pool/a/1@clone snapshot.

Recursive stream package – Consists of the specified dataset and its descendents. Unlike replication stream packages, intermediate snapshots are not included unless they are the origin of a cloned dataset that is included in the stream. By default, if the origin of a dataset is not a descendent of the snapshot specified on the command line, the behavior is the similar to replication streams. However, a self-contained recursive stream, discussed below, are created in such a way that there are no external dependencies.

In the preceding output, the pool/a/1@clone snapshot is not included in the recursive stream package. As such, this recursive stream package can only be received in a pool that already has pool/a/1@clone snapshot. This behavior is similar to the replication stream package scenario described above.

Self-contained recursive stream package - Is not dependent on any datasets that are not included in the stream package. This recursive stream package is created with the following syntax:

Notice that the self-contained recursive stream has a full stream of the pool/b/1@clone2 snapshot, making it possible receive the pool/b/1 snapshot with no external dependencies.

Sending a ZFS Snapshot

You can use the zfs send command to send a copy of a snapshot
stream and receive the snapshot stream in another pool on the same system
or in another pool on a different system that is used to
store backup data. For example, to send the snapshot stream on a different
pool to the same system, use syntax similar to the following:

# zfs send tank/dana@snap1 | zfs recv spool/ds01

You can use zfs recv as an alias for the zfs receive command.

If you are sending the snapshot stream to a different system, pipe
the zfs send output through the ssh command. For example:

sys1# zfs send tank/dana@snap1 | ssh sys2 zfs recv newtank/dana

When you send a full stream, the destination file system must not
exist.

You can send incremental data by using the zfs send-i option. For
example:

Note that the first argument (snap1) is the earlier snapshot and the second
argument (snap2) is the later snapshot. In this case, the newtank/dana file system
must already exist for the incremental receive to be successful.

The incremental snap1 source can be specified as the last component of the
snapshot name. This shortcut means you only have to specify the name after
the @ sign for snap1, which is assumed to be from the same
file system as snap2. For example:

If you make a change to the destination file system and you
want to perform another incremental send of a snapshot, you must first roll
back the receiving file system.

Consider the following example. First, make a change to the file system as
follows:

sys2# rm newtank/dana/file.1

Then, perform an incremental send of tank/dana@snap3. However, you must first roll back
the receiving file system to receive the new incremental snapshot. Or, you can
eliminate the rollback step by using the -F option. For example:

When you receive an incremental snapshot, the destination file system must already exist.

If you make changes to the file system and you do not
roll back the receiving file system to receive the new incremental snapshot or
you do not use the -F option, you see a message similar to
the following:

The following checks are performed before the -F option is successful:

If the most recent snapshot doesn't match the incremental source, neither the roll back nor the receive is completed, and an error message is returned.

If you accidentally provide the name of different file system that doesn't match the incremental source specified in the zfs receive command, neither the rollback nor the receive is completed, and the following error message is returned:

cannot send 'pool/fs@name': not an earlier snapshot from the same fs

Applying Different Property Values to a ZFS Snapshot Stream

You can send a ZFS snapshot stream with a certain file system
property value, but you can specify a different local property value when the
snapshot stream is received. Or, you can specify that the original property value
be used when the snapshot stream is received to re-create the original file
system. In addition, you can disable a file system property when the snapshot
stream is received.

Use the zfs inherit-S to revert a local property value to the received value, if any. If a property does not have a received value, the behavior of the zfs inherit-S command is the same as the zfs inherit command without the -S option. If the property does have a received value, the zfs inherit command masks the received value with the inherited value until issuing a zfs inherit-S command reverts it to the received value.

You can use the zfs get-o to include the new non-default RECEIVED column. Or, use the zfs get-o all command to include all columns, including RECEIVED.

You can use the zfs send-p option to include properties in the send stream without the -R option.

You can use the zfs send-e option to use the last element of the sent snapshot name to determine the new snapshot name. The following example sends the poola/bee/cee@1 snapshot to the poold/eee file system and only uses the last element (cee@1) of the snapshot name to create the received file system and snapshot.

In some cases, file system properties in a send stream might not
apply to the receiving file system or local file system properties, such as
the mountpoint property value, might interfere with a restore.

For example, the tank/data file system has the compression property disabled. A
snapshot of the tank/data file system is sent with properties (-p option) to
a backup pool and is received with the compression property enabled.

In the example, the compression property is enabled when the snapshot is received
into bpool. So, for bpool/data, the compression value is on.

If this snapshot stream is sent to a new pool, restorepool, for recovery
purposes, you might want to keep all the original snapshot properties. In this
case, you would use the zfs send-b command to restore the original snapshot
properties. For example:

In the example, the compression value is off, which represents the snapshot compression
value from the original tank/data file system.

If you have a local file system property value in a snapshot
stream and you want to disable the property when it is received, use
the zfs receive-x command. For example, the following command sends a recursive snapshot
stream of home directory file systems with all file system properties reserved to
a backup pool, but without the quota property values:

Sending and Receiving Complex ZFS Snapshot Streams

This section describes how to use the zfs send-I and -R options
to send and receive more complex snapshot streams.

Keep the following points in mind when sending and receiving complex ZFS snapshot
streams:

Use the zfs send-I option to send all incremental streams from one snapshot to a cumulative snapshot. Or, use this option to send an incremental stream from the original snapshot to create a clone. The original snapshot must already exist on the receiving side to accept the incremental stream.

Use the zfs send-R option to send a replication stream of all descendent file systems. When the replication stream is received, all properties, snapshots, descendent file systems, and clones are preserved.

When using the zfs send-r option without the -c option and when using the zfs send-R option stream packages omit the origin of clones in some circumstances. For more information, see Identifying ZFS Snapshot Streams.

Use both options to send an incremental replication stream.

Changes to properties are preserved, as are snapshot and file system rename and destroy operations are preserved.

If zfs recv-F is not specified when receiving the replication stream, dataset destroy operations are ignored. The zfs recv-F syntax in this case also retains its rollback if necessary meaning.

As with other (non zfs send-R) -i or -I cases, if -I is used, all snapshots between snapA and snapD are sent. If -i is used, only snapD (for all descendents) are sent.

To receive any of these new types of zfs send streams, the receiving system must be running a software version capable of sending them. The stream version is incremented.

However, you can access streams from older pool versions by using a newer software version. For example, you can send and receive streams created with the newer options to and from a version 3 pool. But, you must be running recent software to receive a stream sent with the newer options.

Example 7-1 Sending and Receiving Complex ZFS Snapshot Streams

A group of incremental snapshots can be combined into one snapshot by using
the zfs send-I option. For example:

You can use the zfs send-R command to replicate a ZFS file system
and all descendent file systems, up to the named snapshot. When this stream
is received, all properties, snapshots, descendent file systems, and clones are preserved.

In the following example, snapshots are created for user file systems. One replication
stream is created for all user snapshots. Next, the original file systems and
snapshots are destroyed and then recovered.

This command sends the tank/cindy@today snapshot data and receives it into the sandbox/restfs
file system. The command also creates a restfs@today snapshot on the newsys system.
In this example, the user has been configured to use ssh on the
remote system.