zfs-mount-generator

title: zfs-mount-generator(8)

text:
# zfs-mount-generator(8)

## NAME
zfs-mount-generator — generate systemd mount units for ZFS filesystems

## SYNOPSIS
/lib/systemd/system-generators/zfs-mount-generator

## DESCRIPTION
zfs-mount-generator is a systemd.generator(7) that generates native systemd.mount(5) units for configured ZFS datasets.

### Properties
mountpoint=

Skipped if legacy or none.

canmount=

Skipped if off. Skipped if only noauto datasets exist for a given mountpoint and there's more than one. Datasets with yes take precedence over ones with noauto for the same mountpoint. Sets logical noauto flag if noauto. Encryption roots always generate zfs-load-key@root.service, even if off.

atime=, relatime=, devices=, exec=, readonly=, setuid=, nbmand=

Used to generate mount options equivalent to zfs mount.

encroot=, keylocation=

If the dataset is an encryption root, its mount unit will bind to zfs-load-key@root.service, with additional dependencies as follows: keylocation=prompt

None, uses systemd-ask-password(1)

keylocation=https://URL (et al.)

Wants=, After=: network-online.target

keylocation=file://<path>

RequiresMountsFor=path

The service also uses the same Wants=, After=, Requires=, and RequiresMountsFor=, as the mount unit.

org.openzfs.systemd:requires=path[ path]…

Sets Requires= for the mount- and key-loading unit.

org.openzfs.systemd:requires-mounts-for=path[ path]…

Sets RequiresMountsFor= for the mount- and key-loading unit.

org.openzfs.systemd:before=unit[ unit]…

Sets Before= for the mount unit.

org.openzfs.systemd:after=unit[ unit]…

Sets After= for the mount unit.

org.openzfs.systemd:wanted-by=unit[ unit]…

Sets logical noauto flag (see below). If not none, sets WantedBy= for the mount unit.

org.openzfs.systemd:required-by=unit[ unit]…

Sets logical noauto flag (see below). If not none, sets RequiredBy= for the mount unit.

org.openzfs.systemd:nofail=(unset)|on|off

Waxes or wanes strength of default reverse dependencies of the mount unit, see below.

org.openzfs.systemd:ignore=on|off

Skip if on. Defaults to off.

### Unit Ordering And Dependencies
Additionally, unless the pool the dataset resides on is imported at generation time, both units gain Wants=zfs-import.target and After=zfs-import.target.

Additionally, unless the logical noauto flag is set, the mount unit gains a reverse-dependency for local-fs.target of strength

(unset)

WantedBy= + Before=

on

WantedBy=

off

RequiredBy= + Before=

### Cache File
Because ZFS pools may not be available very early in the boot process, information on ZFS mountpoints must be stored separately. The output of

zfs list -Ho name,⟨every property above in order⟩

for datasets that should be mounted by systemd should be kept at /etc/zfs/zfs-list.cache/poolname, and, if writeable, will be kept synchronized for the entire pool by the history_event-zfs-list-cacher.sh ZEDLET, if enabled (see zed(8)).

## ENVIRONMENT
If the ZFS_DEBUG environment variable is nonzero (or unset and /proc/cmdline contains "debug"), print summary accounting information at the end.

## EXAMPLES
To begin, enable tracking for the pool:

\# touch /etc/zfs/zfs-list.cache/poolname

Then enable the tracking ZEDLET: # ln -s /usr/libexec/zfs/zed.d/history_event-zfs-list-cacher.sh /etc/zfs/zed.d

\# systemctl enable zfs-zed.service

\# systemctl restart zfs-zed.service

If no history event is in the queue, inject one to ensure the ZEDLET runs to refresh the cache file by setting a monitored property somewhere on the pool:

\# zfs set relatime=off poolname/dset

\# zfs inherit relatime poolname/dset

To test the generator output:

$ mkdir /tmp/zfs-mount-generator

$ /lib/systemd/system-generators/zfs-mount-generator /tmp/zfs-mount-generator

If the generated units are satisfactory, instruct systemd to re-run all generators: # systemctl daemon-reload

## SEE ALSO
systemd.mount(5), systemd.target(5), zfs(5), systemd.generator(7), systemd.special(7), zed(8), zpool-events(8)


zfs-program

package: zfs-utils

title: zfs-program(8)

summary: execute ZFS channel programs

text:
# zfs-program(8)

## NAME
zfs-program — execute ZFS channel programs

## SYNOPSIS
zfs

program [-jn] [-t instruction-limit] [-m memory-limit] pool script [script arguments]

## DESCRIPTION
The ZFS channel program interface allows ZFS administrative operations to be run programmatically as a Lua script. The entire script is executed atomically, with no other administrative operations taking effect concurrently. A library of ZFS calls is made available to channel program scripts. Channel programs may only be run with root privileges.

A modified version of the Lua 5.2 interpreter is used to run channel program scripts. The Lua 5.2 manual can be found at http://www.lua.org/manual/5.2/

The channel program given by script will be run on pool, and any attempts to access or modify other pools will cause an error.

## OPTIONS
-j, --json

Display channel program output in JSON format. When this flag is specified and standard output is empty - channel program encountered an error. The details of such an error will be printed to standard error in plain text.

-n

Executes a read-only channel program, which runs faster. The program cannot change on-disk state by calling functions from the zfs.sync submodule. The program can be used to gather information such as properties and determining if changes would succeed (zfs.check.*). Without this flag, all pending changes must be synced to disk before a channel program can complete.

-t instruction-limit

Limit the number of Lua instructions to execute. If a channel program executes more than the specified number of instructions, it will be stopped and an error will be returned. The default limit is 10 million instructions, and it can be set to a maximum of 100 million instructions.

-m memory-limit

Memory limit, in bytes. If a channel program attempts to allocate more memory than the given limit, it will be stopped and an error returned. The default memory limit is 10 MiB, and can be set to a maximum of 100 MiB.

