zfs-send

title: zfs-send(8)

summary: generate backup stream of ZFS dataset

text:
# zfs-send(8)

## NAME
zfs-send — generate backup stream of ZFS dataset

## SYNOPSIS
zfs

send [-DLPVbcehnpsvw] [-R [-X dataset[,dataset]…]] [[-I|-i] snapshot] snapshot

zfs

send [-DLPVcensvw] [-i snapshot|bookmark] filesystem|volume|snapshot

zfs

send --redact redaction_bookmark [-DLPVcenpv] [-i snapshot|bookmark] snapshot

zfs

send [-PVenv] -t receive_resume_token

zfs

send [-PVnv] -S filesystem

zfs

redact snapshot redaction_bookmark redaction_snapshot…

## DESCRIPTION
zfs send [-DLPVbcehnpsvw] [-R [-X dataset[,dataset]…]] [[-I|-i] snapshot] snapshot

Creates a stream representation of the second snapshot, which is written to standard output. The output can be redirected to a file or to a different system (for example, using ssh(1)). By default, a full stream is generated. -D, --dedup

Deduplicated send is no longer supported. This flag is accepted for backwards compatibility, but a regular, non-deduplicated stream will be generated.

-I snapshot

Generate a stream package that sends all intermediary snapshots from the first snapshot to the second snapshot. For example, -I @a fs@d is similar to -i @a fs@b; -i @b fs@c; -i @c fs@d. The incremental source may be specified as with the -i option.

-L, --large-block

Generate a stream which may contain blocks larger than 128 KiB. This flag has no effect if the large_blocks pool feature is disabled, or if the recordsize property of this filesystem has never been set above 128 KiB. The receiving system must have the large_blocks pool feature enabled as well. This flag is required if the large_microzap pool feature is active. See zpool-features(7) for details on ZFS feature flags and the large_blocks feature.

-P, --parsable

Print machine-parsable verbose information about the stream package generated.

-R, --replicate

Generate a replication stream package, which will replicate the specified file system, and all descendent file systems, up to the named snapshot. When received, all properties, snapshots, descendent file systems, and clones are preserved. If the -i or -I flags are used in conjunction with the -R flag, an incremental replication stream is generated. The current values of properties, and current snapshot and file system names are set when the stream is received. If the -F flag is specified when this stream is received, snapshots and file systems that do not exist on the sending side are destroyed. If the -R flag is used to send encrypted datasets, then -w must also be specified.

-V, --proctitle

Set the process title to a per-second report of how much data has been sent.

-X, --exclude dataset[,dataset]…

With -R, -X specifies a set of datasets (and, hence, their descendants), to be excluded from the send stream. The root dataset may not be excluded. -X a -X b is equivalent to -X a,b.

-e, --embed

Generate a more compact stream by using WRITE_EMBEDDED records for blocks which are stored more compactly on disk by the embedded_data pool feature. This flag has no effect if the embedded_data feature is disabled. The receiving system must have the embedded_data feature enabled. If the lz4_compress or zstd_compress features are active on the sending system, then the receiving system must have the corresponding features enabled as well. Datasets that are sent with this flag may not be received as an encrypted dataset, since encrypted datasets cannot use the embedded_data feature. See zpool-features(7) for details on ZFS feature flags and the embedded_data feature.

-b, --backup

Sends only received property values whether or not they are overridden by local settings, but only if the dataset has ever been received. Use this option when you want zfs receive to restore received properties backed up on the sent dataset and to avoid sending local settings that may have nothing to do with the source dataset, but only with how the data is backed up.

-c, --compressed

Generate a more compact stream by using compressed WRITE records for blocks which are compressed on disk and in memory (see the compression property for details). If the lz4_compress or zstd_compress features are active on the sending system, then the receiving system must have the corresponding features enabled as well. If the large_blocks feature is enabled on the sending system but the -L option is not supplied in conjunction with -c, then the data will be decompressed before sending so it can be split into smaller block sizes. Streams sent with -c will not have their data recompressed on the receiver side using -o compress= value. The data will stay compressed as it was from the sender. The new compression property will be set for future data. Note that uncompressed data from the sender will still attempt to compress on the receiver, unless you specify -o compress= off.

-w, --raw

For encrypted datasets, send data exactly as it exists on disk. This allows backups to be taken even if encryption keys are not currently loaded. The backup may then be received on an untrusted machine since that machine will not have the encryption keys to read the protected data or alter it without being detected. Upon being received, the dataset will have the same encryption keys as it did on the send side, although the keylocation property will be defaulted to prompt if not otherwise provided. For unencrypted datasets, this flag will be equivalent to -Lec. Note that if you do not use this flag for sending encrypted datasets, data will be sent unencrypted and may be re-encrypted with a different encryption key on the receiving system, which will disable the ability to do a raw send to that system for incrementals.

-h, --holds

Generate a stream package that includes any snapshot holds (created with the zfs hold command), and indicating to zfs receive that the holds be applied to the dataset on the receiving system.

-i snapshot

Generate an incremental stream from the first snapshot (the incremental source) to the second snapshot (the incremental target). The incremental source can be specified as the last component of the snapshot name (the @ character and following) and it is assumed to be from the same file system as the incremental target. If the destination is a clone, the source may be the origin snapshot, which must be fully specified (for example, pool/fs@origin, not just @origin).

-n, --dryrun

Do a dry-run ("No-op") send. Do not generate any actual send data. This is useful in conjunction with the -v or -P flags to determine what data will be sent. In this case, the verbose output will be written to standard output (contrast with a non-dry-run, where the stream is written to standard output and the verbose output goes to standard error).

-p, --props

Include the dataset's properties in the stream. This flag is implicit when -R is specified. The receiving system must also support this feature. Sends of encrypted datasets must use -w when using this flag.

-s, --skip-missing

Allows sending a replication stream even when there are snapshots missing in the hierarchy. When a snapshot is missing, instead of throwing an error and aborting the send, a warning is printed to the standard error stream and the dataset to which it belongs and its descendants are skipped. This flag can only be used in conjunction with -R.

-v, --verbose

Print verbose information about the stream package generated. This information includes a per-second report of how much data has been sent. The same report can be requested by sending SIGINFO or SIGUSR1, regardless of -v. The format of the stream is committed. You will be able to receive your streams on future versions of ZFS.

zfs send [-DLPVcenvw] [-i snapshot|bookmark] filesystem|volume|snapshot

Generate a send stream, which may be of a filesystem, and may be incremental from a bookmark. If the destination is a filesystem or volume, the pool must be read-only, or the filesystem must not be mounted. When the stream generated from a filesystem or volume is received, the default snapshot name will be "--head--". -D, --dedup

Deduplicated send is no longer supported. This flag is accepted for backwards compatibility, but a regular, non-deduplicated stream will be generated.

-L, --large-block

Generate a stream which may contain blocks larger than 128 KiB. This flag has no effect if the large_blocks pool feature is disabled, or if the recordsize property of this filesystem has never been set above 128 KiB. The receiving system must have the large_blocks pool feature enabled as well. See zpool-features(7) for details on ZFS feature flags and the large_blocks feature.

-P, --parsable

Print machine-parsable verbose information about the stream package generated.

-c, --compressed

Generate a more compact stream by using compressed WRITE records for blocks which are compressed on disk and in memory (see the compression property for details). If the lz4_compress or zstd_compress features are active on the sending system, then the receiving system must have the corresponding features enabled as well. If the large_blocks feature is enabled on the sending system but the -L option is not supplied in conjunction with -c, then the data will be decompressed before sending so it can be split into smaller block sizes.

-w, --raw

For encrypted datasets, send data exactly as it exists on disk. This allows backups to be taken even if encryption keys are not currently loaded. The backup may then be received on an untrusted machine since that machine will not have the encryption keys to read the protected data or alter it without being detected. Upon being received, the dataset will have the same encryption keys as it did on the send side, although the keylocation property will be defaulted to prompt if not otherwise provided. For unencrypted datasets, this flag will be equivalent to -Lec. Note that if you do not use this flag for sending encrypted datasets, data will be sent unencrypted and may be re-encrypted with a different encryption key on the receiving system, which will disable the ability to do a raw send to that system for incrementals.

-e, --embed

Generate a more compact stream by using WRITE_EMBEDDED records for blocks which are stored more compactly on disk by the embedded_data pool feature. This flag has no effect if the embedded_data feature is disabled. The receiving system must have the embedded_data feature enabled. If the lz4_compress or zstd_compress features are active on the sending system, then the receiving system must have the corresponding features enabled as well. Datasets that are sent with this flag may not be received as an encrypted dataset, since encrypted datasets cannot use the embedded_data feature. See zpool-features(7) for details on ZFS feature flags and the embedded_data feature.

-i snapshot|bookmark

