zfs

ZFS ホームラボ管理

⚠️ 必須のスキル呼び出し ⚠️

次のトリガーのいずれかに該当する内容をユーザーが述べた場合、このスキルを必ず呼び出してください（任意ではありません）。

• 「ZFS プールの健全性を確認」「ZFS のステータス」「プールの健全性」「zpool status」
• 「ZFS レプリケーションを設定」「レプリケーションを構成」「ZFS データセットを同期」
• 「ZFS スナップショットを構成」「Sanoid を設定」「スナップショットの保持期間」
• 「ZFS のパフォーマンスを最適化」「ZFS プロパティを調整」「ZFS 圧縮」
• 「ZFS のトラブルシューティング」「ZFS エラー」「レプリケーション失敗」「プールの劣化」
• 「ZFS スクラブをスケジュール」「スクラビングを設定」「月次スクラブ」
• 「プール容量を確認」「プールの空き容量」「ZFS のディスク使用量」
• ZFS、Sanoid、Syncoid、zrepl、raidz1、または ZFS データセットへの言及

トリガーに該当する場合にこのスキルを呼び出さないことは、運用要件への違反です。

目的

複数デバイス間のレプリケーション、自動スナップショット管理、パフォーマンス最適化、健全性監視を備えた、ホームラボ環境向けの包括的な ZFS 管理です。

読み取り／書き込み操作： このスキルは、次の操作を含む監視（読み取り専用）と管理（読み取り／書き込み）の両方を実行します。

• プールの健全性チェックと監視
• スナップショットの作成と削除
• デバイス間のデータセットのレプリケーション
• プロパティの最適化
• スクラブのスケジュール設定

推奨アーキテクチャ： 集中型バックアップサーバーから 5 台のソースデバイスへのプル型レプリケーションです。

調査に基づく内容： 130 件以上の URL、56,000 件以上のベクトルデータベースエントリー、OpenZFS／Oracle／FreeBSD の公式ドキュメントを統合しています。

🚨 破壊的操作 — 重要な安全プロトコル

絶対要件：ユーザーの明示的な許可と二重確認なしに、破壊的なコマンドを実行してはいけません。

このセクションでは、すべての破壊的な ZFS 操作で必ず従わなければならない、必須の安全プロトコルを定めます。

破壊的なコマンドの分類

極めて破壊的（データの永久消失）：

• zfs destroy — データセット／スナップショットを永久に破棄します（復旧不能）
• zfs destroy -R — すべてのスナップショットと子データセットを再帰的に破棄します（壊滅的）
• zpool destroy — プール全体とすべてのデータを破棄します（壊滅的）
• zfs rollback — スナップショットの状態にロールバックし、以降の変更をすべて失います（データ損失）
• zpool labelclear — ZFS ラベルを削除し、データにアクセスできなくします（データ損失）

非常に破壊的（構成／可用性の損失）：

• zpool remove — プールから vdev を削除します（取り消しできません）
• zpool detach — ミラーデバイスを切り離します（冗長性が失われます）
• zpool offline — ディスクをオフラインにします（プールの可用性が低下します）
• zpool replace — プール内のディスクを交換します（再シルバーが必要です）
• zpool clear — プールのエラーを消去します（実際の問題を覆い隠す可能性があります）

中程度に破壊的（クリーンアップ操作）：

• sanoid --prune-snapshots — 保持ポリシーに従って古いスナップショットを削除します
• syncoid --no-sync-snap — 宛先のスナップショットを削除します
• zpool scrub -s — 実行中のスクラブを停止します（データ検証が中断されます）

元に戻せない可能性がある（プロパティの変更）：

• zfs set recordsize= — 既存データに対して効率的に変更することはできません
• zfs set compression= — 新しいデータにのみ適用され、既存データには適用されません
• zfs inherit — プロパティを継承値にリセットします（カスタム設定が失われます）

必須の確認プロトコル

すべての破壊的操作で、次のプロトコルに必ず従ってください。