All remaining argument strings will be passed directly to the Lua script as described in the LUA INTERFACE section below.

## LUA INTERFACE
A channel program can be invoked either from the command line, or via a library call to lzc_channel_program().

### Arguments
Arguments passed to the channel program are converted to a Lua table. If invoked from the command line, extra arguments to the Lua script will be accessible as an array stored in the argument table with the key 'argv':

```
args = ...
argv = args["argv"]
-- argv == {1="arg1", 2="arg2", ...}
```

If invoked from the libzfs interface, an arbitrary argument list can be passed to the channel program, which is accessible via the same "..." syntax in Lua:

```
args = ...
-- args == {"foo"="bar", "baz"={...}, ...}
```

Note that because Lua arrays are 1-indexed, arrays passed to Lua from the libzfs interface will have their indices incremented by 1. That is, the element in arr[0] in a C array passed to a channel program will be stored in arr[1] when accessed from Lua.

### Return Values
Lua return statements take the form:

return ret0, ret1, ret2, ...

Return statements returning multiple values are permitted internally in a channel program script, but attempting to return more than one value from the top level of the channel program is not permitted and will throw an error. However, tables containing multiple values can still be returned. If invoked from the command line, a return statement:

```
a = {foo="bar", baz=2}
return a
```

Will be output formatted as:

```
Channel program fully executed with return value:
    return:
        baz: 2
        foo: 'bar'
```

### Fatal Errors
If the channel program encounters a fatal error while running, a non-zero exit status will be returned. If more information about the error is available, a singleton list will be returned detailing the error:

error: "error string, including Lua stack trace"

If a fatal error is returned, the channel program may have not executed at all, may have partially executed, or may have fully executed but failed to pass a return value back to userland.

If the channel program exhausts an instruction or memory limit, a fatal error will be generated and the program will be stopped, leaving the program partially executed. No attempt is made to reverse or undo any operations already performed. Note that because both the instruction count and amount of memory used by a channel program are deterministic when run against the same inputs and filesystem state, as long as a channel program has run successfully once, you can guarantee that it will finish successfully against a similar size system.

If a channel program attempts to return too large a value, the program will fully execute but exit with a nonzero status code and no return value.

Note: ZFS API functions do not generate Fatal Errors when correctly invoked, they return an error code and the channel program continues executing. See the ZFS API section below for function-specific details on error return codes.

### Lua to C Value Conversion
When invoking a channel program via the libzfs interface, it is necessary to translate arguments and return values from Lua values to their C equivalents, and vice-versa.

There is a correspondence between nvlist values in C and Lua tables. A Lua table which is returned from the channel program will be recursively converted to an nvlist, with table values converted to their natural equivalents:

string

->

string

number

->

int64

boolean

->

boolean_value

nil

->

boolean (no value)

table

->

nvlist

Likewise, table keys are replaced by string equivalents as follows:

string

->

no change

number

->

signed decimal string ("%lld")

boolean

->

"true" | "false"

Any collision of table key strings (for example, the string "true" and a true boolean value) will cause a fatal error.

Lua numbers are represented internally as signed 64-bit integers.

## LUA STANDARD LIBRARY
The following Lua built-in base library functions are available:

assert

rawlen

collectgarbage

rawget

error

rawset

getmetatable

select

ipairs

setmetatable

next

tonumber

pairs

tostring

rawequal

type

All functions in the coroutine, string, and table built-in submodules are also available. A complete list and documentation of these modules is available in the Lua manual.

The following functions base library functions have been disabled and are not available for use in channel programs:

dofile

loadfile

load

pcall

print

xpcall

## ZFS API

### Function Arguments
Each API function takes a fixed set of required positional arguments and optional keyword arguments. For example, the destroy function takes a single positional string argument (the name of the dataset to destroy) and an optional "defer" keyword boolean argument. When using parentheses to specify the arguments to a Lua function, only positional arguments can be used:

zfs.sync.destroy("rpool@snap")

To use keyword arguments, functions must be called with a single argument that is a Lua table containing entries mapping integers to positional arguments and strings to keyword arguments:

zfs.sync.destroy({1="rpool@snap", defer=true})

The Lua language allows curly braces to be used in place of parenthesis as syntactic sugar for this calling convention:

zfs.sync.snapshot{"rpool@snap", defer=true}

### Function Return Values
If an API function succeeds, it returns 0. If it fails, it returns an error code and the channel program continues executing. API functions do not generate Fatal Errors except in the case of an unrecoverable internal file system error.

In addition to returning an error code, some functions also return extra details describing what caused the error. This extra description is given as a second return value, and will always be a Lua table, or Nil if no error details were returned. Different keys will exist in the error details table depending on the function and error case. Any such function may be called expecting a single return value:

errno = zfs.sync.promote(dataset)

Or, the error details can be retrieved:

```
errno, details = zfs.sync.promote(dataset)
if (errno == EEXIST) then
    assert(details ~= Nil)
    list_of_conflicting_snapshots = details
end
```

The following global aliases for API function error return codes are defined for use in channel programs:

EPERM

ECHILD

ENODEV

ENOSPC

ENOENT

EAGAIN

ENOTDIR

ESPIPE

ESRCH

ENOMEM

EISDIR

EROFS

EINTR

EACCES

EINVAL

EMLINK

EIO

EFAULT

ENFILE

EPIPE

ENXIO

ENOTBLK

EMFILE

EDOM

E2BIG

EBUSY

ENOTTY

ERANGE

ENOEXEC

EEXIST

ETXTBSY

EDQUOT

EBADF

EXDEV

EFBIG

### API Functions
For detailed descriptions of the exact behavior of any ZFS administrative operations, see the main zfs(8) manual page.

zfs.debug(msg)

Record a debug message in the zfs_dbgmsg log. A log of these messages can be printed via mdb's "::zfs_dbgmsg" command, or can be monitored live by running dtrace -n 'zfs-dbgmsg{trace(stringof(arg0))}'

msg (string)

Debug message to be printed.

zfs.exists(dataset)

