ProxMenux/web/messages/en/docs/storage-share/lxc-nfs-client.json

{
  "meta": {
    "title": "NFS client in LXC | ProxMenux Documentation",
    "description": "Mount NFS shares directly from inside a Proxmox LXC container with ProxMenux. Auto-installs nfs-common, supports auto-discovery on the LAN, persistent mounts via /etc/fstab, and safe boot behaviour. Requires a privileged container.",
    "ogTitle": "NFS client in LXC | ProxMenux Documentation",
    "ogDescription": "Mount NFS shares from inside a privileged LXC container. Auto-discovery, /etc/fstab persistence, safe boot defaults."
  },
  "header": {
    "title": "NFS client in LXC",
    "description": "Mount NFS shares directly from inside a Proxmox LXC container. The container becomes a real NFS client — talks to the NFS server over the network, runs mount.nfs, writes to /etc/fstab. ProxMenux installs nfs-common for you, helps you find servers and exports, and applies safe boot defaults.",
    "section": "Storage & Share · LXC"
  },
  "privReq": {
    "title": "Privileged container required",
    "body": "The kernel <code>mount.nfs</code> client needs capabilities (<code>SYS_ADMIN</code> at minimum) that unprivileged LXC containers do not expose. The script enforces this — it asks you to pick a CT and <strong>aborts if it is unprivileged</strong>. If you need the share inside an unprivileged CT, mount it on the Proxmox host first (with <hostNfsLink>NFS share as Proxmox storage</hostNfsLink>) and bind-mount it into the CT with the <mountLink>LXC Mount Manager</mountLink>."
  },
  "what": {
    "heading": "What this does",
    "body": "Unlike the LXC Mount Manager — which makes the CT see something <em>via</em> the Proxmox host — this script gives the container its <strong>own NFS client</strong>: it speaks NFS over the network, mounts shares directly from the NFS server, and stores the mount in the container's <code>/etc/fstab</code>. The Proxmox host is not in the data path.",
    "diagramServerLabel": "NFS Server",
    "diagramServerDetail": "/export/data",
    "diagramHostLabel": "Proxmox Host",
    "diagramHostDetail": "(just a\nnetwork bridge)",
    "diagramCtLabel": "LXC (privileged)",
    "diagramCtDetail": "/mnt/data\nmount.nfs inside CT",
    "diagramArrow": "NFS",
    "twoWaysTitle": "Two ways to give a CT NFS access — pick one",
    "twoWaysBind": "<strong>Bind mount via host</strong> (<mountLink>LXC Mount Manager</mountLink>): host mounts the NFS once, every CT bind-mounts the same path. Works with unprivileged CTs. Recommended when several CTs need the same share.",
    "twoWaysDirect": "<strong>Direct NFS mount inside the CT</strong> (this page): the CT mounts the NFS itself. Requires privileged. Useful when the CT must own its connection / credentials, or for setups where each CT talks to a different server."
  },
  "opening": {
    "heading": "Opening the tool",
    "body": "From ProxMenux's main menu, open <strong>Storage &amp; Share Manager → Configure NFS Client in LXC (only privileged)</strong>. ProxMenux first asks you to <strong>pick the target CT</strong> (and starts it if stopped); aborts if unprivileged. Once the CT is selected, you see this sub-menu:",
    "imageAlt": "NFS Client Manager menu — Mount / View / Unmount / Test connectivity"
  },
  "howRuns": {
    "heading": "How the script runs (Mount flow)"
  },
  "fstabFlags": {
    "heading": "Why those fstab flags",
    "intro": "For permanent mounts the script adds three flags beyond the standard NFS options: <code>_netdev,x-systemd.automount,noauto</code>. Each one solves a real boot-time problem:",
    "headerFlag": "Flag",
    "headerEffect": "What it does",
    "rows": [
      {
        "flag": "_netdev",
        "effect": "Tells the init system this mount needs the network. Boot does not block waiting for it before networking is up."
      },
      {
        "flag": "x-systemd.automount",
        "effectRich": "Creates a systemd auto-mount unit: the mount only happens the first time something accesses <code>/mnt/&lt;path&gt;</code>. NFS server unreachable at boot does not stall the CT."
      },
      {
        "flag": "noauto",
        "effect": "Skip the eager mount at boot. Combined with the automount unit above, the mount is established lazily on first access."
      }
    ],
    "netEffectTitle": "Net effect",
    "netEffectBody": "Your container always boots, even if the NFS server is offline. The first time something touches the mount path, systemd quietly mounts it. If the server is still down, that one access fails with <em>resource temporarily unavailable</em> — but nothing else in the CT is affected."
  },
  "manual": {
    "heading": "Manual equivalent",
    "body": "Replicate the whole flow by hand — every command runs <strong>inside the CT</strong> via <code>pct exec &lt;ctid&gt; --</code> or directly via <code>pct enter &lt;ctid&gt;</code>:"
  },
  "view": {
    "heading": "View current mounts",
    "body": "Lists every NFS mount point active inside the CT (<code>mount | grep nfs</code>) plus every NFS line in the CT's <code>/etc/fstab</code>. For each fstab entry, the live mount status is shown — useful to spot permanent mounts that did not come up at boot."
  },
  "unmount": {
    "heading": "Unmount NFS share",
    "body": "Combines the live mounts and the fstab entries into one list, lets you pick one, and <strong>removes the corresponding line from <code>/etc/fstab</code></strong>. The script does <em>not</em> run <code>umount</code> on the live mount — instead it tells you a CT reboot is needed for the unmount to take effect.",
    "warnTitle": "The script removes fstab entries, not live mounts",
    "warnBody": "This is a deliberate design choice: <code>umount</code> on a busy mount fails with \"device busy\" when something inside the CT is still using it. Removing the fstab entry guarantees the mount disappears cleanly on the next CT start. If you want the mount gone <em>now</em> and you are sure nothing is using it, run <code>pct exec &lt;ctid&gt; -- umount /mnt/&lt;path&gt;</code> by hand after the script finishes."
  },
  "test": {
    "heading": "Test NFS connectivity",
    "body": "Diagnostic pass inside the CT: confirms <code>nfs-common</code> is installed, <code>rpcbind</code> is running, lists current NFS mounts, then iterates over every NFS server referenced in fstab and checks ping → port 2049 → <code>showmount -e</code>. Good first stop when a permanent mount fails to come up."
  },
  "troubleshoot": {
    "heading": "Troubleshooting",
    "privTitle": "Privileged container required (script aborts)",
    "privBody": "The selected CT is unprivileged. The kernel NFS client needs <code>SYS_ADMIN</code> capability that unprivileged CTs do not expose. Either convert the CT to privileged (Disk Manager &amp; conversion is documented in the <importLink>Import Disk to LXC</importLink> page) or use the alternative path described in the warning at the top of this page.",
    "aptTitle": "apt-get install nfs-common fails",
    "aptIntro": "The script assumes a Debian-family CT (<code>apt-get</code>). If the CT runs Alpine / Arch / Rocky / Alma, the install step fails silently. Install the NFS client by hand for that distro:",
    "aptItems": [
      "Alpine: <code>apk add nfs-utils</code>",
      "Arch: <code>pacman -S nfs-utils</code>",
      "Rocky / Alma: <code>dnf install nfs-utils</code>"
    ],
    "aptOutro": "Then re-run the ProxMenux script — the install step skips when the tools are already present.",
    "portTitle": "\"NFS port (2049) is not accessible\"",
    "portBody": "Ping succeeded but <code>nc -z &lt;server&gt; 2049</code> failed from inside the CT. Check that the NFS service is running on the server, that the firewall allows 2049 from the CT's network, and that the CT actually has a valid network route (try <code>pct exec &lt;ctid&gt; -- ip route</code>).",
    "bootTitle": "Permanent mount succeeds but does not come up at boot",
    "bootBody": "Almost always one of: the network is not ready when the CT mounts (the script's <code>_netdev,x-systemd.automount,noauto</code> flags fix this — re-add the mount via the script if you wrote the fstab line by hand without those), the server is unreachable at boot (auto-mount waits for first access — that's normal), or DNS is unresolved at boot (use the server's IP, not its hostname).",
    "squashTitle": "Server squashes root, no write access from inside CT",
    "squashIntro": "The NFS export uses <code>root_squash</code> (the default) and the CT writes as root. Two options:",
    "squashItems": [
      "Server-side: change the export to <code>no_root_squash</code> (only if you trust the CT).",
      "CT-side: write as a non-root user that the server accepts, or chown the share appropriately."
    ],
    "squashOutro": "ProxMenux cannot fix this — it is server policy."
  },
  "related": {
    "heading": "Related",
    "items": [
      {
        "href": "/docs/storage-share/lxc-mount-points",
        "label": "LXC Mount Points (Host ↔ Container)",
        "tail": " — the alternative for unprivileged CTs: mount on host, bind into CT."
      },
      {
        "href": "/docs/storage-share/lxc-samba-client",
        "label": "Samba client in LXC",
        "tail": " — sibling page, same pattern for SMB / CIFS shares."
      },
      {
        "href": "/docs/storage-share/lxc-nfs-server",
        "label": "NFS server in LXC",
        "tailRich": " — the inverse: expose folders <em>from</em> a CT over NFS."
      },
      {
        "href": "/docs/storage-share/host-nfs",
        "label": "NFS share as Proxmox storage",
        "tail": " — register the share in Proxmox itself instead of inside a single CT."
      }
    ]
  }
}