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

{
  "meta": {
    "title": "Host: Mount Samba share on Host | ProxMenux Documentation",
    "description": "Mount an external Samba / CIFS share on the Proxmox host — either as Proxmox storage (pvesm add cifs), as a plain host fstab mount with open uid/gid/file_mode (NOT visible in Datacenter > Storage), or both. The fstab method opens permissions so an unprivileged LXC bind-mounting the path can read/write without any changes inside the container.",
    "ogTitle": "Host: Mount Samba share on Host | ProxMenux Documentation",
    "ogDescription": "Mount an external Samba / CIFS share on the Proxmox host via pvesm, fstab with open perms (ideal for LXC bind-mounts), or both."
  },
  "header": {
    "title": "Host: Mount Samba share on Host",
    "description": "Mount an external Samba (SMB / CIFS) share — from a NAS, a Windows box, a TrueNAS SMB export — on the Proxmox host. Pick one or both methods: register it as Proxmox storage (visible in Datacenter > Storage) and/or add a plain /etc/fstab mount at a path you choose, with open uid/gid/file_mode so unprivileged LXCs can bind-mount and write without any changes inside the container.",
    "section": "Storage & Share · Host"
  },
  "intro": {
    "title": "What this does",
    "body": "ProxMenux offers two mount methods for a Samba share: <strong>(1) Proxmox storage</strong> via <code>pvesm add cifs</code>, visible in Datacenter > Storage and mounted at <code>/mnt/pve/&lt;id&gt;</code>. The password is stored as plaintext in <code>/etc/pve/priv/storage/&lt;id&gt;.pw</code>, protected by the root-only private directory; this is access control, not encryption. <strong>(2) Host fstab mount</strong> at a chosen path, persistent through <code>/etc/fstab</code> and mounted with <code>uid=0,gid=0,file_mode=0777,dir_mode=0777</code> so unprivileged LXC bind mounts can write. Its credentials are in a root-only file under <code>/etc/samba/credentials/</code>, never directly in <code>fstab</code>. Either or both methods can be used."
  },
  "opening": {
    "heading": "Opening the tool",
    "body": "From ProxMenux's main menu, open <strong>Storage &amp; Share Manager → Mount Samba Share on Host</strong>. You will see this sub-menu with four options:",
    "imageAlt": "Samba Host Manager menu — Mount / View / Remove / Test connectivity"
  },
  "howRuns": {
    "heading": "How the script runs",
    "body": "The flow has two phases. Phase 1: discover server, validate credentials, pick share, then pick mount method(s) via a checklist. Phase 2: only the methods you marked are executed. Credentials are needed up-front because <code>smbclient</code> needs them to list shares. Until the final confirmation, neither <code>/etc/pve/storage.cfg</code> nor <code>/etc/fstab</code> are touched."
  },
  "modes": {
    "heading": "Mount method picker (two options, mark one or both)",
    "intro": "After selecting the share and validating credentials, ProxMenux shows a checklist with the two mount methods. You can mark either, or both. If you press OK without marking anything, the dialog re-appears until you choose at least one option or press Cancel to exit the flow.",
    "headerMethod": "Method",
    "headerMount": "Mount path",
    "headerUi": "Visible in Datacenter > Storage",
    "headerUseCase": "Typical use case",
    "rows": [
      {
        "method": "<strong>As Proxmox storage (pvesm)</strong>",
        "mountRich": "<code>/mnt/pve/&lt;storage-id&gt;</code> (managed by Proxmox)",
        "ui": "Yes",
        "useCase": "Backups, ISOs, LXC templates — anything that needs to appear in the Proxmox UI. Live VM disks are technically supported but discouraged on CIFS (locking semantics)."
      },
      {
        "method": "<strong>Host fstab only</strong>",
        "mountRich": "<code>/mnt/&lt;path&gt;</code> with open uid/gid/file_mode",
        "ui": "No",
        "useCaseRich": "Bind-mount the share into one or more LXCs <em>without</em> registering Proxmox storage. Open local permissions help unprivileged CTs access it, but writing still requires permission from the SMB server for the authenticated user."
      },
      {
        "method": "<strong>Both</strong>",
        "mount": "Both paths above (two mount points for the same CIFS export)",
        "ui": "Yes",
        "useCase": "You want UI integration AND a stable host-side path with open permissions for LXC bind-mounts. The pvesm mount uses Proxmox defaults; the fstab mount applies the open uid/gid/file_mode separately."
      }
    ],
    "bothTitle": "“Both” creates two CIFS mount points",
    "bothBody": "pvesm mounts at <code>/mnt/pve/&lt;id&gt;</code> with Proxmox defaults. fstab mounts at <code>/mnt/&lt;path&gt;</code> with <code>uid=0,gid=0,file_mode=0777,dir_mode=0777</code> to permit local access through LXC bind mounts. The SMB server still enforces the mounted user’s permissions. These are two mount points; they do not guarantee two separate TCP connections."
  },
  "pvesmBranch": {
    "heading": "Method A — As Proxmox storage (pvesm)",
    "intro": "If <em>As Proxmox storage</em> is marked, ProxMenux runs the original pvesm flow:",
    "items": [
      "<strong>Storage ID</strong> — default <code>cifs-&lt;server-ip-with-dashes&gt;</code>. Only letters, digits, <code>-</code> and <code>_</code>.",
      "<strong>Content types</strong> — this ProxMenux checklist offers <strong>6</strong> choices. It omits <code>rootdir</code> compared with the NFS checklist; this is a script-level choice, not a claim that every Proxmox CIFS backend version forbids LXC root filesystems:"
    ],
    "headerType": "Content type",
    "headerAllows": "What it allows",
    "rows": [
      {
        "type": "import",
        "allows": "Disk image imports (selected by default)."
      },
      {
        "type": "backup",
        "allowsRich": "VM and CT backup files (<code>vzdump</code>)."
      },
      {
        "type": "iso",
        "allows": "Installation ISO images."
      },
      {
        "type": "vztmpl",
        "allows": "LXC templates."
      },
      {
        "type": "images",
        "allowsRich": "Live VM disk images — <strong>warned inline</strong>, see below."
      },
      {
        "type": "snippets",
        "allows": "Hook scripts and cloud-init snippets."
      }
    ],
    "warnTitle": "Live VM disks on CIFS",
    "warnBody": "Selecting <code>images</code> triggers a ProxMenux warning that CIFS/SMB can cause locking issues with VM disk operations. The script recommends NFS for VM disk images but lets you continue. Backups and ISOs are common CIFS uses. Assess locking, snapshots, migration and workload requirements before using CIFS for <code>images</code>.",
    "credsTitle": "Where pvesm stores credentials",
    "credsBody": "The password is not written in <code>/etc/pve/storage.cfg</code>. Proxmox writes plaintext credentials in <code>/etc/pve/priv/storage/&lt;storage-id&gt;.pw</code>, inside the private area of the cluster filesystem, readable only by <code>root</code> (mode <code>0600</code>); it is protected by access control, not by encryption. After a server password change, use <code>pvesm set &lt;id&gt; --password &lt;new&gt;</code> or remove and re-add through ProxMenux."
  },
  "fstabBranch": {
    "heading": "Method B — Host fstab mount only",
    "intro": "If <em>As host fstab mount only</em> is marked, ProxMenux asks for a host mount path and persistent options, writes a root-only credentials file (User mode), then mounts and writes the entry to <code>/etc/fstab</code>:",
    "items": [
      "<strong>Host mount path</strong> — default <code>/mnt/&lt;share-name&gt;</code>. Must be an absolute path. If something is already mounted there, or a fstab entry exists, ProxMenux offers to replace it.",
      "<strong>Mount options</strong> — choose <em>Read/Write</em> (default: <code>rw,uid=0,gid=0,file_mode=0777,dir_mode=0777,iocharset=utf8,nofail,_netdev</code>), <em>Read-only</em> (<code>file_mode=0555,dir_mode=0555</code>), or <em>Custom</em> (enter your own options). The script recommends open uid/gid/file_mode for writes through LXC bind mounts."
    ],
    "credsTitle": "Credentials file (User mode)",
    "credsBody": "If you authenticated with a username + password, ProxMenux writes a root-only credentials file at <code>/etc/samba/credentials/&lt;server&gt;_&lt;share&gt;.cred</code> (mode <code>0600</code>) with <code>username=</code> and <code>password=</code> lines, and references it in the fstab entry via the <code>credentials=</code> mount option. Plain text never lands in <code>/etc/fstab</code>. For Guest mode, the option <code>guest</code> is appended instead and no credentials file is created.",
    "appliesIntro": "Once you confirm, the script:",
    "applies": [
      "<code>mkdir -p</code> the mount path.",
      "<code>mount -t cifs -o &lt;opts&gt;,credentials=&lt;file&gt;</code> (or <code>guest</code>) <code>//&lt;srv&gt;/&lt;share&gt; &lt;path&gt;</code>.",
      "Writes a one-line entry to <code>/etc/fstab</code>: <code>//&lt;srv&gt;/&lt;share&gt; &lt;path&gt; cifs &lt;opts&gt; 0 0</code>.",
      "Runs <code>systemctl daemon-reload</code> so systemd picks up the new fstab entry."
    ],
    "lxcTitle": "Using the fstab mount from an unprivileged LXC",
    "lxcBody": "The CIFS options <code>uid=0,gid=0,file_mode=0777,dir_mode=0777</code> open local permission checks for LXC bind mounts. Server ACLs and negotiated Unix/POSIX semantics can still affect access. <strong>No changes are made inside the container</strong>: no CT <code>chown</code>, groups or edits to <code>/etc/lxc</code>. The <code>mp</code> line is managed in Proxmox CT configuration. Use the printed <code>pct set</code> command or the <mountLink>LXC Mount Manager</mountLink>.",
    "noUiTitle": "The fstab mount is NOT a Proxmox storage",
    "noUiBody": "The host fstab mount is invisible to the Proxmox web UI — by design. It does not appear in <em>Datacenter > Storage</em>, you cannot select it in the VM / CT creator, and Proxmox backup jobs cannot target it. It is purely a host filesystem path. If you also want UI integration, mark <em>both</em> methods in the picker."
  },
  "manual": {
    "heading": "Manual equivalent",
    "pvesmIntro": "Method A (pvesm) maps to:",
    "fstabUserIntro": "Method B (fstab, user auth) — credentials file + mount:",
    "fstabGuestIntro": "Method B (fstab, guest auth) — no credentials file:"
  },
  "view": {
    "heading": "View configured CIFS storages and host mounts",
    "body": "Shows registered CIFS storages (<code>pvesm status | awk ''$2 == \"cifs\"''</code>) with server, share, content, username or <em>Guest</em>, path and status. Passwords are <strong>never printed</strong>. <strong>Note:</strong> a second section lists host fstab mounts, their options, authentication-file path and active/inactive state. For manual checks use <code>findmnt -t cifs</code> or <code>grep cifs /etc/fstab</code>."
  },
  "remove": {
    "heading": "Remove CIFS storage or a host mount",
    "body": "The removal picker offers pvesm storages and host fstab mounts. For pvesm, it runs <code>pvesm remove &lt;storage-id&gt;</code> and Proxmox removes the paired credentials. For fstab, it attempts <code>umount &lt;path&gt;</code>, removes the matching <code>/etc/fstab</code> entry and credentials under <code>/etc/samba/credentials/</code>, and removes an empty mount directory if possible. A failed unmount requires a manual unmount or reboot. <strong>The remote Samba server and its files are not modified</strong>.",
    "warnTitle": "Back up dependencies first",
    "warnBody": "VMs, CTs or backup jobs that reference this storage by ID will fail after removal. Move / drop those references before removing the storage."
  },
  "test": {
    "heading": "Test Samba connectivity",
    "body": "Runs a diagnostic pass over every CIFS storage registered in Proxmox: checks that <code>smbclient</code> is available, pings each server, probes ports 445 and 139, tries a guest listing, and reports Proxmox's own view (<code>pvesm status</code>). \"Requires authentication\" on guest-list means your server only exposes shares to authenticated users — normal for most NAS setups."
  },
  "troubleshoot": {
    "heading": "Troubleshooting",
    "noServersTitle": "\"No Samba servers found on the network\"",
    "noServersBody": "Auto-discover uses <code>nmap -p 139,445</code>. The server may be on a different subnet, firewalled, or only reachable by hostname (mDNS / WINS). Use the <em>Manual</em> option with the IP or hostname instead.",
    "noSharesTitle": "\"No accessible shares found\"",
    "noSharesBody": "<code>smbclient -L</code> returned nothing for these credentials. Causes: the user has no permission to list shares (try with admin credentials once, or enter the share name manually), the server has share visibility disabled, or the credentials are wrong. The script lets you type the share name by hand in this case.",
    "denyTitle": "Proxmox mount fails with NT_STATUS_ACCESS_DENIED",
    "denyBody": "The credentials pvesm stored are out of sync with the Samba server (password changed, account disabled, domain / workgroup mismatch). Re-enter credentials with <code>pvesm set &lt;id&gt; --username &lt;u&gt; --password &lt;p&gt;</code> or remove and re-add from ProxMenux. If the server is in an AD domain, append <code>--domain &lt;DOMAIN&gt;</code> to the <code>pvesm set</code> call.",
    "sleepTitle": "\"host is down\" or storage status goes inactive at night",
    "sleepBody": "Some NAS appliances put SMB to sleep aggressively. <code>pvestatd</code> then sees the storage as inactive until the first access wakes the NAS. If this is cosmetic, nothing is broken. If it causes backup failures, disable SMB idle disconnect on the NAS or schedule backups outside the sleep window.",
    "lxcNoWriteTitle": "Unprivileged LXC bind-mount can't write to the fstab path",
    "lxcNoWriteBody": "Check <code>findmnt /mnt/&lt;path&gt;</code> for the intended options, such as <code>uid=0,gid=0,file_mode=0777,dir_mode=0777</code>. Missing local write permissions can block mapped LXC UIDs. Reapply the default RW preset or adjust Custom options as needed. Also verify the mounted SMB user can write on the server and whether Unix/POSIX extensions supply server modes; open local modes cannot override server ACLs.",
    "fstabBootTitle": "fstab mount does not come up after reboot",
    "fstabBootBody": "The script adds <code>nofail,_netdev</code> so a missing share at boot does not block startup. If the mount never comes up: confirm the network is reachable (<code>ping &lt;server&gt;</code>), check <code>journalctl -u remote-fs.target</code>, verify the credentials file still exists (<code>ls -l /etc/samba/credentials/</code>) and is readable, and try <code>mount -a</code> manually."
  },
  "related": {
    "heading": "Related",
    "items": [
      {
        "href": "/docs/storage-share/host-nfs",
        "label": "NFS share as Proxmox storage",
        "tail": " — sibling page with the same flow pattern (Method A pvesm + Method B fstab) and side-by-side trade-offs."
      },
      {
        "href": "/docs/storage-share/lxc-mount-points",
        "label": "LXC Mount Manager",
        "tailRich": " — bind-mount the fstab-only path <code>/mnt/&lt;path&gt;</code> into one or more containers."
      },
      {
        "href": "/docs/storage-share/lxc-samba-client",
        "label": "Samba client in LXC",
        "tail": " — alternative: mount Samba directly from inside a privileged container (skips the host)."
      }
    ]
  }
}