Returns true if the given dataset exists, or false if it doesn't. A fatal error will be thrown if the dataset is not in the target pool. That is, in a channel program running on rpool, zfs.exists("rpool/nonexistent_fs") returns false, but zfs.exists("somepool/fs_that_may_exist") will error.

dataset (string)

Dataset to check for existence. Must be in the target pool.

zfs.get_prop(dataset, property)

Returns two values. First, a string, number or table containing the property value for the given dataset. Second, a string containing the source of the property (i.e. the name of the dataset in which it was set or nil if it is readonly). Throws a Lua error if the dataset is invalid or the property doesn't exist. Note that Lua only supports int64 number types whereas ZFS number properties are uint64. This means very large values (like GUIDs) may wrap around and appear negative.

dataset (string)

Filesystem or snapshot path to retrieve properties from.

property (string)

Name of property to retrieve. All filesystem, snapshot and volume properties are supported except for mounted and iscsioptions. Also supports the written@snap and written#bookmark properties and the ⟨user|group⟩⟨quota|used⟩@id properties, though the id must be in numeric form.

zfs.sync submodule

The sync submodule contains functions that modify the on-disk state. They are executed in "syncing context". The available sync submodule functions are as follows:

zfs.sync.clone(snapshot, newdataset)

Create a new filesystem from a snapshot. Returns 0 if the filesystem was successfully created, and a nonzero error code otherwise. Note: Due to general limitations in channel programs, a filesystem created this way will not be mounted, regardless of the value of the mountpoint and canmount properties. This limitation may be removed in the future, so it is recommended that you set mountpoint=none or canmount=off or noauto to avoid surprises.

snapshot (string)

Name of the source snapshot to clone.

newdataset (string)

Name of the target dataset to create.

zfs.sync.destroy(dataset, [defer=true|false])

Destroy the given dataset. Returns 0 on successful destroy, or a nonzero error code if the dataset could not be destroyed (for example, if the dataset has any active children or clones).

dataset (string)

Filesystem or snapshot to be destroyed.

[defer (boolean)]

Valid only for destroying snapshots. If set to true, and the snapshot has holds or clones, allows the snapshot to be marked for deferred deletion rather than failing.

zfs.sync.inherit(dataset, property)

Clears the specified property in the given dataset, causing it to be inherited from an ancestor, or restored to the default if no ancestor property is set. The zfs inherit -S option has not been implemented. Returns 0 on success, or a nonzero error code if the property could not be cleared.

dataset (string)

Filesystem or snapshot containing the property to clear.

property (string)

The property to clear. Allowed properties are the same as those for the zfs inherit command.

zfs.sync.promote(dataset)

Promote the given clone to a filesystem. Returns 0 on successful promotion, or a nonzero error code otherwise. If EEXIST is returned, the second return value will be an array of the clone's snapshots whose names collide with snapshots of the parent filesystem.

dataset (string)

Clone to be promoted.

zfs.sync.rollback(filesystem)

Rollback to the previous snapshot for a dataset. Returns 0 on successful rollback, or a nonzero error code otherwise. Rollbacks can be performed on filesystems or zvols, but not on snapshots or mounted datasets. EBUSY is returned in the case where the filesystem is mounted.

filesystem (string)

Filesystem to rollback.

zfs.sync.set_prop(dataset, property, value)

Sets the given property on a dataset. Currently only user properties are supported. Returns 0 if the property was set, or a nonzero error code otherwise.

dataset (string)

The dataset where the property will be set.

property (string)

The property to set.

value (string)

The value of the property to be set.

zfs.sync.snapshot(dataset)

Create a snapshot of a filesystem. Returns 0 if the snapshot was successfully created, and a nonzero error code otherwise. Note: Taking a snapshot will fail on any pool older than legacy version 27. To enable taking snapshots from ZCP scripts, the pool must be upgraded.

dataset (string)

Name of snapshot to create.

zfs.sync.rename_snapshot(dataset, oldsnapname, newsnapname)

Rename a snapshot of a filesystem or a volume. Returns 0 if the snapshot was successfully renamed, and a nonzero error code otherwise.

dataset (string)

Name of the snapshot's parent dataset.

oldsnapname (string)

Original name of the snapshot.

newsnapname (string)

New name of the snapshot.

zfs.sync.bookmark(source, newbookmark)

Create a bookmark of an existing source snapshot or bookmark. Returns 0 if the new bookmark was successfully created, and a nonzero error code otherwise. Note: Bookmarking requires the corresponding pool feature to be enabled.

source (string)

Full name of the existing snapshot or bookmark.

newbookmark (string)

Full name of the new bookmark.

zfs.check submodule

For each function in the zfs.sync submodule, there is a corresponding zfs.check function which performs a "dry run" of the same operation. Each takes the same arguments as its zfs.sync counterpart and returns 0 if the operation would succeed, or a non-zero error code if it would fail, along with any other error details. That is, each has the same behavior as the corresponding sync function except for actually executing the requested change. For example, zfs.check.destroy("fs") returns 0 if zfs.sync.destroy("fs") would successfully destroy the dataset. The available zfs.check functions are:

zfs.check.clone(snapshot, newdataset)

zfs.check.destroy(dataset, [defer=true|false])

zfs.check.promote(dataset)

zfs.check.rollback(filesystem)

zfs.check.set_property(dataset, property, value)

zfs.check.snapshot(dataset)

zfs.list submodule

The zfs.list submodule provides functions for iterating over datasets and properties. Rather than returning tables, these functions act as Lua iterators, and are generally used as follows:

```
for child in zfs.list.children("rpool") do
    ...
end
```

The available zfs.list functions are:

zfs.list.clones(snapshot)

Iterate through all clones of the given snapshot.

snapshot (string)

Must be a valid snapshot path in the current pool.

zfs.list.snapshots(dataset)

Iterate through all snapshots of the given dataset. Each snapshot is returned as a string containing the full dataset name, e.g. "pool/fs@snap".

