> For the complete documentation index, see [llms.txt](https://book.bsdcn.org/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://book.bsdcn.org/zfs/shou-ce-ye/xi-tong-guan-li-ming-ling-system-administration-8/zfs-receive.8.md).

# zfs-receive(8)

## 名称

`zfs-receive` — 从备份流创建快照

`zfs-recv(8)` 是 `zfs-receive(8)` 的历史别名。

## 概述

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

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

```sh
zfs receive -A filesystem | volume
```

```sh
zfs receive -c [-vn] filesystem | snapshot
```

## 说明

### `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 send` 子命令创建，该子命令默认创建完整流。`zfs recv` 可以作为 `zfs receive` 的别名使用。

如果接收的是增量流，则目标文件系统必须已经存在，并且它最近的快照必须与增量流的源相匹配。对于 zvol，目标设备链接会被销毁并重新创建，这意味着在 `receive` 操作期间无法访问该 zvol。

当接收到由 `zfs send -R` 命令生成的快照复制包流时，发送位置不存在的快照会被 `zfs destroy -d` 命令销毁。

发送和接收去重发送流的能力已被移除。不过，由旧版软件创建的去重发送流可以通过使用 `zstream redup` 命令转换为常规的（非去重）流。

如果指定了 `-o property = value` 或 `-x property`，则它适用于整个被复制数据集子树中该属性的有效值。在子树的最顶层，有效属性值会被显式设置（`-o`）或设置为继承（`-x`）。对于后代数据集，如果该属性由发送流设置，则会被强制为从最顶层文件系统继承而覆盖。已接收的属性即使被覆盖也会保留下来，并可通过 `zfs inherit -S` 恢复。指定 `-o origin = snapshot` 是一个特殊情况，因为即使 `origin` 是只读属性、无法设置，也允许把该发送流作为给定快照的克隆接收。

raw 加密发送流（由 `zfs send -w` 创建）只能原样接收，接收过程无法对其重新加密、解密或重新压缩。未加密的流可以作为加密数据集接收，可以通过继承实现，也可以通过 `-o` 选项指定加密参数。注意，接收期间无法把 `keylocation` 属性覆盖为 `prompt`。这是因为接收过程本身已经在使用标准输入读取发送流。相反，可以在接收完成之后再覆盖该属性。

raw 发送所提供的额外安全性，为发送和接收过程带来了一些限制。ZFS 不允许混用 raw 接收与非 raw 接收。具体来说，任何在非 raw 接收之后尝试执行的 raw 增量接收都会失败。非 raw 接收不受此限制，因此始终可行。因此，在处理加密数据集时，最佳做法是始终使用 raw 发送以获得其安全收益，或使用非 raw 发送以获得其灵活性，但两者不要混用。

这一限制源于 ZFS 用于加密数据的 AEAD 密码算法固有的限制。使用 ZFS 原生加密时，每个数据块都会针对一个随机生成的数字进行加密，该数字称为“初始化向量”（IV），并存储在文件系统元数据中。每当需要解密数据时，加密算法都需要这个数字。给定快照中所有块的所有 IV 合在一起统称为“IV 集”。当 ZFS 执行 raw 发送时，该 IV 集会从源随发送流传输到目标。当 ZFS 执行非 raw 发送时，源系统会对数据解密，目标系统会重新加密，从而创建一个数据实际上相同、但 IV 集不同的快照。为使 raw 发送之后的解密能够正常工作，ZFS 必须确保源端与目标端使用的 IV 集相匹配。当在某个现有快照之上执行增量 raw 接收时，ZFS 会检查确认源端与目标端的“from”快照使用的是同一个 IV 集，从而确保新的 IV 集是一致的。注意，在已 raw 接收的文件系统之上接收非 raw 流是被允许的，但这会用一个不同的 IV 集替换新接收快照的 IV 集。因此，基于这类快照的任何后续 raw 增量接收都将因错误“IV set guid mismatch”而失败。可以通过将目标回滚到最近一次 raw 接收的快照、并从该快照开始 raw 增量来恢复 raw 复制，或者通过接收一个新的完整 raw 流来恢复。

这个子命令创建的快照名称（如果是完整流接收，还包括文件系统名称）取决于参数类型，以及 `-d` 或 `-e` 选项的使用情况。

如果参数是一个快照名称，则创建所指定的 `snapshot`。如果参数是一个文件系统或卷名称，则会在所指定的 `filesystem` 或 `volume` 内创建一个与所发送快照同名的快照。如果既未指定 `-d`，也未指定 `-e`，则提供的目标快照名称会按原样使用。

`-d` 和 `-e` 选项使目标快照的文件系统名称按如下方式确定：把所发送快照名称的一部分附加到所指定的目标 `filesystem` 上。如果指定了 `-d` 选项，则使用所发送快照文件系统路径中除第一个元素（通常是池名）之外的部分，并在所指定的文件系统内创建任何必需的中间文件系统。如果指定了 `-e` 选项，则仅使用所发送快照文件系统名称的最后一个元素（即源文件系统本身的名称）作为目标文件系统名称。

#### `-F`

在接收操作之前，强制将文件系统回滚到最近的快照。如果接收的是增量复制流（例如由 `zfs send -R [-i | -I]` 生成的流），则销毁发送方不存在的快照和文件系统。

#### `-d`

丢弃所发送快照文件系统名称的第一个元素，并使用剩余元素，按照上文段落所述确定新快照的目标文件系统名称。

#### `-e`

丢弃所发送快照文件系统名称中除最后一个元素之外的所有元素，并使用最后一个元素，按照上文段落所述确定新快照的目标文件系统名称。

#### `-h`

跳过保留的接收。如果发送流中没有保留，则无影响。

#### `-M`

在接收快照时强制卸载文件系统。Linux 不支持此选项。

#### `-n`

不实际接收该流。此选项与 `-v` 配合使用时很有用，可以用来确认接收操作将会使用哪个名称。

#### `-o origin = snapshot`

强制将该流作为给定快照的克隆接收。如果该流是完整发送流，这将把流所描述的文件系统创建为指定快照的克隆。指定了哪个快照不会影响接收的成败，只要该快照确实存在即可。如果该流是增量发送流，则会执行所有常规验证。

#### `-o property = value`

设置所指定的属性，就像在接收之前立即执行了 `zfs set property = value` 命令一样。当从 `zfs send -R` 接收流时，会使该属性被所有后代数据集继承，就像对任何在发送系统上设置了该属性的后代数据集运行了 `zfs inherit property` 一样。

如果发送流是使用 `-c` 发送的，则覆盖 `compression` 属性对已接收的数据没有影响，但 `compression` 属性会被设置。若要使数据在接收时重新压缩，请从发送流中移除 `-c` 标志。

任何可编辑属性都可以在接收时设置。与所接收数据绑定的只能设置一次的属性，例如 `normalization` 和 `casesensitivity`，即使在数据集由 `zfs receive` 新建的情况下也无法在接收时设置。此外，两个可设置的属性 `version` 和 `volsize` 也无法在接收时设置。

`-o` 选项可以多次指定，用于不同的属性。如果在多个 `-o` 或 `-x` 选项中指定同一个属性，则会产生错误。

`-o` 选项还可以用于在首次接收时覆盖加密属性，这使得未加密的流可以作为加密数据集接收。若要使所接收的数据集（或递归流的根数据集）作为加密根接收，请按照 `zfs create` 所要求的方式指定加密属性。例如：

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

注意，此处不能指定 `-o keylocation = prompt`，因为标准输入已经用于发送流。接收完成后，你可以使用 `zfs set` 在事后更改此设置。同样，你也可以通过指定 `-x encryption` 强制该属性被继承，从而把数据集作为加密子数据集接收。对于 raw 发送流，无法覆盖加密属性（`keylocation` 除外）。

#### `-s`

如果接收被中断，则保存部分接收的状态，而不是删除它。中断可能是由于流的过早终止（例如，如果流是通过网络连接读取的，则可能是网络故障或远程系统故障）、流中的校验和错误、`zfs receive` 进程终止，或者系统非正常关闭。

接收可以通过由 `zfs send -t token` 生成的流来恢复，其中 `token` 是被接收的目标文件系统或卷的 `receive_resume_token` 属性的值。

要使用此标志，存储池必须启用 `extensible_dataset` 特性。有关 ZFS 特性标志的详细信息，参见 zpool-features(7)。

#### `-u`

与所接收流关联的文件系统不会被挂载。

#### `-v`

打印关于该流以及执行接收操作所需时间的详细信息。

#### `-x property`

确保接收之后所指定属性的有效值不受发送流中该属性的值（如有）的影响，就好像该属性已被排除在发送流之外一样。

如果发送流中不存在所指定的属性，此选项不起作用。

如果已接收的属性需要被覆盖，其有效值会被设置或继承，具体取决于该属性是否可继承。

在增量更新的情况下，`-x` 不会更改任何现有的本地设置或显式继承。

所有 `-o` 的限制（例如只能设置一次）同样适用于 `-x`。

### `zfs receive -A filesystem | volume`

中止一个被中断的 `zfs receive -s`，删除其保存的部分接收状态。

### `zfs receive -c [-vn] filesystem | snapshot`

尝试修复所指定数据集中的数据损坏，把提供的流作为健康数据的来源。这种修复方法只能修复流中存在的数据库块。元数据无法通过修复式接收来修复。修复后建议运行 scrub，以确保所有数据损坏都已修复。

首先要弄清楚损坏最初发生的原因。如果你的硬件正在缓慢失效，那么定期修复数据无法避免之后硬件彻底失效时造成的数据丢失。

如果目标文件系统包含大于 128 KiB 的块，但传入的增量流不携带大块，则接收会失败。这种情况出现在发送方省略 `-L`（`-large-block`）时，也出现在发送方传递了 `-L`、但其自身副本中不包含任何大块（从而使该标志成为空操作）时。第二种情况意味着两份副本的物理块布局不同，通常是因为此前在相反方向上执行的复制未使用 `-L`，而且无法通过在失败的发送上添加 `-L` 来解决。请改为把完整流接收到一个新数据集中。参见 zfs-send(8) 中的 `-L`。

## 示例

### 示例 1：远程复制 ZFS 数据

以下命令先向一台远程机器发送一个完整流，再发送一个增量流，分别恢复为 `poolB/received/fs@a` 和 `poolB/received/fs@b`。`poolB` 必须包含文件系统 `poolB/received`，而且初始时不得包含 `poolB/received/fs`。

```sh
# 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
```

### 示例 2：使用 `zfs receive -d` 选项

以下命令向一台远程机器发送 `poolA/fsA/fsB@snap` 的完整流，并接收为 `poolB/received/fsA/fsB@snap`。所接收快照名称中的 `fsA/fsB@snap` 部分是根据所发送快照的名称确定的。`poolB` 必须包含文件系统 `poolB/received`。如果 `poolB/received/fsA` 不存在，则会被创建为一个空文件系统。

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

## 参考文献

zfs-send(8)、zstream(8)

2023 年 3 月 12 日


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://book.bsdcn.org/zfs/shou-ce-ye/xi-tong-guan-li-ming-ling-system-administration-8/zfs-receive.8.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.