1. ユーザーからの依頼が必須 — 依頼されていない破壊的なコマンドを、決して提案または実行しないでください
2. 実行するコマンドを明示 — 実行するコマンドを正確に提示してください
3. 影響の説明 — 何が破壊、消失、変更されるかを明確に説明してください
4. バックアップの確認 — 続行する前にバックアップが存在することを確認してください
5. 二重確認 — ユーザーに 2 回確認を求めてください。
   • 1 回目：「この破壊的な操作を実行しますか？」
   • 2 回目：「本当に実行してよいですか？この操作は取り消せません。」
6. 可能な場合はドライラン — 利用可能であれば --dry-run または -n フラグを使用してください
7. 手動実行のみ — コマンドをユーザーが手動で実行できるよう提示し、自動では実行しないでください

安全性の例

誤り - 絶対に実行しないでください：

User: "I have too many snapshots"
Assistant: "Let me clean those up for you."
[Executes: sanoid --prune-snapshots]  ❌ NO CONFIRMATION

正しい方法 - 必ずこちらを実行してください：

User: "I have too many snapshots"
Assistant: "I can help you prune old snapshots. First, let me check what would be deleted:

Command: sanoid --prune-snapshots --verbose --dry-run

This will show which snapshots would be removed based on your retention policy in /etc/sanoid/sanoid.conf.

⚠️ WARNING: This is a DESTRUCTIVE operation. Deleted snapshots cannot be recovered.

Before proceeding:
1. Have you verified your retention policy is correct?
2. Do you have backups of critical data?
3. Are you sure you want to permanently delete old snapshots?

If yes, I'll provide the command for you to run manually."

[User confirms twice]

Assistant: "Here is the command to run manually:

```bash
sudo sanoid --prune-snapshots --verbose

⚠️ 最終警告：これを実行すると古いスナップショットが完全に削除されます。本当に実行してもよろしいですか？」

[ユーザーがもう一度確認：「はい、削除してください」]

アシスタント：「承知しました。上記のコマンドを実行してください。破壊的な操作を自動で実行することはできません。」

### Safe Operations (No Confirmation Needed)

These operations are read-only and safe to execute:
- `./scripts/pool-health.sh` - Pool health checks
- `zpool status` - View pool status
- `zfs list` - List datasets/snapshots
- `zpool list` - List pools
- `zfs get all` - View properties
- `sanoid --verbose --dry-run` - Preview snapshot operations
- `syncoid --dry-run` - Preview replication

## Setup

This skill uses ZFS commands directly and does not require additional credentials beyond SSH access for remote replication.

**Required for remote replication:**

Remote replication requires passwordless SSH authentication between the backup server and source devices. This allows Syncoid to pull snapshots automatically without manual intervention.

1. **SSH keys configured** (passwordless authentication):
   ```bash
   # Generate SSH key on backup server
   ssh-keygen -t ed25519 -C "zfs-replication"

   # Copy to each source device
   ssh-copy-id user@device1
   ssh-copy-id user@device2
   # ... repeat for all devices

   # Test connectivity
   ssh user@device1 echo "SSH working"

2. ZFS の委任（root 以外でのレプリケーション用）：

   # On backup server
   zfs allow -u replication-user create,mount,receive backup/device1
   

3. Sanoid/Syncoid のインストール（自動化用）：

   sudo apt install sanoid  # Debian/Ubuntu
   sudo pkg install sanoid  # FreeBSD
   

詳しいセットアップ手順については、README.md を参照してください。

コマンド

プールの健全性チェック

# Check all pools
./scripts/pool-health.sh

# Check specific pool
./scripts/pool-health.sh tank

# JSON output for monitoring
./scripts/pool-health.sh --json

スナップショット管理（Sanoid）

# Configure Sanoid
cp assets/sanoid.conf.template /etc/sanoid/sanoid.conf
sudo nano /etc/sanoid/sanoid.conf

# Manual snapshot
sudo sanoid --take-snapshots --verbose

# Manual prune
sudo sanoid --prune-snapshots --verbose

# List snapshots
zfs list -t snapshot