dataset (string)

Must be a valid filesystem or volume.

zfs.list.children(dataset)

Iterate through all direct children of the given dataset. Each child is returned as a string containing the full dataset name, e.g. "pool/fs/child".

dataset (string)

Must be a valid filesystem or volume.

zfs.list.bookmarks(dataset)

Iterate through all bookmarks of the given dataset. Each bookmark is returned as a string containing the full dataset name, e.g. "pool/fs#bookmark".

dataset (string)

Must be a valid filesystem or volume.

zfs.list.holds(snapshot)

Iterate through all user holds on the given snapshot. Each hold is returned as a pair of the hold's tag and the timestamp (in seconds since the epoch) at which it was created.

snapshot (string)

Must be a valid snapshot.

zfs.list.properties(dataset)

An alias for zfs.list.user_properties (see relevant entry).

dataset (string)

Must be a valid filesystem, snapshot, or volume.

zfs.list.user_properties(dataset)

Iterate through all user properties for the given dataset. For each step of the iteration, output the property name, its value, and its source. Throws a Lua error if the dataset is invalid.

dataset (string)

Must be a valid filesystem, snapshot, or volume.

zfs.list.system_properties(dataset)

Returns an array of strings, the names of the valid system (non-user defined) properties for the given dataset. Throws a Lua error if the dataset is invalid.

dataset (string)

Must be a valid filesystem, snapshot or volume.

## EXAMPLES

### Example 1
The following channel program recursively destroys a filesystem and all its snapshots and children in a naive manner. Note that this does not involve any error handling or reporting.

```
function destroy_recursive(root)
    for child in zfs.list.children(root) do
        destroy_recursive(child)
    end
    for snap in zfs.list.snapshots(root) do
        zfs.sync.destroy(snap)
    end
    zfs.sync.destroy(root)
end
destroy_recursive("pool/somefs")
```

### Example 2
A more verbose and robust version of the same channel program, which properly detects and reports errors, and also takes the dataset to destroy as a command line argument, would be as follows:

```
succeeded = {}
failed = {}

function destroy_recursive(root)
    for child in zfs.list.children(root) do
        destroy_recursive(child)
    end
    for snap in zfs.list.snapshots(root) do
        err = zfs.sync.destroy(snap)
        if (err ~= 0) then
            failed[snap] = err
        else
            succeeded[snap] = err
        end
    end
    err = zfs.sync.destroy(root)
    if (err ~= 0) then
        failed[root] = err
    else
        succeeded[root] = err
    end
end

args = ...
argv = args["argv"]

destroy_recursive(argv[1])

results = {}
results["succeeded"] = succeeded
results["failed"] = failed
return results
```

### Example 3
The following function performs a forced promote operation by attempting to promote the given clone and destroying any conflicting snapshots.

```
function force_promote(ds)
   errno, details = zfs.check.promote(ds)
   if (errno == EEXIST) then
       assert(details ~= Nil)
       for i, snap in ipairs(details) do
           zfs.sync.destroy(ds .. "@" .. snap)
       end
   elseif (errno ~= 0) then
       return errno
   end
   return zfs.sync.promote(ds)
end
```


zfs-project

title: zfs-project(8)

summary: manage projects in ZFS filesystem

text:
# zfs-project(8)

## NAME
zfs-project — manage projects in ZFS filesystem

## SYNOPSIS
zfs

project [-d|-r] file|directory…

zfs

project -C [-kr] file|directory…

zfs

project -c [-0] [-d|-r] [-p id] file|directory…

zfs

project [-p id] [-rs] file|directory…

## DESCRIPTION
zfs project [-d|-r] file|directory…

List project identifier (ID) and inherit flag of files and directories. -d

Show the directory project ID and inherit flag, not its children.

-r

List subdirectories recursively.

zfs project -C [-kr] file|directory…

Clear project inherit flag and/or ID on the files and directories. -k

Keep the project ID unchanged. If not specified, the project ID will be reset to zero.

-r

Clear subdirectories' flags recursively.

zfs project -c [-0] [-d|-r] [-p id] file|directory…

Check project ID and inherit flag on the files and directories: report entries without the project inherit flag, or with project IDs different from the target directory's project ID or the one specified with -p. -0

Delimit filenames with a NUL byte instead of newline, don't output diagnoses.

-d

Check the directory project ID and inherit flag, not its children.

-p id

Compare to id instead of the target files and directories' project IDs.

-r

Check subdirectories recursively.

zfs project -p id [-rs] file|directory…

Set project ID and/or inherit flag on the files and directories. -p id

Set the project ID to the given value.

-r

Set on subdirectories recursively.

-s

Set project inherit flag on the given files and directories. This is usually used for setting up tree quotas with -r. In that case, the directory's project ID will be set for all its descendants, unless specified explicitly with -p.

## SEE ALSO
zfs-projectspace(8)


zfs-projectspace

title: zfs-projectspace(8)

summary: display space and quotas of ZFS dataset

text:
# zfs-projectspace(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-promote

title: zfs-promote(8)

text:
# zfs-promote(8)

## NAME
zfs-promote — promote clone dataset to no longer depend on origin snapshot

## SYNOPSIS
zfs

promote clone

## DESCRIPTION
The zfs promote command makes it possible to destroy the dataset that the clone was created from. The clone parent-child dependency relationship is reversed, so that the origin dataset becomes a clone of the specified dataset.

The snapshot that was cloned, and any snapshots previous to this snapshot, are now owned by the promoted clone. The space they use moves from the origin dataset to the promoted clone, so enough space must be available to accommodate these snapshots. No new space is consumed by this operation, but the space accounting is adjusted. The promoted clone must not have any conflicting snapshot names of its own. The zfs rename subcommand can be used to rename any conflicting snapshots.

## EXAMPLES

