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

{
  "meta": {
    "title": "Samba client in LXC | ProxMenux Documentation",
    "description": "Mount Samba / CIFS shares directly from inside a Proxmox LXC container with ProxMenux. Auto-installs cifs-utils + smbclient, supports auto-discovery, secure credential storage, and persistent mounts via /etc/fstab. Requires a privileged container.",
    "ogTitle": "Samba client in LXC | ProxMenux Documentation",
    "ogDescription": "Mount Samba / CIFS shares from inside a privileged LXC container. Auto-discovery, secure credential file, /etc/fstab persistence."
  },
  "header": {
    "title": "Samba client in LXC",
    "description": "Mount Samba (SMB / CIFS) shares directly from inside a Proxmox LXC container. The container becomes a real CIFS client — talks to the Samba server over the network, runs mount.cifs, stores credentials securely, and writes to /etc/fstab. ProxMenux installs cifs-utils + smbclient for you and validates credentials against the server before mounting.",
    "section": "Storage & Share · LXC"
  },
  "privReq": {
    "title": "Privileged container required",
    "body": "The kernel <code>mount.cifs</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 <hostSambaLink>Samba / CIFS as Proxmox storage</hostSambaLink>) and bind-mount it into the CT with the <mountLink>LXC Mount Manager</mountLink>."
  },
  "what": {
    "heading": "What this does",
    "body": "The container speaks CIFS over the network and mounts the share on its own. The Proxmox host is just the network bridge — it does not see or manage the mount.",
    "diagramServerLabel": "Samba Server",
    "diagramServerDetail": "//srv/share",
    "diagramHostLabel": "Proxmox Host",
    "diagramHostDetail": "(just a\nnetwork bridge)",
    "diagramCtLabel": "LXC (privileged)",
    "diagramCtDetail": "/mnt/share\nmount.cifs inside CT",
    "diagramArrow": "CIFS",
    "twoWaysTitle": "Two ways to give a CT a Samba share — pick one",
    "twoWaysBind": "<strong>Bind mount via host</strong> (<mountLink>LXC Mount Manager</mountLink>): host mounts the CIFS once, every CT bind-mounts the same path. Works with unprivileged CTs. Recommended when several CTs need the same share.",
    "twoWaysDirect": "<strong>Direct CIFS mount inside the CT</strong> (this page): the CT mounts the CIFS itself. Requires privileged. Useful when the CT must own its own credentials, or when 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 Samba 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": "Samba Client Manager menu — Mount / View / Unmount / Test connectivity"
  },
  "howRuns": {
    "heading": "How the script runs (Mount flow)"
  },
  "creds": {
    "heading": "Where the password lives",
    "body": "ProxMenux <strong>does not put the password in the mount command</strong> or in <code>/etc/fstab</code>. It writes a credentials file inside the CT instead. That file contains plaintext credentials protected by root-only permissions; it is not encrypted:",
    "whyTitle": "Why a separate file rather than fstab",
    "whyBody": "The CIFS module accepts <code>username=</code> / <code>password=</code> options inline in fstab, but anyone who can read <code>/etc/fstab</code> sees the password in clear. Putting credentials in a root-only file and pointing fstab at it (<code>credentials=</code>) keeps the password out of world-readable config."
  },
  "options": {
    "heading": "Mount options explained",
    "headerOption": "Option",
    "headerEffect": "What it does",
    "rows": [
      {
        "option": "rw / ro",
        "effect": "Read-write or read-only mode for the whole mount."
      },
      {
        "option": "file_mode=0664",
        "effect": "Permissions reported for files via CIFS. Default lets owner+group write, others read."
      },
      {
        "option": "dir_mode=0775",
        "effect": "Permissions reported for directories. Default lets owner+group enter and create, others traverse."
      },
      {
        "option": "iocharset=utf8",
        "effect": "Force UTF-8 for filenames coming over the wire. Avoids mojibake on non-ASCII names."
      },
      {
        "option": "credentials=file",
        "effect": "Read username / password from the file (added automatically for user auth)."
      },
      {
        "option": "guest",
        "effect": "Authenticate as guest, no credentials needed (added automatically when guest is chosen)."
      },
      {
        "option": "_netdev",
        "effect": "Tells the init system this mount needs the network. Boot does not block waiting for it."
      },
      {
        "option": "x-systemd.automount",
        "effect": "Lazy mount: only mounts on first access. CIFS server unreachable at boot does not stall the CT."
      },
      {
        "option": "noauto",
        "effect": "Skip eager mount at boot. Combined with the automount unit, the mount is established lazily."
      }
    ],
    "netEffectTitle": "Net effect of the fstab flags",
    "netEffectBody": "The CIFS filesystem is mounted on <em>first access</em> rather than eagerly during boot. If the server is offline, that access may wait or fail, and services that depend on the path can be affected. Automount reduces the boot-time dependency; it does not guarantee that every CT service is unaffected by an unavailable CIFS server."
  },
  "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>:",
    "guestIntro": "Guest variant — no credentials file needed:"
  },
  "view": {
    "heading": "View current mounts",
    "body": "Lists every CIFS mount point active inside the CT (<code>mount -t cifs</code>) plus every CIFS 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 Samba 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> plus the matching credentials file. The script does not 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": "Same design as the NFS client: <code>umount</code> on a busy mount fails with \"device busy\". Removing the fstab entry guarantees the mount disappears cleanly on the next CT start. If you want the mount gone <em>now</em>, run <code>pct exec &lt;ctid&gt; -- umount /mnt/&lt;path&gt;</code> by hand after the script finishes."
  },
  "test": {
    "heading": "Test Samba connectivity",
    "body": "Diagnostic pass inside the CT: confirms <code>cifs-utils</code> is installed, lists current CIFS mounts, then for every server referenced in fstab checks ping → ports 139/445 → guest listing. \"Requires authentication\" on the guest test is normal for any server that doesn't expose public shares."
  },
  "troubleshoot": {
    "heading": "Troubleshooting",
    "privTitle": "Privileged container required (script aborts)",
    "privBody": "The selected CT is unprivileged. The kernel CIFS client needs <code>SYS_ADMIN</code> capability that unprivileged CTs do not expose. Either convert the CT to privileged, or use the alternative path described in the warning at the top of this page.",
    "aptTitle": "apt-get install fails",
    "aptIntro": "The script assumes a Debian-family CT (<code>apt-get</code>). On Alpine / Arch / Rocky / Alma, install the CIFS client by hand:",
    "aptItems": [
      "Alpine: <code>apk add cifs-utils samba-client</code>",
      "Arch: <code>pacman -S cifs-utils smbclient</code>",
      "Rocky / Alma: <code>dnf install cifs-utils samba-client</code>"
    ],
    "aptOutro": "Then re-run the ProxMenux script — the install step skips when the tools are already present.",
    "guestFallbackTitle": "\"The server connected you as guest instead of the specified user\"",
    "guestFallbackBody": "The script's active validation caught a real auth problem. The server accepted the connection but downgraded it to guest because the credentials are wrong. Common causes: typo in the username / password, the user does not exist on the server, the user is locked out, or the workgroup / domain is mismatched. Re-run the flow and re-enter credentials carefully (the password is hidden in the dialog).",
    "denyTitle": "\"NT_STATUS_ACCESS_DENIED\" when mounting",
    "denyBody": "Credentials were validated but the share denies access. Check on the server side whether the user has permissions on that specific share (validation only confirms login, not per-share ACLs). Also check whether the server requires a specific SMB protocol version: append <code>vers=3.0</code> (or <code>2.1</code>, <code>2.0</code>) to the mount options.",
    "utf8Title": "UTF-8 / non-ASCII filenames are mangled",
    "utf8Body": "The default options include <code>iocharset=utf8</code>, but some server configurations report an unexpected codepage. If filenames with accents / symbols look wrong, also try <code>nounix</code> (some Linux Samba servers need this when the client is also Linux) or set the server side to <code>unix extensions = no</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), 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)."
  },
  "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-nfs-client",
        "label": "NFS client in LXC",
        "tail": " — sibling page, same pattern for NFS shares."
      },
      {
        "href": "/docs/storage-share/lxc-samba-server",
        "label": "Samba server in LXC",
        "tailRich": " — the inverse: expose folders <em>from</em> a CT over Samba."
      },
      {
        "href": "/docs/storage-share/host-samba",
        "label": "Samba / CIFS as Proxmox storage",
        "tail": " — register the share in Proxmox itself instead of inside a single CT."
      }
    ]
  }
}