ProxMenux/web/messages/en/docs/post-install/storage.json

{
  "meta": {
    "title": "Post-Install: Storage | ProxMenux Documentation",
    "description": "Storage optimizations in the ProxMenux Customizable post-install script: ZFS ARC sizing based on host RAM, zfs-auto-snapshot for periodic snapshots, and vzdump backup speed limits removal."
  },
  "header": {
    "title": "Post-Install: Storage",
    "section": "Settings post-install Proxmox"
  },
  "intro": {
    "title": "What this category covers",
    "body": "Four storage-related optimizations: tune the <strong>ZFS ARC</strong> cache size to a sensible fraction of host RAM, install and schedule <strong>ZFS auto-snapshots</strong>, enable <strong>ZFS autotrim</strong> on SSD/NVMe pools, and remove throttles from <strong>vzdump</strong> so backups run at full speed. All four are independent — pick the ones that match your setup. A fifth storage-adjacent optimization, <link>Log2RAM</link>, reduces SSD/NVMe wear by moving <code>/var/log</code> to a ramdisk — it lives on the Optional page because the ProxMenux Customizable menu groups it there."
  },
  "trackedTitle": "All four are tracked in the Uninstall menu",
  "trackedBody": "Each of these options registers a tool in <code>installed_tools.json</code>, so they appear in <link>Uninstall Optimizations</link>. Reverting <code>zfs_arc</code> removes <code>/etc/modprobe.d/99-zfsarc.conf</code> and rebuilds initramfs; <code>zfs_auto_snapshot</code> reverses the cron schedule and offers to purge the package; <code>zfs_autotrim</code> sets <code>autotrim=off</code> on the pools it enabled; <code>vzdump_speed</code> restores <code>/etc/vzdump.conf</code> from the <code>.bak</code> the install created.",
  "arc": {
    "heading": "Optimize ZFS ARC size",
    "intro": "The <strong>Adaptive Replacement Cache (ARC)</strong> is ZFS’s in-memory read cache. Proxmox VE installations since 8.1 set a limit of 10% of RAM, capped at 16 GiB; older or upgraded hosts may differ. This option writes that same policy explicitly (RAM/10, capped at 16 GiB, with a 64 MiB floor) to its own file, which also covers older or upgraded hosts. Check existing settings and workload needs before changing it; a smaller cache is not always faster.",
    "sizingTitle": "Sizing rules",
    "headerRam": "Host RAM",
    "headerMax": "ARC cap",
    "rows": [
      {
        "ram": "Formula",
        "max": "RAM / 10, capped at 16 GiB, with a 64 MiB floor"
      },
      {
        "ram": "8 GB host",
        "max": "≈ 819 MiB (RAM/10)"
      },
      {
        "ram": "16 GB host",
        "max": "≈ 1.6 GiB (RAM/10)"
      },
      {
        "ram": "64 GB host",
        "max": "≈ 6.4 GiB (RAM/10)"
      },
      {
        "ram": "≥ 160 GB host",
        "max": "16 GiB (cap)"
      }
    ],
    "after": "The file <code>/etc/modprobe.d/99-zfsarc.conf</code> contains a single directive — <code>options zfs zfs_arc_max=…</code>. This option does not tune other ZFS module parameters (<code>zfs_arc_min</code>, L2ARC prefetch/write throttle, TXG timeout). Before writing, a reconcile step scans other <code>*.conf</code> in <code>/etc/modprobe.d/</code> that set <code>zfs_arc_min</code> / <code>zfs_arc_max</code>, backs them up to <code>/usr/local/share/proxmenux/backups/zfs_arc/</code> with a manifest, and removes the conflicting <code>zfs_arc_min</code> / <code>zfs_arc_max</code> values (other options on those lines are kept), so only ProxMenux’s ARC file sets the limit. After writing, it runs <code>update-initramfs -u -k all</code> and, when applicable, <code>proxmox-boot-tool refresh</code>, so the limit also reaches the initramfs used by ZFS-on-root setups.",
    "rebootTitle": "Requires a reboot to take effect",
    "rebootBody": "ARC settings are read when the <code>zfs</code> kernel module loads. To make the cap take effect on ZFS-on-root hosts, ProxMenux regenerates the initramfs with <code>update-initramfs -u -k all</code> and, when applicable, refreshes the boot loader with <code>proxmox-boot-tool refresh</code>. A reboot is still required to pick up the new module parameter; the \"reboot required\" flag is set automatically.",
    "safeTitle": "Safe on non-ZFS hosts",
    "safeBody": "The function only writes the config when <code>zpool list</code> reports at least one imported ZFS pool. On ext4 / LVM-only Proxmox hosts, or on machines with the ZFS tools installed but no pool imported, ticking this option is a no-op — nothing gets written.",
    "verifyTitle": "Verification and manual rollback"
  },
  "autoSnap": {
    "heading": "Install ZFS auto-snapshot",
    "intro": "Installs the <a>zfs-auto-snapshot</a> package and rewrites its cron schedules so snapshots are taken automatically at several intervals. A great no-effort safety net on top of your regular vzdump backups.",
    "cadenceTitle": "Snapshot cadence ProxMenux configures",
    "headerLabel": "Label",
    "headerRuns": "Runs",
    "headerKept": "Snapshots kept",
    "rows": [
      {
        "label": "frequent",
        "runs": "every 15 min",
        "kept": "4"
      },
      {
        "label": "hourly",
        "runs": "every hour",
        "kept": "1"
      },
      {
        "label": "daily",
        "runs": "once a day",
        "kept": "1"
      },
      {
        "label": "weekly",
        "runs": "once a week",
        "kept": "1"
      },
      {
        "label": "monthly",
        "runs": "once a month",
        "kept": "1"
      }
    ],
    "conservativeTitle": "Conservative keep counts",
    "conservativeBody": "ProxMenux ships with conservative retention (just 4 frequent + 1 of each longer interval) so ZFS snapshot storage doesn't balloon. If you want longer retention, edit the numbers in <code>/etc/cron.d/zfs-auto-snapshot</code>, <code>/etc/cron.hourly/zfs-auto-snapshot</code>, etc. after the script runs.",
    "onlyZfsTitle": "Only useful on ZFS pools",
    "onlyZfsBody": "Installing the package on an ext4-only host is harmless but pointless — there are no ZFS datasets for it to snapshot. Skip this option if you don't use ZFS.",
    "verifyTitle": "Verification and manual rollback"
  },
  "autotrim": {
    "heading": "Enable ZFS autotrim (SSD/NVMe pools)",
    "intro": "Enables the <code>autotrim</code> property on ZFS pools backed exclusively by SSDs or NVMe drives with TRIM support. The script conservatively skips pools containing a rotational device. Pools already set to <code>autotrim=on</code> are left unchanged.",
    "trimTitle": "What TRIM does, and why it matters on ZFS",
    "trimBody1": "SSDs / NVMe drives manage internal storage in fixed-size erase blocks that are much larger than the logical sectors the filesystem talks to. When a filesystem deletes a file, the drive doesn't know — it still thinks those sectors are in use, so its internal garbage collector keeps shuffling stale data around to free new erase blocks. <strong>TRIM</strong> is the standard command the OS uses to tell the drive \"these sectors are now free, you can erase them ahead of time\".",
    "trimBody2": "Without TRIM, SSD performance degrades over time as the drive runs out of pre-erased blocks and has to do erase-on-write, and write amplification increases — both shortening the drive's useful life. With TRIM enabled, the drive can keep a healthy pool of empty blocks ready to write into.",
    "trimBody3": "With <code>autotrim=on</code>, ZFS trims recently freed space in the background, grouping ranges before issuing commands. A periodic <code>zpool trim &lt;pool&gt;</code> is another option. Autotrim avoids a separate schedule, but its performance impact depends on the devices; periodic manual trim may suit some lower-end drives better.",
    "practicalTitle": "Why is this practical to enable?",
    "practicalItems": [
      "<strong>Sustained write performance.</strong> TRIM can help a drive reclaim unused blocks efficiently. The benefit and any latency impact depend on the device and workload.",
      "<strong>Drive longevity.</strong> Avoiding unnecessary internal copying can reduce write amplification and NAND wear. It does not guarantee a specific increase in drive lifespan.",
      "<strong>No scheduled cron job to remember.</strong> Unlike a periodic <code>zpool trim</code>, autotrim is fire-and-forget — the pool handles it on its own."
    ],
    "whenTitle": "When is this necessary?",
    "whenIntro1": "<strong>Consider enabling it</strong> on ZFS pools made entirely of TRIM-capable SSD or NVMe devices. Check device behaviour and workload latency; a scheduled manual trim can be preferable on some hardware.",
    "whenIntro2": "<strong>The script skips it automatically</strong> on:",
    "whenSkipItems": [
      "Pools containing any HDD (rotational) vdev — a conservative hardware filter used by this script.",
      "Drives without <code>discard_granularity</code> exposed in sysfs — usually old SSDs without TRIM, or pass-through paths where the OS can't see the underlying device.",
      "Pools where ZFS itself reports the property unsupported (rare; very old pools).",
      "Pools already set to <code>autotrim=on</code> (no-op)."
    ],
    "whenIntro3": "<strong>Not relevant on ext4-only hosts</strong> — there's nothing for ZFS to trim. The function exits with a friendly message in that case.",
    "recordedTitle": "Why only the pools ProxMenux changed are recorded",
    "recordedBody": "The function only writes a pool to its internal state file (<code>/usr/local/share/proxmenux/zfs_autotrim_pools</code>) when it actively flipped that pool from <code>off</code> to <code>on</code>. Pools you had on autotrim before running the script are left out of the list, so a future Uninstall doesn't turn off settings you configured yourself — only ProxMenux's own changes are reverted.",
    "manualTitle": "Manual equivalent (run on your server)",
    "manualIntro": "The full sequence the script runs against each pool is replicable by hand. This is what you would type if you wanted to do the same thing on a single pool without ProxMenux:",
    "verifyTitle": "Verification and manual rollback",
    "oneShotTitle": "Need a one-shot trim instead of continuous?",
    "oneShotBody": "Some operators prefer a manual trim during off-peak hours rather than continuous trim activity. Disable autotrim and schedule a cron job that runs <code>zpool trim &lt;pool&gt;</code> — same end goal, different cadence."
  },
  "vzdump": {
    "heading": "Increase vzdump backup speed",
    "intro": "Writes bwlimit: 0 and ionice: 5 in the global vzdump configuration. Proxmox already defaults to no bandwidth limit, so this removes a cap only if one was configured. Compared with the default ionice: 7, the value 5 gives a higher best-effort I/O priority where the scheduler honours it. This can affect running guests and does not guarantee faster backups.",
    "changedTitle": "What gets changed in /etc/vzdump.conf",
    "backupTitle": "First run creates a .bak of vzdump.conf",
    "backupBody": "The first time this option runs, ProxMenux copies <code>/etc/vzdump.conf</code> to <code>/etc/vzdump.conf.bak</code> before touching it. Subsequent runs re-use that backup and won't overwrite it, so a hand-edited config from before the first apply stays recoverable. The changes to <code>bwlimit</code> and <code>ionice</code> are then made with <code>sed</code>, and any other options in the file (compress, pigz, tmpdir, exclude-path, etc.) are preserved.",
    "skipTitle": "When to skip this",
    "skipBody": "On a host with slow local storage and VMs that are latency-sensitive, removing the bandwidth cap can cause noticeable slowdowns during backups. If you've previously set a specific <code>bwlimit</code> for that reason, keep it — skip this option.",
    "verifyTitle": "Verification and manual rollback"
  },
  "related": {
    "heading": "Related",
    "items": [
      {
        "label": "ZFS Management commands",
        "href": "/docs/help-info/zfs-commands",
        "tail": " — zpool / zfs reference for ARC, snapshots, scrub."
      },
      {
        "label": "Storage and Disks commands",
        "href": "/docs/help-info/storage-commands",
        "tail": " — generic block-device and Proxmox storage reference."
      },
      {
        "label": "Backup and Restore commands",
        "href": "/docs/help-info/backup-commands",
        "tail": " — vzdump CLI reference for bandwidth and I/O-priority settings."
      },
      {
        "label": "Uninstall Optimizations",
        "href": "/docs/post-install/uninstall",
        "tail": " — revert ARC / vzdump changes."
      },
      {
        "label": "Log2RAM",
        "href": "/docs/post-install/optional#log2ram",
        "tail": " — reduces SSD/NVMe wear by ramdisk-backing /var/log; documented under Optional."
      },
      {
        "label": "Customizable Post-Install",
        "href": "/docs/post-install/customizable",
        "tail": " — back to the parent menu."
      }
    ]
  }
}