### Example 1: 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
```

## SEE ALSO
zfs-clone(8), zfs-rename(8)


zfs-receive

title: zfs-receive(8)

summary: create snapshot from backup stream

text:
# zfs-receive(8)

## NAME
zfs-receive — create snapshot from backup stream

## SYNOPSIS
zfs

receive [-FhMnsuv] [-o origin=snapshot] [-o property=value] [-x property] filesystem|volume|snapshot

zfs

receive [-FhMnsuv] [-d|-e] [-o origin=snapshot] [-o property=value] [-x property] filesystem

zfs

receive -A filesystem|volume

zfs

receive -c [-vn] filesystem|snapshot

## DESCRIPTION
zfs receive [-FhMnsuv] [-o origin=snapshot] [-o property=value] [-x property] filesystem|volume|snapshot

zfs receive [-FhMnsuv] [-d|-e] [-o origin=snapshot] [-o property=value] [-x property] filesystem

Creates a snapshot whose contents are as specified in the stream provided on standard input. If a full stream is received, then a new file system is created as well. Streams are created using the zfs send subcommand, which by default creates a full stream. zfs recv can be used as an alias for zfs receive. If an incremental stream is received, then the destination file system must already exist, and its most recent snapshot must match the incremental stream's source. For zvols, the destination device link is destroyed and recreated, which means the zvol cannot be accessed during the receive operation.

When a snapshot replication package stream that is generated by using the zfs send -R command is received, any snapshots that do not exist on the sending location are destroyed by using the zfs destroy -d command.

The ability to send and receive deduplicated send streams has been removed. However, a deduplicated send stream created with older software can be converted to a regular (non-deduplicated) stream by using the zstream redup command.

If -o property=value or -x property is specified, it applies to the effective value of the property throughout the entire subtree of replicated datasets. Effective property values will be set (-o) or inherited (-x) on the topmost in the replicated subtree. In descendant datasets, if the property is set by the send stream, it will be overridden by forcing the property to be inherited from the top‐most file system. Received properties are retained in spite of being overridden and may be restored with zfs inherit -S. Specifying -o origin=snapshot is a special case because, even if origin is a read-only property and cannot be set, it's allowed to receive the send stream as a clone of the given snapshot.

Raw encrypted send streams (created with zfs send -w) may only be received as is, and cannot be re-encrypted, decrypted, or recompressed by the receive process. Unencrypted streams can be received as encrypted datasets, either through inheritance or by specifying encryption parameters with the -o options. Note that the keylocation property cannot be overridden to prompt during a receive. This is because the receive process itself is already using the standard input for the send stream. Instead, the property can be overridden after the receive completes.

The added security provided by raw sends adds some restrictions to the send and receive process. ZFS will not allow a mix of raw receives and non-raw receives. Specifically, any raw incremental receives that are attempted after a non-raw receive will fail. Non-raw receives do not have this restriction and, therefore, are always possible. Because of this, it is best practice to always use either raw sends for their security benefits or non-raw sends for their flexibility when working with encrypted datasets, but not a combination.

The reason for this restriction stems from the inherent restrictions of the AEAD ciphers that ZFS uses to encrypt data. When using ZFS native encryption, each block of data is encrypted against a randomly generated number known as the "initialization vector" (IV), which is stored in the filesystem metadata. This number is required by the encryption algorithms whenever the data is to be decrypted. Together, all of the IVs provided for all of the blocks in a given snapshot are collectively called an "IV set". When ZFS performs a raw send, the IV set is transferred from the source to the destination in the send stream. When ZFS performs a non-raw send, the data is decrypted by the source system and re-encrypted by the destination system, creating a snapshot with effectively the same data, but a different IV set. In order for decryption to work after a raw send, ZFS must ensure that the IV set used on both the source and destination side match. When an incremental raw receive is performed on top of an existing snapshot, ZFS will check to confirm that the "from" snapshot on both the source and destination were using the same IV set, ensuring the new IV set is consistent.

The name of the snapshot (and file system, if a full stream is received) that this subcommand creates depends on the argument type and the use of the -d or -e options.

If the argument is a snapshot name, the specified snapshot is created. If the argument is a file system or volume name, a snapshot with the same name as the sent snapshot is created within the specified filesystem or volume. If neither of the -d or -e options are specified, the provided target snapshot name is used exactly as provided.

The -d and -e options cause the file system name of the target snapshot to be determined by appending a portion of the sent snapshot's name to the specified target filesystem. If the -d option is specified, all but the first element of the sent snapshot's file system path (usually the pool name) is used and any required intermediate file systems within the specified one are created. If the -e option is specified, then only the last element of the sent snapshot's file system name (i.e. the name of the source file system itself) is used as the target file system name.

-F

Force a rollback of the file system to the most recent snapshot before performing the receive operation. If receiving an incremental replication stream (for example, one generated by zfs send -R [-i|-I]), destroy snapshots and file systems that do not exist on the sending side.

-d

Discard the first element of the sent snapshot's file system name, using the remaining elements to determine the name of the target file system for the new snapshot as described in the paragraph above.

-e

Discard all but the last element of the sent snapshot's file system name, using that element to determine the name of the target file system for the new snapshot as described in the paragraph above.

-h

Skip the receive of holds. There is no effect if holds are not sent.

-M

Force an unmount of the file system while receiving a snapshot. This option is not supported on Linux.

-n

Do not actually receive the stream. This can be useful in conjunction with the -v option to verify the name the receive operation would use.

-o origin=snapshot

Forces the stream to be received as a clone of the given snapshot. If the stream is a full send stream, this will create the filesystem described by the stream as a clone of the specified snapshot. Which snapshot was specified will not affect the success or failure of the receive, as long as the snapshot does exist. If the stream is an incremental send stream, all the normal verification will be performed.

-o property=value

Sets the specified property as if the command zfs set property=value was invoked immediately before the receive. When receiving a stream from zfs send -R, causes the property to be inherited by all descendant datasets, as through zfs inherit property was run on any descendant datasets that have this property set on the sending system. If the send stream was sent with -c then overriding the compression property will have no effect on received data but the compression property will be set. To have the data recompressed on receive remove the -c flag from the send stream.

Any editable property can be set at receive time. Set-once properties bound to the received data, such as normalization and casesensitivity, cannot be set at receive time even when the datasets are newly created by zfs receive. Additionally both settable properties version and volsize cannot be set at receive time.

The -o option may be specified multiple times, for different properties. An error results if the same property is specified in multiple -o or -x options.

The -o option may also be used to override encryption properties upon initial receive. This allows unencrypted streams to be received as encrypted datasets. To cause the received dataset (or root dataset of a recursive stream) to be received as an encryption root, specify encryption properties in the same manner as is required for zfs create. For instance:

\# zfs send tank/test@snap1 | zfs recv -o encryption=on -o keyformat=passphrase -o keylocation=file:///path/to/keyfile

Note that -o keylocation=prompt may not be specified here, since the standard input is already being utilized for the send stream. Once the receive has completed, you can use zfs set to change this setting after the fact. Similarly, you can receive a dataset as an encrypted child by specifying -x encryption to force the property to be inherited. Overriding encryption properties (except for keylocation) is not possible with raw send streams.

-s

If the receive is interrupted, save the partially received state, rather than deleting it. Interruption may be due to premature termination of the stream (e.g. due to network failure or failure of the remote system if the stream is being read over a network connection), a checksum error in the stream, termination of the zfs receive process, or unclean shutdown of the system. The receive can be resumed with a stream generated by zfs send -t token, where the token is the value of the receive_resume_token property of the filesystem or volume which is received into.

To use this flag, the storage pool must have the extensible_dataset feature enabled. See zpool-features(7) for details on ZFS feature flags.

-u

File system that is associated with the received stream is not mounted.

-v

Print verbose information about the stream and the time required to perform the receive operation.

-x property

Ensures that the effective value of the specified property after the receive is unaffected by the value of that property in the send stream (if any), as if the property had been excluded from the send stream. If the specified property is not present in the send stream, this option does nothing.

If a received property needs to be overridden, the effective value will be set or inherited, depending on whether the property is inheritable or not.

In the case of an incremental update, -x leaves any existing local setting or explicit inheritance unchanged.

All -o restrictions (e.g. set-once) apply equally to -x.

zfs receive -A filesystem|volume

Abort an interrupted zfs receive -s, deleting its saved partially received state.

zfs receive -c [-vn] filesystem|snapshot

Attempt to repair data corruption in the specified dataset, by using the provided stream as the source of healthy data. This method of healing can only heal data blocks present in the stream. Metadata can not be healed by corrective receive. Running a scrub is recommended post-healing to ensure all data corruption was repaired. It's important to consider why corruption has happened in the first place. If you have slowly failing hardware - periodically repairing the data is not going to save you from data loss later on when the hardware fails completely.

## 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-send(8), zstream(8)


zfs-recv

title: zfs-recv(8)

summary: create snapshot from backup stream

text:
# zfs-recv(8)

## NAME
zfs-receive — create snapshot from backup stream

## SYNOPSIS
zfs

receive [-FhMnsuv] [-o origin=snapshot] [-o property=value] [-x property] filesystem|volume|snapshot

zfs

receive [-FhMnsuv] [-d|-e] [-o origin=snapshot] [-o property=value] [-x property] filesystem

zfs

receive -A filesystem|volume

zfs

receive -c [-vn] filesystem|snapshot

## DESCRIPTION
zfs receive [-FhMnsuv] [-o origin=snapshot] [-o property=value] [-x property] filesystem|volume|snapshot

zfs receive [-FhMnsuv] [-d|-e] [-o origin=snapshot] [-o property=value] [-x property] filesystem

Creates a snapshot whose contents are as specified in the stream provided on standard input. If a full stream is received, then a new file system is created as well. Streams are created using the zfs send subcommand, which by default creates a full stream. zfs recv can be used as an alias for zfs receive. If an incremental stream is received, then the destination file system must already exist, and its most recent snapshot must match the incremental stream's source. For zvols, the destination device link is destroyed and recreated, which means the zvol cannot be accessed during the receive operation.

When a snapshot replication package stream that is generated by using the zfs send -R command is received, any snapshots that do not exist on the sending location are destroyed by using the zfs destroy -d command.

The ability to send and receive deduplicated send streams has been removed. However, a deduplicated send stream created with older software can be converted to a regular (non-deduplicated) stream by using the zstream redup command.

If -o property=value or -x property is specified, it applies to the effective value of the property throughout the entire subtree of replicated datasets. Effective property values will be set (-o) or inherited (-x) on the topmost in the replicated subtree. In descendant datasets, if the property is set by the send stream, it will be overridden by forcing the property to be inherited from the top‐most file system. Received properties are retained in spite of being overridden and may be restored with zfs inherit -S. Specifying -o origin=snapshot is a special case because, even if origin is a read-only property and cannot be set, it's allowed to receive the send stream as a clone of the given snapshot.

Raw encrypted send streams (created with zfs send -w) may only be received as is, and cannot be re-encrypted, decrypted, or recompressed by the receive process. Unencrypted streams can be received as encrypted datasets, either through inheritance or by specifying encryption parameters with the -o options. Note that the keylocation property cannot be overridden to prompt during a receive. This is because the receive process itself is already using the standard input for the send stream. Instead, the property can be overridden after the receive completes.

The added security provided by raw sends adds some restrictions to the send and receive process. ZFS will not allow a mix of raw receives and non-raw receives. Specifically, any raw incremental receives that are attempted after a non-raw receive will fail. Non-raw receives do not have this restriction and, therefore, are always possible. Because of this, it is best practice to always use either raw sends for their security benefits or non-raw sends for their flexibility when working with encrypted datasets, but not a combination.

The reason for this restriction stems from the inherent restrictions of the AEAD ciphers that ZFS uses to encrypt data. When using ZFS native encryption, each block of data is encrypted against a randomly generated number known as the "initialization vector" (IV), which is stored in the filesystem metadata. This number is required by the encryption algorithms whenever the data is to be decrypted. Together, all of the IVs provided for all of the blocks in a given snapshot are collectively called an "IV set". When ZFS performs a raw send, the IV set is transferred from the source to the destination in the send stream. When ZFS performs a non-raw send, the data is decrypted by the source system and re-encrypted by the destination system, creating a snapshot with effectively the same data, but a different IV set. In order for decryption to work after a raw send, ZFS must ensure that the IV set used on both the source and destination side match. When an incremental raw receive is performed on top of an existing snapshot, ZFS will check to confirm that the "from" snapshot on both the source and destination were using the same IV set, ensuring the new IV set is consistent.

The name of the snapshot (and file system, if a full stream is received) that this subcommand creates depends on the argument type and the use of the -d or -e options.

If the argument is a snapshot name, the specified snapshot is created. If the argument is a file system or volume name, a snapshot with the same name as the sent snapshot is created within the specified filesystem or volume. If neither of the -d or -e options are specified, the provided target snapshot name is used exactly as provided.

The -d and -e options cause the file system name of the target snapshot to be determined by appending a portion of the sent snapshot's name to the specified target filesystem. If the -d option is specified, all but the first element of the sent snapshot's file system path (usually the pool name) is used and any required intermediate file systems within the specified one are created. If the -e option is specified, then only the last element of the sent snapshot's file system name (i.e. the name of the source file system itself) is used as the target file system name.

-F

Force a rollback of the file system to the most recent snapshot before performing the receive operation. If receiving an incremental replication stream (for example, one generated by zfs send -R [-i|-I]), destroy snapshots and file systems that do not exist on the sending side.

-d

Discard the first element of the sent snapshot's file system name, using the remaining elements to determine the name of the target file system for the new snapshot as described in the paragraph above.

-e

Discard all but the last element of the sent snapshot's file system name, using that element to determine the name of the target file system for the new snapshot as described in the paragraph above.

-h

Skip the receive of holds. There is no effect if holds are not sent.

-M

Force an unmount of the file system while receiving a snapshot. This option is not supported on Linux.

-n

Do not actually receive the stream. This can be useful in conjunction with the -v option to verify the name the receive operation would use.

-o origin=snapshot

Forces the stream to be received as a clone of the given snapshot. If the stream is a full send stream, this will create the filesystem described by the stream as a clone of the specified snapshot. Which snapshot was specified will not affect the success or failure of the receive, as long as the snapshot does exist. If the stream is an incremental send stream, all the normal verification will be performed.

-o property=value

Sets the specified property as if the command zfs set property=value was invoked immediately before the receive. When receiving a stream from zfs send -R, causes the property to be inherited by all descendant datasets, as through zfs inherit property was run on any descendant datasets that have this property set on the sending system. If the send stream was sent with -c then overriding the compression property will have no effect on received data but the compression property will be set. To have the data recompressed on receive remove the -c flag from the send stream.

Any editable property can be set at receive time. Set-once properties bound to the received data, such as normalization and casesensitivity, cannot be set at receive time even when the datasets are newly created by zfs receive. Additionally both settable properties version and volsize cannot be set at receive time.

The -o option may be specified multiple times, for different properties. An error results if the same property is specified in multiple -o or -x options.

The -o option may also be used to override encryption properties upon initial receive. This allows unencrypted streams to be received as encrypted datasets. To cause the received dataset (or root dataset of a recursive stream) to be received as an encryption root, specify encryption properties in the same manner as is required for zfs create. For instance:

\# zfs send tank/test@snap1 | zfs recv -o encryption=on -o keyformat=passphrase -o keylocation=file:///path/to/keyfile

Note that -o keylocation=prompt may not be specified here, since the standard input is already being utilized for the send stream. Once the receive has completed, you can use zfs set to change this setting after the fact. Similarly, you can receive a dataset as an encrypted child by specifying -x encryption to force the property to be inherited. Overriding encryption properties (except for keylocation) is not possible with raw send streams.

-s

If the receive is interrupted, save the partially received state, rather than deleting it. Interruption may be due to premature termination of the stream (e.g. due to network failure or failure of the remote system if the stream is being read over a network connection), a checksum error in the stream, termination of the zfs receive process, or unclean shutdown of the system. The receive can be resumed with a stream generated by zfs send -t token, where the token is the value of the receive_resume_token property of the filesystem or volume which is received into.

To use this flag, the storage pool must have the extensible_dataset feature enabled. See zpool-features(7) for details on ZFS feature flags.

-u

File system that is associated with the received stream is not mounted.

-v

Print verbose information about the stream and the time required to perform the receive operation.

-x property

Ensures that the effective value of the specified property after the receive is unaffected by the value of that property in the send stream (if any), as if the property had been excluded from the send stream. If the specified property is not present in the send stream, this option does nothing.

If a received property needs to be overridden, the effective value will be set or inherited, depending on whether the property is inheritable or not.

In the case of an incremental update, -x leaves any existing local setting or explicit inheritance unchanged.

All -o restrictions (e.g. set-once) apply equally to -x.

zfs receive -A filesystem|volume

Abort an interrupted zfs receive -s, deleting its saved partially received state.

zfs receive -c [-vn] filesystem|snapshot

Attempt to repair data corruption in the specified dataset, by using the provided stream as the source of healthy data. This method of healing can only heal data blocks present in the stream. Metadata can not be healed by corrective receive. Running a scrub is recommended post-healing to ensure all data corruption was repaired. It's important to consider why corruption has happened in the first place. If you have slowly failing hardware - periodically repairing the data is not going to save you from data loss later on when the hardware fails completely.

## 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-send(8), zstream(8)


zfs-redact

title: zfs-redact(8)

summary: generate backup stream of ZFS dataset

text:
# zfs-redact(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-release

title: zfs-release(8)

text:
# zfs-release(8)

## NAME
zfs-hold — hold ZFS snapshots to prevent their removal

## SYNOPSIS
zfs

hold [-r] tag snapshot…

zfs

holds [-rHp] snapshot…

zfs

release [-r] tag snapshot…

## DESCRIPTION
zfs hold [-r] tag snapshot…

Adds a single reference, named with the tag argument, to the specified snapshots. Each snapshot has its own tag namespace, and tags must be unique within that space. If a hold exists on a snapshot, attempts to destroy that snapshot by using the zfs destroy command return EBUSY.

-r

Specifies that a hold with the given tag is applied recursively to the snapshots of all descendent file systems.

zfs holds [-rHp] snapshot…

Lists all existing user references for the given snapshot or snapshots. -r

Lists the holds that are set on the named descendent snapshots, in addition to listing the holds on the named snapshot.

-H

Do not print headers, use tab-delimited output.

-p

Prints holds timestamps as Unix epoch timestamps.

zfs release [-r] tag snapshot…

Removes a single reference, named with the tag argument, from the specified snapshot or snapshots. The tag must already exist for each snapshot. If a hold exists on a snapshot, attempts to destroy that snapshot by using the zfs destroy command return EBUSY. -r

Recursively releases a hold with the given tag on the snapshots of all descendent file systems.

## SEE ALSO
zfs-destroy(8)


zfs-rename

title: zfs-rename(8)

summary: rename ZFS dataset

text:
# zfs-rename(8)

## NAME
zfs-rename — rename ZFS dataset

## SYNOPSIS
zfs

rename [-f] filesystem|volume|snapshot filesystem|volume|snapshot

zfs

rename -p [-f] filesystem|volume filesystem|volume

zfs

rename -u [-f] filesystem filesystem

zfs

rename -r snapshot snapshot

## DESCRIPTION
zfs rename [-f] filesystem|volume|snapshot filesystem|volume|snapshot

zfs rename -p [-f] filesystem|volume filesystem|volume

zfs rename -u [-f] filesystem filesystem

Renames the given dataset. The new target can be located anywhere in the ZFS hierarchy, with the exception of snapshots. Snapshots can only be renamed within the parent file system or volume. When renaming a snapshot, the parent file system of the snapshot does not need to be specified as part of the second argument. Renamed file systems can inherit new mount points, in which case they are unmounted and remounted at the new mount point. -f

Force unmount any file systems that need to be unmounted in the process. This flag has no effect if used together with the -u flag.

-p

Creates all the nonexistent parent datasets. Datasets created in this manner are automatically mounted according to the mountpoint property inherited from their parent.

-u

Do not remount file systems during rename. If a file system's mountpoint property is set to legacy or none, the file system is not unmounted even if this option is not given.

zfs rename -r snapshot snapshot

Recursively rename the snapshots of all descendent datasets. Snapshots are the only dataset that can be renamed recursively.

## EXAMPLES

### Example 1: 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 2: 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
```