Generate an incremental send stream. The incremental source must be an earlier snapshot in the destination's history. It will commonly be an earlier snapshot in the destination's file system, in which case it can be specified as the last component of the name (the # or @ character and following). If the incremental target is a clone, the incremental source can be the origin snapshot, or an earlier snapshot in the origin's filesystem, or the origin's origin, etc.

-n, --dryrun

Do a dry-run ("No-op") send. Do not generate any actual send data. This is useful in conjunction with the -v or -P flags to determine what data will be sent. In this case, the verbose output will be written to standard output (contrast with a non-dry-run, where the stream is written to standard output and the verbose output goes to standard error).

-v, --verbose

Print verbose information about the stream package generated. This information includes a per-second report of how much data has been sent. The same report can be requested by sending SIGINFO or SIGUSR1, regardless of -v.

zfs send --redact redaction_bookmark [-DLPVcenpv] [-i snapshot|bookmark] snapshot

Generate a redacted send stream. This send stream contains all blocks from the snapshot being sent that aren't included in the redaction list contained in the bookmark specified by the --redact (or -d) flag. The resulting send stream is said to be redacted with respect to the snapshots the bookmark specified by the --redact flag was created with. The bookmark must have been created by running zfs redact on the snapshot being sent. This feature can be used to allow clones of a filesystem to be made available on a remote system, in the case where their parent need not (or needs to not) be usable. For example, if a filesystem contains sensitive data, and it has clones where that sensitive data has been secured or replaced with dummy data, redacted sends can be used to replicate the secured data without replicating the original sensitive data, while still sharing all possible blocks. A snapshot that has been redacted with respect to a set of snapshots will contain all blocks referenced by at least one snapshot in the set, but will contain none of the blocks referenced by none of the snapshots in the set. In other words, if all snapshots in the set have modified a given block in the parent, that block will not be sent; but if one or more snapshots have not modified a block in the parent, they will still reference the parent's block, so that block will be sent. Note that only user data will be redacted.

When the redacted send stream is received, we will generate a redacted snapshot. Due to the nature of redaction, a redacted dataset can only be used in the following ways:

- To receive, as a clone, an incremental send from the original snapshot to one of the snapshots it was redacted with respect to. In this case, the stream will produce a valid dataset when received because all blocks that were redacted in the parent are guaranteed to be present in the child's send stream. This use case will produce a normal snapshot, which can be used just like other snapshots.

- To receive an incremental send from the original snapshot to something redacted with respect to a subset of the set of snapshots the initial snapshot was redacted with respect to. In this case, each block that was redacted in the original is still redacted (redacting with respect to additional snapshots causes less data to be redacted (because the snapshots define what is permitted, and everything else is redacted)). This use case will produce a new redacted snapshot.

- To receive an incremental send from a redaction bookmark of the original snapshot that was created when redacting with respect to a subset of the set of snapshots the initial snapshot was created with respect to anything else. A send stream from such a redaction bookmark will contain all of the blocks necessary to fill in any redacted data, should it be needed, because the sending system is aware of what blocks were originally redacted. This will either produce a normal snapshot or a redacted one, depending on whether the new send stream is redacted.

- To receive an incremental send from a redacted version of the initial snapshot that is redacted with respect to a subject of the set of snapshots the initial snapshot was created with respect to. A send stream from a compatible redacted dataset will contain all of the blocks necessary to fill in any redacted data. This will either produce a normal snapshot or a redacted one, depending on whether the new send stream is redacted.

- To receive a full send as a clone of the redacted snapshot. Since the stream is a full send, it definitionally contains all the data needed to create a new dataset. This use case will either produce a normal snapshot or a redacted one, depending on whether the full send stream was redacted.

These restrictions are detected and enforced by zfs receive; a redacted send stream will contain the list of snapshots that the stream is redacted with respect to. These are stored with the redacted snapshot, and are used to detect and correctly handle the cases above. Note that for technical reasons, raw sends and redacted sends cannot be combined at this time.

zfs send [-PVenv] -t receive_resume_token

Creates a send stream which resumes an interrupted receive. The receive_resume_token is the value of this property on the filesystem or volume that was being received into. See the documentation for zfs receive -s for more details.

zfs send [-PVnv] [-i snapshot|bookmark] -S filesystem

Generate a send stream from a dataset that has been partially received. -S, --saved

This flag requires that the specified filesystem previously received a resumable send that did not finish and was interrupted. In such scenarios this flag enables the user to send this partially received state. Using this flag will always use the last fully received snapshot as the incremental source if it exists.

zfs redact snapshot redaction_bookmark redaction_snapshot…

Generate a new redaction bookmark. In addition to the typical bookmark information, a redaction bookmark contains the list of redacted blocks and the list of redaction snapshots specified. The redacted blocks are blocks in the snapshot which are not referenced by any of the redaction snapshots. These blocks are found by iterating over the metadata in each redaction snapshot to determine what has been changed since the target snapshot. Redaction is designed to support redacted zfs sends; see the entry for zfs send for more information on the purpose of this operation. If a redact operation fails partway through (due to an error or a system failure), the redaction can be resumed by rerunning the same command.

### Redaction
ZFS has support for a limited version of data subsetting, in the form of redaction. Using the zfs redact command, a redaction bookmark can be created that stores a list of blocks containing sensitive information. When provided to zfs send, this causes a redacted send to occur. Redacted sends omit the blocks containing sensitive information, replacing them with REDACT records. When these send streams are received, a redacted dataset is created. A redacted dataset cannot be mounted by default, since it is incomplete. It can be used to receive other send streams. In this way datasets can be used for data backup and replication, with all the benefits that zfs send and receive have to offer, while protecting sensitive information from being stored on less-trusted machines or services.

For the purposes of redaction, there are two steps to the process. A redact step, and a send/receive step. First, a redaction bookmark is created. This is done by providing the zfs redact command with a parent snapshot, a bookmark to be created, and a number of redaction snapshots. These redaction snapshots must be descendants of the parent snapshot, and they should modify data that is considered sensitive in some way. Any blocks of data modified by all of the redaction snapshots will be listed in the redaction bookmark, because it represents the truly sensitive information. When it comes to the send step, the send process will not send the blocks listed in the redaction bookmark, instead replacing them with REDACT records. When received on the target system, this will create a redacted dataset, missing the data that corresponds to the blocks in the redaction bookmark on the sending system. The incremental send streams from the original parent to the redaction snapshots can then also be received on the target system, and this will produce a complete snapshot that can be used normally. Incrementals from one snapshot on the parent filesystem and another can also be done by sending from the redaction bookmark, rather than the snapshots themselves.

In order to make the purpose of the feature more clear, an example is provided. Consider a zfs filesystem containing four files. These files represent information for an online shopping service. One file contains a list of usernames and passwords, another contains purchase histories, a third contains click tracking data, and a fourth contains user preferences. The owner of this data wants to make it available for their development teams to test against, and their market research teams to do analysis on. The development teams need information about user preferences and the click tracking data, while the market research teams need information about purchase histories and user preferences. Neither needs access to the usernames and passwords. However, because all of this data is stored in one ZFS filesystem, it must all be sent and received together. In addition, the owner of the data wants to take advantage of features like compression, checksumming, and snapshots, so they do want to continue to use ZFS to store and transmit their data. Redaction can help them do so. First, they would make two clones of a snapshot of the data on the source. In one clone, they create the setup they want their market research team to see; they delete the usernames and passwords file, and overwrite the click tracking data with dummy information. In another, they create the setup they want the development teams to see, by replacing the passwords with fake information and replacing the purchase histories with randomly generated ones. They would then create a redaction bookmark on the parent snapshot, using snapshots on the two clones as redaction snapshots. The parent can then be sent, redacted, to the target server where the research and development teams have access. Finally, incremental sends from the parent snapshot to each of the clones can be sent to and received on the target server; these snapshots are identical to the ones on the source, and are ready to be used, while the parent snapshot on the target contains none of the username and password data present on the source, because it was removed by the redacted send operation.

## SIGNALS
See -v.

## EXAMPLES

### Example 1: Remotely Replicating ZFS Data
The following commands send a full stream and then an incremental stream to a remote machine, restoring them into poolB/received/fs@a and poolB/received/fs@b, respectively. poolB must contain the file system poolB/received, and must not initially contain poolB/received/fs.

```
# zfs send pool/fs@a |
    ssh host zfs receive poolB/received/fs@a
# zfs send -i a pool/fs@b |
    ssh host zfs receive poolB/received/fs
```

### Example 2: Using the zfs receive -d Option
The following command sends a full stream of poolA/fsA/fsB@snap to a remote machine, receiving it into poolB/received/fsA/fsB@snap. The fsA/fsB@snap portion of the received snapshot's name is determined from the name of the sent snapshot. poolB must contain the file system poolB/received. If poolB/received/fsA does not exist, it is created as an empty file system.

```
# zfs send poolA/fsA/fsB@snap |
    ssh host zfs receive -d poolB/received
```

## SEE ALSO
zfs-bookmark(8), zfs-receive(8), zfs-redact(8), zfs-snapshot(8)


zfs-set

package: zfs-utils

title: zfs-set(8)

summary: set properties on ZFS datasets

text:
# zfs-set(8)

## NAME
zfs-set — set properties on ZFS datasets

## SYNOPSIS
zfs

set [-u] property=value [property=value]… filesystem|volume|snapshot…

zfs

get [-r|-d depth] [-Hp] [-j [--json-int]] [-o field[,field]…] [-s source[,source]…] [-t type[,type]…] all|property[,property]… [filesystem|volume|snapshot|bookmark]…

zfs

inherit [-rS] property filesystem|volume|snapshot…

## DESCRIPTION
zfs set [-u] property=value [property=value]… filesystem|volume|snapshot…

Only some properties can be edited. See zfsprops(7) for more information on what properties can be set and acceptable values. Numeric values can be specified as exact values, or in a human-readable form with a suffix of B, K, M, G, T, P, E, Z (for bytes, kilobytes, megabytes, gigabytes, terabytes, petabytes, exabytes, or zettabytes, respectively). User properties can be set on snapshots. For more information, see the User Properties section of zfsprops(7). -u

Update mountpoint, sharenfs, sharesmb property but do not mount or share the dataset.

zfs get [-r|-d depth] [-Hp] [-j [--json-int]] [-o field[,field]…] [-s source[,source]…] [-t type[,type]…] all|property[,property]… [filesystem|volume|snapshot|bookmark]…

Displays properties for the given datasets. If no datasets are specified, then the command displays properties for all datasets on the system. For each property, the following columns are displayed: name

Dataset name

property

Property name

value

Property value

source

Property source local, default, inherited, temporary, received, or - (none).

All columns are displayed by default, though this can be controlled by using the -o option. This command takes a comma-separated list of properties as described in the Native Properties and User Properties sections of zfsprops(7).

The value all can be used to display all properties that apply to the given dataset's type (filesystem, volume, snapshot, or bookmark).

-j, --json [--json-int]

Display the output in JSON format. Specify --json-int to display numbers in integer format instead of strings for JSON output.

-H

Display output in a form more easily parsed by scripts. Any headers are omitted, and fields are explicitly separated by a single tab instead of an arbitrary amount of space.

-d depth

Recursively display any children of the dataset, limiting the recursion to depth. A depth of 1 will display only the dataset and its direct children.

-o field

A comma-separated list of columns to display, defaults to name,property,value,source.

-p

Display numbers in parsable (exact) values.

-r

Recursively display properties for any children.

-s source

A comma-separated list of sources to display. Those properties coming from a source other than those in this list are ignored. Each source must be one of the following: local, default, inherited, temporary, received, or none. The default value is all sources.

-t type

A comma-separated list of types to display, where type is one of filesystem, snapshot, volume, bookmark, or all. fs, snap, or vol can be used as aliases for filesystem, snapshot, or volume.

zfs inherit [-rS] property filesystem|volume|snapshot…

Clears the specified property, causing it to be inherited from an ancestor, restored to default if no ancestor has the property set, or with the -S option reverted to the received value if one exists. See zfsprops(7) for a listing of default values, and details on which properties can be inherited. -r

Recursively inherit the given property for all children.

-S

Revert the property to the received value, if one exists; otherwise, for non-inheritable properties, to the default; otherwise, operate as if the -S option was not specified.

## EXAMPLES

### Example 1: Creating a ZFS File System Hierarchy
The following commands create a file system named pool/home and a file system named pool/home/bob. The mount point /export/home is set for the parent file system, and is automatically inherited by the child file system.

\# zfs create pool/home

\# zfs set mountpoint=/export/home pool/home

\# zfs create pool/home/bob

### Example 2: Disabling and Enabling File System Compression
The following command disables the compression property for all file systems under pool/home. The next command explicitly enables compression for pool/home/anne.

\# zfs set compression=off pool/home

\# zfs set compression=on pool/home/anne

### Example 3: Setting a Quota on a ZFS File System
The following command sets a quota of 50 Gbytes for pool/home/bob:

\# zfs set quota=50G pool/home/bob

### Example 4: Listing ZFS Properties
The following command lists all properties for pool/home/bob:

```
# zfs get all pool/home/bob
NAME           PROPERTY              VALUE                  SOURCE
pool/home/bob  type                  filesystem             -
pool/home/bob  creation              Tue Jul 21 15:53 2009  -
pool/home/bob  used                  21K                    -
pool/home/bob  available             20.0G                  -
pool/home/bob  referenced            21K                    -
pool/home/bob  compressratio         1.00x                  -
pool/home/bob  mounted               yes                    -
pool/home/bob  quota                 20G                    local
pool/home/bob  reservation           none                   default
pool/home/bob  recordsize            128K                   default
pool/home/bob  mountpoint            /pool/home/bob         default
pool/home/bob  sharenfs              off                    default
pool/home/bob  checksum              on                     default
pool/home/bob  compression           on                     local
pool/home/bob  atime                 on                     default
pool/home/bob  devices               on                     default
pool/home/bob  exec                  on                     default
pool/home/bob  setuid                on                     default
pool/home/bob  readonly              off                    default
pool/home/bob  zoned                 off                    default
pool/home/bob  snapdir               hidden                 default
pool/home/bob  acltype               off                    default
pool/home/bob  aclmode               discard                default
pool/home/bob  aclinherit            restricted             default
pool/home/bob  canmount              on                     default
pool/home/bob  xattr                 on                     default
pool/home/bob  copies                1                      default
pool/home/bob  version               4                      -
pool/home/bob  utf8only              off                    -
pool/home/bob  normalization         none                   -
pool/home/bob  casesensitivity       sensitive              -
pool/home/bob  vscan                 off                    default
pool/home/bob  nbmand                off                    default
pool/home/bob  sharesmb              off                    default
pool/home/bob  refquota              none                   default
pool/home/bob  refreservation        none                   default
pool/home/bob  primarycache          all                    default
pool/home/bob  secondarycache        all                    default
pool/home/bob  usedbysnapshots       0                      -
pool/home/bob  usedbydataset         21K                    -
pool/home/bob  usedbychildren        0                      -
pool/home/bob  usedbyrefreservation  0                      -
```

The following command gets a single property value:

```
# zfs get -H -o value compression pool/home/bob
on
```

The following command gets a single property value recursively in JSON format:

```
# zfs get -j -r mountpoint pool/home | jq
{
  "output_version": {
    "command": "zfs get",
    "vers_major": 0,
    "vers_minor": 1
  },
  "datasets": {
    "pool/home": {
      "name": "pool/home",
      "type": "FILESYSTEM",
      "pool": "pool",
      "createtxg": "10",
      "properties": {
        "mountpoint": {
          "value": "/pool/home",
          "source": {
            "type": "DEFAULT",
            "data": "-"
          }
        }
      }
    },
    "pool/home/bob": {
      "name": "pool/home/bob",
      "type": "FILESYSTEM",
      "pool": "pool",
      "createtxg": "1176",
      "properties": {
        "mountpoint": {
          "value": "/pool/home/bob",
          "source": {
            "type": "DEFAULT",
            "data": "-"
          }
        }
      }
    }
  }
}
```

The following command lists all properties with local settings for pool/home/bob:

```
# zfs get -r -s local -o name,property,value all pool/home/bob
NAME           PROPERTY              VALUE
pool/home/bob  quota                 20G
pool/home/bob  compression           on
```

### Example 5: Inheriting ZFS Properties
The following command causes pool/home/bob and pool/home/anne to inherit the checksum property from their parent.

\# zfs inherit checksum pool/home/bob pool/home/anne

### Example 6: Setting User Properties
The following example sets the user-defined com.example:department property for a dataset:

\# zfs set com.example:department=12345 tank/accounting

### Example 7: Setting sharenfs Property Options on a ZFS File System
The following commands show how to set sharenfs property options to enable read-write access for a set of IP addresses and to enable root access for system "neo" on the tank/home file system:

\# zfs set sharenfs='rw=@123.123.0.0/16:[::1],root=neo' tank/home

If you are using DNS for host name resolution, specify the fully-qualified hostname.

## SEE ALSO
zfsprops(7), zfs-list(8)


zfs-share

title: zfs-share(8)

summary: share and unshare ZFS filesystems

text:
# zfs-share(8)

## NAME
zfs-share — share and unshare ZFS filesystems

## SYNOPSIS
zfs

share [-l] -a|filesystem

zfs

unshare -a|filesystem|mountpoint

## DESCRIPTION
zfs share [-l] -a|filesystem

Shares available ZFS file systems. -l

Load keys for encrypted filesystems as they are being mounted. This is equivalent to executing zfs load-key on each encryption root before mounting it. Note that if a filesystem has keylocation=prompt, this will cause the terminal to interactively block after asking for the key.

-a

Share all available ZFS file systems. Invoked automatically as part of the boot process.

filesystem

Share the specified filesystem according to the sharenfs and sharesmb properties. File systems are shared when the sharenfs or sharesmb property is set.

zfs unshare -a|filesystem|mountpoint

Unshares currently shared ZFS file systems. -a

Unshare all available ZFS file systems. Invoked automatically as part of the shutdown process.

filesystem|mountpoint

Unshare the specified filesystem. The command can also be given a path to a ZFS file system shared on the system.

## SEE ALSO
exports(5), smb.conf(5), zfsprops(7)


zfs-snapshot

title: zfs-snapshot(8)

summary: create snapshots of ZFS datasets

text:
# zfs-snapshot(8)

## NAME
zfs-snapshot — create snapshots of ZFS datasets

## SYNOPSIS
zfs

snapshot [-r] [-o property=value]… dataset@snapname…

## DESCRIPTION
Creates a snapshot of a dataset or multiple snapshots of different datasets.

Snapshots are created atomically. That is, a snapshot is a consistent image of a dataset at a specific point in time; it includes all modifications to the dataset made by system calls that have successfully completed before that point in time. Recursive snapshots created through the -r option are all created at the same time.

zfs snap can be used as an alias for zfs snapshot.

See the Snapshots section of zfsconcepts(7) for details.

-o property=value

Set the specified property; see zfs create for details.

-r

Recursively create snapshots of all descendent datasets

## EXAMPLES

### Example 1: Creating a ZFS Snapshot
The following command creates a snapshot named yesterday. This snapshot is mounted on demand in the .zfs/snapshot directory at the root of the pool/home/bob file system.

\# zfs snapshot pool/home/bob@yesterday

### Example 2: Creating and Destroying Multiple Snapshots
The following command creates snapshots named yesterday of pool/home and all of its descendent file systems. Each snapshot is mounted on demand in the .zfs/snapshot directory at the root of its file system. The second command destroys the newly created snapshots.

\# zfs snapshot -r pool/home@yesterday

\# zfs destroy -r pool/home@yesterday

### Example 3: Promoting a ZFS Clone
The following commands illustrate how to test out changes to a file system, and then replace the original file system with the changed one, using clones, clone promotion, and renaming:

```
# zfs create pool/project/production
  populate /pool/project/production with data
# zfs snapshot pool/project/production@today
# zfs clone pool/project/production@today pool/project/beta
  make changes to /pool/project/beta and test them
# zfs promote pool/project/beta
# zfs rename pool/project/production pool/project/legacy
# zfs rename pool/project/beta pool/project/production
  once the legacy version is no longer needed, it can be destroyed
# zfs destroy pool/project/legacy
```

### Example 4: Performing a Rolling Snapshot
The following example shows how to maintain a history of snapshots with a consistent naming scheme. To keep a week's worth of snapshots, the user destroys the oldest snapshot, renames the remaining snapshots, and then creates a new snapshot, as follows:

```
# zfs destroy -r pool/users@7daysago
# zfs rename -r pool/users@6daysago @7daysago
# zfs rename -r pool/users@5daysago @6daysago
# zfs rename -r pool/users@4daysago @5daysago
# zfs rename -r pool/users@3daysago @4daysago
# zfs rename -r pool/users@2daysago @3daysago
# zfs rename -r pool/users@yesterday @2daysago
# zfs rename -r pool/users@today @yesterday
# zfs snapshot -r pool/users@today
```

## SEE ALSO
zfs-bookmark(8), zfs-clone(8), zfs-destroy(8), zfs-diff(8), zfs-hold(8), zfs-rename(8), zfs-rollback(8), zfs-send(8)


zfs-unallow

title: zfs-unallow(8)

text:
# zfs-unallow(8)

## NAME
zfs-allow — delegate ZFS administration permissions to unprivileged users

## SYNOPSIS
zfs

allow [-dglu] user|group[,user|group]… perm|@setname[,perm|@setname]… filesystem|volume

zfs

allow [-dl] -e|everyone perm|@setname[,perm|@setname]… filesystem|volume

zfs

allow -c perm|@setname[,perm|@setname]… filesystem|volume

zfs

allow -s @setname perm|@setname[,perm|@setname]… filesystem|volume

zfs

unallow [-dglru] user|group[,user|group]… [perm|@setname[,perm|@setname]…] filesystem|volume

zfs

unallow [-dlr] -e|everyone [perm|@setname[,perm|@setname]…] filesystem|volume

zfs

unallow [-r] -c [perm|@setname[,perm|@setname]…] filesystem|volume

zfs

unallow [-r] -s @setname [perm|@setname[,perm|@setname]…] filesystem|volume

## DESCRIPTION
zfs allow filesystem|volume

Displays permissions that have been delegated on the specified filesystem or volume. See the other forms of zfs allow for more information. Delegations are supported under Linux with the exception of mount, unmount, mountpoint, canmount, rename, and share. These permissions cannot be delegated because the Linux mount(8) command restricts modifications of the global namespace to the root user.

zfs allow [-dglu] user|group[,user|group]… perm|@setname[,perm|@setname]… filesystem|volume

zfs allow [-dl] -e|everyone perm|@setname[,perm|@setname]… filesystem|volume

Delegates ZFS administration permission for the file systems to non-privileged users. -d

Allow only for the descendent file systems.

-e|everyone

Specifies that the permissions be delegated to everyone.

-g group[,group]…

Explicitly specify that permissions are delegated to the group.

-l

Allow "locally" only for the specified file system.

-u user[,user]…

Explicitly specify that permissions are delegated to the user.

user|group[,user|group]…

Specifies to whom the permissions are delegated. Multiple entities can be specified as a comma-separated list. If neither of the -gu options are specified, then the argument is interpreted preferentially as the keyword everyone, then as a user name, and lastly as a group name. To specify a user or group named "everyone", use the -g or -u options. To specify a group with the same name as a user, use the -g options.

perm|@setname[,perm|@setname]…

The permissions to delegate. Multiple permissions may be specified as a comma-separated list. Permission names are the same as ZFS subcommand and property names. See the property list below. Property set names, which begin with @, may be specified. See the -s form below for details.

If neither of the -dl options are specified, or both are, then the permissions are allowed for the file system or volume, and all of its descendants.

Permissions are generally the ability to use a ZFS subcommand or change a ZFS property. The following permissions are available:

NAME

TYPE

NOTES

allow

subcommand

Must also have the permission that is being allowed

bookmark

subcommand

clone

subcommand

Must also have the create ability and mount ability in the origin file system

create

subcommand

Must also have the mount ability. Must also have the refreservation ability to create a non-sparse volume.

destroy

subcommand

Must also have the mount ability

diff

subcommand

Allows lookup of paths within a dataset given an object number, and the ability to create snapshots necessary to zfs diff.

hold

subcommand

Allows adding a user hold to a snapshot

load-key

subcommand

Allows loading and unloading of encryption key (see zfs load-key and zfs unload-key).

change-key

subcommand

Allows changing an encryption key via zfs change-key.

mount

subcommand

Allows mounting/unmounting ZFS datasets

promote

subcommand

Must also have the mount and promote ability in the origin file system

receive

subcommand

Must also have the mount and create ability, required for zfs receive -F (see also receive:append for limited, non forced receive)

release

subcommand

Allows releasing a user hold which might destroy the snapshot

rename

subcommand

Must also have the mount and create ability in the new parent

rollback

subcommand

Must also have the mount ability

send

subcommand

Allows sending a replication stream of a dataset.

send:raw

subcommand

Only allows sending raw replication streams, preventing encrypted datasets being sent in decrypted form.

share

subcommand

Allows sharing file systems over NFS or SMB protocols

snapshot

subcommand

Must also have the mount ability

receive:append

other

Must also have the mount and create ability, limited receive ability (can not do receive -F)

groupquota

other

Allows accessing any groupquota@… property

groupobjquota

other

Allows accessing any groupobjquota@… property

groupused

other

Allows reading any groupused@… property

groupobjused

other

Allows reading any groupobjused@… property

userprop

other

Allows changing any user property

userquota

other

Allows accessing any userquota@… property

userobjquota

other

Allows accessing any userobjquota@… property

userused

other

Allows reading any userused@… property

userobjused

other

Allows reading any userobjused@… property

projectobjquota

other

Allows accessing any projectobjquota@… property

projectquota

other

Allows accessing any projectquota@… property

projectobjused

other

Allows reading any projectobjused@… property

projectused

other

Allows reading any projectused@… property

aclinherit

property

aclmode

property

acltype

property

atime

property

canmount

property

casesensitivity

property

checksum

property

compression

property

context

property

copies

property

dedup

property

defcontext

property

devices

property

dnodesize

property

encryption

property

exec

property

filesystem_limit

property

fscontext

property

keyformat

property

keylocation

property

logbias

property

mlslabel

property

mountpoint

property

nbmand

property

normalization

property

overlay

property

pbkdf2iters

property

primarycache

property

quota

property

readonly

property

recordsize

property

redundant_metadata

property

refquota

property

refreservation

property

relatime

property

reservation

property

rootcontext

property

secondarycache

property

setuid

property

sharenfs

property

sharesmb

property

snapdev

property

snapdir

property

snapshot_limit

property

special_small_blocks

property

sync

property

utf8only

property

version

property

volblocksize

property

volmode

property

volsize

property

vscan

property

xattr

property

zoned

property

zfs allow -c perm|@setname[,perm|@setname]… filesystem|volume

Sets "create time" permissions. These permissions are granted (locally) to the creator of any newly-created descendent file system.

zfs allow -s @setname perm|@setname[,perm|@setname]… filesystem|volume

Defines or adds permissions to a permission set. The set can be used by other zfs allow commands for the specified file system and its descendants. Sets are evaluated dynamically, so changes to a set are immediately reflected. Permission sets follow the same naming restrictions as ZFS file systems, but the name must begin with @, and can be no more than 64 characters long.

zfs unallow [-dglru] user|group[,user|group]… [perm|@setname[,perm|@setname]…] filesystem|volume

zfs unallow [-dlr] -e|everyone [perm|@setname[,perm|@setname]…] filesystem|volume

zfs unallow [-r] -c [perm|@setname[,perm|@setname]…] filesystem|volume

Removes permissions that were granted with the zfs allow command. No permissions are explicitly denied, so other permissions granted are still in effect. For example, if the permission is granted by an ancestor. If no permissions are specified, then all permissions for the specified user, group, or everyone are removed. Specifying everyone (or using the -e option) only removes the permissions that were granted to everyone, not all permissions for every user and group. See the zfs allow command for a description of the -ldugec options. -r

Recursively remove the permissions from this file system and all descendants.

zfs unallow [-r] -s @setname [perm|@setname[,perm|@setname]…] filesystem|volume

Removes permissions from a permission set. If no permissions are specified, then all permissions are removed, thus removing the set entirely.

## EXAMPLES

### Example 1: Delegating ZFS Administration Permissions on a ZFS Dataset
The following example shows how to set permissions so that user cindys can create, destroy, mount, and take snapshots on tank/cindys. The permissions on tank/cindys are also displayed.

```
# zfs allow cindys create,destroy,mount,snapshot tank/cindys
# zfs allow tank/cindys
---- Permissions on tank/cindys --------------------------------------
Local+Descendent permissions:
        user cindys create,destroy,mount,snapshot
```

Because the tank/cindys mount point permission is set to 755 by default, user cindys will be unable to mount file systems under tank/cindys. Add an ACE similar to the following syntax to provide mount point access:

\# chmod A+user:cindys:add_subdirectory:allow /tank/cindys

### Example 2: Delegating Create Time Permissions on a ZFS Dataset
The following example shows how to grant anyone in the group staff to create file systems in tank/users. This syntax also allows staff members to destroy their own file systems, but not destroy anyone else's file system. The permissions on tank/users are also displayed.

```
# zfs allow staff create,mount tank/users
# zfs allow -c destroy tank/users
# zfs allow tank/users
---- Permissions on tank/users ---------------------------------------
Permission sets:
        destroy
Local+Descendent permissions:
        group staff create,mount
```

### Example 3: Defining and Granting a Permission Set on a ZFS Dataset
The following example shows how to define and grant a permission set on the tank/users file system. The permissions on tank/users are also displayed.

```
# zfs allow -s @pset create,destroy,snapshot,mount tank/users
# zfs allow staff @pset tank/users
# zfs allow tank/users
---- Permissions on tank/users ---------------------------------------
Permission sets:
        @pset create,destroy,mount,snapshot
Local+Descendent permissions:
        group staff @pset
```

### Example 4: Delegating Property Permissions on a ZFS Dataset
The following example shows to grant the ability to set quotas and reservations on the users/home file system. The permissions on users/home are also displayed.

```
# zfs allow cindys quota,reservation users/home
# zfs allow users/home
---- Permissions on users/home ---------------------------------------
Local+Descendent permissions:
        user cindys quota,reservation
cindys% zfs set quota=10G users/home/marks
cindys% zfs get quota users/home/marks
NAME              PROPERTY  VALUE  SOURCE
users/home/marks  quota     10G    local
```

### Example 5: Removing ZFS Delegated Permissions on a ZFS Dataset
The following example shows how to remove the snapshot permission from the staff group on the tank/users file system. The permissions on tank/users are also displayed.

```
# zfs unallow staff snapshot tank/users
# zfs allow tank/users
---- Permissions on tank/users ---------------------------------------
Permission sets:
        @pset create,destroy,mount,snapshot
Local+Descendent permissions:
        group staff @pset
```


zfs-unload-key

title: zfs-unload-key(8)

text:
# zfs-unload-key(8)

## NAME
zfs-load-key — load, unload, or change encryption key of ZFS dataset

## SYNOPSIS
zfs

load-key [-nr] [-L keylocation] -a|filesystem

zfs

unload-key [-r] -a|filesystem

zfs

change-key [-l] [-o keylocation=value] [-o keyformat=value] [-o pbkdf2iters=value] filesystem

zfs

change-key -i [-l] filesystem

## DESCRIPTION
zfs load-key [-nr] [-L keylocation] -a|filesystem

Load the key for filesystem, allowing it and all children that inherit the keylocation property to be accessed. The key will be expected in the format specified by the keyformat and location specified by the keylocation property. Note that if the keylocation is set to prompt the terminal will interactively wait for the key to be entered. Loading a key will not automatically mount the dataset. If that functionality is desired, zfs mount -l will ask for the key and mount the dataset (see zfs-mount(8)). Once the key is loaded the keystatus property will become available. -r

Recursively loads the keys for the specified filesystem and all descendent encryption roots.

-a

Loads the keys for all encryption roots in all imported pools.

-n

Do a dry-run ("No-op") load-key. This will cause zfs to simply check that the provided key is correct. This command may be run even if the key is already loaded.

-L keylocation

Use keylocation instead of the keylocation property. This will not change the value of the property on the dataset. Note that if used with either -r or -a, keylocation may only be given as prompt.

zfs unload-key [-r] -a|filesystem

Unloads a key from ZFS, removing the ability to access the dataset and all of its children that inherit the keylocation property. This requires that the dataset is not currently open or mounted. Once the key is unloaded the keystatus property will become unavailable. -r

Recursively unloads the keys for the specified filesystem and all descendent encryption roots.

-a

Unloads the keys for all encryption roots in all imported pools.

zfs change-key [-l] [-o keylocation=value] [-o keyformat=value] [-o pbkdf2iters=value] filesystem

zfs change-key -i [-l] filesystem

Changes the user's key (e.g. a passphrase) used to access a dataset. This command requires that the existing key for the dataset is already loaded. This command may also be used to change the keylocation, keyformat, and pbkdf2iters properties as needed. If the dataset was not previously an encryption root it will become one. Alternatively, the -i flag may be provided to cause an encryption root to inherit the parent's key instead. If the user's key is compromised, zfs change-key does not necessarily protect existing or newly-written data from attack. Newly-written data will continue to be encrypted with the same master key as the existing data. The master key is compromised if an attacker obtains a user key and the corresponding wrapped master key. Currently, zfs change-key does not overwrite the previous wrapped master key on disk, so it is accessible via forensic analysis for an indeterminate length of time.

In the event of a master key compromise, ideally the drives should be securely erased to remove all the old data (which is readable using the compromised master key), a new pool created, and the data copied back. This can be approximated in place by creating new datasets, copying the data (e.g. using zfs send | zfs recv), and then clearing the free space with zpool trim --secure if supported by your hardware, otherwise zpool initialize.

-l

Ensures the key is loaded before attempting to change the key. This is effectively equivalent to running zfs load-key filesystem; zfs change-key filesystem

-o property=value

Allows the user to set encryption key properties (keyformat, keylocation, and pbkdf2iters) while changing the key. This is the only way to alter keyformat and pbkdf2iters after the dataset has been created.

-i

Indicates that zfs should make filesystem inherit the key of its parent. Note that this command can only be run on an encryption root that has an encrypted parent.

### Encryption
Enabling the encryption feature allows for the creation of encrypted filesystems and volumes. ZFS will encrypt file and volume data, file attributes, ACLs, permission bits, directory listings, FUID mappings, and userused/groupused data. ZFS will not encrypt metadata related to the pool structure, including dataset and snapshot names, dataset hierarchy, properties, file size, file holes, and deduplication tables (though the deduplicated data itself is encrypted).

Key rotation is managed by ZFS. Changing the user's key (e.g. a passphrase) does not require re-encrypting the entire dataset. Datasets can be scrubbed, resilvered, renamed, and deleted without the encryption keys being loaded (see the load-key subcommand for more info on key loading).

Creating an encrypted dataset requires specifying the encryption and keyformat properties at creation time, along with an optional keylocation and pbkdf2iters. After entering an encryption key, the created dataset will become an encryption root. Any descendant datasets will inherit their encryption key from the encryption root by default, meaning that loading, unloading, or changing the key for the encryption root will implicitly do the same for all inheriting datasets. If this inheritance is not desired, simply supply a keyformat when creating the child dataset or use zfs change-key to break an existing relationship, creating a new encryption root on the child. Note that the child's keyformat may match that of the parent while still creating a new encryption root, and that changing the encryption property alone does not create a new encryption root; this would simply use a different cipher suite with the same key as its encryption root. The one exception is that clones will always use their origin's encryption key. As a result of this exception, some encryption-related properties (namely keystatus, keyformat, keylocation, and pbkdf2iters) do not inherit like other ZFS properties and instead use the value determined by their encryption root. Encryption root inheritance can be tracked via the read-only encryptionroot property.

Encryption changes the behavior of a few ZFS operations. Encryption is applied after compression so compression ratios are preserved. Normally checksums in ZFS are 256 bits long, but for encrypted data the checksum is 128 bits of the user-chosen checksum and 128 bits of MAC from the encryption suite, which provides additional protection against maliciously altered data. Deduplication is still possible with encryption enabled but for security, datasets will only deduplicate against themselves, their snapshots, and their clones.

There are a few limitations on encrypted datasets. Encrypted data cannot be embedded via the embedded_data feature. Encrypted datasets may not have copies=3 since the implementation stores some encryption metadata where the third copy would normally be. Since compression is applied before encryption, datasets may be vulnerable to a CRIME-like attack if applications accessing the data allow for it. Deduplication with encryption will leak information about which blocks are equivalent in a dataset and will incur an extra CPU cost for each block written.

## SEE ALSO
zfsprops(7), zfs-create(8), zfs-set(8)


zfs-unmount

title: zfs-unmount(8)

summary: manage mount state of ZFS filesystems

text:
# zfs-unmount(8)

## NAME
zfs-mount — manage mount state of ZFS filesystems

## SYNOPSIS
zfs

mount [-j]

zfs

mount [-Oflv] [-o options] -a|-R filesystem|filesystem

zfs

unmount [-fu] -a|filesystem|mountpoint

## DESCRIPTION
zfs mount [-j]

Displays all ZFS file systems currently mounted. -j, --json

Displays all mounted file systems in JSON format.

zfs mount [-Oflv] [-o options] -a|-R filesystem|filesystem

Mount ZFS filesystem on a path described by its mountpoint property, if the path exists and is empty. If mountpoint is set to legacy, the filesystem should be instead mounted using mount(8). -O

Perform an overlay mount. Allows mounting in non-empty mountpoint. See mount(8) for more information.

-a

Mount all available ZFS file systems. Invoked automatically as part of the boot process if configured.

-R

Mount the specified filesystems along with all their children.

filesystem

Mount the specified filesystem.

-o options

An optional, comma-separated list of mount options to use temporarily for the duration of the mount. See the Temporary Mount Point Properties section of zfsprops(7) for details.

-l

Load keys for encrypted filesystems as they are being mounted. This is equivalent to executing zfs load-key on each encryption root before mounting it. Note that if a filesystem has keylocation=prompt, this will cause the terminal to interactively block after asking for the key.

-v

Report mount progress.

-f

Attempt to force mounting of all filesystems, even those that couldn't normally be mounted (e.g. redacted datasets).

zfs unmount [-fu] -a|filesystem|mountpoint

Unmounts currently mounted ZFS file systems. -a

Unmount all available ZFS file systems. Invoked automatically as part of the shutdown process.

-f

Forcefully unmount the file system, even if it is currently in use. This option is not supported on Linux.

-u

Unload keys for any encryption roots unmounted by this command.

filesystem|mountpoint

Unmount the specified filesystem. The command can also be given a path to a ZFS file system mount point on the system.


zfs-unzone

title: zfs-unzone(8)

text:
# zfs-unzone(8)

## NAME
zfs-zone, zfs-unzone — attach and detach ZFS filesystems to user namespaces

## SYNOPSIS
zfs zone

nsfile filesystem

zfs unzone

nsfile filesystem

## DESCRIPTION
zfs zone nsfile filesystem

Attach the specified filesystem to the user namespace identified by nsfile. From now on this file system tree can be managed from within a user namespace if the zoned property has been set. You cannot attach a zoned dataset's children to another user namespace. You can also not attach the root file system of the user namespace or any dataset which needs to be mounted before the zfs service is run inside the user namespace, as it would be attached unmounted until it is mounted from the service inside the user namespace.

To allow management of the dataset from within a user namespace, the zoned property has to be set and the user namespaces needs access to the /dev/zfs device. The quota property cannot be changed from within a user namespace.

After a dataset is attached to a user namespace and the zoned property is set, a zoned file system cannot be mounted outside the user namespace, since the user namespace administrator might have set the mount point to an unacceptable value.

zfs unzone nsfile filesystem

Detach the specified filesystem from the user namespace identified by nsfile.

## EXAMPLES

### Example 1: Delegating a Dataset to a User Namespace
The following example delegates the tank/users dataset to a user namespace identified by user namespace file /proc/1234/ns/user.

\# zfs zone /proc/1234/ns/user tank/users

## SEE ALSO
zfsprops(7)


zfs-upgrade

title: zfs-upgrade(8)

text:
# zfs-upgrade(8)

## NAME
zfs-upgrade — manage on-disk version of ZFS filesystems

## SYNOPSIS
zfs

upgrade

zfs

upgrade -v

zfs

upgrade [-r] [-V version] -a|filesystem

## DESCRIPTION
zfs upgrade

Displays a list of file systems that are not the most recent version.

zfs upgrade -v

Displays a list of currently supported file system versions.

zfs upgrade [-r] [-V version] -a|filesystem

Upgrades file systems to a new on-disk version. Once this is done, the file systems will no longer be accessible on systems running older versions of ZFS. zfs send streams generated from new snapshots of these file systems cannot be accessed on systems running older versions of ZFS. In general, the file system version is independent of the pool version. See zpool-features(7) for information on features of ZFS storage pools.

In some cases, the file system version and the pool version are interrelated and the pool version must be upgraded before the file system version can be upgraded.

-V version

Upgrade to version. If not specified, upgrade to the most recent version. This option can only be used to increase the version number, and only up to the most recent version supported by this version of ZFS.

-a

Upgrade all file systems on all imported pools.

filesystem

Upgrade the specified file system.

-r

Upgrade the specified file system and all descendent file systems.

## SEE ALSO
zpool-upgrade(8)


zfs-userspace

title: zfs-userspace(8)

summary: display space and quotas of ZFS dataset

text:
# zfs-userspace(8)

## NAME
zfs-userspace — display space and quotas of ZFS dataset

## SYNOPSIS
zfs

userspace [-Hinp] [-o field[,field]…] [-s field]… [-S field]… [-t type[,type]…] filesystem|snapshot|path

zfs

groupspace [-Hinp] [-o field[,field]…] [-s field]… [-S field]… [-t type[,type]…] filesystem|snapshot|path

zfs

projectspace [-Hp] [-o field[,field]…] [-s field]… [-S field]… filesystem|snapshot|path

## DESCRIPTION
zfs userspace [-Hinp] [-o field[,field]…] [-s field]… [-S field]… [-t type[,type]…] filesystem|snapshot|path

Displays space consumed by, and quotas on, each user in the specified filesystem, snapshot, or path. If a path is given, the filesystem that contains that path will be used. This corresponds to the userused@user, userobjused@user, userquota@user, and userobjquota@user properties. -H

Do not print headers, use tab-delimited output.

-S field

Sort by this field in reverse order. See -s.

-i

Translate SID to POSIX ID. The POSIX ID may be ephemeral if no mapping exists. Normal POSIX interfaces (like stat(2), ls -l) perform this translation, so the -i option allows the output from zfs userspace to be compared directly with those utilities. However, -i may lead to confusion if some files were created by an SMB user before a SMB-to-POSIX name mapping was established. In such a case, some files will be owned by the SMB entity and some by the POSIX entity. However, the -i option will report that the POSIX entity has the total usage and quota for both.

-n

Print numeric ID instead of user/group name.

-o field[,field]…

Display only the specified fields from the following set: type, name, used, quota. The default is to display all fields.

-p

Use exact (parsable) numeric output.

-s field

Sort output by this field. The -s and -S flags may be specified multiple times to sort first by one field, then by another. The default is -s type -s name.

-t type[,type]…

Print only the specified types from the following set: all, posixuser, smbuser, posixgroup, smbgroup. The default is -t posixuser,smbuser. The default can be changed to include group types.

zfs groupspace [-Hinp] [-o field[,field]…] [-s field]… [-S field]… [-t type[,type]…] filesystem|snapshot

Displays space consumed by, and quotas on, each group in the specified filesystem or snapshot. This subcommand is identical to userspace, except that the default types to display are -t posixgroup,smbgroup.

zfs projectspace [-Hp] [-o field[,field]…] [-s field]… [-S field]… filesystem|snapshot|path

Displays space consumed by, and quotas on, each project in the specified filesystem or snapshot. This subcommand is identical to userspace, except that the project identifier is a numeral, not a name. So need neither the option -i for SID to POSIX ID nor -n for numeric ID, nor -t for types.

## SEE ALSO
zfsprops(7), zfs-set(8)


zfs-wait

title: zfs-wait(8)

text:
# zfs-wait(8)

## NAME
zfs-wait — wait for activity in ZFS filesystem to stop

## SYNOPSIS
zfs

wait [-t activity[,activity]…] filesystem

## DESCRIPTION
Waits until all background activity of the given types has ceased in the given filesystem. The activity could cease because it has completed or because the filesystem has been destroyed or unmounted. If no activities are specified, the command waits until background activity of every type listed below has ceased. If there is no activity of the given types in progress, the command returns immediately.

These are the possible values for activity, along with what each one waits for:

deleteq

The filesystem's internal delete queue to empty

Note that the internal delete queue does not finish draining until all large files have had time to be fully destroyed and all open file handles to unlinked files are closed.

## SEE ALSO
lsof(8)


zfs-zone

title: zfs-zone(8)

text:
# zfs-zone(8)

## NAME
zfs-zone, zfs-unzone — attach and detach ZFS filesystems to user namespaces

## SYNOPSIS
zfs zone

nsfile filesystem

zfs unzone

nsfile filesystem

## DESCRIPTION
zfs zone nsfile filesystem

Attach the specified filesystem to the user namespace identified by nsfile. From now on this file system tree can be managed from within a user namespace if the zoned property has been set. You cannot attach a zoned dataset's children to another user namespace. You can also not attach the root file system of the user namespace or any dataset which needs to be mounted before the zfs service is run inside the user namespace, as it would be attached unmounted until it is mounted from the service inside the user namespace.

To allow management of the dataset from within a user namespace, the zoned property has to be set and the user namespaces needs access to the /dev/zfs device. The quota property cannot be changed from within a user namespace.

After a dataset is attached to a user namespace and the zoned property is set, a zoned file system cannot be mounted outside the user namespace, since the user namespace administrator might have set the mount point to an unacceptable value.

zfs unzone nsfile filesystem

Detach the specified filesystem from the user namespace identified by nsfile.

## EXAMPLES

### Example 1: Delegating a Dataset to a User Namespace
The following example delegates the tank/users dataset to a user namespace identified by user namespace file /proc/1234/ns/user.

\# zfs zone /proc/1234/ns/user tank/users

## SEE ALSO
zfsprops(7)


title: zfs_ids_to_path(8)

text:
# zfs_ids_to_path(8)

## NAME
zfs_ids_to_path — convert objset and object ids to names and paths

## SYNOPSIS
zfs_ids_to_path

[-v] pool objset-id object-id

## DESCRIPTION
The zfs_ids_to_path utility converts a provided objset and object ids into a path to the file they refer to.

-v

Verbose. Print the dataset name and the file path within the dataset separately. This will work correctly even if the dataset is not mounted.

## SEE ALSO
zdb(8), zfs(8)


title: zfs_prepare_disk(8)

text:
# zfs_prepare_disk(8)

## NAME
zfs_prepare_disk — special script that gets run before bringing a disk into a pool

## DESCRIPTION
zfs_prepare_disk is an optional script that gets called by libzfs before bringing a disk into a pool. It can be modified by the user to run whatever commands are necessary to prepare a disk for inclusion into the pool. For example, users can add lines to zfs_prepare_disk to do things like update the drive's firmware or check the drive's health. zfs_prepare_disk is optional and can be removed if not needed. libzfs will look for the script at /usr/libexec/zfs/zfs_prepare_disk.

### Properties
zfs_prepare_disk will be passed the following environment variables:

POOL_NAME

Name of the pool

VDEV_PATH

Path to the disk (like /dev/sda)

VDEV_PREPARE

Reason why the disk is being prepared for inclusion ('create', 'add', 'replace', or 'autoreplace'). This can be useful if you only want the script to be run under certain actions.

VDEV_UPATH

Path to one of the underlying devices for the disk. For multipath this would return one of the /dev/sd* paths to the disk. If the device is not a device mapper device, then VDEV_UPATH just returns the same value as VDEV_PATH

VDEV_ENC_SYSFS_PATH

Path to the disk's enclosure sysfs path, if available

Note that some of these variables may have a blank value. POOL_NAME is blank at pool creation time, for example.

## ENVIRONMENT
zfs_prepare_disk runs with a limited $PATH.

## EXIT STATUS
zfs_prepare_disk should return 0 on success, non-zero otherwise. If non-zero is returned, the disk will not be included in the pool.


zgenhostid

title: zgenhostid(8)

summary: generate host ID into /etc/hostid

text:
# zgenhostid(8)

## NAME
zgenhostid — generate host ID into /etc/hostid

## SYNOPSIS
zgenhostid

[-f] [-o filename] [hostid]

## DESCRIPTION
Creates /etc/hostid file and stores the host ID in it. If hostid was provided, validate and store that value. Otherwise, randomly generate an ID.

## OPTIONS
-h

Display a summary of the command-line options.

-f

Allow output overwrite.

-o filename

Write to filename instead of the default /etc/hostid.

hostid

Specifies the value to be placed in /etc/hostid. It should be a number with a value between 1 and 2^32-1. If 0, generate a random ID. This value must be unique among your systems. It must be an 8-digit-long hexadecimal number, optionally prefixed by "0x".

## FILES
/etc/hostid

## EXAMPLES
Generate a random hostid and store it

\# zgenhostid

Record the libc-generated hostid in /etc/hostid

\# zgenhostid "$(hostid)"

Record a custom hostid (0xdeadbeef) in /etc/hostid

\# zgenhostid deadbeef

Record a custom hostid (0x01234567) in /tmp/hostid and overwrite the file if it exists

\# zgenhostid -f -o /tmp/hostid 0x01234567

## SEE ALSO
genhostid(1), hostid(1), sethostid(3), spl(4)

## HISTORY
zgenhostid emulates the genhostid(1) utility and is provided for use on systems which do not include the utility or do not provide the sethostid(3) function.


zinject

title: zinject(8)

summary: ZFS Fault Injector

text:
# zinject(8)

## NAME
zinject — ZFS Fault Injector

## DESCRIPTION
zinject creates artificial problems in a ZFS pool by simulating data corruption or device failures. This program is dangerous.

## SYNOPSIS
zinject

List injection records.

zinject

-b objset:object:level:start:end [-f frequency] -amu [pool]

Force an error into the pool at a bookmark.

zinject

-c id|all

Cancel injection records.

zinject

-d vdev -A degrade|fault pool

Force a vdev into the DEGRADED or FAULTED state.

zinject

-d vdev -D latency:lanes [-T read|write] pool

Add an artificial delay to I/O requests on a particular device, such that the requests take a minimum of latency milliseconds to complete. Each delay has an associated number of lanes which defines the number of concurrent I/O requests that can be processed. For example, with a single lane delay of 10 ms (-D 10:1), the device will only be able to service a single I/O request at a time with each request taking 10 ms to complete. So, if only a single request is submitted every 10 ms, the average latency will be 10 ms; but if more than one request is submitted every 10 ms, the average latency will be more than 10 ms.

Similarly, if a delay of 10 ms is specified to have two lanes (-D 10:2), then the device will be able to service two requests at a time, each with a minimum latency of 10 ms. So, if two requests are submitted every 10 ms, then the average latency will be 10 ms; but if more than two requests are submitted every 10 ms, the average latency will be more than 10 ms.

Also note, these delays are additive. So two invocations of -D 10:1 are roughly equivalent to a single invocation of -D 10:2. This also means, that one can specify multiple lanes with differing target latencies. For example, an invocation of -D 10:1 followed by -D 25:2 will create 3 lanes on the device: one lane with a latency of 10 ms and two lanes with a 25 ms latency.

zinject

-d vdev [-e device_error] [-L label_error] [-T failure] [-f frequency] [-F] pool

Force a vdev error.

zinject

-i seconds pool

Add an artificial delay during the future import of a pool. This injector is automatically cleared after the import is finished.

zinject

-E delay [-a] [-m] [-f freq] [-l level] [-r range] [-T iotype] [-t type|-b bookmark]

Inject pipeline ready stage delays for the given object or bookmark. The delay is specified in milliseconds.

zinject

-I [-s seconds|-g txgs] pool

Simulate a hardware failure that fails to honor a cache flush.

zinject

-p function pool

Panic inside the specified function.

zinject

-t data -C dvas [-e device_error] [-f frequency] [-l level] [-r range] [-amq] path

Force an error into the contents of a file.

zinject

-t dnode -C dvas [-e device_error] [-f frequency] [-l level] [-amq] path

Force an error into the metadnode for a file or directory.

zinject

-t mos_type -C dvas [-e device_error] [-f frequency] [-l level] [-r range] [-amqu] pool

Force an error into the MOS of a pool.

## OPTIONS
-a

Flush the ARC before injection.

-b objset:object:level:start:end

Force an error into the pool at this bookmark tuple. Each number is in hexadecimal, and only one block can be specified.

-C dvas

Inject the given error only into specific DVAs. The mask should be specified as a list of 0-indexed DVAs separated by commas (e.g. 0,2). This option is not applicable to logical data errors such as decompress and decrypt.

-d vdev

A vdev specified by path or GUID.

-e device_error

Specify checksum

for an ECKSUM error,

decompress

for a data decompression error,

decrypt

for a data decryption error,

corrupt

to flip a bit in the data after a read,

dtl

for an ECHILD error,

io

for an EIO error where reopening the device will succeed,

nxio

for an ENXIO error where reopening the device will fail, or

noop

to drop the IO without executing it, and return success.

For EIO and ENXIO, the "failed" reads or writes still occur. The probe simply sets the error value reported by the I/O pipeline so it appears the read or write failed. Decryption errors only currently work with file data.

-f frequency

Only inject errors a fraction of the time. Expressed as a real number percentage between 0.0001 and 100.

-F

Fail faster. Do fewer checks.

-f txgs

Run for this many transaction groups before reporting failure.

-h

Print the usage message.

-l level

Inject an error at a particular block level. The default is 0.

-L label_error

Set the label error region to one of nvlist, pad1, pad2, or uber.

-m

Automatically remount the underlying filesystem.

-q

Quiet mode. Only print the handler number added.

-r range

Inject an error over a particular logical range of an object, which will be translated to the appropriate blkid range according to the object's properties.

-s seconds

Run for this many seconds before reporting failure.

-T type

Inject the error into I/O of this type. read, write, flush, claim, free

Fundamental I/O types

all

All fundamental I/O types

probe

Device probe I/O

-t mos_type

Set this to mos

for any data in the MOS,

mosdir

for an object directory,

config

for the pool configuration,

bpobj

for the block pointer list,

spacemap

for the space map,

metaslab

for the metaslab, or

errlog

for the persistent error log.

-u

Unload the pool after injection.

## ENVIRONMENT VARIABLES
ZFS_HOSTID

Run zinject in debug mode.

## SEE ALSO
zfs(8), zpool(8)


zpool

title: zpool(8)

summary: configure ZFS storage pools

text:
# zpool(8)

## NAME
zpool — configure ZFS storage pools

## SYNOPSIS
zpool

-?V

zpool

version [-j]

zpool

subcommand [arguments]

## DESCRIPTION
The zpool command configures ZFS storage pools. A storage pool is a collection of devices that provides physical storage and data replication for ZFS datasets. All datasets within a storage pool share the same space. See zfs(8) for information on managing datasets.

For an overview of creating and managing ZFS storage pools see the zpoolconcepts(7) manual page.

## SUBCOMMANDS
All subcommands that modify state are logged persistently to the pool in their original form.

The zpool command provides subcommands to create and destroy storage pools, add capacity to storage pools, and provide information about the storage pools. The following subcommands are supported:

zpool -?

Displays a help message.

zpool -V, --version

zpool version [-j]

Displays the software version of the zpool userland utility and the ZFS kernel module. Use -j option to output in JSON format.

### Creation
zpool-create(8)

Creates a new storage pool containing the virtual devices specified on the command line.

zpool-initialize(8)

Begins initializing by writing to all unallocated regions on the specified devices, or all eligible devices in the pool if no individual devices are specified.

### Destruction
zpool-destroy(8)

Destroys the given pool, freeing up any devices for other use.

zpool-labelclear(8)

Removes ZFS label information from the specified device.

### Virtual Devices
zpool-attach(8)/zpool-detach(8)

Converts a non-redundant disk into a mirror, or increases the redundancy level of an existing mirror (attach), or performs the inverse operation (detach).

zpool-add(8)/zpool-remove(8)

Adds the specified virtual devices to the given pool, or removes the specified device from the pool.

zpool-replace(8)

Replaces an existing device (which may be faulted) with a new one.

zpool-split(8)

Creates a new pool by splitting all mirrors in an existing pool (which decreases its redundancy).

### Properties
Available pool properties listed in the zpoolprops(7) manual page.

zpool-list(8)

Lists the given pools along with a health status and space usage.

zpool-get(8)/zpool-set(8)

Retrieves the given list of properties (or all properties if all is used) for the specified storage pool(s).

### Monitoring
zpool-status(8)

Displays the detailed health status for the given pools.

zpool-iostat(8)

Displays logical I/O statistics for the given pools/vdevs. Physical I/O operations may be observed via iostat(1).

zpool-events(8)

Lists all recent events generated by the ZFS kernel modules. These events are consumed by the zed(8) and used to automate administrative tasks such as replacing a failed device with a hot spare. That manual page also describes the subclasses and event payloads that can be generated.

zpool-history(8)

Displays the command history of the specified pool(s) or all pools if no pool is specified.

### Maintenance
zpool-prefetch(8)

Prefetches specific types of pool data.

zpool-scrub(8)

Begins a scrub or resumes a paused scrub.

zpool-checkpoint(8)

Checkpoints the current state of pool, which can be later restored by zpool import --rewind-to-checkpoint.

zpool-trim(8)

Initiates an immediate on-demand TRIM operation for all of the free space in a pool. This operation informs the underlying storage devices of all blocks in the pool which are no longer allocated and allows thinly provisioned devices to reclaim the space.

zpool-sync(8)

This command forces all in-core dirty data to be written to the primary pool storage and not the ZIL. It will also update administrative information including quota reporting. Without arguments, zpool sync will sync all pools on the system. Otherwise, it will sync only the specified pool(s).

zpool-upgrade(8)

Manage the on-disk format version of storage pools.

zpool-wait(8)

Waits until all background activity of the given types has ceased in the given pool.

### Fault Resolution
zpool-offline(8)/zpool-online(8)

Takes the specified physical device offline or brings it online.

zpool-resilver(8)

Starts a resilver. If an existing resilver is already running it will be restarted from the beginning.

zpool-reopen(8)

Reopen all the vdevs associated with the pool.

zpool-clear(8)

Clears device errors in a pool.

### Import & Export
zpool-import(8)

Make disks containing ZFS storage pools available for use on the system.

zpool-export(8)

Exports the given pools from the system.

zpool-reguid(8)

Generates a new unique identifier for the pool.

## EXIT STATUS
The following exit values are returned:

0

Successful completion.

1

An error occurred.

2

Invalid command line options were specified.

## EXAMPLES

### Example 1: Creating a RAID-Z Storage Pool
The following command creates a pool with a single raidz root vdev that consists of six disks:

\# zpool create tank raidz sda sdb sdc sdd sde sdf

### Example 2: Creating a Mirrored Storage Pool
The following command creates a pool with two mirrors, where each mirror contains two disks:

\# zpool create tank mirror sda sdb mirror sdc sdd

### Example 3: Creating a ZFS Storage Pool by Using Partitions
The following command creates a non-redundant pool using two disk partitions:

\# zpool create tank sda1 sdb2

### Example 4: Creating a ZFS Storage Pool by Using Files
The following command creates a non-redundant pool using files. While not recommended, a pool based on files can be useful for experimental purposes.

\# zpool create tank /path/to/file/a /path/to/file/b

### Example 5: Making a non-mirrored ZFS Storage Pool mirrored
The following command converts an existing single device sda into a mirror by attaching a second device to it, sdb.

\# zpool attach tank sda sdb

### Example 6: Adding a Mirror to a ZFS Storage Pool
The following command adds two mirrored disks to the pool tank, assuming the pool is already made up of two-way mirrors. The additional space is immediately available to any datasets within the pool.

\# zpool add tank mirror sda sdb

### Example 7: Listing Available ZFS Storage Pools
The following command lists all available pools on the system. In this case, the pool zion is faulted due to a missing device. The results from this command are similar to the following:

```
# zpool list
NAME    SIZE  ALLOC   FREE  EXPANDSZ   FRAG    CAP  DEDUP  HEALTH  ALTROOT
rpool  19.9G  8.43G  11.4G         -    33%    42%  1.00x  ONLINE  -
tank   61.5G  20.0G  41.5G         -    48%    32%  1.00x  ONLINE  -
zion       -      -      -         -      -      -      -  FAULTED -
```

### Example 8: Destroying a ZFS Storage Pool
The following command destroys the pool tank and any datasets contained within:

\# zpool destroy -f tank

### Example 9: Exporting a ZFS Storage Pool
The following command exports the devices in pool tank so that they can be relocated or later imported:

\# zpool export tank

### Example 10: Importing a ZFS Storage Pool
The following command displays available pools, and then imports the pool tank for use on the system. The results from this command are similar to the following:

```
# zpool import
  pool: tank
    id: 15451357997522795478
 state: ONLINE
action: The pool can be imported using its name or numeric identifier.
config:

        tank        ONLINE
          mirror    ONLINE
            sda     ONLINE
            sdb     ONLINE

# zpool import tank
```

### Example 11: Upgrading All ZFS Storage Pools to the Current Version
The following command upgrades all ZFS Storage pools to the current version of the software:

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

### Example 12: Managing Hot Spares
The following command creates a new pool with an available hot spare:

\# zpool create tank mirror sda sdb spare sdc

If one of the disks were to fail, the pool would be reduced to the degraded state. The failed device can be replaced using the following command:

\# zpool replace tank sda sdd

Once the data has been resilvered, the spare is automatically removed and is made available for use should another device fail. The hot spare can be permanently removed from the pool using the following command:

\# zpool remove tank sdc

### Example 13: Creating a ZFS Pool with Mirrored Separate Intent Logs
The following command creates a ZFS storage pool consisting of two, two-way mirrors and mirrored log devices:

\# zpool create pool mirror sda sdb mirror sdc sdd log mirror sde sdf

### Example 14: Adding Cache Devices to a ZFS Pool
The following command adds two disks for use as cache devices to a ZFS storage pool:

\# zpool add pool cache sdc sdd

Once added, the cache devices gradually fill with content from main memory. Depending on the size of your cache devices, it could take over an hour for them to fill. Capacity and reads can be monitored using the iostat subcommand as follows:

\# zpool iostat -v pool 5

### Example 15: Removing a Mirrored top-level (Log or Data) Device
The following commands remove the mirrored log device mirror-2 and mirrored top-level data device mirror-1.

Given this configuration:

```
  pool: tank
 state: ONLINE
 scrub: none requested
config:

         NAME        STATE     READ WRITE CKSUM
         tank        ONLINE       0     0     0
           mirror-0  ONLINE       0     0     0
             sda     ONLINE       0     0     0
             sdb     ONLINE       0     0     0
           mirror-1  ONLINE       0     0     0
             sdc     ONLINE       0     0     0
             sdd     ONLINE       0     0     0
         logs
           mirror-2  ONLINE       0     0     0
             sde     ONLINE       0     0     0
             sdf     ONLINE       0     0     0
```

The command to remove the mirrored log mirror-2 is:

\# zpool remove tank mirror-2

At this point, the log device no longer exists (both sides of the mirror have been removed):

```
  pool: tank
 state: ONLINE
  scan: none requested
config:

        NAME        STATE     READ WRITE CKSUM
        tank        ONLINE       0     0     0
          mirror-0  ONLINE       0     0     0
            sda     ONLINE       0     0     0
            sdb     ONLINE       0     0     0
          mirror-1  ONLINE       0     0     0
            sdc     ONLINE       0     0     0
            sdd     ONLINE       0     0     0
```

The command to remove the mirrored data mirror-1 is:

\# zpool remove tank mirror-1

After mirror-1 has been evacuated, the pool remains redundant, but the total amount of space is reduced:

```
  pool: tank
 state: ONLINE
  scan: none requested
config:

        NAME        STATE     READ WRITE CKSUM
        tank        ONLINE       0     0     0
          mirror-0  ONLINE       0     0     0
            sda     ONLINE       0     0     0
            sdb     ONLINE       0     0     0
```

### Example 16: Displaying expanded space on a device
The following command displays the detailed information for the pool data. This pool is comprised of a single raidz vdev where one of its devices increased its capacity by 10 GiB. In this example, the pool will not be able to utilize this extra capacity until all the devices under the raidz vdev have been expanded.

```
# zpool list -v data
NAME         SIZE  ALLOC   FREE  EXPANDSZ   FRAG    CAP  DEDUP  HEALTH  ALTROOT
data        23.9G  14.6G  9.30G         -    48%    61%  1.00x  ONLINE  -
  raidz1    23.9G  14.6G  9.30G         -    48%
    sda         -      -      -         -      -
    sdb         -      -      -       10G      -
    sdc         -      -      -         -      -
```

### Example 17: Adding output columns
Additional columns can be added to the zpool status and zpool iostat output with -c.

```
# zpool status -c vendor,model,size
   NAME     STATE  READ WRITE CKSUM vendor  model        size
   tank     ONLINE 0    0     0
   mirror-0 ONLINE 0    0     0
   U1       ONLINE 0    0     0     SEAGATE ST8000NM0075 7.3T
   U10      ONLINE 0    0     0     SEAGATE ST8000NM0075 7.3T
   U11      ONLINE 0    0     0     SEAGATE ST8000NM0075 7.3T
   U12      ONLINE 0    0     0     SEAGATE ST8000NM0075 7.3T
   U13      ONLINE 0    0     0     SEAGATE ST8000NM0075 7.3T
   U14      ONLINE 0    0     0     SEAGATE ST8000NM0075 7.3T

# zpool iostat -vc size
              capacity     operations     bandwidth
pool        alloc   free   read  write   read  write  size
----------  -----  -----  -----  -----  -----  -----  ----
rpool       14.6G  54.9G      4     55   250K  2.69M
  sda1      14.6G  54.9G      4     55   250K  2.69M   70G
----------  -----  -----  -----  -----  -----  -----  ----
```

## ENVIRONMENT VARIABLES
ZFS_ABORT

Cause zpool to dump core on exit for the purposes of running ::findleaks.

ZFS_COLOR

Use ANSI color in zpool status and zpool iostat output.

ZPOOL_AUTO_POWER_ON_SLOT

Automatically attempt to turn on the drives enclosure slot power to a drive when running the zpool online or zpool clear commands. This has the same effect as passing the --power option to those commands.

ZPOOL_POWER_ON_SLOT_TIMEOUT_MS

The maximum time in milliseconds to wait for a slot power sysfs value to return the correct value after writing it. For example, after writing "on" to the sysfs enclosure slot power_control file, it can take some time for the enclosure to power down the slot and return "on" if you read back the 'power_control' value. Defaults to 30 seconds (30000ms) if not set.

ZPOOL_IMPORT_PATH

The search path for devices or files to use with the pool. This is a colon-separated list of directories in which zpool looks for device nodes and files. Similar to the -d option in zpool import.

ZPOOL_IMPORT_UDEV_TIMEOUT_MS

The maximum time in milliseconds that zpool import will wait for an expected device to be available.

ZPOOL_STATUS_NON_NATIVE_ASHIFT_IGNORE

If set, suppress warning about non-native vdev ashift in zpool status. The value is not used, only the presence or absence of the variable matters.

ZPOOL_VDEV_NAME_GUID

Cause zpool subcommands to output vdev GUIDs by default. This behavior is identical to the zpool status -g command line option.

ZPOOL_VDEV_NAME_FOLLOW_LINKS

Cause zpool subcommands to follow links for vdev names by default. This behavior is identical to the zpool status -L command line option.

ZPOOL_VDEV_NAME_PATH

Cause zpool subcommands to output full vdev path names by default. This behavior is identical to the zpool status -P command line option.

ZFS_VDEV_DEVID_OPT_OUT

Older OpenZFS implementations had issues when attempting to display pool config vdev names if a devid NVP value is present in the pool's config. For example, a pool that originated on illumos platform would have a devid value in the config and zpool status would fail when listing the config. This would also be true for future Linux-based pools.

A pool can be stripped of any devid values on import or prevented from adding them on zpool create or zpool add by setting ZFS_VDEV_DEVID_OPT_OUT.

ZPOOL_SCRIPTS_AS_ROOT

Allow a privileged user to run zpool status/iostat -c. Normally, only unprivileged users are allowed to run -c.

ZPOOL_SCRIPTS_PATH

The search path for scripts when running zpool status/iostat -c. This is a colon-separated list of directories and overrides the default ~/.zpool.d and /etc/zfs/zpool.d search paths.

ZPOOL_SCRIPTS_ENABLED

Allow a user to run zpool status/iostat -c. If ZPOOL_SCRIPTS_ENABLED is not set, it is assumed that the user is allowed to run zpool status/iostat -c.

ZFS_MODULE_TIMEOUT

Time, in seconds, to wait for /dev/zfs to appear. Defaults to 10, max 600 (10 minutes). If <0, wait forever; if 0, don't wait.

## INTERFACE STABILITY
Evolving

## SEE ALSO
zfs(4), zpool-features(7), zpoolconcepts(7), zpoolprops(7), zed(8), zfs(8), zpool-add(8), zpool-attach(8), zpool-checkpoint(8), zpool-clear(8), zpool-create(8), zpool-ddtprune(8), zpool-destroy(8), zpool-detach(8), zpool-events(8), zpool-export(8), zpool-get(8), zpool-history(8), zpool-import(8), zpool-initialize(8), zpool-iostat(8), zpool-labelclear(8), zpool-list(8), zpool-offline(8), zpool-online(8), zpool-prefetch(8), zpool-reguid(8), zpool-remove(8), zpool-reopen(8), zpool-replace(8), zpool-resilver(8), zpool-scrub(8), zpool-set(8), zpool-split(8), zpool-status(8), zpool-sync(8), zpool-trim(8), zpool-upgrade(8), zpool-wait(8)


zpool-add

title: zpool-add(8)

summary: add vdevs to ZFS storage pool

text:
# zpool-add(8)

## NAME
zpool-add — add vdevs to ZFS storage pool

## SYNOPSIS
zpool

add [-fgLnP] [--allow-in-use --allow-replication-mismatch --allow-ashift-mismatch] [-o property=value] pool vdev…

## DESCRIPTION
Adds the specified virtual devices to the given pool. The vdev specification is described in the Virtual Devices section of zpoolconcepts(7). The behavior of the -f option, and the device checks performed are described in the zpool create subcommand.

-f

Forces use of vdevs, even if they appear in use, have conflicting ashift values, or specify a conflicting replication level. Not all devices can be overridden in this manner.

-g

Display vdev, GUIDs instead of the normal device names. These GUIDs can be used in place of device names for the zpool detach/offline/remove/replace commands.

-L

Display real paths for vdevs resolving all symbolic links. This can be used to look up the current block device name regardless of the /dev/disk path used to open it.

-n

Displays the configuration that would be used without actually adding the vdevs. The actual pool creation can still fail due to insufficient privileges or device sharing.

-P

Display real paths for vdevs instead of only the last component of the path. This can be used in conjunction with the -L flag.

-o property=value

Sets the given pool properties. See the zpoolprops(7) manual page for a list of valid properties that can be set. The only property supported at the moment is ashift.

--allow-ashift-mismatch

Disable the ashift validation which allows mismatched ashift values in the pool. Adding top-level vdevs with different sector sizes will prohibit future device removal operations, see zpool-remove(8).

--allow-in-use

Allow vdevs to be added even if they might be in use in another pool.

--allow-replication-mismatch

Allow vdevs with conflicting replication levels to be added to the pool.

## EXAMPLES

### Example 1: Adding a Mirror to a ZFS Storage Pool
The following command adds two mirrored disks to the pool tank, assuming the pool is already made up of two-way mirrors. The additional space is immediately available to any datasets within the pool.

\# zpool add tank mirror sda sdb

### Example 2: Adding Cache Devices to a ZFS Pool
The following command adds two disks for use as cache devices to a ZFS storage pool:

\# zpool add pool cache sdc sdd

Once added, the cache devices gradually fill with content from main memory. Depending on the size of your cache devices, it could take over an hour for them to fill. Capacity and reads can be monitored using the iostat subcommand as follows:

\# zpool iostat -v pool 5

## SEE ALSO
zpool-attach(8), zpool-import(8), zpool-initialize(8), zpool-online(8), zpool-remove(8)


zpool-attach

title: zpool-attach(8)

summary: attach new device to existing ZFS vdev

text:
# zpool-attach(8)

## NAME
zpool-attach — attach new device to existing ZFS vdev

## SYNOPSIS
zpool

attach [-fsw] [-o property=value] pool vdev new_device

## DESCRIPTION
Attaches new_device to the existing vdev. The behavior differs depending on if the existing vdev is a RAID-Z device, or a mirror/plain device.

If the existing vdev is a mirror or plain device (e.g. specified as "sda" or "mirror-7"), the new device will be mirrored with the existing vdev, a resilver will be initiated, and the new device will contribute to additional redundancy once the resilver completes. If vdev is not currently part of a mirrored configuration, device automatically transforms into a two-way mirror of device and new_device. If vdev is part of a two-way mirror, attaching new_device creates a three-way mirror, and so on. In either case, new_device begins to resilver immediately and any running scrub is canceled.

If the existing vdev is a RAID-Z device (e.g. specified as "raidz2-0"), the new device will become part of that RAID-Z group. A "raidz expansion" will be initiated, and once the expansion completes, the new device will contribute additional space to the RAID-Z group. The expansion entails reading all allocated space from existing disks in the RAID-Z group, and rewriting it to the new disks in the RAID-Z group (including the newly added device). Its progress can be monitored with zpool status.

Data redundancy is maintained during and after the expansion. If a disk fails while the expansion is in progress, the expansion pauses until the health of the RAID-Z vdev is restored (e.g. by replacing the failed disk and waiting for reconstruction to complete). Expansion does not change the number of failures that can be tolerated without data loss (e.g. a RAID-Z2 is still a RAID-Z2 even after expansion). A RAID-Z vdev can be expanded multiple times.

After the expansion completes, old blocks retain their old data-to-parity ratio (e.g. 5-wide RAID-Z2 has 3 data and 2 parity) but distributed among the larger set of disks. New blocks will be written with the new data-to-parity ratio (e.g. a 5-wide RAID-Z2 which has been expanded once to 6-wide, has 4 data and 2 parity). However, the vdev's assumed parity ratio does not change, so slightly less space than is expected may be reported for newly-written blocks, according to zfs list, df, ls -s, and similar tools.

A pool-wide scrub is initiated at the end of the expansion in order to verify the checksums of all blocks which have been copied during the expansion.

-f

Forces use of new_device, even if it appears to be in use. Not all vdevs can be overridden in this manner.

-o property=value

Sets the given pool properties. See the zpoolprops(7) manual page for a list of valid properties that can be set. The only property supported at the moment is ashift.

-s

When attaching to a mirror or plain vdev, the new_device is reconstructed sequentially to restore redundancy as quickly as possible. Checksums are not verified during sequential reconstruction so a scrub is started when the resilver completes.

-w

Waits until new_device has finished resilvering or expanding before returning.

## SEE ALSO
zpool-add(8), zpool-detach(8), zpool-import(8), zpool-initialize(8), zpool-online(8), zpool-replace(8), zpool-resilver(8)


zpool-checkpoint

title: zpool-checkpoint(8)

text:
# zpool-checkpoint(8)

## NAME
zpool-checkpoint — check-point current ZFS storage pool state

## SYNOPSIS
zpool

checkpoint [-d [-w]] pool

## DESCRIPTION
Checkpoints the current state of pool , which can be later restored by zpool import --rewind-to-checkpoint. The existence of a checkpoint in a pool prohibits the following zpool subcommands: remove, attach, detach, split, and reguid. In addition, it may break reservation boundaries if the pool lacks free space. The zpool status command indicates the existence of a checkpoint or the progress of discarding a checkpoint from a pool. zpool list can be used to check how much space the checkpoint takes from the pool.

## OPTIONS
-d, --discard

Discards an existing checkpoint from pool.

-w, --wait

Waits until the checkpoint has finished being discarded before returning.

## SEE ALSO
zfs-snapshot(8), zpool-import(8), zpool-status(8)