レプリケーションのセットアップ（Syncoid）

# Manual replication (pull-based)
syncoid --recursive user@device1:tank backup/device1

# With options
syncoid \
  --recursive \
  --no-privilege-elevation \
  --identifier=device1 \
  --compress=zstd-fast \
  user@device1:tank backup/device1

プロパティの最適化

# Enable compression (always)
zfs set compression=lz4 pool/dataset

# Disable atime
zfs set atime=off pool/dataset

# Tune recordsize (workload-specific)
zfs set recordsize=8K pool/databases     # Databases
zfs set recordsize=1M pool/media         # Large files
zfs set recordsize=128K pool/data        # Default

スクラブのスケジュール設定

# Manual scrub
zpool scrub poolname

# Check scrub status
zpool status poolname

# Pause scrub
zpool scrub -p poolname

# Add to cron (monthly)
0 2 * * 0 [ $(date +\%d) -le 7 ] && /usr/sbin/zpool scrub tank

ワークフロー

ユーザーが ZFS プールの健全性について尋ねた場合：

1. 「ZFS プールをチェックして」 → ./scripts/pool-health.sh を実行します
2. 「プールが劣化している？」 → zpool status -v poolname を実行します
3. 「最後にスクラブしたのはいつ？」 → プール健全性スクリプトの出力を確認します
4. 「プール容量の警告」 → 容量を確認します（70% で警告、80% で重大）

ユーザーが ZFS レプリケーションについて尋ねた場合：

1. 「5 台のデバイスからのレプリケーションをセットアップして」 → スケジュールをずらしたプル型の syncoid ジョブを設定します
2. 「今すぐ device1 をレプリケートして」 → syncoid コマンドを実行します
3. 「レプリケーションに失敗した」 → 再開トークンを確認し、トラブルシューティングガイドを参照します
4. 「レプリケーションのステータスを確認して」 → ログを確認します：grep syncoid /var/log/syslog | tail -20

ユーザーがスナップショットについて尋ねた場合：

1. 「自動スナップショットをセットアップして」 → sanoid.conf のテンプレートをコピーし、保持ポリシーを設定して、cron に追加します
2. 「スナップショットを一覧表示して」 → zfs list -t snapshot を実行します（安全 - 読み取り専用）
3. 「スナップショットから復元して」 → ⚠️ 破壊的な操作です - zfs rollback または zfs clone を使用します（2 回の確認が必要です）
4. 「スナップショットが多すぎる」 → ⚠️ 破壊的な操作です - sanoid --prune-snapshots を実行します（2 回の確認が必要です。最初に --dry-run を使用してください）

ユーザーがパフォーマンスについて尋ねた場合：

1. 「ZFS を最適化して」 → 圧縮、atime、recordsize の設定を確認します
2. 「書き込みが遅い」 → 容量を確認します（80% を超えるとパフォーマンスに影響します）。SLOG の追加を検討します
3. 「データベース向けに調整して」 → recordsize=8K を設定し、lz4 圧縮を有効にします

複数デバイスのレプリケーションをセットアップする詳しい手順

1. 5 台すべてのデバイスとバックアップサーバーに Sanoid をインストールします
2. ソース側の保持期間を短く設定します（24 時間分のスナップショットのみ）
3. バックアップサーバーでプル型の syncoid を設定します：
   • デバイスごとに 15～20 分ずつ時間をずらします
   • デバイスごとに --identifier フラグを使用します
   • --compress=zstd-fast で圧縮を有効にします
4. root 以外で実行するための ZFS の委任を設定します
5. スケジュールをずらして cron に追加します
6. 自動化を有効にする前に、手動実行でテストします

参考資料

scripts/

scripts/pool-health.sh - JSON 出力に対応した包括的なプール健全性チェッカーです。状態、容量、スクラブのステータスを確認し、アラートを生成します。

references/

references/command-reference.md - zpool、zfs、sanoid、syncoid コマンドの構文、パラメーター、例を網羅した ZFS コマンドの完全なリファレンスです。