zfs-rewrite

title: zfs-rewrite(8)

text:
# zfs-rewrite(8)

## NAME
zfs-rewrite — rewrite specified files without modification

## SYNOPSIS
zfs

rewrite [-Prvx] [-l length] [-o offset] file|directory…

## DESCRIPTION
Rewrite blocks of specified file as is without modification at a new location and possibly with new properties, as if they were atomically read and written back. See NOTES. for more information about property changes that may be applied during rewrite.

-P

Perform physical rewrite, preserving logical birth time of blocks. By default, rewrite updates logical birth times, making blocks appear as modified in snapshots and incremental send streams. Physical rewrite preserves logical birth times, avoiding unnecessary inclusion in incremental streams. Physical rewrite requires the physical_rewrite feature to be enabled on the pool.

-l length

Rewrite at most this number of bytes.

-o offset

Start at this offset in bytes.

-r

Recurse into directories.

-v

Print names of all successfully rewritten files.

-x

Don't cross file system mount points when recursing.

## NOTES
Rewrite works by replacing an existing block with a new block of the same logical size. Changed dataset properties that operate on the data or metadata without changing the logical size will be applied. These include checksum, compression, dedup and copies. Changes to properties that affect the size of a logical block, like recordsize, will have no effect.

Rewrite of cloned blocks and blocks that are part of any snapshots, same as some property changes may increase pool space usage. Holes that were never written or were previously zero-compressed are not rewritten and will remain holes even if compression is disabled.

