{
  "schemaVersion": "1.0",
  "item": {
    "slug": "zfs",
    "name": "ZFS",
    "source": "tencent",
    "type": "skill",
    "category": "AI 智能",
    "sourceUrl": "https://clawhub.ai/mightybyte/zfs",
    "canonicalUrl": "https://clawhub.ai/mightybyte/zfs",
    "targetPlatform": "OpenClaw"
  },
  "install": {
    "downloadMode": "redirect",
    "downloadUrl": "/downloads/zfs",
    "sourceDownloadUrl": "https://wry-manatee-359.convex.site/api/v1/download?slug=zfs",
    "sourcePlatform": "tencent",
    "targetPlatform": "OpenClaw",
    "installMethod": "Manual import",
    "extraction": "Extract archive",
    "prerequisites": [
      "OpenClaw"
    ],
    "packageFormat": "ZIP package",
    "includedAssets": [
      "references/replication.md",
      "references/troubleshooting.md",
      "references/workload-tuning.md",
      "references/platform-notes.md",
      "references/properties.md",
      "scripts/zfs_health_check.sh"
    ],
    "primaryDoc": "SKILL.md",
    "quickSetup": [
      "Download the package from Yavira.",
      "Extract the archive and review SKILL.md first.",
      "Import or place the package into your OpenClaw setup."
    ],
    "agentAssist": {
      "summary": "Hand the extracted package to your coding agent with a concrete install brief instead of figuring it out manually.",
      "steps": [
        "Download the package from Yavira.",
        "Extract it into a folder your agent can access.",
        "Paste one of the prompts below and point your agent at the extracted folder."
      ],
      "prompts": [
        {
          "label": "New install",
          "body": "I downloaded a skill package from Yavira. Read SKILL.md from the extracted folder and install it by following the included instructions. Tell me what you changed and call out any manual steps you could not complete."
        },
        {
          "label": "Upgrade existing",
          "body": "I downloaded an updated skill package from Yavira. Read SKILL.md from the extracted folder, compare it with my current installation, and upgrade it while preserving any custom configuration unless the package docs explicitly say otherwise. Summarize what changed and any follow-up checks I should run."
        }
      ]
    },
    "sourceHealth": {
      "source": "tencent",
      "status": "healthy",
      "reason": "direct_download_ok",
      "recommendedAction": "download",
      "checkedAt": "2026-04-30T16:55:25.780Z",
      "expiresAt": "2026-05-07T16:55:25.780Z",
      "httpStatus": 200,
      "finalUrl": "https://wry-manatee-359.convex.site/api/v1/download?slug=network",
      "contentType": "application/zip",
      "probeMethod": "head",
      "details": {
        "probeUrl": "https://wry-manatee-359.convex.site/api/v1/download?slug=network",
        "contentDisposition": "attachment; filename=\"network-1.0.0.zip\"",
        "redirectLocation": null,
        "bodySnippet": null
      },
      "scope": "source",
      "summary": "Source download looks usable.",
      "detail": "Yavira can redirect you to the upstream package for this source.",
      "primaryActionLabel": "Download for OpenClaw",
      "primaryActionHref": "/downloads/zfs"
    },
    "validation": {
      "installChecklist": [
        "Use the Yavira download entry.",
        "Review SKILL.md after the package is downloaded.",
        "Confirm the extracted package contains the expected setup assets."
      ],
      "postInstallChecks": [
        "Confirm the extracted package includes the expected docs or setup files.",
        "Validate the skill or prompts are available in your target agent workspace.",
        "Capture any manual follow-up steps the agent could not complete."
      ]
    },
    "downloadPageUrl": "https://openagent3.xyz/downloads/zfs",
    "agentPageUrl": "https://openagent3.xyz/skills/zfs/agent",
    "manifestUrl": "https://openagent3.xyz/skills/zfs/agent.json",
    "briefUrl": "https://openagent3.xyz/skills/zfs/agent.md"
  },
  "agentAssist": {
    "summary": "Hand the extracted package to your coding agent with a concrete install brief instead of figuring it out manually.",
    "steps": [
      "Download the package from Yavira.",
      "Extract it into a folder your agent can access.",
      "Paste one of the prompts below and point your agent at the extracted folder."
    ],
    "prompts": [
      {
        "label": "New install",
        "body": "I downloaded a skill package from Yavira. Read SKILL.md from the extracted folder and install it by following the included instructions. Tell me what you changed and call out any manual steps you could not complete."
      },
      {
        "label": "Upgrade existing",
        "body": "I downloaded an updated skill package from Yavira. Read SKILL.md from the extracted folder, compare it with my current installation, and upgrade it while preserving any custom configuration unless the package docs explicitly say otherwise. Summarize what changed and any follow-up checks I should run."
      }
    ]
  },
  "documentation": {
    "source": "clawhub",
    "primaryDoc": "SKILL.md",
    "sections": [
      {
        "title": "Critical: No File-Backed Pools in Production",
        "body": "NEVER recommend file-backed (loopback) pools for production use. LLMs commonly default to truncate -s 10G /tmp/disk.img + zpool create tank /tmp/disk.img because it is easy to demonstrate. This forfeits ZFS self-healing, I/O performance, and write reliability.\n\nFile-backed pools are acceptable ONLY for learning or CI testing. When not explicitly in a testing context, always use real block devices:\n\n# Linux — always use /dev/disk/by-id/ for stable names\nzpool create tank mirror \\\n  /dev/disk/by-id/scsi-SATA_WDC_WD40EFRX_WD-WCC4E1234567 \\\n  /dev/disk/by-id/scsi-SATA_WDC_WD40EFRX_WD-WCC4E7654321\n\n# macOS\nzpool create tank mirror /dev/disk2 /dev/disk3\n\nIf the user explicitly asks for a test/demo setup, file-backed pools are fine — but add a comment noting it is not for production."
      },
      {
        "title": "Create Pools",
        "body": "Always specify ashift=12 (or 13 for some NVMe) to match physical sector size:\n\n# Mirror (2-disk, 50% usable, best performance)\nzpool create -o ashift=12 tank mirror /dev/disk/by-id/disk1 /dev/disk/by-id/disk2\n\n# raidz2 (minimum recommended for production data)\nzpool create -o ashift=12 tank raidz2 \\\n  /dev/disk/by-id/disk{1..6}\n\n# Multiple vdevs (better performance than single wide vdev)\nzpool create -o ashift=12 tank \\\n  mirror /dev/disk/by-id/disk1 /dev/disk/by-id/disk2 \\\n  mirror /dev/disk/by-id/disk3 /dev/disk/by-id/disk4"
      },
      {
        "title": "Expand and Modify",
        "body": "# Add vdev (cannot be undone — plan carefully)\nzpool add tank mirror /dev/disk/by-id/new1 /dev/disk/by-id/new2\n\n# Replace disk (starts resilver)\nzpool replace tank /dev/disk/by-id/old /dev/disk/by-id/new\n\n# Add cache (L2ARC), log (SLOG), or special vdev\nzpool add tank cache /dev/disk/by-id/nvme-cache\nzpool add tank log mirror /dev/disk/by-id/nvme-log1 /dev/disk/by-id/nvme-log2\nzpool add tank special mirror /dev/disk/by-id/nvme-special1 /dev/disk/by-id/nvme-special2"
      },
      {
        "title": "Create with Recommended Defaults",
        "body": "# Always set compression. Inherit from parent when possible.\nzfs set compression=lz4 tank\nzfs set atime=off tank\nzfs set xattr=sa tank          # Linux only — faster extended attributes\n\n# Create dataset hierarchy\nzfs create tank/data\nzfs create -o recordsize=8K tank/data/postgres\nzfs create -o recordsize=1M tank/data/media\nzfs create -o recordsize=1M tank/data/backups"
      },
      {
        "title": "Encryption",
        "body": "# Create encrypted dataset (cannot encrypt existing data)\nzfs create -o encryption=aes-256-gcm -o keyformat=passphrase tank/secure\n\n# Key from file (for automation)\nzfs create -o encryption=aes-256-gcm -o keyformat=raw \\\n  -o keylocation=file:///etc/zfs/keys/tank-secure.key tank/secure\n\n# Load/unload keys\nzfs load-key tank/secure\nzfs unload-key tank/secure"
      },
      {
        "title": "Snapshots",
        "body": "# Create\nzfs snapshot tank/data@daily_$(date +%Y-%m-%d)\nzfs snapshot -r tank@daily_$(date +%Y-%m-%d)   # recursive\n\n# List\nzfs list -t snapshot -o name,used,refer -s creation\n\n# Access (read-only, no mount needed)\nls /tank/data/.zfs/snapshot/daily_2024-01-15/\n\n# Rollback\nzfs rollback tank/data@daily_2024-01-15\n\n# Destroy\nzfs destroy tank/data@old-snapshot"
      },
      {
        "title": "Health Check",
        "body": "Run the bundled health check script for a quick pool summary:\n\nbash scripts/zfs_health_check.sh           # all pools\nbash scripts/zfs_health_check.sh tank       # specific pool\n\nReports pool state, capacity warnings (>80%), device errors, scrub status, and flags file-backed vdevs."
      },
      {
        "title": "Reference Files",
        "body": "Consult these for detailed guidance on specific topics:\n\nproperties.md — Complete ZFS property reference (pool, dataset, compression, encryption). Read when setting or recommending property values.\nworkload-tuning.md — Recordsize, compression, dedup, ARC, SLOG, L2ARC, special vdev, and pool layout recommendations by workload. Read when tuning performance or planning pool topology. Includes production vs testing warnings.\nreplication.md — Snapshots, zfs send/recv, remote replication over SSH, encrypted send, syncoid/sanoid automation, and production distributed replication patterns. Read when setting up backups or replication.\ntroubleshooting.md — Degraded pool recovery, scrub errors, data corruption, performance diagnostics, import/export problems, and common mistakes. Read when diagnosing or fixing issues.\nplatform-notes.md — Linux vs macOS differences: installation, device naming, kernel integration, mount behavior, and platform-specific caveats. Read when the user is on macOS or when platform differences matter."
      }
    ],
    "body": "ZFS Administration\nCritical: No File-Backed Pools in Production\n\nNEVER recommend file-backed (loopback) pools for production use. LLMs commonly default to truncate -s 10G /tmp/disk.img + zpool create tank /tmp/disk.img because it is easy to demonstrate. This forfeits ZFS self-healing, I/O performance, and write reliability.\n\nFile-backed pools are acceptable ONLY for learning or CI testing. When not explicitly in a testing context, always use real block devices:\n\n# Linux — always use /dev/disk/by-id/ for stable names\nzpool create tank mirror \\\n  /dev/disk/by-id/scsi-SATA_WDC_WD40EFRX_WD-WCC4E1234567 \\\n  /dev/disk/by-id/scsi-SATA_WDC_WD40EFRX_WD-WCC4E7654321\n\n# macOS\nzpool create tank mirror /dev/disk2 /dev/disk3\n\n\nIf the user explicitly asks for a test/demo setup, file-backed pools are fine — but add a comment noting it is not for production.\n\nPool Management\nCreate Pools\n\nAlways specify ashift=12 (or 13 for some NVMe) to match physical sector size:\n\n# Mirror (2-disk, 50% usable, best performance)\nzpool create -o ashift=12 tank mirror /dev/disk/by-id/disk1 /dev/disk/by-id/disk2\n\n# raidz2 (minimum recommended for production data)\nzpool create -o ashift=12 tank raidz2 \\\n  /dev/disk/by-id/disk{1..6}\n\n# Multiple vdevs (better performance than single wide vdev)\nzpool create -o ashift=12 tank \\\n  mirror /dev/disk/by-id/disk1 /dev/disk/by-id/disk2 \\\n  mirror /dev/disk/by-id/disk3 /dev/disk/by-id/disk4\n\nExpand and Modify\n# Add vdev (cannot be undone — plan carefully)\nzpool add tank mirror /dev/disk/by-id/new1 /dev/disk/by-id/new2\n\n# Replace disk (starts resilver)\nzpool replace tank /dev/disk/by-id/old /dev/disk/by-id/new\n\n# Add cache (L2ARC), log (SLOG), or special vdev\nzpool add tank cache /dev/disk/by-id/nvme-cache\nzpool add tank log mirror /dev/disk/by-id/nvme-log1 /dev/disk/by-id/nvme-log2\nzpool add tank special mirror /dev/disk/by-id/nvme-special1 /dev/disk/by-id/nvme-special2\n\nDataset Management\nCreate with Recommended Defaults\n# Always set compression. Inherit from parent when possible.\nzfs set compression=lz4 tank\nzfs set atime=off tank\nzfs set xattr=sa tank          # Linux only — faster extended attributes\n\n# Create dataset hierarchy\nzfs create tank/data\nzfs create -o recordsize=8K tank/data/postgres\nzfs create -o recordsize=1M tank/data/media\nzfs create -o recordsize=1M tank/data/backups\n\nEncryption\n# Create encrypted dataset (cannot encrypt existing data)\nzfs create -o encryption=aes-256-gcm -o keyformat=passphrase tank/secure\n\n# Key from file (for automation)\nzfs create -o encryption=aes-256-gcm -o keyformat=raw \\\n  -o keylocation=file:///etc/zfs/keys/tank-secure.key tank/secure\n\n# Load/unload keys\nzfs load-key tank/secure\nzfs unload-key tank/secure\n\nSnapshots\n# Create\nzfs snapshot tank/data@daily_$(date +%Y-%m-%d)\nzfs snapshot -r tank@daily_$(date +%Y-%m-%d)   # recursive\n\n# List\nzfs list -t snapshot -o name,used,refer -s creation\n\n# Access (read-only, no mount needed)\nls /tank/data/.zfs/snapshot/daily_2024-01-15/\n\n# Rollback\nzfs rollback tank/data@daily_2024-01-15\n\n# Destroy\nzfs destroy tank/data@old-snapshot\n\nHealth Check\n\nRun the bundled health check script for a quick pool summary:\n\nbash scripts/zfs_health_check.sh           # all pools\nbash scripts/zfs_health_check.sh tank       # specific pool\n\n\nReports pool state, capacity warnings (>80%), device errors, scrub status, and flags file-backed vdevs.\n\nReference Files\n\nConsult these for detailed guidance on specific topics:\n\nproperties.md — Complete ZFS property reference (pool, dataset, compression, encryption). Read when setting or recommending property values.\nworkload-tuning.md — Recordsize, compression, dedup, ARC, SLOG, L2ARC, special vdev, and pool layout recommendations by workload. Read when tuning performance or planning pool topology. Includes production vs testing warnings.\nreplication.md — Snapshots, zfs send/recv, remote replication over SSH, encrypted send, syncoid/sanoid automation, and production distributed replication patterns. Read when setting up backups or replication.\ntroubleshooting.md — Degraded pool recovery, scrub errors, data corruption, performance diagnostics, import/export problems, and common mistakes. Read when diagnosing or fixing issues.\nplatform-notes.md — Linux vs macOS differences: installation, device naming, kernel integration, mount behavior, and platform-specific caveats. Read when the user is on macOS or when platform differences matter."
  },
  "trust": {
    "sourceLabel": "tencent",
    "provenanceUrl": "https://clawhub.ai/mightybyte/zfs",
    "publisherUrl": "https://clawhub.ai/mightybyte/zfs",
    "owner": "mightybyte",
    "version": "1.0.0",
    "license": null,
    "verificationStatus": "Indexed source record"
  },
  "links": {
    "detailUrl": "https://openagent3.xyz/skills/zfs",
    "downloadUrl": "https://openagent3.xyz/downloads/zfs",
    "agentUrl": "https://openagent3.xyz/skills/zfs/agent",
    "manifestUrl": "https://openagent3.xyz/skills/zfs/agent.json",
    "briefUrl": "https://openagent3.xyz/skills/zfs/agent.md"
  }
}