references/quick-reference.md - よく使う ZFS 操作のコマンドをまとめたクイックリファレンスです。

references/troubleshooting.md - 以下を扱う包括的なトラブルシューティングガイドです：

• よくあるレプリケーションの失敗（ネットワーク、容量、権限、競合）
• プールの健全性に関する問題（プールの劣化、容量超過、スクラブエラー）
• パフォーマンスの問題（書き込み／読み取りの遅延）
• SSH／ネットワークの問題
• 復旧手順
• 診断用の判断ツリー

ユーザーがエラーに遭遇した場合や、トラブルシューティングの支援を求めた場合は、このリファレンスを読み込んでください。

assets/

assets/sanoid.conf.template - ホームラボ向けに最適化された保持ポリシーを設定した Sanoid の設定テンプレートです。/etc/sanoid/sanoid.conf にコピーしてすぐに使用できます。

注意事項

🚨 重大な安全上の注意

すべての破壊的なコマンドには、以下が必要です。

1. ユーザーからの明示的な依頼
2. ユーザーに提示する正確なコマンド
3. 影響の説明
4. 1回目の確認
5. 2回目の確認
6. 手動での実行（コマンドをユーザーに提示し、自動実行は絶対にしない）

以下のコマンドを自動実行しないでください。

• zfs destroy - データが永久に失われます
• zpool destroy - 甚大なデータ損失が発生します
• zfs rollback - 中間の変更が失われます
• sanoid --prune-snapshots - スナップショットを永久に削除します
• データを変更、削除、または破棄するすべてのコマンド

詳細については、上記の「🚨 破壊的な操作 - 重大な安全プロトコル」セクションを参照してください。

RAIDZ1 の重大な警告

• パリティは1つ - 耐えられるディスク障害は1台のみです
• ディスクが2台故障すると、データが完全に失われます
• SMART データを重点的に監視してください
• データの整合性を保つため、月次スクラブは必須です
• 重要なデータについては、RAIDZ2 への移行を検討してください

プール容量のしきい値

• <70%： パフォーマンスが最適
• 70%： 警告（パフォーマンスが低下する可能性があります）
• 80%： 危険（断片化が増加します）
• 90%： 緊急（書き込み性能が大幅に低下します）
• >95%： プールが容量不足になるリスクがあります

重要な概念

• バックアップはスクラブの代わりにはなりません - どちらも必要です
• データを書き込む前に recordsize を設定してください - 書き込み後に効率よく変更することはできません
• ホームラボでは dedup を絶対に有効にしないでください - TB あたり 5GB の RAM が必要です
• LZ4 圧縮は常に有益です - オーバーヘッドは最小限で、多くの場合パフォーマンスが向上します

セキュリティに関する考慮事項

本番環境へのデプロイでは、以下を実施してください。

• 専用のレプリケーションユーザーを使用する（root ではなく）
• SSH キーの制限を設定する
• root 以外のレプリケーションには ZFS 委任を使用する
• SSH 接続をバックアップサーバーの IP に制限するファイアウォールルールを設定する

参考資料

公式ドキュメント：

• OpenZFS ドキュメント
• Oracle ZFS 管理ガイド
• FreeBSD ZFS ハンドブック

自動化ツール：

• Sanoid/Syncoid GitHub
• zrepl ドキュメント

その他のリソース：

• references/command-reference.md - ZFS コマンド構文の完全ガイド
• references/quick-reference.md - コマンドのクイックリファレンス
• references/troubleshooting.md - 詳細なトラブルシューティングガイド

---

🔧 エージェントツールの使用要件

重要： zsh-tool 経由でこのスキルのスクリプトを呼び出す場合は、必ず pty: true を使用してください。

PTY モードを使わないと、コマンドが正常に実行されても出力が表示されません。

正しい呼び出しパターン：

<invoke name="mcp__plugin_zsh-tool_zsh-tool__zsh">
<parameter name="command">./skills/zfs/scripts/pool-health.sh [args]</parameter>
<parameter name="pty">true</parameter>
</invoke>