If a -l or -o value request a rewrite to regions past the end of the file, then those regions are silently ignored, and no error is reported.

By default, rewritten blocks update their logical birth time, meaning they will be included in incremental zfs send streams as modified data. When the -P flag is used, rewritten blocks preserve their logical birth time, since there are no user data changes.

## SEE ALSO
zfsprops(7), zpool-features(7)


zfs-rollback

title: zfs-rollback(8)

summary: roll ZFS dataset back to snapshot

text:
# zfs-rollback(8)

## NAME
zfs-rollback — roll ZFS dataset back to snapshot

## SYNOPSIS
zfs

rollback [-Rfr] snapshot

## DESCRIPTION
When a dataset is rolled back, all data that has changed since the snapshot is discarded, and the dataset reverts to the state at the time of the snapshot. By default, the command refuses to roll back to a snapshot other than the most recent one. In order to do so, all intermediate snapshots and bookmarks must be destroyed by specifying the -r option.

The -rR options do not recursively destroy the child snapshots of a recursive snapshot. Only direct snapshots of the specified filesystem are destroyed by either of these options. To completely roll back a recursive snapshot, you must roll back the individual child snapshots.

-R

Destroy any more recent snapshots and bookmarks, as well as any clones of those snapshots.

-f

Used with the -R option to force an unmount of any clone file systems that are to be destroyed.

-r

Destroy any snapshots and bookmarks more recent than the one specified.

## EXAMPLES

### Example 1: Rolling Back a ZFS File System
The following command reverts the contents of pool/home/anne to the snapshot named yesterday, deleting all intermediate snapshots:

\# zfs rollback -r pool/home/anne@yesterday

## SEE ALSO
zfs-snapshot(8)